Codex Tuanjie MCP

Este es un adaptador MCP STDIO local para Codex. Reutiliza el Package oficial cn.tuanjie.codely.bridge del motor Tuanjie, permitiendo que Codex inicie un proyecto Tuanjie específico y opere el editor, escenas, GameObject, scripts, recursos y consola a través de Codely Bridge.

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

Este proyecto no reemplaza ni modifica la implementación de Codely Bridge. El adaptador solo se encarga de descubrir Bridge, completar el handshake del protocolo TCP, verificar el proyecto de destino y convertir los comandos de Bridge en herramientas MCP.

Capacidades actuales

• Inicializa y arranca un proyecto Tuanjie existente mediante tuanjie_start.

• Cuando al proyecto le falta Bridge, añade la dependencia oficial cn.tuanjie.codely.bridge a Packages/manifest.json.

• Crea una copia de seguridad con marca de tiempo en el mismo directorio antes de modificar el manifest.

• Inicia el proyecto con tuanjie.exe open <project>; si el proyecto ya está abierto, lo reutiliza directamente.

• Espera a que .com-unity-codely.json pase a ready, se conecta al puerto dinámico y verifica el directorio raíz del proyecto.

• Tras una recarga del editor o un cambio de puerto, redescubre y reconecta automáticamente antes de la siguiente llamada a una herramienta.

• Expone 22 herramientas MCP: editor, escena, GameObject, script, Shader, recursos, Package, UI Toolkit, captura de pantalla, Game View, simulación de entrada, consola, tareas asíncronas y ejecución de C#, entre otras.

Límite actual: MCP debe estar vinculado a un proyecto ya creado por Tuanjie Hub. Actualmente no crea proyectos Tuanjie desde un directorio vacío ni cambia automáticamente entre varios proyectos.

Requisitos previos

1. Instalar el software

• Windows 10 o superior.

• Node.js 20 o superior.

• Codex Desktop o Codex CLI.

• Tuanjie Cowork, así como la versión requerida del motor Tuanjie y Tuanjie Hub.

• Motor Tuanjie 2021.3 o superior. La documentación oficial de Codely Bridge requiere Unity/motor Tuanjie 2021.3 o superior.

Tras instalar o actualizar Tuanjie Cowork, se debe reiniciar Cowork y Codex para garantizar que el tuanjie.exe que proporciona sea visible para el proceso MCP. Se puede verificar primero:

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

2. Crear un proyecto en Tuanjie Hub

Primero crea y registra un proyecto mediante Tuanjie Hub, y confirma que el directorio raíz del proyecto contiene al menos:

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

También se puede crear un proyecto con la CLI de Tuanjie, pero primero hay que determinar la versión pública de motor 1.x.x y el ID de plantilla exacto:

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

No pases versiones internas de editor como 2022.3.xxtxx a --editor-version; usa la versión pública 1.x.x que muestra Hub.

3. Preparar Codely Bridge

Normalmente no es necesaria la instalación manual. En la primera llamada a tuanjie_start, si el manifest del proyecto no contiene Bridge, MCP consulta el Package Registry oficial de Tuanjie, escribe la dependencia y luego inicia el editor esperando a que Package Manager complete la instalación.

Para instalarlo manualmente, abre en el editor de Tuanjie:

Window -> Package Manager -> Tuanjie Registry

Busca Tuanjie AI e instala Codely Bridge. Las instrucciones oficiales están en la Guía de instalación de Codely Bridge.

Desarrollo y compilación

Clona el repositorio:

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

En el directorio del código fuente, ejecuta:

npm ci
npm test

npm test primero ejecuta la compilación de TypeScript y luego ejecuta las pruebas de tramas de protocolo, descubrimiento de configuración, handshake de Bridge, correlación de solicitudes, inicialización de Package y arranque de proyecto. Para compilar por separado, ejecuta:

npm run build

Instalación en Codex

Convención: cada MCP usa un directorio independiente:

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

