Loomle MCP for Unreal

Loomle

Loomle 是面向 Agent 的 Unreal Engine 集成，通过 SAL（结构化 Agent 语言）读取和更改复杂的编辑器对象。

SAL 将 Blueprint 图表、Widget 树、Class 反射、Assets 和其他非文本 UE 状态转换为简洁有序的文本，供人和 Agent 阅读、复制、讨论和修补。它忠实于 UE：原生路径、类型、字段名称、值、调色板操作、编译器诊断和编辑器语义都保持原生，不会被并行的 JSON 模型取代。

为什么选择 Loomle

文本代码已能为 Agent 提供精确的搜索、引用、差异比较和编辑能力，而 Unreal 资产做不到。Loomle 补足了这一缺失的文本工作流，同时仍以编辑器和 UE API 为事实来源。

• 简洁的 SAL 对象文本比大型通用 JSON 负载占用更少的 Token。
• 查询从摘要和局部视图开始，而不是下载整个图表。
• 相对于目标的稳定身份路径，让返回的 Nodes、Pins、Graphs、Widgets 和 Blueprint 对象可以安全地用于后续操作，无需命名空间区分类型。
• 调色板和动态架构发现功能让 Agent 能使用 UE 实际提供的能力，而非猜测构造函数或字段。
• 在应用任何变更之前，试运行会走与实际操作相同的解析、解析引用、验证和规划路径。
• 原生编译器和对象健康诊断会与其描述的对象相邻显示。

当前的 0.7 接口

独立客户端提供八个 MCP 工具：

• status：检查客户端版本、更新可用性，以及已绑定会话和 Bridge 的健康状态。
• project：检查项目可用性，并将此 MCP 会话绑定到一个 Unreal 项目。
• sal_query：执行一段自包含的 SAL 查询文本。
• sal_patch：执行一段有序的 SAL 补丁文本。
• sal_schema：发现常驻的 SAL 指南和当前启用的接口卡。
• agent_skill：发现并加载由 MCP 管理的 Loomle 工作流技能，无需单独进行特定 Agent 的安装。
• editor：使用空参数观察当前 Unreal 交互，或根据规范的 SAL 目标文本打开、聚焦和关闭指定的 Blueprint 或 Graph。
• python：仅在结构化 Loomle 接口未覆盖所需能力时，作为后备方式运行不受限制的 Unreal Editor Python；仅当初始结果提供了延续信息时，才轮询执行状态。

当前公开的 SAL 模块包括 Asset、Blueprint、Class、Graph、StateTree 和 Widget。它们涵盖 Asset Registry 发现、Blueprint 声明和组件、Class 反射和默认值、图表局部流程和变更、StateTree 层级结构和绑定、Widget 树、事实引用查询、编译、保存和编辑器上下文。

示例：

door = target {
  domain: blueprint,
  asset: "/Game/Blueprints/BP_Door.BP_Door"
}

query door
summary

使用 sal_schema({}) 获取当前启用的模块索引，使用 sal_schema({ module: "graph" }) 获取一张指定的接口卡。支持的精确读取和调色板条目可通过 with schema 提供动态发现；每张接口卡都会说明哪些确切主题支持该功能。

安装

最新的稳定版 Loomle 可从 GitHub Releases 获取，适用于 Unreal Engine 5.7 和 5.8。请选择与已安装的 引擎版本匹配的程序包：

程序包	内容
loomle-bridge-ue5.7.zip	完整的 UE 5.7 插件，适用于 Mac Apple Silicon 和 Windows x64
loomle-bridge-ue5.8.zip	完整的 UE 5.8 插件，适用于 Mac Apple Silicon 和 Windows x64

这些稳定文件名始终指向最新的正式 GitHub Release。 该 Release 还保留了两个归档文件不可变的带版本副本。

Fab 列表 提供当前已通过市场审核的 Loomle 版本。在 Fab 更新审核期间，GitHub Releases 上的版本可能更新。

完整归档包含两个原生目标及其对应的客户端：

LoomleBridge/
  Source/
  Resources/
    Loomle/
      <platform-arch>/
        loomle(.exe)

Resources/Loomle 下的可执行文件是独立的 SAL 客户端。它 不需要单独安装 Python、uv、Node.js、全局 Loomle 或 项目本地客户端。

从 0.6 升级前，请关闭 Unreal Editor，并移除或移动旧的 <Project>/Plugins/LoomleBridge 目录。同名的项目插件优先级高于新的引擎插件， 因此会继续加载 0.6。

