mcp-server-imagine

1. 项目简介

mcp-server-imagine 是一个 Go 实现的独立 MCP Server，面向图像生成、图像编辑和图像导入场景，统一通过 POST /mcp 提供协议入口。

当前服务支持：

• initialize
• tools/list
• tools/call
• 单条 SSE 响应

模型能力通过 MCP 可发现：

• tools/list 返回工具入口
• image.models.list 返回所有已配置图像模型，以及每个模型每个 operation 的精确 inputSchema

仓库当前同时支持两类交付方式：

• 本地开发与联调：make run、make docker-up
• 版本化离线发布：make release

2. 快速开始

前置要求

• Go 1.26+
• Docker Engine 20+ 与 docker compose v2

初始化本地环境

cp .env.example .env

至少准备一个非 example 的 provider 配置：

cp configs/provider.example.yml configs/provider.yml

本地运行

make run

默认入口：

http://localhost:11962/mcp

测试

make test

全量模型联调

make verify-models

联调命令会：

• 自动拉起本地 MCP 服务
• 强制把运行时资产写入仓库内 data/
• 先调用 image.models.list 做 discovery
• 导入一张内嵌测试图，作为所有 edit 模型的统一输入
• 对每个已声明 capability 的模型发起一次真实调用
• 生成 data/verification/<run-id>/summary.md
• 为每个模型生成独立的 data/verification/<run-id>/curl/*.md

Poe 的代理优先来自 configs/poe.yml 顶层的 endpoint.proxyUrl，因此可以只让 Poe 走代理而不影响其他 provider。HTTP_PROXY / HTTPS_PROXY 仍可作为整进程代理的补充方案，NO_PROXY 建议至少包含 localhost,127.0.0.1。

3. 推荐调用方式

先发现模型

curl -X POST http://localhost:11962/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "models-1",
    "method": "tools/call",
    "params": {
      "name": "image.models.list",
      "arguments": {
        "operation": "generate"
      },
      "_meta": {
        "chatId": "11111111-1111-4111-8111-111111111111"
      }
    }
  }'

响应中的 result.structuredContent.models[*].operations[*].inputSchema 就是执行时应遵守的参数契约。

再执行生成

curl -X POST http://localhost:11962/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "poe-generate-1",
    "method": "tools/call",
    "params": {
      "name": "image.generate",
      "arguments": {
        "model": "GPT-Image-1",
        "prompt": "冬天到春天交界时，冰雪消融、嫩芽破土、阳光洒落的希望场景",
        "size": "1024x1024",
        "quality": "high"
      },
      "_meta": {
        "chatId": "11111111-1111-4111-8111-111111111111"
      }
    }
  }'

返回结果中的 result.structuredContent.asset.relativePath 表示图片已保存到当前 chat 目录，可据此读取生成文件。

如果上游超时，错误文本会带上 model、requestKind、endpoint 和 timeoutMs，用于区分参数问题与供应商超时。

4. 配置说明

• 根目录 .env.example 用于服务运行参数示例
• 根目录 configs/*.yml 会在启动时自动加载，*.example.yml 仅作模板展示
• 默认配置来自 internal/config/application.yml
• CONFIG_PATH 可追加覆盖进程级配置
• 版本单一来源是根目录 VERSION

配置优先级：

代码默认值 < internal/config/application.yml < configs/*.yml < CONFIG_PATH 指向 yml < 环境变量

关键约束：

• 根目录至少需要一个非 example 的 configs/*.yml 本地配置，否则启动失败
• 每个 configs/*.yml 只描述一个 provider 文件分组
• 每个 provider 文件都必须显式声明：
  • name
  • endpoint.baseUrl
  • auth.apiKey
• 每个模型都必须显式声明：
  • name
  • capabilities.generate 和/或 capabilities.edit
• 每个模型可选声明：
  • endpoint.baseUrl
  • endpoint.proxyUrl
  • auth.apiKey
• 每个 capability 都必须显式声明：
  • inputSchema
  • request.kind
  • request.sizeMode
  • response.defaultFormat
  • response.parserByFormat
• arguments 是唯一参与 schema 校验的对象，_meta 不参与 schema 校验
• 旧的“每个 model 自带 endpoint/auth，provider 顶层缺省”的写法已不再支持

release bundle 只分发模板配置，不分发当前本地 configs/*.yml。部署端应自行从 configs/provider.example.yml 复制出真实配置文件。

capability 配置结构

name: your-provider
endpoint:
  baseUrl: https://api.example.com/v1
  proxyUrl: http://127.0.0.1:8001
auth:
  apiKey: your-api-key
models:
  - name: your-model
    capabilities:
      generate:
        inputSchema:
          type: object
          properties:
            model:
              type: string
            prompt:
              type: string
            size:
              type: string
          required: [model, prompt, size]
          additionalProperties: false
        request:
          kind: chat_completions
          sizeMode: ratio
          aspectField: aspect
        response:
          defaultFormat: url
          allowedFormats: []

... [View full README on GitHub](https://github.com/linlay/mcp-server-imagine#readme)