cocos-mcp-server and the opcode design behind its 50 editor tools

What the Cocos Creator MCP plug-in actually exposes to an AI client

Cocos Creator scenes are `.scene` files full of UUIDs, `__id__` references and property ordering that the engine is picky about. Getting an AI assistant to produce valid ones means either teaching it the file format or giving it a hand to the live editor. This project takes the second route: a plug-in that runs inside Cocos Creator and speaks the Model Context Protocol, so a client such as Claude CLI or Cursor can open a scene, create nodes, mount scripts, edit prefabs and read logs through tool calls rather than through text.

The audience is specific. It is not game players and not engine developers who prefer the inspector; it is teams and solo developers who have already decided to let an agent perform editor operations, and who want those operations to go through the engine rather than around it. The README's framing is one-click install and one-click start, with the qualifier that Claude CLI and Cursor have been tested and other editors are described as theoretically supported.

The scope is also specific to a version range. The README targets Cocos Creator 3.8 and above, and the manifest is more precise, declaring an `editor` field of `>=3.8.6` along with a development dependency on `@cocos/creator-types` at `^3.8.6`. The v1.5.4 changelog entry repeats that it is compatible with 3.8.6 and every version above it. If your project is on 3.7 or on 2.x, this plug-in is not the answer, and the same vendor's 2.x Pro plug-in is a separate product that the README describes as aimed at live 2.x projects.

Opcode plus argument: how 150 tools became 50

The design decision in the open-source build is the tool shape, and the v1.5.4 changelog entry describes it plainly. The previous generation of 150 or more tools was consolidated and reorganised into 50 core tools, with redundant code removed. Every tool now follows an opcode plus parameter pattern, and the README's wording is that this simplifies the calling flow, raises the success rate of AI calls, and cuts token consumption by 50 percent.

The naming convention makes the consolidation visible: tools are named category underscore operation, with a unified schema and support for switching between multiple opcodes through an `action` field. A create, update and delete of a node are one tool with three actions rather than three tools. The categories listed in the README cover scene management, node query, lifecycle and transform, component management, script and query, prefab browse, lifecycle and instance, asset management and analysis, project management and build, the debug console and logs, preferences, server info, and a broadcast message tool.

The concrete call looks like this, and it is the example the README gives:

{
  "tool": "node_lifecycle",
  "arguments": {
    "action": "create",
    "name": "MyNode",
    "parentUuid": "parent-uuid",
    "nodeType": "2DNode"
  }
}

A model that has seen the tool list once can drive every node operation from that single shape. Whether the 50 percent token figure holds for your prompts is a separate question, since it is a claim in the changelog rather than a measurement you can inspect, but the direction of the change is the right one: fewer schemas to read means less of the context window spent on tool descriptions.

Which of the twelve capability modules the open-source build actually has

The README documents twelve capability modules with operation counts, but the counts belong to the Pro tier, not to the open-source repository. The Pro build is described as sixteen intent-level tools covering 231 operations across those twelve modules, using Streamable HTTP instead of plain HTTP. The open-source build is the fifty-tool version on HTTP, and the comparison table in the README is explicit about what the open-source column lacks.

Marked unavailable in the open-source version: opcode methods, one-click client configuration, tool customisation, one-shot scene creation, the built-in knowledge base, and the animation and Spine system with its 39 animation operations. The Pro column marks all of them present. The twelve module names themselves, scene management, node operations, component system, prefabs, assets, editor control, scene view, UI and templates, animation, knowledge base, verification and snapshots, and fonts and labels, are presented as the shared taxonomy of the family, so treat the operation counts as Pro figures.

That matters when you plan an adoption. Scene and node work is the core of what is here. Animation editing, including Spine skeletal animation management, is not in the open-source build, which rules the plug-in out for a team whose agent work is mostly animation. The built-in knowledge base, which the README describes as a queryable set of component property tables, UI design rules, coordinate system rules and layout patterns, is also Pro-only, so an agent on the open-source build has the tools but not the documentation sidecar.

Building the plug-in: tsc, dist/panels/default, and no one-click setup

The install story for the open-source build is a build story. The manifest is small and readable: `name` is `cocos-mcp-server`, `version` is `1.5.4`, `author` is LiDaxian, and the entry point is `./dist/main.js`. Three scripts exist, and one of them runs before install:

"editor": ">=3.8.6",
"main": "./dist/main.js",
"build": "tsc",

`npm run build` invokes `tsc`, and `npm run watch` invokes `tsc -w`. A `preinstall` script runs `node ./scripts/preinstall.js`, which is presumably where the editor-side setup happens, though the README does not document what that script does. Both `source/` and a committed `dist/` are present at the top level, and the panel contribution points into the compiled output, so what the editor loads is the build result rather than the TypeScript.

The panel is a dockable Cocos Creator extension panel with a minimum size of 400 by 300 and a default of 600 by 500, using an icon at `./static/icon.png`. Its title, its menu label and its description are all i18n keys such as `i18n:cocos-mcp-server.panel_title` and `i18n:menu.extension/Cocos MCP Server`, and the `i18n/` directory plus ten translated README files at the repository root are what back them. Menu messages map to three editor methods, `openPanel`, `openToolManager` and `startServer`, with a `stop-server` entry alongside them, so server start and stop are driven from the panel rather than from a command line.

