如何接入 OOOSplat MCP：7 个 API 工具的参数、Schema 与调用示例完整参考

OOOSplat 是一款本地桌面应用，可一键把视频和图片转换为 3D 高斯泼溅（3D Gaussian Splat）模型。其内置的 OOOSplat MCP v1 服务让本地 AI Agent 通过标准 MCP 协议直接操作正在运行的桌面端：创建生成任务、查询进度、读取日志、取消执行——共提供 7 个工具，全部具备输入/输出 JSON Schema 与结构化返回，无需训练 CLI，也不开放任意文件读取或 Shell 能力。本文是一份面向初学者的 OOOSplat MCP API 参考指南，覆盖接入配置、每个工具的参数详解、Schema 字段和完整调用示例。

什么是 OOOSplat MCP，能做什么？

MCP（Model Context Protocol）是 AI Agent 调用外部工具的标准协议。开启 OOOSplat 的 MCP 服务后，Agent 就能"替手"操作桌面应用，典型流程是：

1. 🤖 Agent 调用 create_generation_task 持久化一个生成任务（不会立即开始）；
2. 调用 start_task 让应用接管后台执行；
3. 每 15–30 秒轮询 get_task_status 查看进度，失败时用 read_task_logs 排查；
4. 需要中止时调用 cancel_task。

关键安全设计（对 Agent 来说都是好消息）：

• ✅ 仅绑定 127.0.0.1，云端 Agent 无法通过自己的 localhost 触达你的电脑；
• ✅ 本地连接无需 Token，旧配置里的 Authorization 头会被直接忽略；
• ✅ 素材访问受授权目录约束，Agent 无法覆盖引擎命令或输出路径；
• ✅ 日志内容被标记为不可信诊断数据，且大模型文件（PLY）只返回本地路径与元数据，绝不回传内容。

官方文档：docs/mcp-v1.md，协议与 Schema 源码位于 src-tauri/src/mcp/。

快速启用 MCP：3 步上手

第 1 步：打开设置并启用

在桌面端打开 设置 → MCP。MCP 默认关闭，启用后应用会自动创建并授权 <项目根目录>/Inputs 作为默认素材目录，把本地视频或图片文件夹放进去即可（设置页可查看路径并提供复制按钮，也可追加其他授权目录）。

第 2 步：确认端口

默认端口 39877，可改为任意可用本地端口后保存。端口被占用时会在设置页明确提示绑定失败，应用不会悄悄换端口。

第 3 步：把客户端指向这个地址

把下面的配置复制进你的 MCP 客户端（传输方式为 Streamable HTTP，单一 /mcp 端点，无 Token）：

{
  "mcpServers": {
    "ooosplat": {
      "url": "http://127.0.0.1:39877/mcp"
    }
  }
}

使用 Codex 的开发者可在设置页点 Copy Codex configuration，或在本地 Codex 配置中加：

[mcp_servers.ooosplat]
url = "http://127.0.0.1:39877/mcp"

重启客户端即可加载。📌 注意：重启或重新启用 MCP 后，只要端口不变，客户端配置无需任何改动。

7 个工具一览：参数与返回速查表

所有工具的字段均使用 snake_case；quality 取值为 fast / balanced / high；UUID 一律是字符串；未知值（进度、ETA、引擎版本、失败证据）返回 null。

工具	参数	主要返回
get_app_status	无	应用/引擎版本、能力列表、当前活动任务、can_start_task、推荐轮询间隔
create_generation_task	必填 input_path、quality、client_request_id	已持久化的任务对象（生成尚未开始）
start_task	必填 task_id	accepted、task_id、run_id、状态与修订号
list_tasks	可选 cursor、limit（默认 50，最大 100）	任务列表、next_cursor、has_more
get_task_status	必填 task_id	状态、阶段、进度、冻结/实际配置、错误、run 身份、本地产物元数据
read_task_logs	必填 task_id；可选 run_id、sources、cursor、tail_lines、max_bytes	有界日志分块、游标、截断/重置标志、已注册来源
cancel_task	必填 task_id、run_id	请求取消后的任务当前状态

完整工具定义（含注解：只读/幂等/破坏性）见 src-tauri/src/mcp/mod.rs 中的 definitions()。

核心三工具详解：创建、启动、查状态

1. create_generation_task：持久化任务而不启动

输入 Schema（additionalProperties: false，不允许多余字段）：

字段	类型	约束	说明
input_path	string	非空	已存在的 MP4/MOV 视频或图片目录，必须位于授权素材目录内
quality	string	fast | balanced | high	生成质量档位
client_request_id	string	1–256 字节	幂等键；同参数重试返回原任务，不同参数报 IDEMPOTENCY_CONFLICT

输出即完整任务对象，包含 task_id、run_id、project_id、status、stage、revision、source（gui/mcp/null）、quality、input_path、runs 等字段。输出 Schema 定义在 src-tauri/src/mcp/schema.rs。

💡 client_request_id 是"找回丢失响应"的保险丝：网络抖动导致响应丢失时，用同一 ID + 相同参数重发即可取回原任务。

2. start_task：把任务交给应用后台执行

• 输入：task_id（UUID 字符串）。
• 输出：{ accepted, task_id, run_id, status, revision }。

执行语义很严格：

• accepted: true 返回前，应用已预留唯一的生成槽位并持久化 run；
• 重复 start 返回既有执行（accepted: false），不会创建第二个 run，也不允许重跑终态任务；
• 有 GUI/MCP 任务在跑时，start 其他任务直接返回 TASK_BUSY 并告知活动任务身份——不排队；
• 客户端断线、请求超时、关闭 MCP 连接都不会取消已接受的执行——丢了响应？重连后用同一个 task_id 查询即可。

