kmeng MCP 服务接入说明

本页面向编程 Agent（ZCode / Claude Code 等）及其使用者。把本页链接和一个 MCP 令牌发给 Agent，Agent 按下文自行完成接入。

给 AI 助手：就做这两条命令（其余章节都是补充说明）

你在本机执行（需 Node ≥ 18；把占位符换成用户发给你的令牌，其余参数默认即可，不用问用户）：

curl -fsSL https://kmeng.tech/mcp-install.mjs -o mcp-install.mjs
node mcp-install.mjs --token kma_用户发给你的令牌

Windows PowerShell 里 curl 是 Invoke-WebRequest 的别名、不认 -fsSL，请用系统自带的 curl.exe：

curl.exe -fsSL https://kmeng.tech/mcp-install.mjs -o mcp-install.mjs
node mcp-install.mjs --token kma_用户发给你的令牌

• 宿主选择：你在 ZCode 里运行无需额外参数（默认写 ~/.zcode/cli/config.json）；你在 Claude Code 里运行无需额外参数（安装器识别到 CLAUDECODE 环境变量自动选 claude，并用 claude mcp add --scope user 真正注册，全项目可见）；也可显式加 --host claude；不写宿主配置加 --host none。--host 省略时安装器自动识别（CLAUDECODE 环境变量 → claude；否则本机有 ~/.zcode/cli 选 zcode，有 ~/.claude 选 claude，都没有选 zcode）。
• 成功判据：安装器末行输出「令牌验证通过：用户名（余额 N 积分…）」即接入完成，把结果转告用户；随后重启宿主（或重连 MCP），调用 whoami 应返回同一身份。401 = 令牌失效，请用户在「我的账户 → MCP 接入」重新生成。

你会拿到什么

用户会发给你两样东西：

• 本页链接（接入说明）；
• 一个 kma_ 开头的 MCP 令牌（即用户身份凭证）。

令牌对应用户在 kmeng 平台的完整身份：工作区数据隔离、积分计费、任务归属与该用户网页登录完全一致。所有以该令牌做的生成任务都会出现在用户自己的项目与任务中心里，用户可随时查看、纠正、吊销。

第 1 步：安装 kmeng-mcp（推荐：一条命令，全自动）

kmeng-mcp 是 stdio 形态的本地 MCP 服务，全部调用走 kmeng 平台 REST API，平台服务器不承载任何额外组件。本机装有 Node ≥ 18 即可：

curl -fsSL https://kmeng.tech/mcp-install.mjs -o mcp-install.mjs
node mcp-install.mjs --token kma_用户发给你的令牌

安装器自动完成：按平台分发清单逐文件下载 kmeng-mcp（sha256 校验）→ npm install → 写入宿主配置（ZCode：自动备份，只更新 mcp.servers.kmeng 节点；Claude Code：claude mcp add --scope user 真注册）→ 自动建本机上传根 ~/.kmeng/upload 并双层写入 KMENG_MCP_ALLOWED_UPLOAD_ROOTS（宿主 config + 用户级环境变量，其它客户端也继承）→ 立即验证令牌并回报用户名/余额。可选参数：

手动途径（离线环境）：本机已有 kmeng 仓库（开发机）直接用 kmeng-mcp/ 目录；否则向 kmeng 官方索取目录拷贝，然后 cd kmeng-mcp && npm install。

第 2 步：宿主配置（安装器已代写，手动时按下述）

ZCode——配置文件是 ~/.zcode/cli/config.json（注意：mcp.servers 是嵌套在 mcp 下的；该文件还承载其他服务器配置，手改请先备份、只动 kmeng 节点；Windows 路径在 JSON 里用正斜杠 /）：

{
  "mcp": {
    "servers": {
      "kmeng": {
        "command": "node",
        "args": ["C:/Users/你/.kmeng/mcp/server.js"],
        "env": {
          "KMENG_BASE_URL": "https://kmeng.tech",
          "KMENG_MCP_TOKEN": "kma_用户发给你的令牌"
        }
      }
    }
  }
}

Claude Code——安装器已代注册（--scope user，写入 ~/.claude.json 的 mcpServers.kmeng）。手动时：

