# cocos-mcp-v2-ui

MCP server (UI-design tools) for **Cocos Creator 2.x** (verified on 2.4.11), built as an
editor package. It lets an MCP client (Claude Code) drive the editor to build UI —
ideal for translating a Figma design into a Cocos scene: read the design with the Figma
MCP, then create nodes/components/sprites/prefabs here.

Ported (not mechanically) from the 3.8.x `cocos-mcp-server`. 2.x differs fundamentally:
the scene bridge is the callback-based `Editor.Scene.callSceneScript`, node size/anchor
live on the node (no `UITransform`), and the package is plain CommonJS.

## Architecture

```
Claude Code ──stdio(MCP)──▶ bridge/  ──HTTP /rpc──▶ editor package (main proc)
                          (system Node,            core/server + registry + tools
                           @modelcontextprotocol)        │
                                                          ▼  Editor.Scene.callSceneScript
                                                   scene.js (scene proc, cc.* live)
```

- **Editor package** (`main.js`, `core/`, `tools/`, `scene.js`, `scene/`) runs inside
  Cocos Creator. `main.js` starts an HTTP server (`core/server.js`) exposing
  `GET /health`, `POST /rpc {tool,args}`, `GET /tools`, and a stateless `POST /mcp`.
- **Bridge** (`bridge/`) is a separate Node process Claude spawns. It speaks the MCP
  protocol over stdio (via the official SDK) and proxies `tools/list`+`tools/call` to the
  editor's HTTP `/tools`+`/rpc`. Keeping MCP-spec compliance out of the editor's old Node.
- **Single-responsibility / DRY**: tool modules are thin (schema + delegate). Everything
  crossing into the scene goes through one `core/scene-bridge.js#callScene`; one
  `core/response.js` shape; scene-side has one `resolveNode`, one `serialize`, one
  `applyTransform`.

## Install

1. Symlink (or copy) this folder into the project's `packages/`:
   ```
   ln -s /Users/nguyennt/Documents/MCP/cocos-mcp-v2-ui \
         /Users/nguyennt/Documents/Cocos/testMCP/packages/cocos-mcp-v2-ui
   ```
2. Install the bridge deps once: `cd bridge && npm install`.
3. Open the project in Cocos Creator 2.4.x. The package auto-starts the server on
   **port 8585** (`autoStart: true`). Panel: menu **Extension → Cocos MCP v2 UI**.

## Connect to Claude Code

```
claude mcp add cocos-ui --transport stdio -- \
  node /Users/nguyennt/Documents/MCP/cocos-mcp-v2-ui/bridge/bin/cocos-ui-bridge.js --port 8585
```
Verify: `/mcp` in Claude lists `cocos-ui` connected and the 32 tools. The editor must be
running with a scene open for scene tools to work (otherwise they return `No active scene`).

## Tools (32)

| Category | Tools |
|---|---|
| ping | `ping` |
| scene | `get_current_scene`, `get_scene_hierarchy`, `open_scene`, `save_scene`, `capture_node` |
| node | `create_node`, `create_node_tree`, `get_node_info`, `find_nodes`, `set_node_transform`, `set_node_property`, `set_node_properties_batch`, `set_sibling_index`, `delete_node`, `duplicate_node` |
| component | `add_component`, `set_component_property`, `get_components`, `set_component_reference`, `add_click_event`, `set_label_style`, `apply_widget`, `draw_rounded_rect`, `apply_gradient` |
| asset | `import_asset`, `query_asset_uuid` |
| prefab | `create_prefab`, `instantiate_prefab` |
| referenceImage | `add_reference_image`, `set_reference_image_data`, `remove_reference_image` |

### Highlights (added per build-experience feedback)
- **`color` is forgiving**: `set_component_property`/`set_node_property`/tree specs accept `{r,g,b,a}`,
  `[r,g,b,a]`, or a hex string (`"#161718"`).
- **`create_node_tree`**: build an entire node + component + property subtree in ONE call (returns uuids).
- **`capture_node`**: render a node/Canvas to a PNG on disk so the agent can see and self-correct.
- **`draw_rounded_rect`**: native rounded backgrounds/borders via `cc.Graphics` — no texture hacks.
- **`apply_gradient`**: bakes a rounded gradient PNG and binds it as a spriteFrame — real gradient
  buttons/badges (`cc.Graphics` fill is solid-only).
