Codex Tuanjie MCP

This is a local STDIO MCP adapter for Codex. It reuses the official cn.tuanjie.codely.bridge Package in the Tuanjie engine, allowing Codex to launch a specified Tuanjie project and operate the editor, scenes, GameObjects, scripts, assets, and console through Codely Bridge.

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

This project does not replace or modify the Codely Bridge implementation. The adapter is only responsible for discovering the Bridge, completing the TCP protocol handshake, validating the target project, and converting Bridge commands into MCP tools.

Current Capabilities

• Initialize and launch an existing Tuanjie project via tuanjie_start.

• When the project lacks the Bridge, add the official cn.tuanjie.codely.bridge dependency to Packages/manifest.json.

• Create a timestamped backup in the same directory before modifying the manifest.

• Launch the project via tuanjie.exe open <project>; reuse it directly if the project is already open.

• Wait for .com-unity-codely.json to become ready, connect to the dynamic port, and validate the project root directory.

• After an editor reload or port change, automatically rediscover and reconnect before the next tool call.

• Expose 22 MCP tools covering the editor, scenes, GameObjects, scripts, Shaders, assets, Packages, UI Toolkit, screenshots, Game View, input simulation, console, async tasks, and C# execution.

Current boundary: the MCP must be bound to a project already created by Tuanjie Hub. It does not currently create Tuanjie projects from empty directories, nor does it automatically switch between multiple projects.

Prerequisites

1. Install Software

• Windows 10 or later.

• Node.js 20 or later.

• Codex Desktop or Codex CLI.

• Tuanjie Cowork, along with the required version of the Tuanjie engine and Tuanjie Hub.

• Tuanjie engine 2021.3 or later. The official Codely Bridge documentation requires Unity/Tuanjie engine 2021.3 or later.

After installing or updating Tuanjie Cowork, restart Cowork and Codex to ensure the tuanjie.exe it provides is visible to the MCP process. You can verify first:

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

2. Create a Project in Tuanjie Hub

First create and register a project through Tuanjie Hub, and confirm the project root directory contains at least:

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

You can also create a project with the Tuanjie CLI, but you must first determine the public 1.x.x engine version and the exact template ID:

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

Do not pass internal editor versions like 2022.3.xxtxx to --editor-version; use the public 1.x.x version shown in Hub.

3. Prepare Codely Bridge

Manual installation is usually not needed. On the first call to tuanjie_start, if the project manifest has no Bridge, the MCP queries the official Tuanjie Package Registry, writes the dependency, then launches the editor and waits for Package Manager to finish the installation.

To install manually, open the following in the Tuanjie editor:

Window -> Package Manager -> Tuanjie Registry

Search for Tuanjie AI and install Codely Bridge. See the Codely Bridge Installation Guide for official instructions.

Development and Build

Clone the repository:

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

Run in the source directory:

npm ci
npm test

npm test first runs the TypeScript build, then runs tests for protocol framing, config discovery, Bridge handshake, request correlation, Package initialization, and project launch. To build alone, run:

npm run build

Installing into Codex

By convention, each MCP uses its own dedicated directory:

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

Place the built dist, package.json, package-lock.json, and this README into that directory, then install runtime dependencies in the installation directory:

npm ci --omit=dev

Register the MCP and bind it to the target Tuanjie project:

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

Check the registration result:

codex mcp get tuanjie

After registering or updating the MCP, create a new Codex task or restart Codex; already-running tasks will not dynamically load newly added tools.

Usage

Launch and Connect to a Project

In Codex, simply ask to "launch the Tuanjie project", or explicitly call tuanjie_start:

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

The execution flow is as follows:

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

Optional parameters:

• install_bridge: defaults to true. When set to false, the project must already have the Bridge installed.

• bridge_package_version: specifies the Bridge Package version; when omitted, the official Registry is queried.

• wait_timeout_seconds: time to wait for the editor and Bridge, default 300 seconds, range 10-900 seconds.

Check the Connection

• tuanjie_bridge_status: reads the Bridge configuration and current connection status without actively reconnecting.

• unity_refresh: re-reads the dynamic port, reconnects, and validates the project root directory.

Once connected, you can use tools such as unity_editor, unity_scene, unity_gameobject, unity_script, and unity_asset to operate on the project.

Configuration Discovery Order

The adapter locates the Bridge in the following order:

1. --config <path> or TUANJIE_BRIDGE_CONFIG.

2. --project <path> or TUANJIE_PROJECT_PATH.

3. The MCP process working directory and its parent directories.

It is recommended to always use --project in the Codex registration parameters to explicitly bind the project, avoiding connections to the wrong editor instance.

Verification and Diagnostics

Probe the Bridge against an actual project:

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

Run tool listing, launch, status, and editor read verification through real MCP STDIO:

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

Common issues:

• tuanjie.exe not found: install or update Tuanjie Cowork, then restart Cowork and Codex.

• tuanjie_start missing in Codex: create a new task or restart Codex, and confirm codex mcp get tuanjie shows enabled: true.

• Bridge wait timeout: check whether the editor is blocked by login, license, Package installation, or compilation dialogs.

• Project mismatch: check whether --project in the MCP registration points to the project currently open in the editor.

• MCP tools unavailable: check the Codex MCP logs, as well as C:\Users\<username>\.codely\logs.

Security Boundaries

• The MCP does not automatically pop up the editor at startup; only an explicit call to tuanjie_start launches the project.

• Commands already sent to the Bridge are not automatically retried after a connection error, to avoid re-executing write operations.

• Play Mode write restrictions are still determined by the official Codely Bridge.

• execute_csharp_script and most administrative tools can modify the project; use them in a Git working tree.

• When the Bridge already exists, Packages/manifest.json is not rewritten; when the Bridge is missing, a backup is made before modifying.

Project Structure

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 测试

Protocol Notes

• Bridge welcome message: WELCOME UNITY-TCP 1 FRAMING=1 SERVER_VERSION=2.

• Client frame: CLIENT_VERSION=2, PLATFORM=codex.

• Data frames use an 8-byte unsigned big-endian length prefix.

• Maximum single frame size is 64 MiB.

• Each command contains type, params, and request_id.

License

This project is licensed under the MIT License.