企业官网建设流程全解析

• 桌面应用
• 图形学
• 3D渲染
• 计算机视觉

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。

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

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

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

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

输出即完整任务对象，包含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：有界日志读取 + 游标分页

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

实现保证（见 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 轮询循环，应用必须保持运行（退出/崩溃后不保证执行继续）。

常见错误码速查

写在最后

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

• 桌面应用
• 图形学
• 3D渲染
• 计算机视觉