- **`set_component_reference`** + **`add_click_event`**: wire `ScrollView.content`, `Widget.target`,
  button handlers, etc.
- **Enum names**: enum props accept names (`type:"VERTICAL"`, `sizeMode:"CUSTOM"`) as well as numbers.
- **`import_asset`** auto-creates the destination folder, auto-rasterizes SVG-content files, and fails
  loudly instead of silently importing nothing. **spriteFrame** assignment now preserves node size.

MCP tool name = `<category>_<method>` (e.g. `node_create_node`,
`referenceImage_add_reference_image`).

## Figma → Cocos workflow

1. Read the design with the Figma MCP (positions, sizes, colors, text).
2. `scene_get_scene_hierarchy` → find the `Canvas` uuid.
3. (optional) export a screenshot from Figma → `asset_import_asset` →
   `referenceImage_add_reference_image { spriteFrameUuid }` to trace it.
4. `node_create_node` per element → `component_add_component` (`cc.Sprite`/`cc.Label`/
   `cc.Button`/`cc.Widget`/`cc.Layout`) → `component_set_component_property`
   (string, fontSize, color, spriteFrame) → `node_set_node_transform` to place/size.
5. For images: `asset_import_asset` returns **`spriteFrameUuid`** — pass that to
   `set_component_property property:"spriteFrame"` (it persists; the texture uuid does not).
6. Reusable bits: `prefab_create_prefab` → `prefab_instantiate_prefab`.
7. `scene_save_scene`.

## Notes & limitations (2.x specifics)

- **`capture_node` framing (edit-mode)** — in the editor (not Play), only a screen-aligned camera
  renders to an off-screen texture; a custom orthographic projection comes back blank. So `capture_node`
  renders through the scene's game camera at the scene's **design resolution**. It captures correctly
  when the UI is authored at that design resolution; a node much larger than the design resolution is
  framed to the design-res region (not the whole node). Tip: set the scene's design resolution to your
  screen size (e.g. 1080×2400) for full-screen captures.
- **One render component per node (2.x)** — `cc.Sprite`, `cc.Graphics`, `cc.Label`, `cc.RichText`
  all derive from `cc.RenderComponent` and are **mutually exclusive** on a node. So a node can't have
  both `draw_rounded_rect` (Graphics) and `apply_gradient`/`spriteFrame` (Sprite). This is an engine
  rule, not a tool bug — `add_component` reports the exact conflict, and `apply_gradient` auto-applies
  to a child node when the target already has a render component.
- **Reference image is simulated** — Cocos 2.x has no native reference-image gizmo. We add
  a low-opacity `Sprite` node `__ReferenceImage__` behind the UI. Remove it before shipping
  (`remove_reference_image`); it is a real scene node.
- **Editor Hierarchy/Inspector may not refresh instantly** after mutations made through the
  cc runtime — the live scene/canvas does update; reselect a node or reload the scene to
  refresh the panels. Not a tool failure.
- **No main-process hot-reload** in 2.4.x: editing `main.js`/`core/`/`tools/`/`scene/`
  during development requires a full editor restart (Developer → Reload Editor). At runtime
  this is irrelevant — the server starts on project open.
- **spriteFrame**: importing a PNG yields a texture *and* a `sprite-frame` sub-asset. Bind
  the **sub-asset** uuid (returned as `spriteFrameUuid`). Passing a texture uuid is handled
  as a best-effort wrap but does not persist on save.
- Verified editor IPC (2.4.11): save `scene:stash-and-save`, open `scene:open-by-uuid`,
  asset query/import `asset-db:query-uuid-by-url` / `asset-db:import-assets`, prefab create
  `scene:create-prefab` (url, serialized-content) via the `_Scene.PrefabUtils` recipe.

## Tests

- **Unit** (pure logic — colors, enums, PNG encoder, gradient, SVG sniff; no editor needed):
  ```
  node test/unit.test.js
  ```
- **Integration** (error/edge paths for the scene & component tools; needs the editor running with a
  scene open — creates a temp container node and deletes it afterwards):
  ```
  node test/integration.test.js --port 8585
  ```
- See `test/manual-checklist.md` for the per-tool manual verification steps.