Codex Tuanjie MCP

这是一个面向 Codex 的本地 STDIO MCP 适配器。它复用团结引擎中的官方 cn.tuanjie.codely.bridge Package，让 Codex 可以启动指定团结项目，并通过 Codely Bridge 操作编辑器、场景、GameObject、脚本、资源和控制台。

Codex
  -> MCP STDIO
  -> codex-tuanjie-mcp
  -> Codely Bridge TCP
  -> Tuanjie Editor

本项目不会替换或修改 Codely Bridge 的实现。适配器只负责发现 Bridge、完成 TCP 协议握手、验证目标项目，并把 Bridge 命令转换为 MCP 工具。

当前能力

• 通过 tuanjie_start 初始化并启动已经存在的团结项目。

• 项目缺少 Bridge 时，将官方 cn.tuanjie.codely.bridge 依赖加入 Packages/manifest.json。

• 修改 manifest 前在同一目录创建带时间戳的备份。

• 通过 tuanjie.exe open <project> 启动项目；项目已打开时直接复用。

• 等待 .com-unity-codely.json 变为 ready，连接动态端口并校验项目根目录。

• 编辑器重载或端口变化后，在下一次工具调用前自动重新发现并连接。

• 暴露编辑器、场景、GameObject、脚本、Shader、资源、Package、UI Toolkit、 截图、Game View、输入模拟、控制台、异步任务和 C# 执行等 22 个 MCP 工具。

当前边界：MCP 必须绑定一个已经由 Tuanjie Hub 创建的项目。它目前不会从空目录 创建团结项目，也不会在多个项目之间自动切换。

前置步骤

1. 安装软件

• Windows 10 或更高版本。

• Node.js 20 或更高版本。

• Codex Desktop 或 Codex CLI。

• Tuanjie Cowork，以及所需版本的团结引擎和 Tuanjie Hub。

• 团结引擎 2021.3 或更高版本。官方 Codely Bridge 文档要求 Unity/团结引擎 2021.3 或更高版本。

安装或更新 Tuanjie Cowork 后应重新启动 Cowork 和 Codex，确保其提供的 tuanjie.exe 对 MCP 进程可见。可先验证：

tuanjie.exe --help
tuanjie.exe editors list-installed

2. 在 Tuanjie Hub 创建项目

先通过 Tuanjie Hub 创建并注册项目，确认项目根目录至少包含：

Assets/
Packages/manifest.json
ProjectSettings/ProjectVersion.txt

也可以使用 Tuanjie CLI 创建项目，但必须先确定公开的 1.x.x 引擎版本和准确的 模板 ID：