解压完整归档，然后将 LoomleBridge 目录复制到：

<UE_5.7-or-5.8>/Engine/Plugins/Marketplace/LoomleBridge

启用 LoomleBridge，重启 Unreal Editor，并配置名为 loomle 的 MCP 服务，以参数 mcp 启动捆绑的客户端：

macOS:   LoomleBridge/Resources/Loomle/darwin-arm64/loomle
Windows: LoomleBridge/Resources/Loomle/win32-x64/loomle.exe

完整说明：https://loomle.ai/install.html

快速入门

1. 打开已启用 LoomleBridge 的 Unreal 项目。
2. 配置 Loomle 后，重启 Codex、Claude 或相关 MCP 主机。
3. 调用 status 一次，检查客户端、更新、会话和 Bridge 的健康状态。
4. 如果会话尚未绑定，请调用 project 检查或绑定目标项目。
5. 调用 editor({})，从用户当前的编辑器状态开始；使用 editor({ operation: "open" | "close", target }) 精确控制 Blueprint 或 Graph 的显示。
6. 如果不熟悉目标模块或具体操作，请使用 sal_schema。
7. 使用 sal_query 检查，通过 sal_patch 试运行更改，然后通过所属资产应用并 完成操作。

请参阅 https://loomle.ai/quickstart.html，了解完整的首次查询和补丁示例。

架构

Agent / MCP host
  -> bundled Loomle Client (stdio MCP + SAL)
  -> local runtime record
  -> LoomleBridge inside Unreal Editor
  -> UE 5.7 or 5.8 editor APIs and object model

客户端通过 ~/.loomle/state/runtimes 发现在线的 Bridge 实例。此目录用于运行时发现， 并非全局安装目录。每个 MCP 会话都会保留一个固定的项目绑定，并通过简短的实时健康探测 验证该项目当前的 Editor。如果绑定的项目处于离线状态，Loomle 会报告该状态，绝不会转而连接 其他在线项目。需要时，请使用 project({}) 检查候选项目，并明确绑定或切换。

开发

此仓库目前包含四个产品边界：

• sal/：语言解析器、规范化模型、架构和 TypeScript SDK。
• interfaces/：常驻指南和静态 UE 接口卡片。
• client/：独立的 MCP 客户端。
• engine/LoomleBridge/：Unreal Editor 插件。

安装工作区依赖并运行 TypeScript 测试套件：

npm install
npm test

为当前支持的运行器构建并测试原生客户端：

npm run build:executable
npm run test:executable

针对与原生测试使用相同提交编译的开发插件，运行完整的 Loomle UE Automation 类别：

npm run test:ue-automation -- \
  --ue-root <UE-root> \
  --project-template tests/fixtures/ue/LoomleTestHost \
  --plugin-dir <compiled-same-commit-test-plugin> \
  --output-dir <new-artifact-directory> \
  --target darwin-arm64

输出目录必须尚不存在。原始插件源代码不能作为可运行的候选版本。最终 Release 归档会有意排除原生测试代码，因此不能作为完整的 Automation 候选版本。

针对确切审核过的 Release 归档及其捆绑的客户端，运行小型的客户端到 UE 工作流：

npm run test:packaged-e2e -- \
  --ue-root <UE-root> \
  --project-template tests/fixtures/ue/LoomleTestHost \
  --plugin-archive <final-release-candidate.zip> \
  --output-dir <new-artifact-directory> \
  --target darwin-arm64

Release 组装只使用位于 .tmp/client/<platform-arch>/loomle(.exe) 的规范程序，并将其与 Bridge 源插件组合。有关产物规范，请参阅 packaging/client/ 和 packaging/fab/。

文档

• 网站：https://loomle.ai/
• 安装：https://loomle.ai/install.html
• 快速入门：https://loomle.ai/quickstart.html
• 界面概览：https://loomle.ai/tools/
• 发布版本：https://github.com/loomle/loomle/releases

仓库和产品设计文档位于 docs/ 下；规范的 SAL 和 UE 接口契约位于 sal/docs/ 和 interfaces/ 下。Loomle 0.6 的源代码和文档仍可通过 0.6 分支、其发布标签 以及仓库历史获取；main 仅包含当前设计和代码。

许可证

Loomle 基于 MIT 许可证开源。请参阅 LICENSE。