BiuBiu工坊 MCP 接入指南

连接端点、协议与占位配置

客户端负责 initialize、notifications/initialized 和工具发现。此服务不提供 GET SSE 或 DELETE session；这不代表 POST 传输失败，通知或断线也不会取消持久业务任务。

客户端配置 JSON（只含占位符）

{
  "mcpServers": {
    "biubiu": {
      "url": "https://www.semebiubiu.com/biubiu/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json",
        "MCP-Protocol-Version": "2025-06-18"
      }
    }
  }
}

以上格式仅供支持 url 与自定义 headers 的客户端参考，不保证所有客户端采用同一配置语法。由你在客户端可信的凭据设置中替换占位符，本文没有真实令牌。

5 类权限，按实际用途选择

在 MCP 管理中登录后创建个人访问令牌。仅查看账户可只选 account:read；仅查询本人任务可只选 jobs:read。确需查看或下载产物时再加 resources:read，确需生成时才授予写权限并取得用户创建及费用授权。

工具列表按令牌权限过滤。完整生成并检查产物会用到上述各类权限，但不应因此把完整权限授予仅需只读的客户端。令牌权限不能替代每次必要的人工媒体确认。

7 项工具速览

get_task_status 只有同时具备 resources:read 才返回可用 assets；没有 assets 不等于没有任务。状态详情不能完整还原原始 direction、customAction、customStyle、frameCount 或已选周期；最终帧数与周期应从实际产物核验，无法下载时明确标为未核验。

list_my_history 默认每页 10 条，limit 为 1–20 的整数。第一次同时省略两个游标；后续完整传回服务端 next.beforeTime 与 next.beforeId，不只传一个或猜测游标。beforeTime 是秒级数字字符串，createdAt 为毫秒，不混用。

创建任务字段：只生成参考图入队

调用 create_frame_task 前必须获得用户创建任务与费用授权。参数对象禁止未声明字段，不传自定义价格、用户 ID、外部 API 密钥、上传 URL 或服务器路径；字符串长度按 JavaScript UTF-16 单元计算。

风格代码分别对应像素风、石器时代卡通、赛璐璐、水彩手绘、黏土玩偶、3D卡通、低多边形、扁平矢量和自定义风格。

创建阶段不传 frameCount、start 或 end。所有 jobId 保持正整数 ID 的字符串形式，范围为 1 至 18446744073709551615，不转成浮点数。

创建参数示意（不是执行指令）

{
  "requestId": "12345678-1234-4123-8123-123456789abc",
  "description": "戴着薄荷绿围巾的小狐狸冒险家，全身独立角色",
  "action": "待机",
  "style": "pixel",
  "direction": "south",
  "mode": "auto"
}

示例 UUID 仅展示格式，首次真实新操作须重新生成，不复用示例值。成功回执的 accepted: true 和 stage: reference 只表示入队，不表示产物已完成或已扣费。

两次确认必须来自用户看过真实媒体

周期实际范围与采样校验可能在后台解码后进行，accepted: true 仅表示入队，不代表所选周期有效。超出真实视频时长或采样不足可能随后进入 frames_error，请核查原任务及试用返还状态，不要重新确认同一操作。

auto 模式禁止传 backgroundReviewed、keyColor、tolerance。不能自动勾选审阅字段，不能用任意媒体、元信息或一段文字冒充真实图片/视频展示。没有安全鉴权下载能力时，回 本人历史任务查看实际媒体，并等待用户明确确认；原任务确认应在工作台的对应生成流程进行。

HTTP 200 不等于业务成功，未知写入不换 UUID

1. 先检查 HTTP 及 JSON-RPC 协议层 error，不能只看状态码。
2. 工具调用再检查 result.isError，失败不是空成功。
3. 成功数据位于 content 的 text 中，是 JSON 字符串；解析后核查回执、任务状态和账务。
4. accepted 仅表示入队；nextAction 仅提示下一步，不等于获得用户确认，也不表示已扣费或已完成。

写入超时、断线或返回未知时，保留原 requestId、原操作、原目标及原参数，先只读核查原任务。不得更换 UUID 重发，不自动创建替代任务，不把未知当成失败。若确需按服务端规则重放，只能重放原操作，不能修改参数后伪装成同一写入。

新任务按参考图 1、视频 4、透明帧 1 成功阶段扣费，共 6 积分；试用优先覆盖完整链路，新注册赠 3 次完整试用，积分永久。实际计费、失败取消与返还以服务端记录为准；帧试用失败需取消后新建，不能重试原试用产物。

任务账务包含 known、mode、consumedPoints、debitedPoints、returnedPoints、netDebitPoints、reservedPoints、trialState 和 details。unknown 或 null 如实显示为未知；余额变化不能独立证明任务收费，旧任务也不直接套用新任务 6 积分规则。

私有资源：小 PNG 可内联，其余返回鉴权元信息

get_artifact_info 返回 name、size、mimeType、uri、authenticatedPath 和 authorization。不返回密钥或公开签名 URL；资源属于本人鉴权的私有产物，不是公开媒体库。

• resources/read 使用 biubiu://jobs/{jobId}/{name}，需要 resources:read 权限。
• 大小不超过 256 KiB 且 MIME 为 image/png 的资源可内联 Base64 blob；内联仍需鉴权，不是公开资源。
• 大于 256 KiB 的 PNG、视频、ZIP 及非 PNG 类型仅返回鉴权元信息（inline=false），不会把大视频或 ZIP 内联。
• authenticatedPath 格式为 /biubiu/mcp/assets/{jobId}/{name}；GET/HEAD 下载需本人 Bearer PAT，仅限固定 HTTPS 同源且安全注入鉴权。
• 没有安全鉴权下载能力就回 本人历史任务查看。不得读取客户端私有凭据、把秘密放入命令行或 URL、把元信息当作实际媒体。

resources/list 返回空列表；resources/templates/list 返回本人产物的 URI 模板。状态 assets 未列出 timing、coordinates 或 zip 不代表这些别名不存在，可按实际产物通过 get_artifact_info 核查。

等待、异常状态与请求限制

后台生成通常需要等待几分钟，高峰可能更久，不提供固定完成时间保证。建议只读查询不频于每 5 秒一次，并设定本轮查询截止；请求超时不是后台完成期限，不重复提交。

当前安全上限为每令牌及每用户每分钟 90 个请求、写操作每用户每分钟 20 个请求；这些是上限，不是轮询目标。POST JSON 请求体上限为 64 KiB，资源内联上限为 256 KiB 且仅 PNG，实际限制与工具 schema 以服务端为准。