The honest limitation is the client side. One-click configuration of AI clients is marked as unavailable in the open-source version, and the README excerpt does not give the JSON you need to paste into a client such as Cursor. Expect to write that configuration yourself from the server's own address and transport.

Path resolution, the two second cache, and snapshot rollback

Three of the listed smart features are worth more than the rest for anyone letting an agent write to a live scene.

The first is path resolution. Every node parameter accepts a UUID, a path such as `Canvas/Panel/Button`, or a plain name, and resolves it automatically. An agent that guesses a name gets a helpful miss instead of a new object created in the wrong place, which is the failure mode that makes scene-editing agents dangerous. The second is automatic UI detection: when a node is created under a UI parent, `cc.UITransform` is added for you, which removes a class of malformed nodes that only show up as invisible layout problems later.

The third is the cache, and the number is worth noting precisely. The node tree is cached with a two second time to live to avoid repeated queries, and the cache is invalidated automatically after a change operation. Two seconds is short enough that an agent doing read-then-write in consecutive calls is unlikely to act on a stale tree, and long enough that a burst of introspection calls does not each re-walk the hierarchy.

The fourth is atomicity. Builder and composite operations use a snapshot mechanism with automatic rollback on failure, which is the correct design for a composite call that touches a prefab or a whole UI tree. The same feature set includes a scene builder that constructs a complete node hierarchy from a JSON description in one call, handling the Canvas, camera and component configuration, and a reference image system that overlays a design mock-up in the scene view so the agent can build against it. Those last two are the sort of feature that turns a tool from a remote control into a workflow, and both are worth checking against your own process before you assume they are there in the version you install.

Driving a live editor versus editing scene files directly

The real alternative to an MCP plug-in like this is to let the agent edit the project files. A `.scene` file, a `.prefab` file and the `.meta` files that carry UUIDs are all text, and a capable model with a file-editing tool can write them. The difference in approach is where the serialisation knowledge comes from.

When the agent goes through the editor, the engine does the serialising. Asset creation goes through the asset database, references resolve through the engine's own UUID handling, and property order matches what the editor expects because the editor wrote it. When the agent edits files, all of that becomes the agent's responsibility, and the v1.4.0 changelog entry is a catalogue of what goes wrong. Internal prefab references must be converted to the `{"__id__": x}` form while external references are set to `null` and asset references keep their full UUID; object creation order has to match the engine's standard format; component property order and format have to be right or the engine throws `Cannot read properties of undefined (reading '_name')` or `placeHolder.initDefault is not a function`. The same entry records that the prefab creation problem was only fully fixed by matching the format of a manually created prefab exactly.

There is a second difference. Direct file editing works headlessly, which means it runs in CI on a machine with no editor, while a plug-in like this needs Cocos Creator 3.8.6 or above running with a panel open. For a team that wants generated scenes in a pipeline, that can be decisive. For an interactive assistant sitting next to a designer, the live editor is the only option that shows the result immediately, and the snapshot rollback is what makes an agent's mistake recoverable at all.

No declared licence, no releases, and a README that sells the Pro tier

Three facts about the repository itself matter more than most of the feature list.

First, licensing is undeclared. The licence field for this repository is unknown, and the top-level entries are `.gitignore`, `@types/`, ten translated READMEs, `base.tsconfig.json`, `dist/`, `i18n/`, `image/`, `package-lock.json`, `package.json`, `scripts/`, `source/`, `static/`, a file named `tsconfig copy.json` and `tsconfig.json`. There is no `LICENSE` file in that list. In the same README, the vendor's Godot plug-in is described as completely free and MIT open source, so the absence here looks like an omission rather than a deliberate choice, but that is an inference and not something to build on. Anyone shipping a game with this plug-in in their editor pipeline should ask the author before treating the code as theirs to modify.

Second, there are no GitHub releases. The only version marker is the `1.5.4` in `package.json`, and the changelog lives inside the README rather than in a `CHANGELOG.md`. The one datable entry is v1.4.0 on 2025-07-26, which fixed prefab creation, normalised the component and script removal API, and added the UUID mapping work.

Third, the README is largely a sales page. Large sections promote a Pro tier at version 1.7.8, a design studio, a background removal service and a pricing page, and the emoji-laden headers and tables about intent-level tools are about that product, not about the fifty tools in this repository. The last push to the repository was on 2026-07-08 and it is not archived, so the open-source code is being touched, but the documentation you are reading is a product page with a changelog appended. The part worth your time is the opcode convention, the tool category list, and the two changelog entries that record what broke and what was fixed.

Editorial conclusion

Adopt cocos-mcp-server if your team drives Cocos Creator from an agent today and can accept configuring the AI client by hand, since the one-click client setup listed in the comparison table is marked as unavailable in the open-source build. Do not vendor it into a shipped product until the licence question is settled, because no LICENSE file appears among the top-level entries and the licence field is undeclared. Verify first by reading the v1.5.4 changelog entry for the opcode migration, running npm run build to produce dist/main.js, and confirming the component removal path still requires a cid as described in the v1.4.0 notes.

Frequently asked questions

Official sources

1. DaxianLee/cocos-mcp-server on GitHub
2. Issues
3. README