# Cocos MCP Community

[English](README.md) | [简体中文](README.zh-CN.md)

A community-built [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) extension for Cocos Creator 3.8+. Connect a compatible AI client to inspect and operate the project currently open in Cocos Creator.

The extension runs locally, listens on `127.0.0.1`, and requires explicit confirmation for persistent or structural changes.

> Current version: `0.2.3`. The automated suite passes, and the main read and isolated-write workflows have been verified with Cocos Creator 3.8.8.

## Features

The server exposes 23 intent-oriented MCP tools. Each tool groups related actions so clients receive a focused tool list while retaining broad editor coverage.

| Tool | Capabilities |
| --- | --- |
| `project` | Read project information and asset summaries; query or update project configuration |
| `scene` | Inspect the active scene and hierarchy; open, save, or save as a scene |
| `node` | Find, inspect, create, update, duplicate, copy, cut, paste, reset, reparent, or delete nodes |
| `component` | List, add, remove, inspect, edit, or reset components; edit arrays and Button events; apply text styles |
| `asset` | Check AssetDB, list and inspect assets, read safe text assets, import, create, save, copy, move, refresh, reimport, or delete |
| `prefab` | List and inspect Prefabs, find usage, instantiate linked or unlinked copies, copy or delete assets, and restore instances |
| `snapshot` | Capture and restore hierarchy snapshots; begin, commit, or abort scoped structure transactions |
| `builder` | Create validated node trees or a complete Canvas/Panel/Title/Button UI screen atomically |
| `validation` | Check hierarchy and UI issues; validate references; analyze dependencies, cycles, missing items, and orphan candidates |
| `capture` | Capture structured layout data, a Camera-rendered PNG, or a cropped local Preview-canvas PNG |
| `animation` | Create, save, batch-generate, inspect, and incrementally edit AnimationClips; attach and control clips |
| `viewport` | Read design resolution and editor view state; focus or align nodes; configure 2D, grid, gizmo, and icon options |
| `editor` | Read editor context, selection, dirty state, readiness, Creator Console entries, project logs, and Preview errors |
| `preview` | Inspect Preview networking, start supported Preview targets, reload Preview, stop Game View, and click local Preview buttons |
| `ui` | Ensure a Canvas and create templates, Layout containers, dialogs, lists, navigation bars, or settings screens |
| `spine` | Assign Spine data and list, play, queue, or clear animations on `sp.Skeleton` components |
| `font` | List project fonts and apply a project font or system font to `cc.Label` |
| `reference_image` | List SpriteFrames and place an in-scene reference image from a project asset |
| `environment` | Inspect engine and native paths, devices, editor networking, programming settings, and plugins |
| `knowledge` | Search built-in Cocos workflow guidance by topic |
| `server` | Read local service status and recent operation metadata |
| `preferences` | Inspect, disable, enable, or reset the project-local tool selection |
| `client_config` | Generate client configuration for Claude Desktop, Cursor, VS Code, or Windsurf |

Additional workflow features include session-aware Streamable HTTP, tool-list change notifications, schema-validated inputs, confirmation gates, rollback-aware batch operations, and project-local tool presets.

## Requirements

- Cocos Creator `3.8` or later
- Node.js `18` or later
- npm
- An MCP client with Streamable HTTP support

## Installation and usage

### 1. Install the extension

Clone the repository into the Cocos project's `extensions` directory, install dependencies, and build:

```bash
cd /path/to/YourCocosProject/extensions
git clone <repository-url> cocos-mcp-community
cd cocos-mcp-community
npm ci
npm run build
```

Open the project in Cocos Creator. If the editor was already open, reload extensions or restart the editor.

### 2. Start the MCP server

Open **Extension → Cocos MCP Community** and select **Start server**. The default endpoint is:

```text
http://127.0.0.1:3100/mcp
```

The panel displays the active endpoint and server status. You can also change the project-local port or enable automatic startup.

### 3. Connect an MCP client

