PixelLab Hub MCP 参考文档

多账号集成的 PixelLab MCP 代理。工具语义对齐官方 MCP，底层用本站 provider_keys 池调度。

线上端点

1. 与官方 MCP 的差异（必读）

非目标（v1）：tileset / isometric / UI / chat / sandbox；普通用户 MCP；自动同步官方网页创建的资源。

2. 接入配置

2.1 签发 MCP Key（管理员）

需本站 admin 会话：

curl -sS -X POST "https://api.dotforge.eu.cc/api/v1/admin/mcp-keys" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"cursor-laptop"}'

响应含 token（plmcp_…）仅此一次。另有：

• GET /api/v1/admin/mcp-keys — 列表（无明文）
• POST /api/v1/admin/mcp-keys/{id}/revoke — 吊销

2.2 OpenCode

{
  "mcp": {
    "pixellab-hub": {
      "type": "remote",
      "url": "https://api.dotforge.eu.cc/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer plmcp_YOUR_TOKEN"
      },
      "timeout": 120000
    }
  }
}

校验：opencode mcp list → pixellab-hub connected。

2.3 Cursor / Claude Desktop 等

{
  "mcpServers": {
    "pixellab-hub": {
      "url": "https://api.dotforge.eu.cc/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer plmcp_YOUR_TOKEN"
      }
    }
  }
}

工具名可能带前缀（如 mcp__pixellab-hub__create_character），以客户端实际为准。

2.4 传输兼容性

• 优先使用 /mcp 和 http / streamable-http 传输。初始化响应会返回 Mcp-Session-Id，后续请求需复用该 session。
• 只支持旧 HTTP+SSE 传输的客户端使用 /sse 和 sse 传输。首次 GET 会返回 event: endpoint，客户端随后向该 endpoint POST JSON-RPC。
• WorkBuddy 5.3 系列可继续配置 /mcp；服务端会识别其旧 SSE 握手。其他旧客户端应显式配置 /sse，不要依赖 User-Agent 兼容。
• 两个 URL 均使用同一个 Authorization: Bearer plmcp_…，且都不是上游 https://api.pixellab.ai/mcp。

2.5 客户端 Schema 兼容（严格校验器）

上游 PixelLab MCP 是 FastMCP/Pydantic 服务，其 tools/list 的 inputSchema 会输出 type: ["string","null"]、minimum/maximum、minLength/maxLength、format: "uuid" 与 default: null。部分客户端（如 DeepSeek DSH）使用严格 JSON Schema 子集校验器，只要任何一个工具的 schema 含不受支持的关键字，就会把该服务已注册的工具全部回滚清理，表现为连接成功但工具数为 0。

Hub 已在 tools/list 出口处统一清洗：会话中的 inputSchema 只保留 type / oneOf / properties / required / additionalProperties / items / enum / const / description / default / title。

清洗规则：

• type: ["T","null"] → type: "T"（可选性由 required 表达）；
• 删除 minimum/maximum/exclusiveMinimum/exclusiveMaximum/minLength/maxLength/minItems/maxItems/format，并把边界回填进该字段的 description（如 [min 16 max 256]、[format: uuid]），约束不丢失；
• 删除 default: null；
• enum / const 原样保留（取值约束仍有效）；
• 同名属性不会误删：例如 create_1_direction_object.style_images[].format 是一个真实的参数字段名，清洗器区分"关键字"与"属性名"，该字段及其 default: "png" 均保留。

此清洗只作用于 tools/list 的描述元数据；tools/call 的参数仍原样转发给上游，因此上游的校验与错误语义不变。

2.5.1 握手前的协议协商探测（server/discover）

MCP 2026 规范的「现代协议」客户端（官方客户端的 versionNegotiation: 'auto' 模式）会在 initialize 之前先发一个探测请求：

{"jsonrpc":"2.0","id":"server-discover-probe-1","method":"server/discover",
 "params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}

该探测不可能携带 `Mcp-Session-Id`。Hub 不在 2026 协议之列，按规范应回答：

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":{"code":-32001,"message":"session not found: send initialize first"},
 "id":"server-discover-probe-1","jsonrpc":"2.0"}

要点：

• 必须是 `400` + JSON-RPC 错误体（规范对"需要 session 但未提供"的定义）。客户端会解析该响应体并据其判定服务端为 2025-era，随后继续 initialize。
• `id` 必须原样回显：探测使用字符串 id（如 server-discover-probe-1），不回显则客户端无法匹配该响应，只能等到探测超时。
• 早期实现返回 400 + text/plain（Mcp-Session-Id is required after initialization）。该响应体不是 JSON-RPC，客户端拿不到可解析的错误对象。
• 会话失效（未知 Mcp-Session-Id）同样返回 `404` + JSON-RPC 错误体，而非纯文本。

2.6 POST 响应使用 JSON 模式（默认）

POST /mcp 的响应默认返回 `application/json`，而非 text/event-stream 的 SSE 分块流：

HTTP/2 200
content-type: application/json

为什么：本服务的每个 RPC 响应都是单条、已完整生成的 JSON-RPC 消息，SSE 分块不带来任何流式收益；而 text/event-stream 会让中间层（Cloudflare 等）把响应归类为"流"，从而施加缓冲/keepalive 策略。改为普通 JSON 后该请求完全走普通 HTTP 响应路径。

MCP 规范要求客户端 POST 时同时声明 Accept: application/json, text/event-stream 并处理两种回包，因此对客户端是透明的（官方 v1/v2 SDK 均已实测通过）。客户端处理速度也更快：同一部署下 initialize + tools/list 从 1154ms 降至 ~200ms。

