dramaclaw-mcp-server

v0.3.3

Published

2 months ago

DramaClaw 官方 MCP server — 22 个工具包装 Bearer PAT + x-org-id, 给 Claude Code / Cursor / 飞书 aily / 其他 MCP 客户端直接驱动 DramaClaw 内容工厂.

0High
0Medium
0Low

wukai2011

mcp model-context-protocol dramaclaw ai llm agent claude cursor

dramaclaw-mcp-server v0.3.3

DramaClaw 官方 MCP server — 让 Claude Code / Cursor / opencode / Trae / Cline 等 MCP 客户端直接驱动 DramaClaw 内容工厂，不用手拼 cURL + token + 猜资源图。

22 个工具，七类：

导入侧（0⚡）：

create_adaptation_work — 创建改编作品
import_episodes_batch — 批量导入剧集（最多 80 集）
import_single_episode — 单集导入/覆盖
import_clip_shots — 批量导入分镜（最多 80 镜）
promote_to_production — 改编 → 制作 hand-off

发现/地图（0⚡，v0.2.0 新增，治"猜路径 404"）：

dramaclaw_init_status — 查初始化完整度 + 全生命周期 next_actions（服务端算好下一步该调啥），任何动作前先问地图，按 next_actions[0] 走
dramaclaw_list — 列资源拿真实 ID，别猜

真值/接地（0⚡，v0.3.2 新增，治"外部 agent 编进度 / 凭空假设额度"）：

dramaclaw_get_drama_progress — DB 真实分类 count（episodes_empty_placeholder vs with_content），报告进度/被质疑先核，别编 X/Y
dramaclaw_get_credits — DB 真实积分，调生成类前先核，别凭空假设额度

会话/接入（0⚡，v0.3.2 新增）：

dramaclaw_get_active_session — 核实 drama 是否真有活跃会话（反"派生中"撒谎；status!=active 勿报进行中）
dramaclaw_list_orgs — 列可访问 org，确认 DRAMACLAW_ORG_ID 该填哪个

生成侧（触发+poll，v0.2.0 新增）：

dramaclaw_generate_shots — 触发分镜生成（异步）
dramaclaw_generate_clip_video — 触发视频生成（异步；可选 visualStyleOverride 覆盖风格）
dramaclaw_poll_job — 轮询异步任务进度（shots / job / compose）

合成侧（触发+poll，v0.3.0 新增）：

dramaclaw_compose_clip — 把多个已生成 take 合成为最终成片（制作管线末步，产出可交付成片）

制作侧（v0.3.3 新增，制作页全流程接入）：

extract_entities — 扫剧本提资产 (LLM 提取角色/场景/道具, 异步 1-3 分钟)
extract_props — 专门提道具 (props 0 时明确触发)
batch_gen_assets — 批量生本剧资产图 (chars/scenes/props 三选一)
compose_episode — 跨集合成本集完整片 (多 clip take 拼接)
re_upload_script — 重新/追加/覆盖剧本 (★ 只传几集时务必 mode=append)
backfill_source_text — 历史原文回填 (从作品已存原文切章补)

生成/合成侧走触发+poll：触发工具立即返回 jobId，不同步死等；必须用 dramaclaw_poll_job 轮询到 done/failed。client 对 5xx/限流已自动退避重试。

控制台（接入 + 监控你的 bot）

x.mantur.ai/agent-console：

接入 — 生成 PAT、用配置生成器一键产出上面这段 MCP config、查 skills 参考
概览 — 按具名智能体看你的 bot 健康度（调用/错误率/vitality/常见错误+改进建议）
调用明细 / 排障 — 逐条调用下钻、错误码 → 建议词表

Onboarding

1. 在 x.mantur.ai/agent-console → 接入 tab 生成 PAT（read+write scope）

创建 PAT 时务必选对 platform（feishu-bot / wechat-bot / openclaw / claude-code / cursor / …）——这样你的 bot 调用会在 agent-console「概览」里按具名智能体正确归因（看到这个 bot 的调用量/错误率/健康度/改进建议），否则只能看到一团匿名流量。

2. 配置 MCP

已正式发布到 npmjs.com。 npx -y dramaclaw-mcp-server 直接拉起最新版（推荐使用 >=0.3.0）。

~/.claude.json 或 Cursor MCP 配置（prod；staging 把域名换 staging.claw.mantur.ai）：

{
  "mcpServers": {
    "dramaclaw": {
      "command": "npx",
      "args": ["-y", "dramaclaw-mcp-server"],
      "env": {
        "DRAMACLAW_API_BASE": "https://api.x.mantur.ai",
        "DRAMACLAW_PAT": "dc_live_xxxxxx",
        "DRAMACLAW_ORG_ID": "<your-org-uuid>"
      }
    }
  }
}

（npx 每次拉 npmjs 上最新发布版；要锁版本写 [email protected]。控制台「接入」tab 的配置生成器会按你选的 PAT/org 直接出这段。）

