Codex Tuanjie MCP

これは Codex 向けのローカル STDIO MCP アダプターです。Tuanjie エンジンの公式 cn.tuanjie.codely.bridge Package を再利用し、Codex が指定の Tuanjie プロジェクトを 起動し、Codely Bridge を通じてエディター、シーン、GameObject、スクリプト、アセット、 コンソールを操作できるようにします。

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

本プロジェクトは Codely Bridge の実装を置き換えたり変更したりしません。アダプターは Bridge の発見、TCP プロトコルハンドシェイク、対象プロジェクトの検証、および Bridge コマンドの MCP ツールへの変換のみを担当します。

現在の機能

• tuanjie_start により、既存の Tuanjie プロジェクトを初期化して起動します。

• プロジェクトに 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 が作成したプロジェクトにバインドされている必要があります。 空のディレクトリから Tuanjie プロジェクトを作成することはできず、複数プロジェクト間の 自動切り替えも行いません。

前提手順

1. ソフトウェアのインストール

• Windows 10 以降。

• Node.js 20 以降。

• Codex Desktop または Codex CLI。

• Tuanjie Cowork、および必要なバージョンの Tuanjie エンジンと Tuanjie Hub。

• Tuanjie エンジン 2021.3 以降。公式 Codely Bridge ドキュメントでは Unity/Tuanjie エンジン 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 が Tuanjie 公式 Package Registry を照会して依存関係を 書き込み、エディターを起動して Package Manager のインストール完了を待ちます。

手動でインストールする場合は、Tuanjie エディターで以下を開きます:

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 を登録し、対象の Tuanjie プロジェクトにバインドします:

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 プロジェクトを起動」と指示するか、明示的に 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 を採用しています。