# Cocos MCP Kit

**English** | [简体中文](./README_CN.md)

Cocos MCP Kit is an open-source extension that runs an MCP server inside Cocos Creator. It lets an MCP client inspect a project, work with scenes and assets, and verify results in the editor. It is built on [Funplay MCP for Cocos 0.6.3](https://github.com/FunplayAI/funplay-cocos-mcp) and has its own package, extension, and configuration identity.

The current target is Cocos Creator 3.8.x; the editor checks linked below were performed on **3.8.8**. Available tools are not a promise that every workflow or Creator version has been validated. See the [tool reference](./docs/TOOLS.md), [development plan](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/PLAN.md), [requirements](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/REQUIREMENTS.md), and [official Cocos CLI comparison](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/OFFICIAL_CLI_ANALYSIS.md) for the exact scope.

## Quick start

### Before installation

- This repository is a Creator extension, not a game project. Use an existing Cocos project; start with a disposable test project and back up authored scenes/assets before editing.
- The recorded editor acceptance uses **Windows / Creator 3.8.8**. Other 3.8.x versions and operating systems need their own checks. The local stdio bridge requires **Node.js 18+**; no npm runtime dependencies are bundled or need installation.
- Version **0.1.0 is distributed as a GitHub Pre-release**, not a stable release. Download `CocosMcpKit.v0.1.0.zip` and `SHA256SUMS.txt` from the [project-owned release](https://github.com/abelsdf/cocos-mcp-kit/releases/tag/v0.1.0) and verify the checksum before installation. Manual-installation evidence is limited to Windows / Creator 3.8.8; extension-manager installation remains unverified. npm/Registry publication and default automatic updates remain disabled. Do not use an upstream installer or `npx` package as a substitute.

### Install into one project

1. Prepare `<Cocos project>/extensions/cocos-mcp-kit`. From a clean source checkout, copy `package.json`, `browser.js`, `scene.js`, `bin/`, `lib/`, `panel/`, `i18n/`, and the documentation explicitly listed in `package.json.files`, including `LICENSE`. Do not copy the entire working directory: exclude `.git`, `AGENTS.md`, local configuration, caches, tests and test projects. For a local ZIP candidate, use its extracted `cocos-mcp-kit` folder; for an npm TGZ candidate, place the extracted `package` contents in the same extension directory. These are manual file layouts, not a claim of Creator extension-manager installation approval.
2. Check that `package.json`, `browser.js`, `scene.js` and `LICENSE` are directly inside `extensions/cocos-mcp-kit`, not inside an extra `package/` or `cocos-mcp-kit/` layer. When replacing an installation, first save your work, close the target Creator project and keep a backup of its old extension outside `extensions/`; avoid merging old and new files. Then open the project in Creator. Do not run duplicate project/global copies of this extension for the same project.
3. Open **Cocos MCP Kit > MCP Server**. Confirm that the server says **Running** and copy the URL shown in the panel. The default listener is local (`127.0.0.1`); its port is derived from the project path, so use the displayed URL rather than a fixed port.
4. Select your client in the panel and choose **Configure** for its MCP entry. **Configure + Skills** also installs the optional project skills. If your client needs stdio instead of a direct HTTP MCP URL, run the bundled bridge from the Cocos project root:

   ```sh
   node extensions/cocos-mcp-kit/bin/cocos-mcp-kit.js --url http://127.0.0.1:PORT/
   ```

Replace `PORT` with the port shown in the panel. The bridge requires Node.js 18 or newer. Use **Cocos MCP Kit > Tool Exposure** to select `core`, `full`, or a custom tool set. `core` is the default; `full` includes scene editing and component tools such as `list_available_component_types`. Select `full` for the editing workflow below. The [generated tool reference](./docs/TOOLS.md) shows each tool's profile and access type. Project settings are stored in `cocos-mcp-kit.config.json` at the Cocos project root.

### Confirm the connection

Reconnect the MCP client after configuration or tool-profile changes. Before any write, call `get_project_info` and verify the returned project path/name and Creator version against the intended project. `get_tool_catalog` reports tool exposure; the default catalog currently has **43 core / 154 full** tools, while custom filters can change the visible set. A running process or a health response alone does not prove that the client is connected to the intended scene.

For a manually configured stdio client, use command `node` and arguments containing the **absolute path** to `bin/cocos-mcp-kit.js`, `--url`, and the panel's URL. The relative command above assumes the Cocos project root as its working directory. The bridge does not launch Creator or discover the project port; without an explicit URL it falls back to port 8765, which may be the wrong endpoint. Running `node extensions/cocos-mcp-kit/bin/cocos-mcp-kit.js --help` checks CLI availability only, not MCP connectivity. A bridge waiting quietly for client input is normal.

Project-derived ports and client entry names depend on the project path. After moving/copying a project, or changing its endpoint, configure that project's client entry again and recheck its identity. Old configurations without `portMode` can retain a fixed port. Resolve a temporary fallback-port warning before writing client configuration. Configuration conflicts should be reviewed, not fixed by deleting other projects' entries. **Configure + Skills** writes optional project files; plain **Configure** does not install skills. See [project workflows](./docs/PROJECT_WORKFLOWS.md).

Keep the service local and connect only trusted clients. **`core` is not read-only**: it includes stateful and script-execution tools. Tool filtering and JavaScript safety checks are not an OS sandbox or an authorization boundary; do not expose the editor service to an untrusted network.

## Bundled UI knowledge

Read `cocos://knowledge/index` through MCP Resources for a compact catalog, then request a topic such as `cocos://knowledge/topic/widget-layout` or component links through `cocos://knowledge/component/cc.Widget`. Six original Chinese summaries cover Creator 3.8.x UI concepts with official sources, review dates and project limitations. Queries are offline and read-only; they do not inspect a scene or prove runtime correctness. Requires a Resources-capable client. See the [knowledge contract](./docs/KNOWLEDGE.md).

## What it can do

Full-profile `verify_ui` adds a bounded wait, edit-mode structure checks and optional strictly targeted Scene/Game View PNGs with separate metadata. In preview mode structure is explicitly `not_checked`; a captured image is never a visual pass. Missing/ambiguous targets fail without window fallback, and clipped Game View captures are marked as partial. See the [workflow and screenshot limits](./docs/UI_VERIFICATION.md).

For explicit UI nodes, full-profile `validate_ui` checks UITransform, project design bounds, Sprite/Label asset references and serialized Button events, with rule/node exclusions. Missing data and truncated results remain incomplete. It never repairs, saves, invokes callbacks or proves visual correctness; Widget/Animation coexistence is only a potential-conflict warning. See the [validation contract](./docs/UI_VALIDATION.md) and [Creator 3.8.8 checks](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/UI_VALIDATION_2026-09-28.md).

| Area | Current capabilities | Examples |
|---|---|---|
| Backend capability report | Read the active Creator extension identity, project and platform, current tool exposure, and risk hints. The optional official CLI adapter is reported as unconfigured; exposure does not prove runtime success. | `get_backend_capabilities`, `get_tool_catalog` |
| Node batches | Read-only DTO preflight, plus full-profile bounded creation, reference verification and scoped failure cleanup. Creator 3.8.8 records one parent-scoped Undo; other versions report unsupported. No automatic save or Undo/redo execution; see the [write contract](./docs/NODE_BATCH_DTO.md). | `validate_node_batch`, `create_node_batch` |
| JSON UI builder | Create nested UI under an explicit Canvas/UI parent, with scripts and ordered Button events. `create_scene(mode="ui")` provides a separate Canvas/Camera scene entry with guarded switching; unsaved content is never automatically saved/discarded. Scoped node cleanup/Undo does not roll back scene assets or external script effects. No visual guarantee. See [schema and example](./docs/UI_BUILDER.md). | `build_ui`, `create_scene`, `open_scene` |
| Game UI templates | Read-only, editable pause/settings/result UI JSON with text, size, colors and project-script event data. Build through `build_ui`; unbound buttons start disabled with a gray background and light-gray text. No bundled art, game logic or automatic saving. See [template contract](./docs/UI_TEMPLATES.md). | `get_ui_template` |
| UI viewport context | Read project design resolution, the nearest Canvas and associated camera, local/world/Canvas bounds and orthographic edit-camera pixel clipping. UI building and common modifications attach this report; unknown contexts remain explicit. Not Scene observer, Game View or device visibility. See [scope and coordinates](./docs/UI_VIEWPORT.md). | `get_ui_viewport` |
| Native reference images | Use Creator 3.8's native reference-image library, scene/prefab bindings, 2D offsets, independent scale, opacity, and refresh without importing the source file or adding scene nodes. Creator 3.8.8 exposes no public effective-visibility state, so visible-editor inspection remains separate. See [scope and workflow](./docs/REFERENCE_IMAGES.md). | `get_reference_images`, `add_reference_image`, `set_reference_image_parameters`, `refresh_reference_image` |
| Native Scene view | Query and set verified Gizmo, pivot/coordinate, 2D/3D, grid and IconGizmo state with native readback. Applying the Scene observer view to selected nodes is a scene mutation; the reverse alignment/focus direction remains unexposed because observer-camera results are not publicly observable. See [scope and workflow](./docs/SCENE_VIEW.md). | `get_scene_view_state`, `set_scene_view_state`, `align_selected_nodes_with_scene_view` |
| Project and assets | Read the active project's public name, UUID, paths, and Creator version; inspect scenes and exact asset metadata/data; resolve asset UUIDs, canonical URLs and real source paths; check asset-db readiness; safely create or save JSON/text assets, import bounded external files or folders, copy, move, refresh, or reimport supported assets; and inspect dependencies, logs, and script diagnostics. | `get_project_info`, `inspect_asset`, `query_asset_uuid`, `query_asset_url`, `query_asset_path`, `check_asset_ready`, `create_asset`, `save_asset`, `import_asset`, `import_folder`, `copy_asset`, `move_asset`, `refresh_asset`, `reimport_asset`, `list_assets` |
| Scene graph | Create and inspect nodes; move, reorder, duplicate, transform, or batch-edit ordinary scene nodes. | `find_nodes`, `move_node`, `reorder_node`, `batch_modify_nodes` |
| Components and scripts | Discover registered types; attach, remove, list, inspect, and edit supported component fields. | `list_available_component_types`, `attach_script_component`, `list_components`, `set_component_property` |
| UI and events | Create Canvas, Label, Button, and Sprite nodes; resolve SpriteFrames and manage Button click bindings. | `create_sprite`, `set_sprite_frame`, `list_button_click_events`, `bind_button_click_event` |
| Prefabs | Inspect and create prefab assets, validate references, and work with linked instances through editor messages where supported. | `create_prefab_from_node`, `inspect_prefab_instance`, `apply_prefab_instance` |
| Preview and evidence | Control supported preview modes, capture editor/preview images, and inspect runtime and build status. | `run_project_preview`, `capture_preview_screenshot`, `validate_scene` |

These are examples, not the complete catalog. Some entries come from the Funplay base; newer tools have separate Creator verification records under [docs/verification](https://github.com/abelsdf/cocos-mcp-kit/tree/main/docs/verification). The tool profile controls what an MCP client can see, and read-only, mutating, and stateful tools are marked in the [tool reference](./docs/TOOLS.md).

## A safe editing workflow

### Build and check a first UI

1. Verify the project identity, select `full`, and open a saved scene in ordinary Scene edit mode. A fresh unsaved default scene must first be saved or replaced manually in Creator; guarded tools do not discard it. For a new Canvas/Camera scene, follow the explicit `create_scene(mode="ui")` entry in the [UI builder guide](./docs/UI_BUILDER.md), including its `expectedSceneUuid` and `needsSave` handling.
2. Import a project-owned white image and resolve its actual **SpriteFrame subasset**, not just the image UUID. For working buttons, prepare an imported/registered project script with the intended callback method; the extension does not create game logic.
3. Call `get_ui_template` with `pause_menu`, `settings_dialog` or `result_dialog`, then inspect its returned `ui`. Supply the current scene asset UUID and Canvas/UI parent node UUID to `build_ui`. If a newly created scene has been opened successfully, these are its returned `info.uuid` and `ui.parentUuid`. These two kinds of UUID are not interchangeable. See the [template example](./docs/UI_TEMPLATES.md).
4. Inspect the build result and actual nodes before repeating a write. Same-name roots are rejected, not updated. Unbound actions use static gray styling; manually enabling them also requires restoring Sprite/Label colors. This does not migrate old scenes or implement runtime state transitions.
5. Run `verify_ui` in edit mode with the scene UUID and **all node UUIDs to check**, not just the root: it does not recursively validate descendants. Save explicitly, reopen the saved scene, and recheck assets, scripts and event references. Resolve any unsaved-content warning before switching scenes.
6. Start embedded Game View separately when needed, physically click the buttons and inspect the rendered result. Use `verify_ui(screenshot="game")` only for preview evidence; preview structure is `not_checked`. A clipped image is partial evidence: adjust the visible Game View scale/layout before taking a complete screenshot. The [verification guide](./docs/UI_VERIFICATION.md) explains provenance and result fields. Do not infer business behavior from a test callback alone.

### Edit existing nodes

1. Inspect the target with `get_scene_info`, `find_nodes`, or `list_components`. Prefer a node UUID or a unique path; ambiguous names are rejected, and multiple selectors must agree.
2. For component work, call `list_available_component_types` or `inspect_component` before editing. The type catalog marks missing and non-Component classes; `attachable` means a registered Component subclass was found, not that every node will accept it.
3. Make one bounded change with a tool such as `set_component_property`, `move_node`, or `set_sprite_frame`. For example, this sets a Label's top-level `string` field (`valueJson` is a JSON-encoded string):

   ```json
   {
     "uuid": "<node-uuid>",
     "componentName": "cc.Label",
     "propertyPath": "string",
     "valueJson": "\"Hello Cocos\""
   }
   ```

4. Save the scene, reopen it in Creator, and inspect the node or resource again. For a visual or interactive change, also check the running preview. An MCP success response alone does not prove persistence or visible behavior.

`inspect_asset` is a read-only exact lookup by UUID, `db://` URL, `assets/...` path, or an absolute file path inside the project's `assets` directory. It does not add guessed extensions. Its stable `details` projection identifies the requested target and source asset, project-relative source file, disk presence and size, target/source/metadata importers, metadata ownership, and main/subasset linkage. Bounded raw info and metadata remain available for deeper inspection; serialized asset data is omitted unless `includeData: true`. Depth, item, node, string, and character limits bound returned snapshots and report truncation. A missing reported source file makes `complete` false. Treat `complete: true` as a complete bounded query under the requested options, not as proof that runtime string-based references or visual behavior are valid.

`create_asset` is a full-profile, create-only path for new UTF-8 `.json` and `.txt` assets. The parent directory must already exist under `assets/`. It refuses existing source files, `.meta` files, or asset-db identities; validates JSON and a 1 MiB content bound; creates through `asset-db:create-asset`; then verifies the exact source bytes, metadata UUID/importer, imported Cocos type, database readiness, and a settled second read. It never overwrites, auto-retries an uncertain native create, or accepts scene, prefab, script, metadata, or binary formats. Use the specialized scene/prefab workflows for Cocos serialized assets.

`save_asset` is the corresponding full-profile update path for existing, writable, fully imported UTF-8 `.json` and `.txt` main assets up to 1 MiB. It accepts an optional `expectedSha256` to reject stale edits before mutation, returns a verified no-op when content is unchanged, and otherwise issues exactly one `asset-db:save-asset` request. Success requires the exact new source, unchanged UUID/importer/metadata, database readiness, and a settled second read. Scenes, prefabs, animation clips, scripts, images, audio, directories, and imported subassets are refused with type-specific guidance. `write_file` and `replace_in_file` remain filesystem helpers and do not prove Cocos resource persistence.

`reimport_asset` is a full-profile, existing-resource operation for imported JSON, text, image, and audio main assets up to 64 MiB. It sends one `asset-db:reimport-asset` request, then requires at least one library output to be regenerated and stable, with unchanged source bytes, main/subasset UUIDs, and nested importer settings. It rejects directories, subassets, scenes, prefabs, scripts, unsupported formats, and linked source paths. A native return without regenerated library output is reported as unverified; it is never retried automatically.

`import_asset` is a full-profile, create-only operation for one external JSON, UTF-8 text, image, or audio file up to 64 MiB. Give `source` as a local absolute path and `target` as a new path under an existing `assets/` directory with the same extension; optional `expectedSha256` protects against a stale source. It calls `asset-db:import-asset` once, then checks the imported bytes, new UUID, disk and database metadata, subasset identities, library output, readiness, and a settled second read. It rejects existing targets, external `.meta` sidecars, linked source paths, unsupported formats, and Cocos serialized assets. Uncertain native results are not retried automatically. See the [Creator 3.8.8 verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_IMPORT_2026-09-26.md).

`import_folder` is the full-profile counterpart for one external directory. It creates a new directory below an existing `assets/` parent and limits the source to 64 supported files, 16 directories, four nested levels, and 64 MiB total. It rejects `.meta` sidecars, symbolic links, unsupported files, and existing targets before one native import. Success requires an exact directory tree, matching file bytes, distinct directory/file/subasset UUIDs, matching metadata, available library outputs, and stable asset-db reads. Partial or uncertain imports are left for explicit inspection; the tool never retries or deletes them automatically. See the [verification record](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_IMPORT_FOLDER_2026-09-26.md).

`refresh_asset` is a full-profile exact-file refresh for one existing project JSON, text, image, or audio source (up to 64 MiB). It accepts the file's `db://assets/` URL or path, sends one `asset-db:refresh-asset` request, and checks unchanged source bytes, imported metadata, main/subasset identities, available library outputs, database readiness, and settled reads. A file not yet registered in asset-db may gain a new identity. This checks consistency after refresh; it does not claim that library files were regenerated when Creator already considered the asset current. It refuses a directory or root target and never broadens a failed exact refresh to the entire project. Use `reimport_asset` when regeneration itself must be demonstrated. See the [Creator 3.8.8 verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_REFRESH_2026-09-26.md).

`check_asset_ready` is a read-only full-profile status probe. Without a target it requires two stable `asset-db:query-ready` responses; with an exact UUID or `db://assets` / `db://internal` URL it also requires an imported, non-invalid asset record, matching UUID and URL lookups, and a stable second read. Its polling budget defaults to 1.5 seconds (`waitMs` up to 10 seconds), with a 3-second cap on each native query; a zero wait returns an unconfirmed one-shot observation. Busy, missing, importing, inconsistent, timed-out, and unconfirmed states never report `ready: true`. This is evidence about asset-db queries only; it does not prove an empty importer queue, unchanged source bytes, or completed build outputs.

`query_asset_path` is a read-only full-profile lookup for an exact UUID, db URL, project-relative `assets/` path, or absolute path inside the project assets directory. It cross-checks asset identity and native path mappings. For an imported subasset, `source.path` is the parent asset's real file, while `nativeMapping.path` may contain Creator's `@subasset` alias and is marked `isPhysicalSource: false`. Missing, unimported, inconsistent, or absent source files return an incomplete result. This tool does not open or modify the asset. See the [Creator 3.8.8 verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_PATH_2026-09-26.md).

`query_asset_uuid` is a read-only full-profile lookup for an exact asset UUID, db URL, project-relative `assets/` path, or absolute path inside the project assets directory. It verifies the asset record and Creator's URL-to-UUID mapping, including the parent link for an imported subasset. A relative path is normalized to a db URL before querying because Creator's native `query-uuid` does not resolve it directly. `uuid` is populated only when every identity check passes; missing or inconsistent targets return `null`. See the [Creator 3.8.8 verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_UUID_2026-09-26.md).

`query_asset_url` is a read-only full-profile lookup for the same exact targets. Its top-level `url` is the verified canonical URL from the imported asset record; `nativeMapping.url` reports Creator's native UUID-to-URL result separately. For an imported image subasset, that native value can be an `@` alias instead of the canonical `/texture` URL. Both forms must resolve to the same UUID before a URL is selected. Missing, unimported or inconsistent targets return `url: null`. See the [verification record](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_URL_2026-09-26.md).

`copy_asset` is a full-profile, create-only copy path for imported JSON, text, image, and audio main assets up to 64 MiB. The target must use the same supported extension and an existing parent under `assets/`. It copies once through `asset-db:copy-asset`, refuses every source-file, `.meta`, or asset-db target conflict, and verifies exact bytes, copied importer settings, a distinct main UUID, distinct image subasset UUIDs, an unchanged source, database readiness, and a settled second read. It does not copy folders, imported subassets, scenes, prefabs, scripts, metadata files, or unsupported formats, and never overwrites or automatically retries an uncertain native copy.

`move_asset` is the corresponding full-profile move/rename path for imported JSON, text, image, and audio main assets up to 64 MiB. It requires the same extension and an existing parent under `assets/`, refuses case-only renames and every file, `.meta`, or asset-db target conflict, and issues `asset-db:move-asset` only once. Success requires the old source and `.meta` paths to disappear while the target bytes, importer settings, main UUID, image subasset UUIDs, import state, and a settled second read all match. UUID-based main and subasset references remain valid; string or path-based references are not discovered or rewritten. It does not move folders, imported subassets, scenes, prefabs, scripts, metadata files, or unsupported formats, and an uncertain native result must be inspected at both exact paths before retrying. See the [Creator 3.8.8 verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_MOVE_2026-09-26.md).

`list_assets` searches project assets by default and returns a compact, URL-sorted page instead of an unbounded raw asset-db result. Combine `name` with `contains`, `prefix`, or `exact` matching, an exact `ccType`, and an `assets` directory. Extensionless exact names such as `IconPair` can match `IconPair.prefab`; when an exact name has multiple matches, `selection.candidates` retains their UUIDs, URLs, types, and main/subasset identities so the caller must choose explicitly. Name-filtered results also report duplicate-name groups. Use `includeSubassets: false` to omit imported SpriteFrames/textures, or `scope: "all"` when internal editor assets are intentionally required.

Use `find_asset_by_name` when a later operation needs one exact resource identity. It reports `not_found`, `unique`, or `ambiguous`; `selected` is populated only for a unique result. A filename extension is optional, but main assets and imported subassets can share a display name, so narrow ambiguous results with `ccType`, `directory`, `includeSubassets`, or case-sensitive matching. Candidate output is bounded by `maxCandidates`; the tool never chooses the first duplicate silently.

`set_component_property` currently accepts one supported top-level field at a time: CCClass-declared project-script fields and selected Cocos UI fields. It converts compatible Color, vector, node/component, and asset references, but rejects dot paths, undeclared script state, incompatible values, and linked prefab instances. SpriteFrame assignment can resize UITransform; set `contentSize` afterward if a custom size is needed. `reset_component_property_to_default` restores a declared CCClass default; `reset_component_property` only clears a field.

The component catalog is bounded to 256 project scripts and 32 requested class-name probes. A script reported as `no-component-registration` may be a normal utility module, not a compilation failure. `list_components` shows CCClass-declared project-script fields by default; `includeRuntimeFields: true` reveals additional live fields without proving that they are public or persistent.

Linked prefab instance edits have tool-specific rules. Ordinary node move, duplicate, add/remove component, and property assignment reject linked prefab hierarchies; prefab instance apply/revert and Button click overrides use separate editor workflows. Check the relevant [tool description](./docs/TOOLS.md) and [verification record](https://github.com/abelsdf/cocos-mcp-kit/tree/main/docs/verification) before relying on a persistent prefab change.

For `bind_button_click_event`, the target node must have exactly one matching component and the handler must be a component-owned method, not an engine lifecycle method. `customEventData` is a literal string of at most 1024 characters. List existing events before binding or unbinding; duplicate bindings are reported without adding another event. `batch_bind_button_click_events` applies up to 50 ordered bindings with stop or continue on error and reports each result; successful entries remain changed if a later entry fails.

`list_prefabs` returns a sorted, paged asset catalog (50 per page by default, up to 100). Set `includeMetadata` for a compact `.meta` status and `includeSceneInstances` to join links from the active scene. Instance counts are partial if the bounded scene scan reports truncation.

`inspect_prefab` reports the asset and metadata identity, serialized root/node/component summary, and UUID-like references with an explicit truncation flag. Set `includeSceneInstances` to find matching roots in the active scene; a serialized prefab reference alone does not prove that a nested instance remains linked.

`validate_prefab_references` checks explicit serialized asset references beyond the inspection display limit, plus component entry links and declared nested prefab assets. It reports incomplete scans and lookup errors separately; it cannot prove dynamic runtime loads or that a serialized custom component class is registered.

`create_prefab_from_node` clones an ordinary scene hierarchy, rejects linked nested instances and editor-only nodes, and validates a single connected node tree, component ownership, PrefabInfo metadata, and explicit asset references before writing through asset-db. It then verifies the imported UUID, metadata, root name, and node/component counts; the source scene hierarchy is not modified.

`create_prefab_instance` and `instantiate_prefab` now share a native editor workflow: create once, verify the linked root/asset/instance identity, and assign and verify the parent-local `position`. `parentUuid` selects an exact parent; if `parentPath` is also provided, both must match. Omitted name/position use the prefab root defaults. An imported, saved scene is required; call `save_current_scene` explicitly afterward (`needsSave: true` is not persistence proof).

UI prefabs require an existing Canvas ancestor. Linked parent hierarchies, Canvas roots, enabled root Widgets and enabled parent Layouts are refused to avoid unsupported nesting or editor-controlled placement. There is no runtime fallback on uncertain native creation; failed verification only attempts cleanup of a node confirmed inside this creation scope. Inspect the hierarchy before retrying an uncertain result. See the [Creator 3.8.8 instantiation verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_INSTANTIATE_2026-09-22.md).

`unlink_prefab_instance` uses the native editor message on an explicitly selected, independent instance root in a saved scene. It verifies node/component identities, hierarchy, transforms and removal of link metadata without editing the source prefab; save the scene explicitly afterward. Linked ancestors and nested prefab subtrees are refused: a Creator 3.8.8 control test lost a valid cross-instance component reference after outer-instance unlink/save. `verified: true` is a structural check, not an audit of every component property. There is no automatic retry or relink after uncertain results. See the [unlink verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_UNLINK_2026-09-22.md).

`apply_prefab_instance` immediately writes property changes back to the source prefab and can affect other instances; discarding the scene does not undo that asset write. It requires an explicit non-nested instance root in a saved scene, unchanged node/component structure, and no outgoing external scene references. It compares the native serialized preview against the imported source file, rechecks instance identity, and still requires an explicit scene save. The raw native `result` can be `false` even after a successful write; use the verified tool result, not that boolean. Uncertain writes are never retried or rolled back automatically. See the [apply verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_APPLY_2026-09-22.md).

`revert_prefab_instance` discards property overrides on an explicit non-nested instance root in a saved scene through one native `restore-prefab` request. It preserves the root name, position and rotation, but restores scale, other node properties and component data from the source. It verifies serialized values, live identities and unchanged source/metadata files twice; save the scene explicitly afterward. Structure changes, outgoing external scene references and unverifiable serialization are refused. An uncertain result is not automatically retried or rolled back. See the [restore verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_REVERT_2026-09-22.md).

`enter_prefab_edit_mode` (`full` profile) enters native editing for an exact non-nested project prefab from one clean, saved scene. It compares live serialization with disk even when the dirty flag is clear, verifies the actual editor mode and prefab root, and checks that source/origin files remain unchanged. It returns `sourceHash` for guarded saves. Re-entering the same clean prefab verifies it without reloading; dirty, multi-scene and other-prefab states are refused. It never auto-saves, discards or exits. The generic `open_asset` does not provide these guards. See the [entry verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_EDIT_ENTER_2026-09-22.md).

`save_prefab_edit_mode` (`full` profile) saves property-only edits of the current non-nested prefab using its explicit `prefabUuid` and the `expectedSourceHash` from entry or the last verified save. It rejects source conflicts, structure changes, outgoing scene references and an unsaved origin scene. Saving immediately writes the asset and can affect same-source instances; discarding the scene will not undo that write. It checks content even when dirty is false, waits a bounded time for the target's reimport, and verifies source/live/origin state twice. Use the returned new hash for subsequent saves; a clean, unchanged repeat performs no native save. On a conflict or uncertain result, inspect and reconcile changes before retrying, rather than simply replacing the hash. It never auto-exits, retries the write, rolls back or saves the origin scene; `needsSave: false` refers only to the prefab. Generic `save_current_scene` does not acquire these prefab-specific guards. See the [save verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_EDIT_SAVE_2026-09-22.md).

`exit_prefab_edit_mode` (`full` profile) closes a saved, unchanged non-nested prefab through one native `close-scene` request. Supply its `prefabUuid`; set `returnSceneUuid` to `previousScene.uuid` returned by initial entry or verified save. Dirty prefab state, unsaved serialization even with dirty=false, a mismatched origin, nesting or unverifiable references are refused before closing. It verifies the restored scene and unchanged source/origin files twice; repeating in the matching verified scene does not close that scene. Saved prefab updates may mark the restored scene dirty, so inspect `needsSave` and save that scene explicitly if needed. There is no automatic save, discard, retry, reopen or rollback; saving and exiting remain separate operations. See the [exit verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_EDIT_EXIT_2026-09-22.md).

`test_prefab_edit_mode` (`full` profile) accepts only an explicit `prefabUuid` and performs read-only diagnostics: editor context, source/reference and retained-scene checks, plus live-content comparison only when that target is already open. An unopened target stays unopened (`editing: null`, `complete: false`); each check reports `passed`, `failed` or `not_checked`. `readChecksPassed` means no read check failed, while `complete` means all read checks passed; neither grants permission or proves that enter/save/exit works. Unsaved differences can coexist with successful reads, including dirty=false edits. `observationsStable` is true/false for a successful/failed recheck and null when prerequisites are unavailable, not a transaction guarantee. The outer `ok` only confirms report generation. All `mutationTests` remain `not_run`: there is no automatic open, save, close, snapshot, creation or discard, and no replacement source hash for guarded saves. See the [diagnostic verification and limits](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_EDIT_TEST_2026-09-22.md).

`delete_asset` requires an exact UUID, db URL, or file path; it does not guess extensions. It safely handles project prefabs and imported JSON, text, image, or audio main assets up to 64 MiB. Before one asset-db deletion request it verifies writable imported identity, real source/metadata paths, unchanged bytes and metadata, and native asset/script plus active-scene references for the main UUID and imported subasset UUIDs. Internal links among subassets of the same image do not block deletion; external references do. Referenced assets and currently edited prefabs are rejected, with no force/cascade or filesystem fallback. Success requires UUID/URL records, both mappings, the source, and `.meta` to be absent. A verification failure may occur after deletion, so inspect the exact asset before retrying. Folder, subasset, scene, script, other-format, dynamic string/path loading, and references outside native queries remain unsupported. See the [prefab verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/PREFAB_DELETE_2026-09-22.md) and [regular-asset verification](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/ASSET_DELETE_2026-09-26.md).

## Troubleshooting

| Symptom | First checks |
| --- | --- |
| Menu missing or extension fails to load | Check the exact folder depth and package name, avoid duplicate installations, restart the intended Creator project and inspect its console errors. |
| Connection refused or wrong project | Keep Creator and its MCP service running; copy the current panel URL, verify the selected client entry and `get_project_info`. Resolve port collisions/fallbacks before configuring clients; do not assume 8765 or another project's URL. |
| A browser GET returns 405 | Long-lived GET/SSE streams are not supported. Use a compatible HTTP MCP client or the bundled stdio bridge. `/health` is a read-only liveness check, not a scene or client acceptance test. |
| Builder/template/verification tool missing | Check `full` and any custom tool/category filters in Tool Exposure, then reconnect the client. `core` is intentionally smaller, not read-only. |
| Switch refused or resource/callback rejected | Review `needsSave`, unsaved serialized changes and the exact active scene; verify imported SpriteFrame/script identities and registered methods. Never bypass the guard or blindly repeat an uncertain write. |
| Screenshot fails, is cropped, or a button does nothing | Show the intended non-minimized Scene/Game View. Check `region.clipped`, the correct runtime mode and source; for a gray button, inspect its event binding and disabled state. A captured image never means visual validation passed. |

## Known limits and delivery status

- Recorded persistence, UI clicks and screenshots cover specified Creator 3.8.8 samples, not all projects, text lengths, materials, aspect ratios or devices. Touch, other Creator versions/OSes, the extension-manager installer, updates and uninstall remain unverified. [First-release evidence](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/FIRST_RELEASE_VISUAL_ACCEPTANCE_2026-09-30.md) and [disabled-style follow-up](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/UI_DISABLED_STYLE_2026-09-30.md) state the tested scope; previous physical-click evidence is not a new-package click retest.
- UI templates are fixed-layout starter JSON. They do not implement pause/resume logic, audio preferences, rewards, navigation, modal input blocking or focus management. Custom colors/art and long text need visual review.
- Batch cleanup covers newly created nodes, not arbitrary script effects or scene-asset creation. Single-Undo recording is verified only on Creator 3.8.8; specialized prefab operations retain their documented non-nested/property-only limits. Partial or uncertain results require inspection, not automatic retries.
- The strict Scene/Game View screenshot workflow requires a visible matching Creator window. It does not capture an external browser/Simulator, prove runtime scene freshness, or provide automatic visual approval: `visualValidation` remains `not_run`. The optional official CLI backend is not configured.
- Default `npm run release:package` still produces a local candidate; explicit `--github-prerelease` packaging requires clean, tagged source and records the owned GitHub destination. Neither command publishes. Windows uses `tar.exe`; non-Windows requires `zip`/`unzip` and remains unverified. Each invocation preserves earlier artifacts in a new `releases/<version>/candidate-<unique>/`. Verify `SHA256SUMS.txt` before manual installation. See the [release workflow](./RELEASE_WORKFLOW.md) and [Windows local-install evidence](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/verification/LOCAL_PACKAGE_INSTALL_2026-09-30.md).

## Development and documentation

Run development commands from a **source checkout**, not the installed runtime package: `npm run check` for JavaScript syntax, `npm test` for tests, `npm run docs:check` for the generated catalog, `npm run release:check` for package/license guards, and `npm run pack:dry-run` for the npm file list. Tests and build scripts are intentionally not shipped in the runtime package. The [development plan](https://github.com/abelsdf/cocos-mcp-kit/blob/main/docs/PLAN.md) distinguishes implemented tools from broader requirements still in progress; [verification reports](https://github.com/abelsdf/cocos-mcp-kit/tree/main/docs/verification) record what was tested in Creator. This fork currently has no configured release update channel or package registry publication; install it locally.

## Attribution and license

Thanks to the authors and contributors of [Funplay MCP for Cocos](https://github.com/FunplayAI/funplay-cocos-mcp) for releasing the MIT-licensed foundation. The `Copyright (c) 2026 Funplay` notice, complete MIT terms, and disclaimer remain in [LICENSE](./LICENSE). Cocos MCP Kit is an independent fork, not an official Funplay release. See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution rules and [sources and licenses](./docs/SOURCES_AND_LICENSES.md) for package boundaries. Development and verification records stay in the source repository rather than the install package.