# Codex Tuanjie MCP

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

```text
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 进程可见。可先验证：

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

### 2. 在 Tuanjie Hub 创建项目

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

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

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

```powershell
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 完成安装。

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

```text
Window -> Package Manager -> Tuanjie Registry
```

搜索 `Tuanjie AI` 并安装 `Codely Bridge`。官方说明见
[Codely Bridge 安装指南](https://codely-docs.tuanjie.cn/using-codely/codely-bridge-installation-guide)。

## 开发与构建

克隆仓库：

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

在源码目录执行：

```powershell
npm ci
npm test
```

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

```powershell
npm run build
```

## 安装到 Codex

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

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

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

```powershell
npm ci --omit=dev
```

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

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

检查注册结果：

```powershell
codex mcp get tuanjie
```

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

## 使用方法

### 启动并连接项目

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

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

执行流程如下：

```text
验证项目
  -> 检查/安装 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：

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

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

```powershell
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 时会先备份再修改。

## 项目结构

```text
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](LICENSE)。