# PixelLab Hub MCP 参考文档

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

**线上端点**

| 项 | 值 |
|----|-----|
| 本文档 URL | https://dotforge.eu.cc/docs/mcp-hub |
| 原始 Markdown | https://dotforge.eu.cc/docs/mcp-hub.md |
| API 域名 | `https://api.dotforge.eu.cc` |
| MCP URL（Streamable HTTP） | `https://api.dotforge.eu.cc/mcp` |
| 旧版 SSE URL | `https://api.dotforge.eu.cc/sse` |
| Web | `https://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** 会话：

```bash
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

```jsonc
{
  "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 等

```json
{
  "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`。

---

## 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 推荐工作流

```text
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_frames` | review 中选帧成独立物件 |
| `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`

```text
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`

```text
# 模板（便宜，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. 错误与运维

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

环境变量：

| 变量 | 默认 |
|------|------|
| `MCP_ENABLED` | `true`（`false` 时 `/mcp` 404） |
| `MCP_UPSTREAM_URL` | `https://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. 相关文档

- 设计：`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