Kiro Cocos Accelerator

English | 繁體中文 | 简体中文 | 日本語 | 한국어

Note on language availability: README files are available in 5 languages to support our global community. Steering files (domain knowledge) are in Traditional Chinese with English summary sections. The Power responds in the developer's preferred language. If you encounter any language barriers, please open an issue for community support.

Transform your IDE into a Cocos Creator development AI assistant. Use natural language to command Cocos Creator Editor via MCP (Model Context Protocol). This Power covers scene management, node/component operations, prefab workflows, asset management, build automation, performance analysis, code quality checks, and more — with a verified MCP tool surface, 14 domain knowledge files, and a capability layer that works across two different open-source Cocos MCP servers.

Two supported servers, verified 2026-07-27.

Server	Tool surface	License
DaxianLee/cocos-mcp-server, open-source edition, main (v1.5.x)	51 advertised, 55 callable	Source-available; the author restricts commercial use and resale — read the LICENSE before shipping a commercial title
FunplayAI/funplay-cocos-mcp	39 in core, 105 in full	MIT

The two servers name tools differently — double-prefixed and opcode-driven (scene_scene_management) versus flat (create_node) — and cover different capabilities. This Power detects which one is connected and routes through capability ids, so the same workflow runs on either. Tool names from cocos-mcp-server ≤ v1.4 no longer resolve; if you are upgrading from an earlier release of this Power, update any custom prompts and hooks.

Capabilities missing from a given server are documented with their workaround in POWER.md (Capability Boundary) rather than silently attempted. Nothing here claims a capability the connected server does not have.

Key Concepts:

• MCP (Model Context Protocol): A standardized protocol for AI assistants to communicate with development tools • Node: The basic building block in Cocos Creator's scene hierarchy • Component: Functional modules attached to nodes (Sprite, Label, Button, etc.) • Prefab: Reusable node templates that can be instantiated across scenes • cc.Component: Base class for all Cocos Creator script components • NodePool: Object pooling system for efficient node recycling

Features

• Scene Management — Create, open, save, list scenes; generate complete scene structures from templates
• Node & Component Operations — Create/delete/move nodes, add components, set properties, manage hierarchy
• Prefab Workflow — Create prefabs from nodes, instantiate, validate, duplicate, revert
• Asset Automation — Batch import, search, importer meta settings, dependency inspection
• Build Automation — Multi-platform builds (Web/iOS/Android/Windows/Mac), preview, build status monitoring
• Performance Analysis — Code anti-pattern scanning (10 patterns), scene-scale counters, optimization advice
• Code Quality — Circular dependency detection, coupling analysis, event leak detection, refactoring suggestions
• UI Dependency Analysis — Cross-file reference tracking, event chain analysis, Mermaid diagram output
• Cross-Platform Compatibility — Texture format checks, memory budget validation
• Editor Extension Generation — Generate editor extensions with panels, menus, lifecycle hooks
• Component Template Generation — TypeScript component scripts with decorators, properties, lifecycle methods
• Diagnostics — Connection health check with failure classification and remediation, tool-surface drift detection, build log parsing ranked by root-cause likelihood, platform budget checking that separates measured from derived numbers
• Scene Builder — Compiles a scaffold into a reviewable, snapshot-guarded call plan (parents before children, batched typed property writes, rollback on failure)
• Animation Authoring — Builds AnimationClips through the documented engine API on servers that have no animation tools
• Scene-Script Bridge — Generates a small project extension that adds animation authoring, scene stats and scene validation where the server lacks them

Architecture

Developer (Natural Language)
    → AI Layer (Intent Understanding & Planning)
        → Capability Layer (server detection + routing + preflight)
            → MCP Protocol
                → Cocos Creator Editor (Execution Layer)

Cocos Accelerator (Intelligence Layer)
├── POWER.md        → Tool surface, capability routing, workflows (single source of truth for tool names)
├── steering/       → 14 domain knowledge files (capability ids, never tool names)
├── templates/      → 29 JSON templates (6 categories)
└── src/            → TypeScript modules, incl. src/adapters/ (capability layer)

Why a capability layer

Two servers, two naming schemes, and a plugin that renamed every tool between v1.4 and v1.5. Workflows are therefore written against capability ids (node.create, validate.scene) and each adapter binds them to whatever the connected server exposes — or declares the capability unsupported with a documented workaround. Consequences that matter in daily use:

• A missing capability is reported before a batch starts, not discovered as an Unknown tool halfway through building a hierarchy.
• Batches run under a scene snapshot where the server has one. Where it does not, you are told the batch is not automatically reversible before it runs.
• create_node is a current tool on one server and a removed name on the other, so calls are never rewritten across servers.

Prerequisites

• Cocos Creator 3.8.6+ installed with a project open
• Kiro IDE installed
• Node.js 18+ (for development/testing of this Power only)

Installation

Step 1 — Install this Power in Kiro

