Dotforge
原始 Markdown

PixelLab Hub MCP 参考文档

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

线上端点

项值
本文档 URLhttps://dotforge.eu.cc/docs/mcp-hub
原始 Markdownhttps://dotforge.eu.cc/docs/mcp-hub.md
API 域名https://api.dotforge.eu.cc
MCP URL（Streamable HTTP）https://api.dotforge.eu.cc/mcp
旧版 SSE URLhttps://api.dotforge.eu.cc/sse
Webhttps://dotforge.eu.cc
官方工具说明https://api.pixellab.ai/mcp/docs

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

点官方Hub（本项目）
入口https://api.pixellab.ai/mcp本站 /mcp
鉴权PixelLab 账号 API token管理员专用 plmcp_…（mcp_api_keys）
上游 key单账号多账号 KeySelector + 资源粘性
工具范围全量（含 tileset/UI/chat/sandbox 等）v1 仅角色 + 动画 + 物件（+ agent_help）
list_*该官方账号下全部资源仅本 Hub 创建并登记的资源
本站 credits无不扣；消耗的是上游 PixelLab 额度
下载链接官方 UUID 直链仍为官方 download URL（UUID 即密钥）

非目标（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_…）仅此一次。另有：

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 传输兼容性

3. 核心机制

3.1 非阻塞

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

3.2 账号调度

请求类型Key 选择额度刷新（本站缓存）
新建 create_* 等KeySelector.Acquire（① 从未用过 ② 剩余额度高 ③ 跨 UTC 日空号重检）主路径最多约 12 次 balance 探测；空号冷却到次日 00:00 UTC（+2m）；跨日后最多约 3 次重检；Release 会刷
tools/list临时 Acquire会刷；401/429 会 disable/cooldown
sticky 后续（get/animate/delete/tags…）mcp_resources 固定创建时账号不换号；上游 402/429/额度文案会 NoteOutcome（cooldown / disable）
list_characters / list_objects本地表不访问上游

不做「整条 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_character创建角色（standard / pro / v3）
create_character_state同一角色变体（服装/姿态等，保持身份）
animate_character排队动画（template / v3 / pro）
get_character状态、旋转、动画、下载
list_characters本地登记列表
delete_character删除角色
update_character_tags替换标签
delete_animation删角色或物件上的动画

物件

工具说明
create_map_object地图物件（透明底，可 inpaint）
create_1_direction_object单方向物件（可能多候选 review）
create_8_direction_object八方向物件
get_map_object / get_object查询
list_objects本地登记列表
animate_object物件动画
create_object_state物件变体
select_object_framesreview 中选帧成独立物件
dismiss_review丢弃 review
delete_object删除物件
update_object_tags替换标签

其它

工具说明
agent_help用法问答（几乎不耗生成额度）

不暴露：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"
)

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
)

create_*_object / review

list_*（Hub 特有）

6. 错误与运维

现象含义处理
401 无效 MCP API Keytoken 错/吊销/过期/非 admin重签或检查 Bearer
tool_not_allowed非 v1 白名单换官方 MCP 或等 Hub 扩白名单
no_provider_key / provider_keys_busy / provider_quota_exhausted池无可用 key管理后台检查密钥与额度
resource_not_foundsticky id 未登记必须用本 Hub 创建的 id；勿手填他站 id
upstream_error官方侧失败重试；查上游额度/限流
404 MCP session not foundsession 无效、过期或属于另一把 key重新 initialize，不要复用旧 session
406 Not Acceptable现代客户端未同时接受 JSON 与 SSE，或 GET 不接受 SSE使用标准 MCP SDK 请求头
415 Unsupported Media TypePOST 不是 application/json设置 Content-Type: application/json
GET /mcp 返回 405无 session 的现代独立 SSE GET 不受支持先 POST initialize；旧 SSE 客户端改用 /sse

环境变量：

变量默认
MCP_ENABLEDtrue（false 时 /mcp 404）
MCP_UPSTREAM_URLhttps://api.pixellab.ai/mcp

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

审计：mcp_key.create / mcp_key.revoke。

7. 安全注意

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

8. 相关文档