Guide · MCP

MCP 接入教程

把 AiArtEngine 接入 Claude Code 等 AI Agent：应用启动后自带一个本地 MCP 工具服务，Agent 可以直接规划工作流、编辑节点图、运行生成、查询任务——对标 LibTV CLI 的「产品即 Agent 工具」体验，但完全本地化，无需云账号授权。应用内置的 AI 对话面板（工作区左侧「◈」）也走这套同一工具面：在聊天里 @ 引用资产，让助手直接调用下列工具干活。

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。

前置条件：AiArtEngine 桌面应用处于运行状态；桥脚本需要 Node.js 18+； workflow_plan 类工具依赖应用里已配置的文本模型。

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

方式 A：stdio 桥（推荐）

启动 AiArtEngine 桌面应用。

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"]
    }
  }
}

重启 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 后团队克隆即用。

单人使用不需要建这个文件：直接执行 claude mcp add aiartengine -- node C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs， Claude Code 会自动写入本机配置（~/.claude.json）。两种方式二选一，无需同时做。

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>"
      }
    }
  }
}

应用侧的连接信息文件（%APPDATA%/aiartengine/mcp.json，结构 { "port": 43110, "token": "…", "pid": …, "version": "…" }）由应用自动写入与删除， 不要手改；token 跨重启复用，要重置删除该文件后重启应用即可。

3. 工具清单

分组	工具	作用
工程与资产	`app_status`	版本、当前工程、资产数量
	`project_list` / `project_open` / `project_create`	最近工程、打开、新建
	`asset_list` / `asset_read_file`	资产列表、按相对路径读取工程内文件
	`asset_write_text`	更新剧本 / 备注等文本资产（界面同步）
`folder_list`	资产库文件夹列表（生成工具 folderId 的来源）
规划与运行	`workflow_list_presets`	12 个行业模板列表（id + 标题）
	`workflow_plan`	自然语言 → 节点图计划（走应用已配置文本模型）
	`workflow_commit`	计划落盘为宿主资产（界面同步出现）
	`task_run` / `task_status`	运行宿主资产工作流、轮询执行状态（应用任务列表同步显示）
	`graph_read`	读取宿主资产图结构（节点 id / 连线，graph_edit 前置）
生成	`generate_image`	文生图 / 图生图，落盘为工程资产
	`generate_video`	提交视频生成并登记资产（可 `video_job_*` 跟踪）
	`generate_model3d`	文生 / 图生 3D，产出 GLB 资产
编辑与查询	`graph_edit`	对宿主资产图应用节点 / 连线编辑操作批（端口兼容性在应用内校验）
	`models_list`	已启用模型提供商与各模态勾选模型（不含密钥）
	`video_job_list` / `video_job_get`	异步视频任务状态

4. 场景示例

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

「列出我的最近工程，打开第一个」→ project_list + project_open
「用 shortDrama 模板规划一条工作流并落盘」→ workflow_plan（presetId=shortDrama）+ workflow_commit
「运行刚才创建的工作流，完成后告诉我结果」→ task_run + task_status 轮询
「给这张图节点下面加一个配音节点并连上」→ graph_edit（node_upsert + edge_connect）
「用已配置的模型生成一张 9:16 的海报」→ models_list + generate_image

5. 配置与环境变量

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

环境变量	作用
`AIAE_MCP_CONFIG`	指定 mcp.json 的绝对路径
`AIAE_MCP_PORT` + `AIAE_MCP_TOKEN`	直连指定端口与 token（优先于配置文件）

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

6. 安全与当前限制

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