unreal-mcp

Unreal MCP

你已通过 unreal-mcp MCP 服务接入正在运行的 Unreal Editor。该服务通过 Unreal 的 ToolsetRegistry 注册了 30 多个工具集中的数百种工具，涵盖演员、蓝图、材质、Niagara、Sequencer、Control Rigs、GAS、自动化测试、Live Coding 等。请使用这些工具检查和修改编辑器中的实时状态，而不是让用户手动操作。

你无需记住工具名称。按照以下流程按需发现工具。

如果安装了引擎的可选代理，连接名称可能显示为 unreal-mcp-proxy。请使用该连接调用 Unreal 工具。代理保留 Unreal 的原生工具定义，不会引入替代性的发现或分发工具。安装说明见 references/setup.md。

每次开始时的第一步：先发现所需工具，再通过 call_tool 分发

默认启用工具搜索，因此在整个会话中，MCP 服务只会公布三个元工具：list_toolsets、describe_toolset 和 call_tool。诸如 BlueprintTools.create 或 SequencerTools.create_level_sequence 这样的工具名称不会出现在 tools/list 中。它们会通过 call_tool 在服务端分发，且绝不会注册为原生 MCP 工具。这是有意设计的，可缩小上下文窗口并保持提示词缓存有效。

开始工作时：

1. 调用 list_toolsets 查看已注册的工具集，然后对候选工具集调用 describe_toolset，以查看其工具架构。如果你已知道所需工具集（用户说“创建一个蓝图”→ Blueprint 工具集），可以跳过列表查询，直接调用 describe_toolset，确认可用工具及其签名。
2. 使用 call_tool 调用工具：传入 toolset_name、tool_name，以及符合刚刚读取的架构的 arguments 对象。结果会在同一轮返回，无需额外往返。
3. 顶层分发（省略 toolset_name）仅适用于直接注册在 MCP 服务上的工具；对 call_tool 本身这样做会被拒绝。

缺少工具并不能证明编辑器已停止运行。请检查配置的 unreal-mcp 或 unreal-mcp-proxy 连接，并按照 references/operations.md 操作。代理可能在 Unreal 不可用时仍保持连接，客户端也可能在恢复后保留过期的目录。unreal_mcp_status 报告的是代理的会话状态，而非当前是否可连接。请使用只读 Unreal 工具调用验证是否已恢复。首次配置请参阅 references/setup.md。

安全规则

遵循以下规则，保护编辑器中的实时状态。

• 先保存，再保存一次。 在进行任何批量更改之前，提醒用户保存项目（或调用 AssetTools 保存 API），并在更改后再次保存。MCP 编辑不一定总能撤销，尤其是在跨越编译边界时。将任何涉及多个资产的操作视为需要设置恢复点的破坏性操作。
• 等待编译完成。 如果 C++ 或着色器正在编译，你的工具调用会挂起，或以难以理解的方式失败。要从正在运行的编辑器重建 C++，请驱动 LiveCodingToolset.CompileLiveCoding 并等待其结果，而不是要求用户切换到 IDE。该工具会阻塞，直到编译实际完成，并提供 MSVC 诊断信息。
• 控制并发调用。 MCP 接受并发请求，并处理分发同步。异步工具可能会重叠执行，请求顺序不保证执行或完成顺序。对存在依赖关系的调用，以及可能影响同一资产或编辑器状态的修改操作，务必串行执行。只有在工具支持安全并行时，才并行处理互不相关的工作。多个 Agent 可以共用一个编辑器，但相互冲突的更改可能造成不良影响。
• 始终检查结果。 蓝图编译、创建控件、编辑材质：许多工具会返回状态，状态可能在成功与失败之间切换，且不会在线路上抛出异常。继续操作前请先读取响应。任何未明确显示成功的结果都应视为停止信号。
• 注意 PIE。 编辑器专用工具（尤其是资产创建工具）在“在编辑器中运行”（PIE）处于活动状态时表现会有所不同。如果结果看起来不对，请检查 PIE 是否正在运行；如果是，请停止它。

项目技能

项目或插件可以注册 Agent Skills：这些是带名称的说明合集，包含 Agent 原本可能不了解的工作流知识（例如项目的命名约定、文件夹布局、必要的设置步骤，或多步骤任务的标准操作顺序）。这些说明与工具集相互独立，可通过 Agent 技能工具集（AgentSkillToolset）获取，而不是通过 list_toolsets 获取。

请像发现工具那样查找技能，并且每当开始在项目中处理不熟悉的工作时都要查找，而不是只查一次：

1. 调用 AgentSkillToolset.ListSkills（通过 call_tool）查看项目注册了哪些技能。每个条目都包含简短说明，介绍其涵盖内容和适用时机。
2. 如果某项技能的说明与用户的请求相关，请调用对应技能的 AgentSkillToolset.GetSkills 加载完整说明，并遵循其中的指示。
3. 如果没有匹配的技能，请回退到上述工具发现流程。

相关项目技能中的说明优先于你的通用默认设置：它之所以存在，正是因为项目的做事方式不同于显而易见的做法。（创建或编辑这些技能属于下方 unreal-skill 配套技能的任务。）

参考文件

• references/setup.md：首次设置 MCP 服务、配置客户端以及可选的代理安装。
• references/operations.md：控制台命令、设置、代理恢复，以及工具缺失或调用失败时的故障排查。

配套技能

• create-toolset：在编写新工具集或为现有工具集添加工具时使用。涵盖设计原则、C++ 和 Python 约定、注册、错误处理与测试。
• unreal-skill：在创建、更新或审查 Agent Skill 时使用。涵盖优秀技能的特点及其结构方式。