Codex Tuanjie MCP

Это локальный STDIO MCP-адаптер для Codex. Он использует официальный пакет cn.tuanjie.codely.bridge из движка Tuanjie, позволяя Codex запускать указанный проект Tuanjie и управлять через Codely Bridge редактором, сценой, GameObject, скриптами, ресурсами и консолью.

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

Этот проект не заменяет и не модифицирует реализацию Codely Bridge. Адаптер отвечает только за обнаружение Bridge, выполнение рукопожатия по TCP-протоколу, проверку целевого проекта и преобразование команд Bridge в инструменты MCP.

Текущие возможности

• Инициализация и запуск уже существующего проекта Tuanjie через tuanjie_start.

• Если в проекте отсутствует Bridge, добавляет зависимость официального cn.tuanjie.codely.bridge в Packages/manifest.json.

• Перед изменением manifest создаёт резервную копию с меткой времени в том же каталоге.

• Запускает проект через tuanjie.exe open <project>; если проект уже открыт, повторно использует его.

• Ожидает перехода .com-unity-codely.json в состояние ready, подключается к динамическому порту и проверяет корневой каталог проекта.

• После перезагрузки редактора или изменения порта автоматически выполняет повторное обнаружение и подключение перед следующим вызовом инструмента.

• Предоставляет 22 инструмента MCP: редактор, сцена, GameObject, скрипты, Shader, ресурсы, Package, UI Toolkit, скриншоты, Game View, симуляция ввода, консоль, асинхронные задачи и выполнение C#.

Текущие ограничения: 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; используйте публичную версию 1.x.x, отображаемую в Hub.

3. Подготовка Codely Bridge

Обычно ручная установка не требуется. При первом вызове tuanjie_start, если в manifest проекта нет Bridge, MCP запросит официальный реестр пакетов Tuanjie, запишет зависимость, затем запустит редактор и дождётся завершения установки через 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; если опущено, запрашивается официальный реестр.

• 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 и его родительские каталоги.

Рекомендуется всегда явно указывать --project в параметрах регистрации Codex, чтобы избежать подключения к неправильному экземпляру редактора.

Проверка и диагностика

Проверка 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 или компиляции.

• Несоответствие проекта: проверьте, указывает ли --project в регистрации MCP на проект, открытый в текущем редакторе.

• Инструменты MCP недоступны: просмотрите журналы MCP Codex и 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 МиБ.

• Каждая команда содержит type, params и request_id.

Лицензия

Этот проект распространяется под лицензией MIT.