claude mcp remove kmeng --scope user   # 已有旧注册时先删（不存在会报错，可忽略）
claude mcp add kmeng --scope user -e KMENG_BASE_URL=https://kmeng.tech -e KMENG_MCP_TOKEN=kma_… -- node "<kmeng-mcp 目录>/server.js"

• 作用域：claude mcp add 默认是 local（只对当前项目目录生效），换目录就“消失”；必须带 --scope user 才全项目可见。claude mcp list 应显示 kmeng ✓ Connected；会话内 /mcp 可看状态与重连。
• 注册后须重启 Claude Code 会话（或 /mcp 重连）才会出现 82 个 mcp__kmeng__* 工具；工作流 skill 已装入 ~/.claude/skills/kmeng-film-production，新会话自动可用。
• 启动超时：Claude Code 默认约 30 秒内 MCP 必须握手成功。kmeng-mcp 启动时会先查更新；网络慢时可设 MCP_TIMEOUT=60000（毫秒），或临时设 KMENG_MCP_AUTO_UPDATE=0 跳过启动检查（会话内 5 分钟复查不受影响）。
• 输出上限：Claude Code 单次工具输出默认上限 25000 token，超出会被截断；list_projects/get_project detail:true/list_desk_keyframes 等大返回请先 export MAX_MCP_OUTPUT_TOKENS=50000 再启动，并用 limit/offset 分页。长耗时工具调用上限用 MCP_TOOL_TIMEOUT（毫秒）调整。
• 权限提示：默认每个 mcp__kmeng__* 工具首次调用都会询问。可在 ~/.claude/settings.json 的 permissions.allow 里只放行只读工具（如 mcp__kmeng__whoami、mcp__kmeng__list_projects、mcp__kmeng__get_project、mcp__kmeng__list_asset_slots、mcp__kmeng__list_assets、mcp__kmeng__quote_generation）；会扣积分的提交类工具（click_generate_*、generate_asset、synthesize_speech、post_process_video 等）不要放进 allow，保留逐次确认作为花钱闸门。
• 令牌存放：令牌明文存于 ~/.claude.json（安装器写入时权限 600，不回显）。令牌泄露请立即在「我的账户 → MCP 接入」重新生成（旧令牌即刻作废）。

验证：安装器末尾会自动验证令牌（回报用户名/余额即成功，401 = 请用户重新生成）。写入宿主配置后重启宿主（或重连 MCP），首次调用 whoami 应返回用户名、工作区与积分余额。

本机文件上传（图片/视频/音频/xlsx 直接传路径）

upload_asset（图片/视频/音频）与 upload_storyboard（xlsx）支持两种本机文件输入，让你不用把大文件手动贴成 base64：

• filePath 路径上传（推荐，装好即用）：安装器已默认建 ~/.kmeng/upload 并自动写入 KMENG_MCP_ALLOWED_UPLOAD_ROOTS。把要上传的素材丢进该目录即可直接传路径；想开放自己的素材盘，重装时用 --upload-root /你的素材目录（多个目录分号分隔）。
• base64 上传（兜底）：任意环境可用，不受目录限制；大文件建议优先用 filePath。

装完即自动保持最新

kmeng-mcp 每次启动（宿主启动/重连 MCP 都会重新拉起本服务）时自动对比平台分发清单（逐文件 sha256），有更新就静默下载校验并原子替换——平台功能更新后，用户侧无需任何操作，随下次宿主启动自动同步；工作流 skill kmeng-film-production 副本（安装器装入宿主技能目录，带 .kmeng-managed 标记）一并同步。更新失败不影响使用本地版本；依赖清单变化时后台自动 npm install。whoami 返回的 mcpVersion 是当前版本，若出现 mcpUpdatePendingRestart 表示已拉新待宿主重启完全生效。

• KMENG_MCP_AUTO_UPDATE=0：停用自动更新（固定本地版本）；
• KMENG_MCP_UPDATE_INTERVAL_MS：分发清单检查间隔（默认 0 = 每次启动都查；设置成毫秒数则在该间隔内不重复查）；
• KMENG_MCP_SKILL_ROOTS：自定义 skill 目录（分号分隔，默认 ~/.agents/skills + ~/.claude/skills）。

工具清单（130 个）

精简工具表：为降低每轮上下文开销，工具表里的描述与参数说明是精简版（末尾带〔全文:get_tool_help〕）；完整说明用 get_tool_help({name}) 按需取回，只读不扣费。默认只直接列出身份、说明与计费/删除类工具，其余工具经 call_tool({name, args}) 调用（参数相同）；需要全部直接列出可设环境变量 KMENG_MCP_TOOL_MODE=all。

协作：绑定项目槽位的图片/视频提交会占用 asset/video-shot 锁并保持到任务终态，轮询会续租；同项目不同槽位可并行，同一槽位/镜头遇到 423 必须等待，不抢锁。导演台锁按用户判归属：同一个人的浏览器页面与 MCP 连接视为同一个编辑者，可以一起改同一台台（不互相 423），只有别的成员正在编辑该台时才 423；check_episode_references 只读，不会复制资产或消耗授权。

典型流程：create_project → upload_storyboard → get_project 读分镜行 → upload_asset 备参考图 → list_asset_slots → 图片走 open_image_generator → read_image_generator → update_image_generator → click_generate_image → poll_image_generator；视频走 open_video_generator → read_video_generator → update_video_generator → click_generate_video → poll_video_generator→ trigger_stitch 拼接/白模合成 → download_file 取成品；摆台用 get_desk 读工程 → list_desk_pose_keys/set_desk_pose 摆姿势 → 关键帧模式：list_desk_keyframes 看现有关键帧 → 角色/道具用 set_desk_object_keyframe（某秒某坐标+朝向+姿势，poseControls 给骨骼角度）、机位用 set_desk_camera_keyframe（某秒坐标+镜头旋转角+FOV）；成批路线仍可用 set_desk_path（全集秒打点+胯骨锚点，要精确到达用 preset:"exact"）与动作流 set_desk_action_track（片段起止骨骼角度线性过渡）语义直控 → 复杂结构化改动再 update_desk 提交增量；新建/重命名/归组/删除导演台与文件夹用 create_desk / rename_desk / move_desk / delete_desk / create_desk_folder / rename_desk_folder / delete_desk_folder（删除类必须显式 confirm:true）。

导演台白模渲染（本机执行）

导演台的 3D 渲染发生在浏览器端，白模截图/视频由 Agent 在本机用 playwright + ffmpeg 完成（Agent 会自检并安装依赖）：

• open_desk 返回：短时效登录 cookie（sid/did，默认 30 分钟，令牌吊销即失效）+ 导演台深链 /director-desk/?hostOrigin=…&workspaceId=…；
• playwright 把 cookie 注入上下文后打开深链，等 3D 画布就绪，在页面目录中选择目标导演台（id 来自 list_desks）；
• 截图/逐帧导出在本机完成后，必须用 upload_asset 回传平台项目——否则用户在平台上看不到渲染产物；
• 摆台数据修改走 update_desk（JSON Merge Patch：对象深合并、null 删键、数组整体替换），不要整包回传工程；同一个用户的浏览器页面开着也能改（锁按用户判归属，不再互相 423）；只有别的成员正在编辑该台时才会收到 423，请稍后重试。
• 画面「有角色、没场景」（背景纯黑 + 顶部一条褐色横带）先跑 audit_whitebox_scale：渲染层把导入模型最大边归一化到 2 单位再乘对象的 transform.scale ⇒ 最终渲染最大边 = 2 × transform.scale[0]（与模型原始大小无关）。回执按 modelClass 分两类：native（原始尺寸模型，GLB 最大边 6.9~108 米）才用「应有 = GLB 最大边 ÷ 2」；normalized（归一化单位模型，最大边恰好 1~2 米）的 scale 本身就是「设计尺寸 ÷ 2」、不判 ratio。看到 suspicion=camera-buried-in-oversized-model（归一化模型被撑到 20 米以上且机位在包围盒内）⇒ 修法是改机位（抬到模型外 / 按段配机位），不是缩白模。只有 verdict 为 oversized/undersized 的才按 fixList 改 transform.scale，改完必须重抓帧（旧帧作废）。

