Codex Tuanjie MCP

Dies ist ein lokaler STDIO-MCP-Adapter für Codex. Er nutzt das offizielle cn.tuanjie.codely.bridge-Package aus der Tuanjie-Engine, sodass Codex ein bestimmtes Tuanjie-Projekt starten und über Codely Bridge Editor, Szene, GameObject, Skripte, Assets und Konsole bedienen kann.

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

Dieses Projekt ersetzt oder modifiziert nicht die Implementierung von Codely Bridge. Der Adapter ist nur dafür zuständig, die Bridge zu finden, den TCP-Protokoll-Handshake durchzuführen, das Zielprojekt zu verifizieren und Bridge-Befehle in MCP-Tools umzuwandeln.

Aktuelle Fähigkeiten

• Initialisiert und startet über tuanjie_start ein bereits vorhandenes Tuanjie-Projekt.

• Wenn dem Projekt die Bridge fehlt, wird die offizielle cn.tuanjie.codely.bridge-Abhängigkeit zu Packages/manifest.json hinzugefügt.

• Vor der Änderung des Manifests wird im selben Verzeichnis ein Backup mit Zeitstempel erstellt.

• Startet das Projekt über tuanjie.exe open <project>; wenn das Projekt bereits geöffnet ist, wird es direkt wiederverwendet.

• Wartet, bis .com-unity-codely.json den Status ready erreicht, verbindet sich mit dem dynamischen Port und validiert das Projektstammverzeichnis.

• Nach einem Editor-Reload oder einer Portänderung wird vor dem nächsten Tool-Aufruf automatisch neu erkannt und verbunden.

• Stellt 22 MCP-Tools bereit, darunter Editor, Szene, GameObject, Skript, Shader, Assets, Package, UI Toolkit, Screenshots, Game View, Eingabesimulation, Konsole, asynchrone Aufgaben und C#-Ausführung.

Aktuelle Grenzen: Der MCP muss an ein Projekt gebunden sein, das bereits von Tuanjie Hub erstellt wurde. Er erstellt derzeit keine Tuanjie-Projekte aus leeren Verzeichnissen und wechselt auch nicht automatisch zwischen mehreren Projekten.

Voraussetzungen

1. Software installieren

• Windows 10 oder höher.

• Node.js 20 oder höher.

• Codex Desktop oder Codex CLI.

• Tuanjie Cowork sowie die benötigte Version der Tuanjie-Engine und Tuanjie Hub.

• Tuanjie-Engine 2021.3 oder höher. Die offizielle Codely-Bridge-Dokumentation erfordert Unity/Tuanjie-Engine 2021.3 oder höher.

Nach der Installation oder Aktualisierung von Tuanjie Cowork sollten Cowork und Codex neu gestartet werden, um sicherzustellen, dass das bereitgestellte tuanjie.exe für den MCP-Prozess sichtbar ist. Zuerst kann Folgendes überprüft werden:

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

2. Projekt in Tuanjie Hub erstellen

Erstellen und registrieren Sie zuerst ein Projekt über Tuanjie Hub und stellen Sie sicher, dass das Projektstammverzeichnis mindestens Folgendes enthält:

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

Sie können ein Projekt auch mit der Tuanjie CLI erstellen, müssen aber zuerst die öffentliche 1.x.x-Engine-Version und die genaue Vorlagen-ID ermitteln:

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

Übergeben Sie keine internen Editor-Versionen wie 2022.3.xxtxx an --editor-version, sondern verwenden Sie die im Hub angezeigte öffentliche 1.x.x-Version.

3. Codely Bridge vorbereiten

Normalerweise ist keine manuelle Installation erforderlich. Beim ersten Aufruf von tuanjie_start, wenn die Bridge nicht im Projektmanifest enthalten ist, fragt der MCP die offizielle Tuanjie-Package-Registry ab, schreibt die Abhängigkeit und startet dann den Editor, um zu warten, bis der Package Manager die Installation abgeschlossen hat.

Für eine manuelle Installation öffnen Sie im Tuanjie-Editor:

Window -> Package Manager -> Tuanjie Registry

Suchen Sie nach Tuanjie AI und installieren Sie Codely Bridge. Offizielle Anweisungen finden Sie unter Codely Bridge Installationsanleitung.

Entwicklung und Build

Repository klonen:

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

Im Quellverzeichnis ausführen:

npm ci
npm test

npm test führt zuerst den TypeScript-Build aus und führt dann Tests für Protokoll-Frames, Konfigurationserkennung, Bridge-Handshake, Anfragezuordnung, Package-Initialisierung und Projektstart durch. Ein separater Build kann mit folgendem Befehl ausgeführt werden:

npm run build

Installation in Codex