环境变量：

| Var | 必填 | 默认 | 说明 | |---|---|---|---| | DRAMACLAW_API_BASE | ✓ | https://api.x.mantur.ai | API 根路径，staging 用 https://staging.claw.mantur.ai | | DRAMACLAW_PAT | ✓ | — | dc_live_* 个人访问令牌（read+write scope）| | DRAMACLAW_ORG_ID | ✓ | — | 当前操作的组织 UUID（多 org 用户每次配置一个）| | DRAMACLAW_TIMEOUT_MS | — | 30000 | 单次请求超时 | | DRAMACLAW_MAX_RETRIES | — | 3 | 自动退避重试上限（v0.2.0）|

3. 重启 Claude / Cursor，对话里直接说

帮我创建改编作品「测试剧」，把这 30 集剧本导入，promote 到制作，然后检查初始化状态。

agent 会自动 create_adaptation_work → import_episodes_batch → promote_to_production → dramaclaw_init_status。

典型闭环（别自己猜，跟着 next_actions 走）：

调 dramaclaw_init_status → 看返回的 next_actions[0]（服务端告诉你该 quick_start_init / promote_to_production / sync_production_clips / generate_shots / generate_clip_video / export_or_publish 哪一步及对应端点）→ 执行那一步（生成侧用 dramaclaw_generate_* 触发 + dramaclaw_poll_job 轮到 done）→ 再调 dramaclaw_init_status 拿下一个 next_actions → 循环到 export_or_publish。全程不用自己拼资源图。

Tools 速查

| Tool | 输入 | 输出 | |---|---|---| | create_adaptation_work | title, totalEpisodes, projectId?, sourceReportId?, premise? | { workId, title, totalEpisodes } | | import_episodes_batch | workId, episodes[1..80], force? | { imported, overwrote, skipped, results[] } | | import_single_episode | workId, episodeNumber, rawText, title?, force? | { episodeId, status, imported, overwrote } | | import_clip_shots | clipId, shots[1..80], force? | { imported, overwrote, skipped, results[] } | | promote_to_production | workId | { productionWorkId, dramaId, reused } | | dramaclaw_init_status | dramaId | { initialized, missing[], partialAssets, suggestedStartNode, next_actions[] } ← 走 /agent-context, next_actions=全生命周期下一步 | | dramaclaw_list | kind, parentId? | { kind, result } | | dramaclaw_get_drama_progress | dramaId | { episodes{total,with_content,empty_placeholder}, characters, scenes, props, visual_style, next_actions } | | dramaclaw_get_credits | (无) | { available, total, reserved } | | dramaclaw_get_active_session | dramaId | { has_active_session, status, current_node, current_node_label } | | dramaclaw_list_orgs | (无) | { orgs[{id,name,role}], count } | | dramaclaw_generate_shots | clipId, force? | { triggered, jobId, pollWith } 或 { reused, shots } | | dramaclaw_generate_clip_video | clipId, visualStyleOverride? | { triggered, jobId, pollWith } | | dramaclaw_compose_clip | clipId, takeIds[1..200], subtitleStyle?, transitionStyle?, bgmAssetId? | { triggered, jobId, pollWith } | | dramaclaw_poll_job | kind(shots|job|compose), id, parentId? | { status, done, failed, terminal } |

完整 schema 见每个 tool 文件 zod description。

开发

pnpm install
pnpm --filter dramaclaw-mcp-server build
pnpm --filter dramaclaw-mcp-server test:e2e   # 需配置 env，跑 15 tool happy path（生成/合成侧只验触发，不烧积分）

错误处理

所有 tool 失败返 isError: true + 文本说明。v0.2.0 起，client 透出服务端统一信封（error_code / available_actions / retry_after_seconds / poll_hint）——agent 应据 available_actions 决策下一步，不靠 message 文案猜。

自动退避重试（client 内建，agent 无需手动）：

GET：对 429/502/503/504/网络超时退避重试 ≤3 次
写（POST/PATCH/DELETE）：仅对明确"未处理"的限流码（UPSTREAM_RATE_LIMITED/RATE_LIMITED/429/503/504/网络超时）重试，不对 502/UPSTREAM_INVALID_RESPONSE 自动重试（可能已落库/已扣费）——交 agent 看 available_actions 决定

常见 HTTP：401 PAT 失效 / 403 org 或 scope / 404 资源不存在或别 org（先 dramaclaw_list 确认 ID）/ 409 已存在传 force / 429 限速（已自动退避）

工程

框架：@modelcontextprotocol/sdk stdio transport
Schema：zod + zod-to-json-schema
鉴权：复用上线的 Bearer PAT 路径（Hono requireAuth 已识别 Authorization: Bearer + x-org-id）
信封：对齐服务端 apps/api/src/lib/api-errors.ts（wave 184）

License

MIT — Mantur Labs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme