MCP 接入教程

1. MCP 是什么

MCP（Model Context Protocol）是 AI Agent 调用外部工具的标准协议。接入后，你的编码 Agent 多了一组「AiArtEngine 工具」，对话即可驱动应用：

Claude Code / Codex ──stdio(MCP)──▶ mcp-bridge.mjs ──HTTP──▶ AiArtEngine 应用（127.0.0.1 工具服务）

• 应用每次启动会在 127.0.0.1 起一个带 Bearer token 的本地工具服务，连接信息写入 %APPDATA%/aiartengine/mcp.json（macOS / Linux 路径见下文）。文件跨重启保留，token 稳定不变，客户端配置一次即可；也可在应用「设置 → MCP 接入」中编辑 Token。
• 桥脚本 scripts/mcp-bridge.mjs 零依赖，由 Agent 客户端拉起，负责协议转换与转发。
• 通信仅限本机回环地址；除健康检查外全部需要 token。

2. 三步接入 Claude Code（两种方式任选其一）

方式 A：stdio 桥（推荐）

1. 启动 AiArtEngine 桌面应用。
2. 注册 MCP server（桥脚本在仓库内，把路径换成你的实际仓库位置）：

   claude mcp add aiartengine -- node C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs

   或手动写入 MCP 配置文件：

   {
     "mcpServers": {
       "aiartengine": {
         "command": "node",
         "args": ["C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs"]
       }
     }
   }

3. 重启 Agent 会话，工具即可使用。其他支持 MCP 的客户端（Codex、Trae 等）按同样的「command + args」方式配置。

方式 B：HTTP 直连（无需 Node.js）

支持 streamable HTTP 的客户端可跳过桥脚本，token 取自 mcp.json（持久复用）：

claude mcp add --transport http aiartengine http://127.0.0.1:43110/mcp --header "Authorization: Bearer <token>"

配置模板（.mcp.json）

.mcp.json 是可选文件，需要你手动创建（没有程序会自动生成）—— 新建一个名为 .mcp.json 的文本文件填入下面的内容，放在你运行 Claude Code 的项目根目录， 提交进 git 后团队克隆即用。

stdio 桥版（路径换成实际仓库位置）：

{
  "mcpServers": {
    "aiartengine": {
      "command": "node",
      "args": ["C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs"],
      "env": {
        "AIAE_MCP_CONFIG": "C:/Users/<你>/AppData/Roaming/aiartengine/mcp.json"
      }
    }
  }
}

HTTP 直连版（无需 Node.js，token 取自应用侧 mcp.json）：

{
  "mcpServers": {
    "aiartengine": {
      "type": "http",
      "url": "http://127.0.0.1:43110/mcp",
      "headers": {
        "Authorization": "Bearer <应用侧 mcp.json 里的 token>"
      }
    }
  }
}

3. 工具清单

4. 场景示例

接入后直接用自然语言下指令，Agent 会自动组合工具：

• 「列出我的最近工程，打开第一个」→ project_list + project_open
• 「用 shortDrama 模板规划一条工作流并落盘」→ workflow_plan（presetId=shortDrama）+ workflow_commit
• 「运行刚才创建的工作流，完成后告诉我结果」→ task_run + task_status 轮询
• 「给这张图节点下面加一个配音节点并连上」→ graph_edit（node_upsert + edge_connect）
• 「这张图还能加哪些节点？图标包打包用哪个类型？」→ graph_node_types（typeId + 端口 + 默认参数）
• 「图标包第 3 枚的剑画糊了，重画这一枚」→ graph_icon_refine（cellKey + hint，自动写回并重跑打包）
• 「用已配置的模型生成一张 9:16 的海报」→ models_list + generate_image
• 「做个低多边形太空站捡能量块的 3D 小游戏，WASD 移动」→ gameplay_prepare_project（3d）→ 写 src/assets/** 与 src/game/** → gameplay_build + gameplay_job_status 轮询到 done，对话卡点「试玩」即在浏览器里开玩

5. 配置与环境变量

桥默认读取 %APPDATA%/aiartengine/mcp.json（macOS： ~/Library/Application Support/aiartengine/；Linux： ~/.config/aiartengine/）。需要覆盖时：

应用会依次尝试端口 43110–43119，被占用自动顺延，实际端口以 mcp.json 为准。

5.1 stdio 桥可视化设置

设置页 → MCP 工具服务 → stdio 桥 Tab 可视化配置桥脚本 （无需手写环境变量）。当前可设：桥命令（默认仍是 node + 仓库内 scripts/mcp-bridge.mjs 或安装包内置 <安装目录>/resources/mcp-bridge.mjs）、桥端口 （桥 HTTP 监听端口，默认同上）、Blender addon 的 BLENDER_HOST / BLENDER_PORT 透传。改完即时落盘，外部 Agent 重连即生效，不需要重启应用。

5.2 反向桥：让 dsh（应用内对话面板）直连 stdio MCP server

「正向桥」是把 Claude Code 等外部 Agent 通过 stdio 桥 / HTTP 连进来；反向桥反过来 —— 应用内 ◈ AI 对话面板（DeepSeek Harness / dsh）也能注册并消费 任意外部 stdio MCP server（不再局限于连回应用自己的 /mcp）。

典型场景：Blender addon 等只暴露 stdio 协议的 MCP server，不再需要先开 socket 端口；dsh 注册一条 claude mcp add --transport stdio ... 之类的命令后，AI 对话里说 「在 Blender 里把…做完截张图」即可直接驱动。配置入口在设置面板 MCP 工具服务 → stdio 桥 Tab 同一区域，可加多组外部 stdio server （每组：名称 / 启动命令 / 工作目录 / 环境变量），与 Blender stdio 桥共用一份配置存储。

协议层细节：

• 反向桥在 dsh 进程内 fork stdio 子进程、转 MCP 帧、复用既有 mcp-client 实例 —— 不再 单独起桥进程
• 协议错误 / 子进程崩溃与正向桥共用同一套日志（<userData>/logs/mcp-audit.jsonl）
• 仅限本机 + token 鉴权；外部 stdio server 不会自动获得应用侧 /mcp 的写权限
• Ask / Plan 模式对反向桥的工具同样只读 —— 它不是绕过面板模式的侧门

6. 安全与当前限制

• 服务只监听 127.0.0.1，token 鉴权；文件读写被限制在工程根目录内（唯一例外是 asset_import：按你给出的绝对路径读取工程外文件并复制进工程）；密钥信息不对外暴露。
• 并发闸门：generate_image / generate_speech / decide / workflow_plan 同时最多 3 个（AIAE_MCP_GEN_LIMIT 可调），排队满直接报错，防止 Agent 失控消耗额度。
• 操作审计：每次工具调用追加写 <userData>/logs/mcp-audit.jsonl（参数截断、5MB 滚动），生成与写入可回查。
• graph_edit / graph_icon_refine 对正在编辑器中打开的图会拒绝修改，避免与编辑器内存态互相覆盖。
• workflow_plan 走 LLM，耗时可能数十秒；generate_video / generate_model3d 为异步任务，用 video_job_* 跟踪。
• 接入方式两选一：stdio 桥（安装包内置在 <安装目录>/resources/mcp-bridge.mjs；开发场景用仓库内 scripts/mcp-bridge.mjs，需 Node.js 18+）或 HTTP 直连（无需 Node.js）。

7. Blender 工具集（进阶）

这一组工具不在 /mcp 主工具集里，而是挂在同一服务的另一个端点 /mcp/blender（「设置 → MCP → Blender 工具集」默认开启；关掉后该端点直接回 403，主工具集不受影响）。

让 AI 直接操作本机 Blender —— 搭场景、写 bpy 建模、截图自查画面、导出 GLB / GLTF / FBX 出库。出站直连 addon，不需要装 uv、不起 Python 子进程、不改 Blender 配置：应用主动连 addon 的 localhost:9876。

前置条件

• Blender 正在运行，且已启用 MCP addon（设置面板里选择对应 addon 类型，两种线协议互不兼容，选错表现为「连接超时」或「连接已重置」）：
  • 社区方案（默认）：blender-mcp 项目的 addon.py，在 Blender 的 Edit → Preferences → Add-ons 安装启用
  • 官方方案：Blender 扩展平台上的 Blender Lab「MCP Server」 官方扩展，安装后在扩展偏好里启动服务
• 两种 addon 默认端口都是 9876；改过端口就在设置面板里同步填上
• 外部 Agent 想拿到这组工具，需要再注册一个 MCP server（<token> 取自应用侧 mcp.json）：

  claude mcp add --transport http blender http://127.0.0.1:43110/mcp/blender --header "Authorization: Bearer <token>"

  应用内的 ◈ AI 对话面板自动带上（内部为 dsh 注册第二个 mcp-client 实例），你在对话里说「用 Blender……」即可。

工具清单

工具名称、入参与输出在两种 addon 下完全一致，模型侧无感：

典型闭环

get_scene_info            看清现状
   ↓
execute_blender_code      写 bpy 建模 / 调材质 / 摆相机
   ↓
get_viewport_screenshot   截图自查（多模态客户端直接看到画面）
   ↓
export_scene              出 GLB / GLTF / FBX …
   ↓
asset_import              一键入资产库

安全护栏

• execute_blender_code 不再做词法护栏：脚本可使用完整 Python / bpy（含 class / lambda / open 等）。写入兜底是 §6 的模式约束 —— Ask / Plan 下整组只读，写入调用被拒。
• 截图走一次性临时文件：get_viewport_screenshot 让 Blender 写到系统临时目录的一次性文件，应用读回后立即删除；画面只随 MCP 响应回给多模态客户端，不落工程、不进审计日志。
• 模式绑定请求，不绑定客户端：Blender 端点与主工具集共用 token，Ask / Plan 通过 X-AIArt-Mode / X-AIArt-Run-Id 下发 —— Ask 整组不返回、Plan 只返回只读工具（get_scene_info  / get_world_state_snapshot / get_object_info / get_viewport_screenshot / describe_node_type / bpy_api_lookup / get_addon_status），execute_blender_code 与 export_scene 属 write 被拒并记审计。
• addon 是 socket 服务端：Blender 一关，这组工具全部失败（错误明确说「连不上 addon」）；应用不负责启动 Blender，也没有无界面模式 —— get_viewport_screenshot 对窗口可见性有要求（最小化时抓不到画面）。连接状态在设置面板里每 4 秒刷新一次，get_addon_status 可随时查版本。