Cocos MCP Server 0.0.1-dev.0 (Development Version)

Current branch: develop · Current status: in development · No official release version currently

Package version is 0.0.1-dev.0; protocol and Tool contract version remains 0.0.1.

A local multi-project MCP extension for Cocos Creator 3.8.8. Cocos Dashboard handles project creation, import, Creator version selection, and launch; the Worker in the extension registers with the local Manager, the Agent only connects to the Manager, and explicitly provides projectId in each project-level call.

Development Status

• Code and verification work is based on the develop branch; main is not the current development branch.

• The current package is a development version and cannot be distributed directly as an official release package.

• Package version 0.0.1-dev.0 indicates the current development pre-release state; the protocol, Schema, and Tool contracts still use 0.0.1.

• Commands such as verify:release and build:release are release gates and candidate package verification tools during the development phase; passing them does not mean an official release has been published.

• Before the official release, a clean candidate version, Direct Creator Live, Dashboard Creator Live, and a closed release evidence loop are still required.

Related MCP server: mcp-bridge

Core Boundaries

• Version: package 0.0.1-dev.0; protocol/contract 0.0.1; release status development

• Connection: http://127.0.0.1:38488/mcp

• Transport: MCP Streamable HTTP

• Agent connection: no authentication; only loopback addresses and valid Host/Origin are allowed

• Project launch: user projects can only be launched through Cocos Dashboard; only Direct Creator Live starts and terminates the Runner's own temporary Fixture, and never touches user projects

• Multi-project: one Manager routes multiple started Workers; the Manager automatically exits when the last Worker goes offline and there are no pending startups

• Write operations: pre-check, revision comparison, execution, read-back verification, partial change reporting

• Not provided: transactions, automatic rollback, file backups, MCP operation history, or audit logs

Development Installation

npm install
npm run build

Place the extension directory into the target project:

<project>/extensions/cocos-mcp-server

Then through Cocos Dashboard:

1. Import or select the project;

2. Select Cocos Creator 3.8.8;

3. Launch the project;

4. Wait for the extension Worker to register with the Manager.

Do not launch user projects by directly executing the CocosCreator executable; this bypasses Dashboard's version and login context. Direct Creator Live only applies to the Runner's own disposable temporary Fixture.

Agent Connection

MCP client connection:

http://127.0.0.1:38488/mcp

Example configuration:

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

Recommended flow after connecting:

1. MCP initialize;

2. MCP tools/list to discover the Tools and Schemas registered with the Manager;

3. Call system_control.list_projects;

4. Select the target projectId;

5. Before generating an execution plan, the Agent prompts for the scope and impact that require player confirmation, based on Action metadata;

6. Execute write operations serially per project and check the returned revision, verification, and ChangeManifest.

The Cocos panel does not handle approval, and MCP does not issue approval tokens. Approval prompts remain uniformly in the Agent context.

Dirty Scenarios

Only supported:

reject
save

Default is reject. discard is not supported; unsaved modifications will not be silently discarded.

Common Commands

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 is used for development-phase verification and does not replace the complete evidence required for an official release.

Direct Temporary Fixture Mode (Default)

The default mode of npm run test:live is Direct: the Runner copies the read-only Fixture, then directly executes Creator -nologin only on the copy created this time, and only sends SIGTERM to the temporary Creator child process it tracks itself. It does not launch, save, close, or terminate any user project.

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 Temporary Fixture Mode

Dashboard mode also only prepares the Runner's own temporary Fixture, but does not directly launch or close Creator; the Runner outputs the manifest and absolute project path, and the operator imports, launches, and exits these temporary projects in Cocos Dashboard.

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

Attach Mode

Attach only connects to temporary Fixtures that have been launched through Dashboard and explicitly registered in the Runner manifest; it is a read-only acceptance mode.

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

To attach to a current Dashboard run, the manifest generated by that run must be explicitly specified; the Runner does not scan directories or silently select the "latest" 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

Repository Documentation

• Current Contract Summary

• Development Status and Branch Conventions

• Change Log

• Security Notes

Contract snapshots, test fixtures, and implementation code are all stored in this repository; there is no dependency on relative-path documentation in the Cocos parent project.

Troubleshooting

Manager Unavailable

Confirm that at least one project launched through Cocos Dashboard is still online. The Manager does not run as a resident project manager; it automatically exits when there are no Workers and no pending startups.

Project Does Not Appear

• Confirm the Creator version is 3.8.8;

• Confirm the project contains the built extension;

• Check that projectId in settings/cocos-mcp.json matches the current project identity;

• Do not open two projects with the same projectId but different paths at the same time.

Port Change Does Not Take Effect Immediately

While the Manager is running, it only updates the desired port and does not restart online. Exit all projects through the visible Cocos GUI, wait for the last Worker to unregister and the Manager to exit automatically; after launching the project again from Dashboard, the new Manager will use the new port.

Write Operation Failed

Check first:

• Whether projectId is correct;

• Whether the permission category allows it;

• Whether the path is within the project scope;

• Whether expectedRevisions is stale;

• Whether the current Scene/Prefab is Dirty;

• Whether Creator AssetDB, Scene, or compilation state is ready.

Recovery is handled by the Agent Session and Git; MCP does not implement transactions or automatic rollback.

Development-Phase Release Verification

The following commands are used to verify development candidate packages and do not represent an official release:

# 普通 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

Before the official release, Direct Creator Live, Dashboard Creator Live, SBOM, checksums, and provenance must be completed on a clean and committed candidate version, and the release must be explicitly approved by the maintainer. dist/release/ and dist/release/release/ are both build artifacts and are not included in Git.