需要恢复 SSE 分块时设置服务端 DisableJSONResponse。/sse 旧传输与 WorkBuddy 握手不受影响，仍在 SSE 流上收发 message 事件。

2.6 工具列表缓存与握手健壮性

tools/list 是客户端握手期的关键调用。早期实现每次握手都会租用一把 provider key 并可能触发最多 12 次上游余额探测，导致工具同步依赖密钥池状态与上游延迟：

• 池被占满/无可用 key 时返回 no_provider_key，严格客户端会注册零工具；
• 上游慢或不可达时该请求可能长时间挂起，客户端 15s 超时后同样得到「无工具」。

现在的行为：

能力声明：capabilities.tools.listChanged 现为 false。Hub 的工具面是固定的白名单投影，服务端从不发送 notifications/tools/list_changed，因此不再声明该能力（声明却不发送会让客户端等待永不到来的通知）。

独立 GET SSE 流：默认关闭，返回 405。

带 Mcp-Session-Id 的 GET /mcp 不再建立 SSE 长连接，而是返回：

HTTP/1.1 405 Method Not Allowed
Allow: POST, DELETE

这是规范允许的降级信号：客户端收到 405 后会自动改用纯 POST 模式。

原因不是服务端阻塞，而是客户端连接池饥饿。该流只发送 : connected / : keepalive 注释，从不承载 JSON-RPC，本身没有任何功能；但只要它挂在那里，就会长期占用客户端到本源的连接。当客户端连接池较小或是共享池（代理、受限运行时、同时连多个 MCP 服务器）时，握手关键请求 POST tools/list 会排在该空闲流后面直到超时，客户端随即注册零工具。

实测（单连接池，同一部署）：

关闭该流后同一场景为 197ms / 21 工具。

兼容性：/sse 路径与 WorkBuddy 在 /mcp 上的旧 SSE 握手不受影响（它们本身就是 SSE 握手，不是"独立流"场景）。需要恢复旧行为时设置服务端 AllowStandaloneSSE。

3. 核心机制

3.1 非阻塞

创建类工具立即返回 id，后台生成（约 2–5 分钟）。用 get_* 查状态；完成后用官方 download URL。

3.2 账号调度

不做「整条 MCP 连接绑死一个账号」。同一资源的后续调用必须落在创建账号（官方资源按账号隔离）。

均匀性：先从未用过，再按剩余额度。已知空额冷却到 下一个 UTC 0 点（PixelLab 日额度重置；另 +2 分钟宽限），跨日后再 GetBalance。中途充值可点管理台「刷新余额」立刻清冷却。

可观测：API 日志 mcp tool=… mode=acquire|sticky provider_key=… outcome=…；管理台 /admin/keys 顶部「密钥池健康」与 GET /api/v1/admin/keys/health。

3.3 资源登记

创建成功后写入 mcp_resources（resource_id → provider_key_id）。 未知 id 的 sticky 调用返回 resource_not_found（不 fan-out 猜账号）。

3.4 推荐工作流

1. create_character(...)           → character_id
2. animate_character(character_id, template_animation_id="walking")  # 可立刻排队
3. get_character(character_id)     → 进度 / 完成后的旋转图与下载链

4. v1 工具清单

角色与动画

物件

其它

不暴露：create_topdown_tileset、sidescroller/isometric、UI、chat、sandbox、agent_feedback 等。

参数细节与官方一致，见：https://api.pixellab.ai/mcp/docs 下文只列高频用法与 Hub 注意点。

5. 高频工具用法

create_character

create_character(
  description="brave knight with shining armor",
  name="Knight",
  n_directions=8,          # 4 或 8；pro/v3 常固定 8
  size=48,                 # standard/pro 最大 128；v3 最大 256
  mode="standard",         # standard | pro | v3
  outline="single color black outline",
  shading="basic shading",
  detail="medium detail",
  view="low top-down"
)

• v3 + `reference_image_base64`：把已有南向角色图转成 8 向（不要用 create_8_direction_object 做人形角色）。
• quadruped：body_type="quadruped" 且 template 为 bear|cat|dog|horse|lion。

animate_character

# 模板（便宜，1 gen/方向）
animate_character(
  character_id="<uuid>",
  template_animation_id="walking",
  action_description="walking proudly"   # 可选
)

# 自定义 v3（无 template 时默认）
animate_character(
  character_id="<uuid>",
  action_description="casting a fire spell",
  mode="v3",
  frame_count=8
)

• pro 自定义：先 confirm_cost=false 看价，用户确认后再 true。
• 模板模式可在角色仍 processing 时排队；v3/pro 建议等 completed。

create_*_object / review

• create_1_direction_object：多候选时 status=review → get_object → select_object_frames 或 dismiss_review。
• 人形角色请用 create_character，不要用 8 向 object 管线。

list_*（Hub 特有）

• 只显示经本 MCP 创建的 id。
• 本地 status 可能仍为 processing，以 get_* 为准（v1 不强制 get 回写 list 状态）。

6. 错误与运维

环境变量：

限流：IP + MCP key 约 120/min（可调）。

审计：mcp_key.create / mcp_key.revoke。

7. 安全注意

1. plmcp_ 与官方 PixelLab token 同等敏感，勿提交仓库。
2. 仅 admin 可签发与调用。
3. 吊销立即生效。
4. 下载 URL 含 UUID 即可访问（与官方一致），分享即授权。

8. 相关文档

• 设计：docs/superpowers/specs/2026-07-24-mcp-hub-design.md
• 实现计划：docs/superpowers/plans/2026-07-24-mcp-hub.md
• 生产运维：docs/ops/production.md
• 官方 MCP：https://api.pixellab.ai/mcp/docs
• 官方 REST v2：https://api.pixellab.ai/v2/llms.txt