如果你以为 MCP 服务器只有"工具调用"这一种玩法，那 Unreal_mcp 会刷新你的认知。Unreal_mcp 是一个功能完整的 Model Context Protocol（MCP）服务器，用 TypeScript + C++ 构建，让 AI 助手通过原生 C++ Automation Bridge 插件直接控制 Unreal Engine 编辑器。除核心的unreal工具外，它还在 stdio 和原生/mcp两条链路上完整实现了 MCP 的三大"原语"：Resources（资源）、Prompts（提示）、Completions（补全），以及长任务的进度通知机制。本文带你一次读懂这些原语在 Unreal_mcp 中是怎么落地、怎么用起来的。

为什么 Tools 还不够？MCP 原语全景

MCP 协议里，tools/call只是"让 AI 动手干活"的通道。但真实的开发工作流还需要三样东西：

• 资源（Resources）：让 AI"看到"编辑器当前状态——项目信息、健康度、当前选中的 Actor；
• 提示（Prompts）：给 AI 一份"操作剧本"，按步骤引导它完成检查工作流；
• 补全（Completions）：帮 AI 精确敲定参数，比如 400 多个 capability 的 id 到底叫什么；
• 进度通知（Progress）：渲染、光照构建这种慢操作，让客户端实时看到百分比，而不是干等。

Unreal_mcp 在initialize握手时向客户端宣告的能力面恰好就是这四样：

{ "tools": {}, "resources": {}, "prompts": {}, "completions": {} }

这个能力声明定义在 primitive-wiring.ts，原生链路的对应实现在plugins/EngineWire/Source/EngineWire/Private/MCP/下。值得注意的是：它没有声明 resource 订阅（subscriptions），也没有 task API——能力面"精确到声明什么就提供什么"，不多不少。

资源（Resources）：给 AI 装上一双"眼睛"

资源是只读的。Unreal_mcp 通过ue://前缀的 URI 暴露编辑器状态，注册逻辑在 resource-handlers.ts。

可用资源一览

最后四个"实时状态" URI 只在游戏线程上才能安全读取：stdio 链路会经 Automation Bridge 往返取数；而原生链路在 socket 线程应答，不能阻塞编辑器工作，所以干脆不服务它们。

三种资源模板：按 id 取数

除静态 URI 外，还有三个模板（定义在 resource-catalog.ts），客户端可以按变量取值：

• ue://capability/{capabilityId}—— 单个 capability 的有界记录（标识、类别、动作数，不含完整 schema）；
• ue://knowledge/{topic}—— 按主题组织的稳定 Unreal 引擎知识；
• ue://asset/{assetPath}—— 某内容路径下资产的规范化句柄。

修订号（Revision）：状态会不会"过期"？

所有资源读取都带 64 KiB 上限、路径归一化与脱敏（见 mcp-primitives.md）。每个载荷还携带一个revision：只有ue://capability/catalog的修订号会变动（跟随configure的可见性变化），其余 URI 恒定上报初始修订号1。实现见 resource-revision.ts。

💡 对新手很实用：读完ue://project确认引擎版本，再读ue://health看桥接是否正常，最后读ue://capability/catalog掌握目录——三步就能让 AI 对现场建立完整认知，全程零副作用。

Prompts：六份内置"操作剧本"

prompts/list和prompts/get提供六个固定工作流提示（prompts.ts，原生侧为McpPromptCatalog）：

以sequence-render为例，它会渲染出五步剧本：读取序列属性 → 创建 MRQ 任务 → 配置输出 → 排队 → 启动渲染，每一步都标注了对应的describe/execute调用和一条安全提示（"渲染是长任务且会写文件，由你显式启动"）。

三条值得记住的设计原则：

1. 只返回文本消息——获取一个 prompt 永远不会执行任何操作，执行决定权始终在 AI（和人类）手里；
2. 严格参数校验——未知参数、缺失必填项、超过 512 字符的值都会被InvalidParams拒绝；
3. 自带免责声明——每个提示的末尾都写着："以上任何内容都不会替你执行，每一步请自己跑并复核回执"。

Completions：参数补全的四档评分与三重保险

面对 400 多个 capability，AI 拼错一个 id 就会全盘卡壳。completion/complete就为此而生，实现见 completions.ts。

它只覆盖三个封闭词表：

• ue://capability/{capabilityId}的capabilityId（含别名与旧式tool.action名，仅限已启用的工具）；
• ue://knowledge/{topic}的topic；
• ue://asset/{assetPath}的assetPath（内容根路径）；
• 以及工作流 prompt 中枚举型参数的取值（如sourceFormat的fbx/obj/gltf/png/wav）。

匹配按四档评分排序：前缀 > 子串 > 子序列 > 允许一个拼写错误（typo 匹配只在没有更好结果时才出场）。

三重保险让输出永远有界且安全：

所有候选池都在内存中，补全过程不扫描编辑器、也不碰宿主机文件系统。

进度通知：给渲染和光照构建装上"进度条"

渲染视频、构建光照动辄几分钟。MCP 的做法是：客户端在tools/call里带上_meta.progressToken，服务器就会为该请求推送notifications/progress通知，数据源正是 Unreal 自身的进度事件。Unreal_mcp 的这套实现（progress-reporter.ts、progress-sink-registry.ts）有几处教科书级的细节：

• token 只读、绝不代写：progress-token.ts 原样读取客户端的 token（字符串'42'和数字42严格区分）。没发 token？那就没有进度——服务器宁可沉默，也不会自己编一个 id 顶替，否则客户端根本关联不上；
• 单调递增：progress严格只增，Unreal 重复上报或倒退的数值会被过滤，客户端的进度条永不倒转；
• 有界防洪：每个操作最多 64 条通知，状态文本截断到 512 字符，病态的"话痨"源头无法刷爆 JSON-RPC 通道；
• 串行投递：通知按内部 Promise 链排队，保证客户端收到的顺序和上报顺序一致，不会出现"先看到 80% 再看到 50%"；
• 精准路由：ProgressSinkRegistry 用规范化 MCP 请求 id 做键，把每个请求的进度（和它的 token）严格隔离，并发请求互不串线；表容量上限 256，超限按最旧优先淘汰；
• 收尾干净：结果返回前或请求取消时，流即刻关闭，晚到的帧永远不会拖在最终结果后面。

总结：四原语如何协同成一个完整闭环

把四个原语串起来，就是 Unreal_mcp 推荐的"看 → 定 → 做 → 盯"工作流：

1. 看（Resources）：读ue://project/ue://health/ue://capability/catalog建立现场认知；
2. 定（Completions + Prompts）：用补全敲定 capability id，或取一份 prompt 拿到分步剧本；
3. 做（Tools）：通过唯一的unreal工具execute一个 capability，拿到数据与回执；
4. 盯（Progress）：长操作携带_meta.progressToken，实时接收有界、单调、按序的notifications/progress。

全部实现集中在 src/server/mcp-primitives/ 目录，原生 C++ 侧在plugins/EngineWire/Source/EngineWire/Private/MCP/Primitives/与Private/MCP/Resources/，两条链路的协议行为详见 protocol.md。理解了这一层"超越 Tools"的原语，你才算真正用完了 Unreal_mcp 给 AI 助手准备的全部能力。