tuanjie.exe template list 1.10.1
tuanjie.exe projects create "MyGame" `
  --path "D:\games" `
  --editor-version 1.10.1 `
  --template "<template-id>"

不要把 2022.3.xxtxx 这类内部编辑器版本传给 --editor-version，应使用 Hub 显示的公开 1.x.x 版本。

3. 准备 Codely Bridge

通常不需要手动安装。首次调用 tuanjie_start 时，如果项目 manifest 中没有 Bridge，MCP 会查询团结官方 Package Registry、写入依赖，然后启动编辑器等待 Package Manager 完成安装。

如需手动安装，可在团结编辑器中打开：

Window -> Package Manager -> Tuanjie Registry

搜索 Tuanjie AI 并安装 Codely Bridge。官方说明见 Codely Bridge 安装指南。

开发与构建

克隆仓库：

git clone https://github.com/g82v68xftk-ux/codex-tuanjie-mcp.git
Set-Location codex-tuanjie-mcp

在源码目录执行：

npm ci
npm test

npm test 会先执行 TypeScript 构建，再运行协议帧、配置发现、Bridge 握手、 请求关联、Package 初始化和项目启动测试。单独构建可执行：

npm run build

安装到 Codex

约定每个 MCP 使用一个独立目录：

C:\Users\<username>\.codex\mcp\codex-tuanjie-mcp

把构建后的 dist、package.json、package-lock.json 和本 README 放入该目录， 然后在安装目录安装运行时依赖：

npm ci --omit=dev

注册 MCP，并把它绑定到目标团结项目：

codex mcp add tuanjie -- node `
  "C:\Users\<username>\.codex\mcp\codex-tuanjie-mcp\dist\src\index.js" `
  --project "D:\path\to\tuanjie-project"

检查注册结果：

codex mcp get tuanjie

注册或更新 MCP 后，需要新建 Codex 任务或重启 Codex，当前已经运行的任务不会 动态加载新增工具。

使用方法

启动并连接项目

在 Codex 中直接要求“启动团结项目”，或显式调用 tuanjie_start：

{
  "install_bridge": true,
  "wait_timeout_seconds": 300
}

执行流程如下：

验证项目
  -> 检查/安装 Codely Bridge
  -> 检查现有 Bridge 连接
  -> 必要时调用 tuanjie.exe open
  -> 等待 Bridge ready
  -> 连接并验证项目根目录

可选参数：

• install_bridge：默认 true。设为 false 时，项目必须已经安装 Bridge。

• bridge_package_version：指定 Bridge Package 版本；省略时查询官方 Registry。

• wait_timeout_seconds：等待编辑器和 Bridge 的时间，默认 300 秒，范围 10-900 秒。

检查连接

• tuanjie_bridge_status：读取 Bridge 配置和当前连接状态，不主动重连。

• unity_refresh：重新读取动态端口、重连并验证项目根目录。

连接成功后即可使用 unity_editor、unity_scene、unity_gameobject、 unity_script、unity_asset 等工具操作项目。

配置发现顺序

适配器按以下顺序定位 Bridge：

1. --config <path> 或 TUANJIE_BRIDGE_CONFIG。

2. --project <path> 或 TUANJIE_PROJECT_PATH。

3. MCP 进程工作目录及其父目录。

建议始终在 Codex 注册参数中使用 --project 明确绑定项目，避免连接到错误的 编辑器实例。

验证和诊断

对实际项目探测 Bridge：

npm run probe -- --project "D:\path\to\tuanjie-project"

通过真实 MCP STDIO 完成工具列表、启动、状态和编辑器读取验证：

npm run smoke:mcp -- --project "D:\path\to\tuanjie-project"

常见问题：

• 找不到 tuanjie.exe：安装或更新 Tuanjie Cowork，然后重启 Cowork 和 Codex。

• Codex 中没有 tuanjie_start：新建任务或重启 Codex，确认 codex mcp get tuanjie 显示 enabled: true。

• 等待 Bridge 超时：检查编辑器是否被登录、许可证、Package 安装或编译弹窗阻塞。

• 项目不匹配：检查 MCP 注册中的 --project 是否指向当前编辑器打开的项目。

• MCP 工具不可用：查看 Codex MCP 日志，以及 C:\Users\<username>\.codely\logs。

安全边界

• MCP 启动时不会自动弹出编辑器；只有显式调用 tuanjie_start 才会启动项目。

• 已发送给 Bridge 的命令在连接异常后不会自动重试，避免重复执行写操作。

• Play Mode 写入限制仍由官方 Codely Bridge 决定。

• execute_csharp_script 以及多数管理工具可以修改项目，应在 Git 工作区中使用。

• Bridge 已存在时不会重写 Packages/manifest.json；缺少 Bridge 时会先备份再修改。

项目结构

src/
  bridge-client.ts     Bridge TCP 握手、连接和请求处理
  config.ts            .com-unity-codely.json 发现与解析
  framing.ts           8 字节大端长度帧编码/解码
  project-start.ts     Bridge 初始化、tuanjie.exe 启动和 ready 等待
  tool-definitions.ts  MCP 工具定义
  index.ts             STDIO MCP 服务入口
test/                  Node.js 测试

协议说明

• Bridge 欢迎消息：WELCOME UNITY-TCP 1 FRAMING=1 SERVER_VERSION=2。

• 客户端帧：CLIENT_VERSION=2、PLATFORM=codex。

• 数据帧使用 8 字节无符号大端长度前缀。

• 单帧最大 64 MiB。

• 每条命令包含 type、params 和 request_id。

许可证

本项目采用 MIT License。