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를 사용합니다.