Add a Streamable HTTP server to the MCP settings of your client. The generic server entry is:

```json
{
  "type": "http",
  "url": "http://127.0.0.1:3100/mcp"
}
```

The surrounding configuration differs between clients. After the first connection, the `client_config` tool can generate complete entries for Claude Desktop, Cursor, VS Code, and Windsurf.

Restart or reconnect the MCP client after changing its configuration. If the server port is changed in the Cocos panel, update the client URL as well.

### 4. Verify the connection

Keep the target project and scene open in Cocos Creator, then ask the AI client for a read-only action such as:

```text
Summarize the current Cocos scene hierarchy.
```

```text
List the assets under db://assets and report any missing references.
```

```text
Check the current editor and Preview errors without changing the project.
```

If the client can return project or scene information, the connection is ready.

### 5. Use editing workflows

You can describe editor tasks in natural language. For example:

```text
Create a Canvas with a centered panel, a title, and a button in the current scene.
```

```text
Set the selected Label font size to 32 and change its text to "Play".
```

```text
Create an AnimationClip that moves the selected node from x=0 to x=300 in one second.
```

Persistent and structural changes require confirmation. A recommended workflow is:

1. Ask the client to inspect the current state and explain the planned change.
2. Review the target scene, nodes, assets, and paths.
3. Confirm the operation when the client requests permission.
4. Inspect the result in Cocos Creator and save the scene when appropriate.

Commit or back up important work before using mutation tools. Use a disposable scene and temporary assets for the first trial.

## Tool management

The extension panel contains two tabs:

- **Server** controls the port, automatic startup, and server state.
- **Tool management** provides individual tool toggles and All, Core workflow, UI workflow, and Minimal presets.

Reducing the exposed tool set decreases the MCP tool definitions sent to the client. The `preferences` recovery tool always remains available. Clients that support tool-list change notifications refresh automatically; reconnect older clients if their tool list stays unchanged.

Settings are stored per project in `library/cocos-mcp-community.settings.json`.

## Troubleshooting

- **The client cannot connect:** confirm that Cocos Creator is open, the extension is enabled, and the panel reports the server as running. Check that the client URL uses the same port.
- **The tool list is outdated:** reconnect the MCP client after saving Tool management changes.
- **A scene action fails:** open the target scene and try a read-only scene summary first.
- **An edit is rejected:** verify the target UUID or asset path and explicitly approve the requested write operation.
- **Port already in use:** choose another port between `1024` and `65535` in the Server tab, then update the client configuration.

## Development

```bash
npm install
npm run check
npm run build
npm run test:ci
```

| Command | Purpose |
| --- | --- |
| `npm run check` | Type-check without emitting build files |
| `npm run build` | Compile the extension to `dist/` |
| `npm run test:regression` | Run local regression checks |
| `npm run test:smoke` | Run regression and MCP transport/tool-discovery checks |
| `npm run test:ci` | Build and run the complete automated suite |

The smoke suite does not mutate a Cocos project. Write integration tests should use disposable scenes and temporary assets.

### Project structure

```text
src/main.ts                 Extension lifecycle and panel messages
src/server/                 MCP transport, sessions, and tool registration
src/cocos/editor-bridge.ts  Cocos Editor integration
src/scene.ts                Scene-process operations
src/tools/                  Schema-validated MCP tools
src/panels/default/         Dockable extension panel
scripts/                    Regression and smoke tests
```

## Contributing

Issues and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md), preserve confirmation gates for persistent edits, and include tests and documentation for user-facing changes.

## Acknowledgements

Thanks to the following open-source projects for reference and inspiration:

- [caravanglory/cocos-mcp-server](https://github.com/caravanglory/cocos-mcp-server)
- [DaxianLee/cocos-mcp-server](https://github.com/DaxianLee/cocos-mcp-server)

## License

Released under the [MIT License](LICENSE).

This is an independent community project and is not an official Cocos product. Cocos and Cocos Creator are trademarks of their respective owners.