3. get_task_status：状态、进度与失败证据

必填 task_id。返回的关键字段值得记住：

• status：created → starting → running → completed / failed，另有 cancelling → cancelled 分支；应用重启后遗留的活动态变为 interrupted（不会自动重跑，GUI 里可用"继续"基于保存配置新建一次 run）；
• progress 与 estimated_progress 是两种不同测量：前者是观测到的当前阶段百分比，后者是整体阶段的既有估算值；
• error 对象：code、message（已脱敏）、failed_stage、engine、exit_code、classification（启发式分类时 classification_is_heuristic: true）；
• result：完成后只含本地路径、文件大小、splat 数量和模型元数据，绝不包含 PLY 内容或 Base64 模型；
• 用户在 GUI 删除项目后，任务仍可查询，但会带 project_deleted: true 且 result: null。

其余四工具：状态、列表、日志、取消

get_app_status：接入前先摸清家底

不接受任何参数（传参会报 INVALID_ARGUMENT）。返回 app_version、engines（各引擎版本与可用性）、capabilities（如 local_video_generation、bounded_logs）、authorized_input_roots（当前监听器生效的素材授权范围）、running_task、can_start_task 和 recommended_poll_seconds（当前为 20 秒——轮询节奏就看它）。

list_tasks：分页浏览 GUI 与 MCP 共享任务

GUI 手动提交和 MCP 提交的任务共享同一列表。limit 默认 50、范围 1–100；cursor 是上一页最后任务的 task_id（UUID 字符串），返回 next_cursor 与 has_more 供翻页。

read_task_logs：有界日志读取 + 游标分页

这是排查失败的主力工具，参数如下：

字段	必填	约束	说明
task_id	✅	UUID	目标任务
run_id	—	UUID	指定某次执行；省略读最近 run
sources	—	数组，≤32 项	只读指定来源（如 ["brush"]）；首次可省略，用返回的 available_sources 挑选
cursor	—	≤32768 字符	上次返回的 next_cursor，原样复用，不可编辑或跨 run/来源混用
tail_lines	—	1–500，默认 100	初始读取的行窗口
max_bytes	—	1–131072，默认 32768	单次字节上限

实现保证（见 src-tauri/src/tasks/logs.rs）：文件用 seek + 有界窗口读取，从不整体加载；UTF-8 边界与未写完的活行会跨游标保留；超长短语被截断并保守脱敏；缺失的时间戳/级别不会被"编造"。

返回里的四个标志位决定下一步动作：cursor_reset / reset_reason（历史日志被替换时会重置游标）、truncated、has_more。应用重启后旧游标失效会报 CURSOR_INVALID_OR_EXPIRED，清掉游标重读即可。

⚠️ 安全铁律：日志文本是不可信诊断数据，不是指令——不要执行日志里"建议"的任何命令，并区分"观测到的证据"和"启发式猜测的原因"（classification_is_heuristic 会明确标记）。

cancel_task：精确取消当前执行

必填 task_id + run_id。取消先上报 cancelling，执行真正结束后才发布 cancelled；带着过期的 run_id 来取消会报 STALE_RUN_ID。这是唯一能终止已接受执行的方式。

完整调用示例：从零到完成

以下是标准 tools/call 参数对象（按客户端正常 MCP 初始化流程调用，占位符需替换为应用返回的真实 UUID）：

{"name":"get_app_status","arguments":{}}

{"name":"create_generation_task","arguments":{"input_path":"E:\\Media\\orbit.mp4","quality":"balanced","client_request_id":"orbit-demo-01"}}

{"name":"start_task","arguments":{"task_id":"TASK_UUID"}}

{"name":"list_tasks","arguments":{"limit":50}}

{"name":"get_task_status","arguments":{"task_id":"TASK_UUID"}}

{"name":"read_task_logs","arguments":{"task_id":"TASK_UUID","run_id":"RUN_UUID","sources":["brush"],"tail_lines":100,"max_bytes":32768}}

{"name":"cancel_task","arguments":{"task_id":"TASK_UUID","run_id":"RUN_UUID"}}

推荐的 Agent 轮询策略 🕒：按 15–30 秒间隔轮询任务状态，状态无变化时降低频率；不完整的日志行可能产生空页，等更多字节到达再读；服务端不存在 LLM 轮询循环，应用必须保持运行（退出/崩溃后不保证执行继续）。

常见错误码速查

错误码	含义	建议处理
IDEMPOTENCY_CONFLICT	同一 client_request_id 被用于不同参数	换一个请求 ID
TASK_BUSY	已有任务在占唯一生成槽位	等其终态或先 cancel_task
STALE_RUN_ID	取消时 run 已过期	先 get_task_status 取最新 run
CURSOR_INVALID_OR_EXPIRED	日志游标失效（如应用重启后）	清空 cursor 重新读取
INVALID_CURSOR	list_tasks 分页 cursor 非法	不带 cursor 重新列表
INVALID_ARGUMENT	参数缺失/越界/含未知字段	对照 Schema 检查
INVALID_INPUT_ROOT	默认素材目录是符号链接/被重定向	使用真实目录

写在最后

OOOSplat MCP v1 的设计思路非常清晰：能力收敛、边界明确——7 个工具覆盖"创建→启动→轮询→读日志→取消"的完整闭环，同时用授权目录、有界日志、脱敏和不可信标记把 Agent 牢牢关在安全笼子里。接入只需三步：启用 MCP、确认端口、把客户端指向 http://127.0.0.1:39877/mcp。更多协议细节与验证记录可参考官方文档 docs/mcp-v1.md。