Coloca el dist compilado, package.json, package-lock.json y este README en ese directorio, y luego instala las dependencias de ejecución en el directorio de instalación:

npm ci --omit=dev

Registra el MCP y vincúlalo al proyecto Tuanjie de destino:

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

Comprueba el resultado del registro:

codex mcp get tuanjie

Tras registrar o actualizar el MCP, es necesario crear una nueva tarea de Codex o reiniciar Codex; las tareas ya en ejecución no cargan dinámicamente las herramientas recién añadidas.

Uso

Iniciar y conectar el proyecto

En Codex, pide directamente "iniciar el proyecto Tuanjie" o llama explícitamente a tuanjie_start:

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

El flujo de ejecución es el siguiente:

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

Parámetros opcionales:

• install_bridge: por defecto true. Si se establece en false, el proyecto debe tener Bridge ya instalado.

• bridge_package_version: especifica la versión del Package Bridge; si se omite, consulta el Registry oficial.

• wait_timeout_seconds: tiempo de espera para el editor y Bridge, por defecto 300 segundos, rango 10-900 segundos.

Comprobar la conexión

• tuanjie_bridge_status: lee la configuración de Bridge y el estado de conexión actual, sin reconectar activamente.

• unity_refresh: vuelve a leer el puerto dinámico, reconecta y verifica el directorio raíz del proyecto.

Una vez conectado, se pueden usar herramientas como unity_editor, unity_scene, unity_gameobject, unity_script, unity_asset, etc., para operar el proyecto.

Orden de descubrimiento de configuración

El adaptador localiza Bridge en el siguiente orden:

1. --config <path> o TUANJIE_BRIDGE_CONFIG.

2. --project <path> o TUANJIE_PROJECT_PATH.

3. El directorio de trabajo del proceso MCP y sus directorios padre.

Se recomienda usar siempre --project en los parámetros de registro de Codex para vincular explícitamente el proyecto y evitar conectarse a una instancia de editor incorrecta.

Verificación y diagnóstico

Prueba Bridge en un proyecto real:

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

Realiza la verificación de lista de herramientas, arranque, estado y lectura del editor a través de un MCP STDIO real:

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

Problemas comunes:

• No se encuentra tuanjie.exe: instala o actualiza Tuanjie Cowork y luego reinicia Cowork y Codex.

• No aparece tuanjie_start en Codex: crea una nueva tarea o reinicia Codex, y confirma que codex mcp get tuanjie muestra enabled: true.

• Tiempo de espera de Bridge agotado: comprueba si el editor está bloqueado por inicio de sesión, licencia, instalación de Packages o diálogos de compilación.

• El proyecto no coincide: comprueba si --project en el registro del MCP apunta al proyecto abierto actualmente en el editor.

• Herramientas MCP no disponibles: revisa los registros MCP de Codex y C:\Users\<username>\.codely\logs.

Límites de seguridad

• MCP no abre el editor automáticamente al iniciarse; solo una llamada explícita a tuanjie_start inicia el proyecto.

• Los comandos ya enviados a Bridge no se reintentan automáticamente tras una anomalía de conexión, para evitar ejecutar operaciones de escritura dos veces.

• Las restricciones de escritura en Play Mode siguen determinadas por el Codely Bridge oficial.

• execute_csharp_script y la mayoría de las herramientas de administración pueden modificar el proyecto; deben usarse en un espacio de trabajo Git.

• Si Bridge ya existe, no se reescribe Packages/manifest.json; si falta Bridge, se hace una copia de seguridad antes de modificar.

Estructura del proyecto

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

Notas sobre el protocolo

• Mensaje de bienvenida de Bridge: WELCOME UNITY-TCP 1 FRAMING=1 SERVER_VERSION=2.

• Trama de cliente: CLIENT_VERSION=2, PLATFORM=codex.

• Las tramas de datos usan un prefijo de longitud de 8 bytes sin signo en big-endian.

• Tamaño máximo de trama: 64 MiB.

• Cada comando incluye type, params y request_id.

Licencia

Este proyecto está bajo la Licencia MIT.