Cocos MCP Server 0.0.1-dev.0(개발 버전)

현재 브랜치: develop · 현재 상태: 개발 중 · 현재 공식 릴리스 버전 없음

패키지 버전은 0.0.1-dev.0이며, 프로토콜 및 Tool 계약 버전은 여전히 0.0.1입니다.

Cocos Creator 3.8.8용 로컬 멀티 프로젝트 MCP 확장입니다. Cocos Dashboard가 프로젝트 생성, 가져오기, Creator 버전 선택 및 시작을 담당하며, 확장 내 Worker는 단일 머신의 Manager에 등록되고, Agent는 Manager에만 연결되며, 모든 프로젝트 수준 호출에서 projectId를 명시적으로 제공합니다.

개발 상태

• 코드 및 검증 작업은 develop 브랜치를 기준으로 합니다. main은 현재 개발 작업 브랜치가 아닙니다.

• 현재 패키지는 개발 버전이므로 공식 릴리스 패키지로 직접 배포할 수 없습니다.

• 패키지 버전 0.0.1-dev.0은 현재 개발 사전 릴리스 상태를 나타냅니다. 프로토콜, Schema 및 Tool 계약은 여전히 0.0.1을 사용합니다.

• verify:release, build:release 등의 명령은 개발 단계의 릴리스 게이트 및 후보 패키지 검증 도구입니다. 이를 통과했다고 해서 공식 릴리스가 된 것은 아닙니다.

• 공식 릴리스 전에 깨끗한 후보 버전, Direct Creator Live, Dashboard Creator Live 및 릴리스 증거 폐쇄 루프를 완료해야 합니다.

Related MCP server: mcp-bridge

핵심 경계

• 버전: 패키지 0.0.1-dev.0; 프로토콜/계약 0.0.1; 배포 상태 development

• 연결: http://127.0.0.1:38488/mcp

• 전송: MCP Streamable HTTP

• Agent 연결: 인증 사용 안 함; 루프백 주소, 유효한 Host/Origin만 허용

• 프로젝트 시작: 사용자 프로젝트는 Cocos Dashboard를 통해서만 시작할 수 있습니다. Direct Creator Live만 Runner 자체의 임시 Fixture를 시작하고 종료하며, 사용자 프로젝트는 절대 조작하지 않습니다.

• 멀티 프로젝트: 하나의 Manager가 여러 시작된 Worker를 라우팅합니다. 마지막 Worker가 오프라인 상태이고 pending 시작이 없으면 Manager가 자동으로 종료됩니다.

• 쓰기 작업: 사전 검사, revision 비교, 실행, 재읽기 검증, 부분 변경 보고

• 제공하지 않음: 트랜잭션, 자동 롤백, 파일 백업, MCP 작업 기록 또는 감사 로그

개발 설치

npm install
npm run build

확장 디렉터리를 대상 프로젝트에 넣습니다:

<project>/extensions/cocos-mcp-server

그런 다음 Cocos Dashboard를 통해:

1. 프로젝트를 가져오거나 선택합니다;

2. Cocos Creator 3.8.8을 선택합니다;

3. 프로젝트를 시작합니다;

4. 확장 Worker가 Manager에 등록될 때까지 기다립니다.

CocosCreator 실행 파일을 직접 실행하여 사용자 프로젝트를 시작하지 마십시오. 이렇게 하면 Dashboard의 버전 및 로그인 컨텍스트를 우회하게 됩니다. Direct Creator Live는 Runner 자체의 폐기 가능한 임시 Fixture에만 적용됩니다.

Agent 연결

MCP 클라이언트 연결:

http://127.0.0.1:38488/mcp

예시 구성:

{
  "mcpServers": {
    "cocos": {
      "url": "http://127.0.0.1:38488/mcp"
    }
  }
}

연결 후 권장 흐름:

1. MCP initialize;

2. MCP tools/list로 Manager에 등록된 Tool과 Schema를 확인합니다;

3. system_control.list_projects를 호출합니다;

4. 대상 projectId를 선택합니다;

5. 실행 계획을 생성하기 전에 Agent가 Action 메타데이터를 기반으로 플레이어 확인이 필요한 범위와 영향을 안내합니다;

6. 프로젝트별로 쓰기 작업을 직렬로 실행하고 반환된 revision, verification 및 ChangeManifest를 확인합니다.

Cocos 패널은 승인을 담당하지 않으며, MCP도 승인 토큰을 발급하지 않습니다. 승인 안내는 Agent 컨텍스트에만 남깁니다.

Dirty 시나리오

다음만 지원합니다:

reject
save

기본값은 reject입니다. discard는 지원하지 않으며, 저장되지 않은 수정 사항을 알림 없이 버리지 않습니다.

