cocos-mcp-v3-ui

MCP server (UI-design tools) for Cocos Creator 3.8.x, 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 a 2.x cocos-mcp-v2-ui. 3.x differs fundamentally: the scene bridge is the Promise-based Editor.Message.request('scene','execute-scene-script'), node size/anchor/opacity/color live on components (cc.UITransform / cc.UIOpacity / the render component — not on the node as in 2.x), 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.Message.request
                                                             ('scene','execute-scene-script')
                                                   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. The server is loopback-only and rejects browser-originated requests (no Origin header, loopback Host only) so a web page cannot drive the editor (see isLocalRequest).

• 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 process.

• 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. Each mutating tool records an editor snapshot (undo + dirty flag).

Related MCP server: mcp-bridge

Install

1. Symlink (or copy) this folder into the project's extensions/ (or packages/):

   ln -s /Users/nguyennt/Documents/MCP/cocos-mcp-v3-ui \
         <your-cocos-3.x-project>/extensions/cocos-mcp-v3-ui

2. Install the bridge deps once: cd bridge && npm install.

3. Open the project in Cocos Creator 3.8.x. The package auto-starts the server on port 8585 (autoStart: true). Panel: menu Extension → Cocos MCP v3 UI → Open Panel.

Connect to Claude Code

claude mcp add cocos-ui --transport stdio -- \
  node /Users/nguyennt/Documents/MCP/cocos-mcp-v3-ui/bridge/bin/cocos-ui-bridge.js --port 8585

Verify: /mcp in Claude lists cocos-ui connected and the 36 tools. The editor must be running with a scene open for scene tools to work (otherwise they return No active scene).

Tools (36)

MCP tool name = <category>_<method> (e.g. node_create_node, referenceImage_add_reference_image). A category must not contain an underscore — dispatch splits on the FIRST underscore.

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).

• 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 preserves node size.

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 (3.x specifics)

• capture_node (edit-mode) — 3.x has no immediate-mode camera.render(node), so we render through a temporary off-screen cc.Camera + cc.RenderTexture framed on the node's world bounds, force a frame, then readPixels() (falls back to borrowing the scene camera). The scene side returns base64 RGBA (bottom-up); the main side flips + PNG-encodes to disk and returns the path. Works in edit mode at the node's own aspect; maxSize caps the longest side (default 720). You can also verify by DATA with get_scene_hierarchy / get_components.

• One render component per node (3.8.x) — cc.Sprite, cc.Graphics, cc.Label, cc.RichText all derive from cc.UIRenderer and remain mutually exclusive on a node (verified: adding cc.Sprite next to cc.Graphics throws a conflict error). So a node can't have both draw_rounded_rect (Graphics) and apply_gradient/spriteFrame (Sprite) — apply_gradient auto-routes to a child gradient_bg node when the target already has a render component, and add_component surfaces the engine's conflict message.

• Reference image is simulated — Cocos has a native reference-image gizmo, but to keep the workflow 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 refresh on the next reselect/reload after raw-runtime mutations. Each mutating tool records a snapshot (so undo works and the scene is marked dirty); the live scene/canvas updates immediately.

• No main-process hot-reload: editing main.js/core//tools//scene/ during development requires a full editor restart (Developer → Reload Extensions/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). In 3.x these sub-assets have stable uuid suffixes (<uuid>@f9941 spriteFrame, <uuid>@6c48a texture); assetdb.importFiles verifies them via asset-db:query-url before returning.

• Verified editor messages (3.8.x): scene execute-scene-script / save-scene / open-scene / snapshot; asset-db:query-uuid / query-url / import-asset / create-asset / refresh-asset. Prefab create uses the scene create-prefab message where available, with a manual drag-to-Assets fallback.

Security

The HTTP server binds 127.0.0.1 and only serves loopback requests that carry no Origin header (i.e. the Node bridge, not a browser). This prevents a malicious web page from POSTing to http://127.0.0.1:8585/rpc to drive the editor or write files, and the loopback Host check blocks DNS-rebinding. Do not expose the port beyond localhost.

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.