Konvention: Jeder MCP verwendet ein eigenes Verzeichnis:

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

Legen Sie das gebaute dist, package.json, package-lock.json und diese README in dieses Verzeichnis und installieren Sie dann die Laufzeitabhängigkeiten im Installationsverzeichnis:

npm ci --omit=dev

Registrieren Sie den MCP und binden Sie ihn an das Ziel-Tuanjie-Projekt:

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

Registrierungsergebnis prüfen:

codex mcp get tuanjie

Nach der Registrierung oder Aktualisierung des MCP muss eine neue Codex-Aufgabe erstellt oder Codex neu gestartet werden. Bereits laufende Aufgaben laden neue Tools nicht dynamisch.

Verwendung

Projekt starten und verbinden

Fordern Sie in Codex direkt „Tuanjie-Projekt starten" an oder rufen Sie explizit tuanjie_start auf:

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

Der Ausführungsablauf ist wie folgt:

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

Optionale Parameter:

• install_bridge: Standard true. Bei false muss die Bridge im Projekt bereits installiert sein.

• bridge_package_version: Gibt die Bridge-Package-Version an; wenn weggelassen, wird die offizielle Registry abgefragt.

• wait_timeout_seconds: Wartezeit auf Editor und Bridge, Standard 300 Sekunden, Bereich 10–900 Sekunden.

Verbindung prüfen

• tuanjie_bridge_status: Liest die Bridge-Konfiguration und den aktuellen Verbindungsstatus, ohne aktiv neu zu verbinden.

• unity_refresh: Liest den dynamischen Port erneut, verbindet sich neu und validiert das Projektstammverzeichnis.

Nach erfolgreicher Verbindung können Tools wie unity_editor, unity_scene, unity_gameobject, unity_script, unity_asset usw. verwendet werden, um das Projekt zu bedienen.

Reihenfolge der Konfigurationserkennung

Der Adapter lokalisiert die Bridge in folgender Reihenfolge:

1. --config <path> oder TUANJIE_BRIDGE_CONFIG.

2. --project <path> oder TUANJIE_PROJECT_PATH.

3. Arbeitsverzeichnis des MCP-Prozesses und dessen übergeordnete Verzeichnisse.

Es wird empfohlen, in den Codex-Registrierungsparametern immer --project zu verwenden, um das Projekt explizit zu binden und zu vermeiden, dass eine Verbindung zur falschen Editor-Instanz hergestellt wird.

Validierung und Diagnose

Bridge für ein reales Projekt untersuchen:

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

Über echte MCP-STDIO die Tool-Liste, den Start, den Status und das Editor-Lesen validieren:

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

Häufige Probleme:

• tuanjie.exe nicht gefunden: Tuanjie Cowork installieren oder aktualisieren, dann Cowork und Codex neu starten.

• tuanjie_start fehlt in Codex: Neue Aufgabe erstellen oder Codex neu starten, prüfen, ob codex mcp get tuanjie enabled: true anzeigt.

• Timeout beim Warten auf die Bridge: Prüfen, ob der Editor durch Anmeldung, Lizenz, Package-Installation oder Kompilierungsdialoge blockiert ist.

• Projekt stimmt nicht überein: Prüfen, ob --project in der MCP-Registrierung auf das aktuell im Editor geöffnete Projekt zeigt.

• MCP-Tools nicht verfügbar: Codex-MCP-Protokolle sowie C:\Users\<username>\.codely\logs ansehen.

Sicherheitsgrenzen

• Der MCP öffnet beim Start keinen Editor automatisch; nur ein expliziter Aufruf von tuanjie_start startet das Projekt.

• Bereits an die Bridge gesendete Befehle werden nach einer Verbindungsstörung nicht automatisch wiederholt, um die wiederholte Ausführung von Schreiboperationen zu vermeiden.

• Die Schreibbeschränkungen im Play Mode werden weiterhin von der offiziellen Codely Bridge bestimmt.

• execute_csharp_script sowie die meisten Verwaltungstools können das Projekt verändern und sollten in einem Git-Arbeitsbereich verwendet werden.

• Wenn die Bridge bereits vorhanden ist, wird Packages/manifest.json nicht überschrieben; wenn die Bridge fehlt, wird zuerst ein Backup erstellt und dann geändert.

Projektstruktur

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

Protokollhinweise

• Bridge-Begrüßungsnachricht: WELCOME UNITY-TCP 1 FRAMING=1 SERVER_VERSION=2.

• Client-Frame: CLIENT_VERSION=2, PLATFORM=codex.

• Datenframes verwenden ein 8-Byte-unsigned-Big-Endian-Längenpräfix.

• Maximale Framegröße: 64 MiB.

• Jeder Befehl enthält type, params und request_id.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.