# Cocos MCP

A Cocos Creator 3.8.x MCP bridge for code agents. The editor extension runs a local TCP socket server, and a Python MCP server (stdio) forwards tools over that socket. This mirrors the Blender MCP architecture.

## Architecture
- **Editor extension (TS)**: `packages/cocos-mcp` starts a TCP server inside Cocos Creator.
- **MCP server (Python)**: `python/src/cocos_mcp_server/server.py` exposes tools over stdio and talks to the editor socket.

```
MCP Client (Claude Code / Cursor)
    ↕ stdio (MCP protocol)
Python MCP Server (cocos_mcp_server.py)
    ↕ TCP socket (JSON-RPC, port 8787)
Cocos Editor Extension (packages/cocos-mcp)
    ↕ Editor.Message / scene script APIs
Cocos Creator Engine
```

## Install (Editor Side)
1. Copy `packages/cocos-mcp` into your Cocos project:
   - Preferred: `extensions/cocos-mcp`
   - Legacy: `packages/cocos-mcp`
2. Restart Cocos Creator and enable the extension in Extension Manager.
3. Optional: set port via env var before launching editor:
   - `COCOS_MCP_PORT=8787`

If you change TypeScript, rebuild:
```sh
npx tsc -p packages/cocos-mcp/tsconfig.json
```

## Install (Python Side)
```sh
cd python && uv sync
```

## Run MCP Server
```sh
cd python && uv run cocos-mcp-server --host 127.0.0.1 --port 8787
```

## Claude Code Integration

Cocos MCP 完整支持 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) —— Anthropic 官方的 CLI 编程工具。连接后，Claude Code 可以直接通过自然语言操控 Cocos Creator 编辑器：创建/删除节点、修改属性、管理资源、搭建 UI、配置物理和动画等。

### 快速添加（发布到 PyPI 后）

```sh
claude mcp add cocos-mcp-server uvx cocos-mcp-server
```

### 自动发现

项目根目录包含 `.mcp.json` 配置文件。在此目录下启动 Claude Code 时会自动发现并连接 MCP 服务器，无需额外配置。

```sh
cd /path/to/cocos-mcp
claude
```

### 手动配置

也可以将配置手动添加到 Claude Code 的设置中：

**项目级别**（`.claude/settings.json`）：
```json
{
  "mcpServers": {
    "cocos-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/cocos-mcp/python", "cocos-mcp-server", "--port", "8787"]
    }
  }
}
```

**全局级别**（`~/.claude/settings.json`），适用于所有项目：
```json
{
  "mcpServers": {
    "cocos-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/cocos-mcp/python", "cocos-mcp-server", "--port", "8787"]
    }
  }
}
```

### 使用流程

1. 启动 Cocos Creator 并打开包含 `cocos-mcp` 扩展的项目
2. 确认编辑器控制台输出 `[cocos-mcp] TCP server listening on 127.0.0.1:8787`
3. 在终端启动 Claude Code
4. Claude Code 会自动连接 MCP 服务器，5 个路由工具（ping/execute/scene/assets/editor）立即可用

### 使用示例

```
> 列出当前场景的所有节点

> 创建一个名为 Player 的节点，位置设为 (0, 1, 0)

> 给 Player 节点添加一个 RigidBody 和 BoxCollider

> 在场景中创建一个 Button，文字为"开始游戏"

> 把 Player 节点保存为 prefab 到 db://assets/prefabs/Player.prefab

> 查找项目中所有 prefab 资源
```

### 其他 MCP 客户端

Cursor、Windsurf 等支持 MCP 协议的工具也可以使用相同的配置格式接入。

## Tools

当前是 **5 个路由工具**（旧版的 43 个平铺工具已收敛为 action 路由模型）：

- `ping()` – 连通性检查
- `execute(scope, code, args)` – 在 `scene` 或 `main` 作用域执行任意 JS
- `scene(action, params)` – 场景操作路由（节点 CRUD、组件、UI、动画、材质、物理等）
- `assets(action, params)` – 资产操作路由（查找、导入、移动、删除、依赖等）
- `editor(action, params)` – 编辑器操作路由（保存、打开场景、undo/redo、prefab 等）

**新增 action 的方式**：在 `python/src/cocos_mcp_server/server.py` 的映射表（`SCENE_ACTIONS` / `ASSETS_ACTIONS` / `EDITOR_ACTIONS` 等）登记，工具本身无需改动；可用 action 全集以映射表为准。

另有 3 个 MCP resources 提供参考文档：`cocos://reference/scene`、`cocos://reference/assets`、`cocos://reference/editor`。

**Python 侧入口**：`python/src/cocos_mcp_server/server.py`（编辑器扩展在 `packages/cocos-mcp/`）。

## 与 CelestialSphere 的同步

改完扩展（TS/Python）后，rsync 到宿主项目的扩展目录（对本目录的唯一 sanctioned 投放方式）：

```sh
rsync -av --delete --exclude .git \
  packages/cocos-mcp/ \
  /Users/wanghe/apps/engines/CelestialSphere/extensions/cocos-mcp/
```

## Troubleshooting

### "Failed to communicate with Cocos Creator"
- Make sure Cocos Creator is running and the project with the extension is open.
- Check that the extension is enabled in Extension Manager.
- Verify the port matches (default 8787). Check the editor console for `[cocos-mcp] TCP server listening on 127.0.0.1:8787`.

### Port already in use
- Another instance may be using port 8787. Set a different port:
  ```sh
  COCOS_MCP_PORT=8788 # set before launching Cocos Creator
  python python/cocos_mcp_server.py --port 8788
  ```

### Extension not loading
- Ensure `package.json` has `"package_version": 2` and `"editor": ">=3.8.0"`.
- The extension folder must be named `cocos-mcp` (matching the `name` field).
- Check the editor console for error messages.

### Scene operations return "No active scene"
- Open a scene in the editor before calling scene tools.

## Notes
- Asset operations map to common `asset-db` message names (e.g. `query-assets`). If your editor build differs, use `assets_request` with the exact method name.
- Scene modifications via MCP do not currently trigger the editor's undo system. Save your scene before making bulk changes.