Unity MCP Efficient

这是一个面向 MCP for Unity 的独立、token 高效的 MCP facade 与 Codex 技能。

它在一个面向模型的小型 API 背后保留了完整的 Unity 功能集。模型只看到六个稳定工具，按需搜索上游工具目录，接收紧凑且对 Unity 感知的响应，并且可以在不把每个中间结果都带入对话的情况下串联起例行工作。

[!IMPORTANT] 本项目并不替代 Unity 包或其 Python 服务器。MCP for Unity 仍然是后端。请向 AI 客户端注册 facade，而不是上游服务端。如果同时暴露两套工具面，省下的上下文大多会被抵消。

实测上下文缩减

在 2026-08-24，benchmarks/ 中的脚本针对 MCP for Unity v10.1.0（c14de1e6）测出了以下结果。

动态目录收录了 377 个 Unity 操作。一套小型确定性英/俄搜索用例，在全部 15 个用例中都将预期操作排在第 1 位，也全部进入前 3。候选版本通过了 35 项 facade 测试。一次现场冒烟测试没有对项目做任何改动，并在已打开的 Unity 编辑器中验证了这六个工具构成 surface、editor.refresh 位列第 1、编辑器状态，以及分两步检查场景的一个批次。

¹ Token 数使用“每 token 约 4 字符”的保守估算。它们描述的是上下文占用，而非 API 计费。实际 token 化结果因模型和负载而异。
² 该层级压力用例模拟一条接口噪声很大的响应，包含 250 个对象、每个对象 300 个顶点索引，并且同一份内容同时出现在文本和结构化负载中。这种极端场景并不承诺每个场景都能同等缩减。方法和原始数值见 BENCHMARKS.md。

Related MCP server: Agent Bridge for Unity

六个工具各自的作用

模型依然能触到 facade 后面那 377 个已索引的操作，只是它们不再一次性占满完整提示词。

接线层处理的问题

架构

Codex or another MCP client
        |
        | sees 6 tools
        v
Unity MCP Efficient (stdio by default)
        |-- capability search over the live upstream catalog
        |-- compact Unity-specific post-processing
        |-- bounded workflow runtime
        |-- local SQLite result and request receipts
        |
        | HTTP, default http://127.0.0.1:8080/mcp
        v
MCP for Unity server
        |
        v
Unity Editor package

一个 skill 本身不能隐藏 MCP 客户端已经加载的工具 schema。这也是本仓库同时提供两件东西的原因：

• facade 负责维系更小的 API 和紧凑响应；

• skill 教 Codex 如何高效地搜索、批量、恢复和验证。

安装

1. 以 HTTP 模式启动 MCP for Unity

请按上游它的说明来安装 CoplayDev/MCP for Unity。在 Unity 中打开 Window → MCP for Unity，选择本地 HTTP 传输并启动服务。

上游的默认端点是：

http://127.0.0.1:8080/mcp

如果你的项目使用的是另一个端口，请通过下面的 UNITY_MCP_BACKEND_URL 传进去。

2. 在 Codex 中注册 facade

需要时可以 uv 先安装，然后运行：

codex mcp add unity-efficient \
  --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp \
  -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

在 PowerShell 里面，请把命令写到一行再运行：

codex mcp add unity-efficient --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

把同一个 Codex 客户端里直接挂的 MCP for Unity 条目移除/禁用，让上游 HTTP 服务保持运行，但不要把这个拥有 48 个工具的完整表面对注册给模型。

3. 安装 Codex skill

最简单的办法是直接让 Codex 来做：

$skill-installer Install the skill from https://github.com/Vangardo/unity-mcp-efficient/tree/main/skills/unity-mcp-efficient

如果要手工做用户级安装，克隆仓库，并把 skills/unity-mcp-efficient 复制到：

$HOME/.agents/skills/unity-mcp-efficient

Codex 会自动感知 skill 的变化。如果 skill 没出现，重启 Codex。

其他 MCP 客户端

使用这个 stdio 配置：

{
  "mcpServers": {
    "unity-efficient": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vangardo/unity-mcp-efficient.git",
        "unity-mcp-efficient"
      ],
      "env": {
        "UNITY_MCP_BACKEND_URL": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}

如果客户端支持 Agent Skills 格式，就安装打包好的 skill。没有它 facade 也照样能用，但这个 skill 会提升工具选择和恢复行为。

推荐的 agent 流程

1. 先做一次浅层 Unity 状态读取。

2. 用一个明确的任务句搜索。

3. 参数不明时，只去获取对应的 schema。

4. 先后顺序处理已知有依赖的工作；独立读取可以并行，Unity 的变更绝不能并行。

5. 保留紧凑输出，再按路径/页去展开已存的结果。

6. 验证的语义要做，而不是对着每个中间暴露检查。

这个流程已经写进 skills/unity-mcp-efficient/SKILL.md。

配置

除非确实要独自通过网络暴露 facade，否则保持默认的 stdio。在用 HTTP/SSE 之前请先看 SECURITY.md。

开发与验证

git clone https://github.com/Vangardo/unity-mcp-efficient.git
cd unity-mcp-efficient
uv sync --extra dev
uv run pytest -q

当上游 HTTP 服务正在运行时：

uv run python benchmarks/evaluate_facade.py
uv run python benchmarks/measure_surface.py
uv run python benchmarks/live_smoke.py

evaluate_facade.py 和 measure_surface.py 都会读取实时的上游目录。live_smoke.py 不会做任何变更，但它需要已经打开并连接到 Unity Editor。

已知限制

• 输出刻意有损。未处理的完整原始结果通过 get_result 在一个有界的时间内保持可用。

• facade 并不会让任意的 Unity 变更更安全；权限与复审仍属于 MCP 客户端和用户自己。

• 并行是保守的。Unity 内部很可能本身就串行化了编辑器工作。

• 某些可选能力（如 Roslyn 支持）也许不会出现在这个 Unity 工程里。

• Scene/Game 视图捕获可能会漏掉 ImGUI 编辑器上的浮层。

• 兼容性测试以 MCP for Unity v10.1.0 为准。目录是动态的，所以在声称支持上游较新版本之前，请以较新版本再跑一次基准。

设计渊源

渐进显示的想法是从 Vangardo/mcp_hub 学到并的，那是一个把大型集成目录经由小搜索+调用面路由的 MCP 网关。Unity MCP Efficient 则把这种上下文纪律应用到 Unity，再加上 Unity 专属的压缩、rev 状态、变更恢复、截图和有界局部工作流。

如果你在 Slack、Teamwork、Telegram、日历、记忆、自动化或跨服务 agent 上也需要这种形态，请看 MCP Hub。

Unity 兼容后端是 CoplayDev/MCP for Unity，以 MIT 协议分发。本仓库与它是独立的项目，不包含它的源代码。参见 NOTICE.md 和 THIRD_PARTY_NOTICES.md。

License and Trademark

本仓库里的原创代码以 MIT License 发布。

Unity 是 Unity Technologies 或它的关联方在美国以及其他地方的商标或注册商标。本项目与 Unity Technologies 或 CoplayDev 无关，也不受它们背书。其他名称与商标归各自的所有者所有。