MCP 只管功能，工作流看 skill

本 MCP 的每个工具只负责"单个平台功能怎么调"；整条影视生产流水线的作业顺序（建项目→分镜→资产→摆台→白模→分镜图→视频→交付，先做什么、何时停、何时问用户）封装在宿主的 kmeng-film-production skill 里，随 kmeng-mcp 一起分发（kmeng-mcp/skills/kmeng-film-production/SKILL.md，装入宿主技能目录即可）。用户说"用 kmeng 做视频/跑流水线"时会自动触发。

使用纪律（Agent 必读）

• get_task 不带 waitSeconds 时对同一任务强制 ≥10 秒间隔（平台任务查询会触发上游刷新），过密返回缓存并标注 throttled；带 waitSeconds≤25 则由服务端长轮询按 ≥10 秒节奏驱动上游刷新、状态变化立即返回，提交后等结果优先用它；
• 图片必须使用 open_image_generator → read_image_generator → update_image_generator → click_generate_image → poll_image_generator，不得直接提交裸图片参数；视频任务立即返回任务号，不要在一次工具调用里等待生成完成（生视频通常需数分钟），用格子工具轮询；
• 创建与提交硬闸：①create_project 前，题材（dramaStyle）与视觉风格（visualStyle）必须先向用户询问、得到明确答复（带平台预设选项问；题材：科幻/现代/古风/悬疑/玄幻/神话/历史/动画片/近现代架空/哥特西幻，视觉风格：超写实/3D动漫/3D国漫仿真/2D动漫/MG卡通/定格动画），用户明确说"随意/你定"才允许走默认「都市现代×超写实」；②model（模型选择）与 resolution（分辨率）必须先向用户询问、得到明确答复后才能 click_generate_image / click_generate_video 提交任务，先 list_models 带着选项去问；③生视频只问模型、分辨率、比例（16:9/9:16/auto）三项，其余按定稿执行不问：音频默认开、条数固定 1、输入模式默认多模态参考、时长按分镜该镜段时间窗自设（list_asset_slots 镜头视频槽位的 segRange/segStartSeconds/segEndSeconds；创作页无分镜依据时才与用户确认）；
• 参考图/参考素材一律使用 kmeng 域链接（upload_asset 返回的 src 或资产库 list_assets 里的地址）；
• 从平台取图/取片到本地（download_file → 写盘）全程静默执行：不逐张、不逐步向用户汇报过程（不发"正在下载…/已保存到…"类消息），做完直接进入最终交付展示；只在下载失败或用户主动询问时才说明过程；
• 生成过程进度可展示：get_task 返回的 progressText 是平台三段式进度字样（正在理解需求 / 正在进行创作 / 即将为您呈现；终态：图片已生成 / 视频已生成 / 生成报错），用户等待或询问进度时可原样转述（仅标题字样，无明细）。
• 看图微调提示词：get_task 返回的图片链接可直接下载后用你的视觉能力评审，再改 prompt 重新提交。
• 下载成品：轮询拿到任务号后，用 get_task_file {kind, taskId} 换出该任务成品的 kmeng URL（图片任务多张全给、视频任务含成片与封面），再把 files[].url 逐个传给 download_file 写盘交付；项目槽位产物也可直接取格子状态里的 current.url。

平台侧安全规则

• kmeng 出口原则：工具返回的一切 URL 只能是 kmeng 域，上游供应商链接一律被改写为占位符；上游报文（错误详情等）一律剥除，失败信息与普通用户看到的通用文案一致；
• 令牌不能访问平台管理面，也不能管理令牌自身；
• 每令牌每分钟限 120 次请求；每日消费上限由用户在生成令牌时设定（0 = 不限），超限提交会被拒绝；
• 用户吊销令牌或重新生成后，旧令牌立即失效（表现为全部请求 401）。

常见故障

—— kmeng 平台 · 本说明随平台版本更新，Agent 应以拉取到的最新页面为准。