Open Kiro → Left panel click Powers icon → Click "+" → Select "Add Custom Power" → Select this project's root directory

Step 2 — Install an MCP server extension in Cocos Creator

Pick one. Both are open source and both work with this Power; they differ in capabilities and license (see the table at the top).

Option A — cocos-mcp-server (open-source edition)

From the Cocos Store or GitHub:

1. Copy the plugin into your project's extensions/cocos-mcp-server/ folder
2. Before a first install or an upgrade, delete <project>/settings/mcp-server.json and <project>/settings/tool-manager.json — the plugin author documents that stale files make the tool list render incorrectly
3. Cocos Creator → Extensions → Cocos MCP Server → Start Server
4. Confirm the status indicator is green

Strengths: scene snapshots (reversible batches), importer meta writes, reimport, asset manifest, headless build trigger, reference-image overlay. Gaps: no animation tools, no scene/asset validation, no screenshots, no arbitrary code execution.

Option B — funplay-cocos-mcp (MIT)

From the Cocos Store or GitHub:

1. Copy the plugin into your project's extensions/funplay-cocos-mcp/ folder
2. Cocos Creator → Funplay → MCP Server
3. Use the built-in one-click client configuration and choose Kiro
4. Switch the tool profile to full if you need animation, node editing or prefab tools — the default core profile hides them

Strengths: execute_javascript (scene and editor contexts), scene/asset/prefab validation, animation tools, screenshots, TypeScript diagnostics. Gaps: no scene snapshot, so batches are not automatically reversible; no importer meta writes; no headless build trigger.

You can install both. The Power will tell you it detected two and ask which to drive, because rollback behaviour differs.

Step 3 — Configure MCP Connection

Edit mcp.json or .kiro/settings/mcp.json.

For cocos-mcp-server (default port 3000):