일반 명령

npm run build
npm test
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:live:matrix
npm run build:release
npm run scan:release

Creator Live

Creator Live는 개발 단계 검증용이며, 공식 릴리스에 필요한 완전한 증거를 대체하지 않습니다.

Direct 임시 Fixture 모드(기본값)

npm run test:live의 기본 모드는 Direct입니다. Runner는 읽기 전용 Fixture를 복사한 후, 이번에 생성된 복사본에 대해서만 Creator -nologin을 직접 실행하며, 자신이 추적하는 임시 Creator 자식 프로세스에만 SIGTERM을 보냅니다. 사용자 프로젝트를 시작, 저장, 종료 또는 종료하지 않습니다.

npm run test:live
npm run test:live:direct
npm run test:live:action -- LIVE-SYS-001
npm run test:live:action:direct -- LIVE-SYS-001

Dashboard 임시 Fixture 모드

Dashboard 모드도 Runner 자체의 임시 Fixture만 준비하지만, Creator를 직접 시작하거나 종료하지 않습니다. Runner는 manifest와 절대 프로젝트 경로를 출력하며, 운영자는 Cocos Dashboard에서 이러한 임시 프로젝트를 가져오고, 시작하고, 종료합니다.

npm run test:live:dashboard
npm run test:live:action:dashboard -- LIVE-SYS-001

Attach 모드

Attach는 Dashboard를 통해 시작되었고 Runner manifest에 명시적으로 등록된 임시 Fixture에만 연결됩니다. 이는 읽기 전용 승인 모드입니다.

npm run test:live:attach
npm run test:live:action:attach -- LIVE-SYS-001

특정 Dashboard run에 attach하려면 해당 run에서 생성된 manifest를 명시적으로 지정해야 합니다. Runner는 디렉터리를 스캔하거나 "최신" manifest를 묵시적으로 선택하지 않습니다:

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:attach

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:action:attach -- LIVE-SYS-001

저장소 문서

• 현재 계약 요약

• 개발 상태 및 브랜치 규칙

• 변경 기록

• 보안 설명

계약 스냅샷, 테스트 픽스처 및 구현 코드는 모두 이 저장소 내에 보관됩니다. Cocos 상위 프로젝트의 상대 경로 문서에 의존하지 않습니다.

문제 해결

Manager를 사용할 수 없음

Cocos Dashboard로 시작된 프로젝트가 하나 이상 온라인 상태인지 확인하십시오. Manager는 상주 프로젝트 관리자로 실행되지 않습니다. Worker가 없고 pending 시작이 없으면 자동으로 종료됩니다.

프로젝트가 나타나지 않음

• Creator 버전이 3.8.8인지 확인합니다;

• 프로젝트에 빌드된 확장이 포함되어 있는지 확인합니다;

• settings/cocos-mcp.json의 projectId가 현재 프로젝트 ID와 일치하는지 확인합니다;

• 동일한 projectId를 사용하지만 경로가 다른 두 프로젝트를 동시에 열지 마십시오.

포트 변경이 즉시 적용되지 않음

Manager 실행 중에는 desired port만 업데이트하고 온라인 재시작은 하지 않습니다. 보이는 Cocos GUI를 통해 모든 프로젝트를 종료하고, 마지막 Worker가 등록 해제되고 Manager가 자동으로 종료될 때까지 기다린 후, Dashboard에서 프로젝트를 다시 시작하면 새 Manager가 새 포트를 사용합니다.

쓰기 작업 실패

우선 확인할 사항:

• projectId가 올바른지;

• 권한 카테고리가 허용되는지;

• 경로가 프로젝트 범위 내에 있는지;

• expectedRevisions가 만료되었는지;

• 현재 Scene/Prefab이 Dirty인지;

• Creator AssetDB, Scene 또는 컴파일 상태가 ready인지.

복구는 Agent Session과 Git이 담당합니다. MCP는 트랜잭션이나 자동 롤백을 구현하지 않습니다.

개발 단계 릴리스 검증

다음 명령은 개발 후보 패키지 검증용이며, 공식 릴리스를 의미하지 않습니다:

# 普通 CI：干净安装、构建、测试、契约、扫描和高危依赖审计
npm run verify:release:ci

# 开发候选包的完整验证步骤
npm run test:live:release
npm run test:live:dashboard:release
npm run release:evidence
npm run verify:release

공식 릴리스 전에 깨끗하고 커밋된 후보 버전에서 Direct Creator Live, Dashboard Creator Live, SBOM, 체크섬 및 provenance를 완료하고, 유지보수자의 명시적 릴리스 승인을 받아야 합니다. dist/release/ 및 dist/release/release/는 모두 생성 산출물이며 Git에 포함되지 않습니다.