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.