{
  "mcpServers": {
    "cocos-creator": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

For funplay-cocos-mcp (default port 8765) — its panel can write this for you:

{
  "mcpServers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

Security Note: HTTP is used intentionally. These endpoints talk only to the Cocos Creator Editor on localhost. Traffic never leaves your machine. Note that execute_javascript on funplay runs code inside your editor process; its safety checks are on by default and turning them off is a decision worth making deliberately.

Port: If you change the port in the extension panel, update mcp.json to match.

Step 3b — Optional: the scene-script bridge

Only needed on cocos-mcp-server, and only for animation authoring, scene stats or scene validation. Ask Kiro to "generate the Cocos bridge extension", copy the generated folder into <project>/extensions/kiro-cocos-bridge/, reload extensions, then ask it to "ping the bridge" to confirm. Without it, those three capabilities are simply reported as unavailable rather than half-attempted.

Step 4 — Install Auto-Guidance Hook (Recommended)

This hook ensures the AI automatically activates the Power and uses MCP tools correctly on every prompt:

mkdir -p .kiro/hooks
cp hooks/pre-cocos-tool.json .kiro/hooks/

Without this hook, you'll need to manually remind the AI to use MCP tools each time.

Verify Connection

Type any Cocos-related command in Kiro (e.g., "List all nodes in the current scene"). If the AI responds correctly, the connection is successful.

Usage

Once installed, just talk to Kiro in natural language. The AI will automatically activate the Power, select the right MCP tools, and execute operations in your Cocos Creator Editor.

Workshops

Two hands-on paths from an empty project to something that runs:

Workshop	Covers	Time
01 — UI Main Menu	Health check, scene creation, UI hierarchy from a scaffold, Label/Button configuration, click wiring, prefab extraction, preview	~30 min
02 — 2D Gameplay Prototype	Movement script, 2D physics groups and collision callbacks, animation authoring, NodePool spawning, platform budget, build with parsed failures, drift check	~60 min

Both teach the failure modes that produce no error message — missing cc.UITransform, stale UUIDs, unpaired event registration, physics group masks, and importer meta that silently reverts.

Getting Started (First Time)

After completing installation, open your Cocos Creator project, then open Kiro and try:

1. Check your project status:

Show me the current scene info

2. List scene nodes:

List all nodes in the current scene

3. Create something:

Create a 2D node called Player with a Sprite component under Canvas

4. Modify the scene:

Move Player to position (100, -200)

What Can You Ask?

Category	Example Commands
Scene	"Create a new scene called GameLevel1", "List all scenes", "Open the main scene", "Save the scene"
Nodes	"Create a 3D node called Player", "Move Player to (10, 0, 5)", "Delete the HelloKiro node", "Duplicate soldier node"
UI	"Create a Canvas with a Label showing 'Score: 0' at font size 48", "Add a red health bar at top-right", "Build a main menu with title and start button"
Components	"Add a WASD movement script to soldier", "Check what components soldier has", "Create a rotation script that spins 90°/sec"
Prefabs	"Save soldier as a prefab", "List all prefabs", "Instantiate grass.prefab at (5, 0, 3)"
Assets	"Search for all texture assets", "Create a scripts folder", "Find unused assets", "Validate all asset references"
Build	"Preview in browser", "Build for web-mobile", "Build Android debug version"
Performance	"Check for performance anti-patterns", "Show performance stats", "Generate optimization report"
Code Quality	"Analyze circular dependencies", "Check for event listener leaks", "Generate coupling report"

Example Workflow: Build a 2D Game Scene

1. "Create a new scene called MyGame, save to db://assets/scene/MyGame.scene"

2. "Open db://assets/scene/MyGame.scene"

3. "Build this structure under Canvas:
   - Background (cc.Sprite)
   - Player (cc.Sprite, position (0, -300))
   - ScoreLabel (cc.Label, text 'Score: 0', fontSize 40)
   - StartButton (cc.Button, text 'Start Game')"

4. "Save the scene"

5. "Save Player as a prefab to db://assets/prefabs/Player.prefab"

6. "Preview in browser"

Tips

• You don't need to remember any tool names or APIs — just describe what you want
• The AI will ask clarifying questions if your request is ambiguous
• For complex scenes, describe the hierarchy structure and the AI will create nodes in order
• If something goes wrong, say "undo" or describe what you want to fix
• For 2D nodes, positions use (x, y); for 3D nodes, use (x, y, z)

Development

npm install
npm run verify           # typecheck + lint + tests — run this before committing
npm test                 # All tests (139)
npm run test:adapters    # Capability layer and server detection
npm run test:engine      # Scene builder call plans and rollback
npm run test:generators  # Animation authoring and bridge extension
npm run test:coverage    # Tests with coverage
npm run lint             # ESLint
npm run typecheck        # tsc --noEmit
npm run build            # Emit dist/ (tests excluded)

Project Structure

kiro-cocos-accelerator/
├── POWER.md                    # Main document for the AI assistant
├── mcp.json                    # MCP Server connection config
├── steering/                   # Domain knowledge Steering Files (14)
├── templates/                  # Built-in templates
│   ├── presets/                # Asset Presets (6)
│   ├── scaffolds/              # Scene Scaffolds (6)
│   ├── build-configs/          # Build Configurations (6)
│   ├── platform-profiles/      # Platform Profiles (4)
│   ├── architecture-rules/     # Architecture Rules (3)
│   └── workflows/              # Workflow Templates (4)
├── workshop/                   # Hands-on tutorials (2)
├── src/
│   ├── adapters/               # Capability layer: server detection + routing
│   ├── mcp-tool-catalogue.ts   # Verified tool surface + legacy name resolver
│   ├── scene-builder.ts        # Scaffold → snapshot-guarded call plan
│   ├── animation-clip.ts       # Clip authoring without animation tools
│   ├── scene-script-gen.ts     # Bridge extension generator
│   ├── mcp-health.ts           # Connection health check + remediation
│   ├── drift-detection.ts      # Live tools/list vs documented surface
│   ├── build-log-parser.ts     # Build failures → ranked actionable items
│   ├── platform-budget.ts      # Platform profiles → measured/derived findings
│   └── …                       # Analysis, generation and template modules
├── hooks/                      # IDE hooks
├── .github/workflows/          # CI: typecheck, lint, test, build, doc guards
├── package.json
├── tsconfig.json
└── vitest.config.ts

Troubleshooting

Problem	Solution
Kiro says "fetch failed" or no response	The MCP server extension is not running. Start it from the extension's panel in Cocos Creator
Port already in use	Change the port in the extension panel and update mcp.json to match
Node operations not responding	Ensure a scene is open. Try "What scene is currently open?"
Wrong server assumed	Ask "which Cocos MCP server am I connected to?" — detection reads the live tool list. If both extensions are running, say which one to use
A tool is missing on funplay	Its default core profile exposes 39 of 105 tools. Switch to full in the Tool Exposure window
"This batch is not reversible" warning	Expected on funplay: it has no scene snapshot. Save the scene first, or use smaller steps
Animation request reported as unavailable	On cocos-mcp-server, generate the bridge extension (Step 3b). Correct behaviour — that server has no animation tools
Unknown tool: …	Wrong tool name. Advertised names are double-prefixed (scene_scene_management, not scene_create_scene), and pre-v1.5 names were removed. See POWER.md → MCP Tool Surface
validate_scene not found	Correct — the open-source edition has no scene validator. The validation category only contains JSON argument helpers. See POWER.md → Capability Boundary
asset_optimize always fails	Known plugin bug: advertised in tools/list with no handler. Use save_meta + reimport for texture settings
A tool is missing from tools/list	The plugin's Tool Manager panel can disable tools per project. Check the panel before assuming a version difference
Tests failing	Run npm test for detailed error messages
TypeScript type errors	Run npx tsc --noEmit; ensure npm install has been run

Security

See CONTRIBUTING for more information.

License

MIT License. See the LICENSE file.