t1k:cocos:base:editor-mcp-truth
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| Tools | — |
Keywords: assetArray, autostart mcp server, changeVerified, checkout health, cocos mcp server not loaded, cocos preflight, cocos-mcp-server version, dangling asset ref, editor doctor, editor mcp, editor mcp tools missing, editor operator, editor reload, execute_menu_item, extension pin, git restore scene, healthy port no tools, json-rpc fallback, kiểm tra môi trường cocos, manage_component, manage_node, manage_prefab, manage_scene, mcp port health, mcp preflight, mcp server name mismatch, mcp tools absent, mcp write, missing node, ogg in resources audio, port, prefab edit mode save, prefab uuid mismatch, property default, read-back, reimport, restart claude code mcp, sai port mcp, session port binding, setup script wrong project, silent failure, stale default, stale library artifact, stale scene memory, subagent no mcp family, submodule not populated, submodule sha, super-html version drift, target project port, TargetOverrideInfo, two editors open, user scope mcp, wrong editor, wrong project
How to invoke
Section titled “How to invoke”/t1k:cocos:base:editor-mcp-truthEditor MCP Truth — preflight, write, and prove it landed
Section titled “Editor MCP Truth — preflight, write, and prove it landed”Cocos MCP writes fail silently and report success. This protocol makes a write falsifiable:
resolve where you are connected, write, save the editor, reimport, read the asset JSON back off
disk, compare fields. Mandatory first activation for every editor-writing agent
(t1k-cocos-base-developer, t1k-cocos-playable-feel-developer, t1k-cocos-base-editor-operator).
Why base owns this protocol and not playable, and how it relates to t1k-cocos-playable-tooling-gotchas: references/protocol-step-detail.md § “Why base owns this protocol (not playable)”. This skill says what to do; the playable skill holds the full catalogue of what each call does wrong.
Protocol (ordered — no step is optional for a WRITE)
Section titled “Protocol (ordered — no step is optional for a WRITE)”(a) and (b) run before any editor work. (c) applies only after the caller’s OWN write — a diagnosing agent that has written nothing must not save or reimport (a save can persist an in-memory corruption; a reimport can discard the user’s unsaved edits).
(a) Preflight — port, then identity
Section titled “(a) Preflight — port, then identity”Ports are per-editor, not fixed. Resolve, never assume 3000:
bun .claude/skills/t1k-cocos-base-editor-mcp-truth/scripts/resolve-mcp-port.cjs . --jsonThe script emits facts — the registered server names, their ports, the editor’s configured port, and a warning when the two config files disagree. Fix a mismatch before writing anything.
The port this session can reach is not the target project’s port. The cocos-creator binding is
fixed when the MCP client connects and is session-wide, not per-project; a project with no
.mcp.json resolves to nothing here (missing: true). Measured census and remedies:
references/session-port-binding-not-project-port.md and references/protocol-step-detail.md § “Session port binding — measured”.
Compare the two before writing, and note the asymmetry in the remedies:
- The session’s port == the editor you intend to write to → proceed.
- They differ → you cannot re-point a live session. Either bring the target’s editor up on the port the session dialled, or align the registration and Restart Claude Code. Re-running the script cannot help: it re-reads files, and the client’s binding is already made — the same connection-timing rule as the not-reachable-yet note below, one layer up.
A registered server that is not reachable YET is not a missing tool: cocos-creator
is an HTTP registration, and what answers http://127.0.0.1:<port>/mcp is the cocos-mcp-server
extension running inside a Cocos Creator window — it exists only while that window is open, so
absent tools can mean no editor window, autoStart: false, or a session that connected before the
server started. Only the last case needs a restart of Claude Code — re-probing the port never
adds tools already missed at connect time. Three-consequence breakdown and the symptom-to-cause
table: references/bridge-startup-and-tool-visibility.md.
One cause this preflight CANNOT see: every call times out while the port, /health and the
window all look healthy. A modal editor TaskDialog (the unsaved-scene “Apply / No” prompt, or
“Scene Not Response”) pumps the editor’s single-threaded loop, so every queued request waits behind
it and expires — indistinguishable from a dead editor, and restarting loses work without helping.
Enumerate the CocosCreator process’s top-level windows before concluding the bridge is down, and
dismiss with PostMessage(WM_COMMAND, IDCANCEL) (maps to No; never IDOK/Apply). Full
recipe: playable t1k-cocos-playable-tooling-gotchas → taskdialog-modal-mcp-timeout.md.
Check the server NAME, not just the port. An MCP server’s tool family is derived from its
key in .mcp.json. Two keys are in the wild and the kit grants the tools of both —
cocos-creator (6 audited projects) and cocos-mcp-server (8): agents and skills declare
mcp__cocos-creator__* and mcp__cocos-mcp-server__*, so use whichever family the project
resolves and do not rename the key (a rename invalidates every prompt that already names
the old family). Any OTHER key (cocos, an otherwise unnamed user-scope entry) resolves none
of the kit’s tools — the failure reads as “tool unavailable”, which looks like a missing plugin,
not a naming mismatch.
No MCP family in this spawn at all: report it first, then only references/no-family-jsonrpc-fallback.md.
Then check the PIN, not the version. manage_prefab is not an engine API — it is a tool in the
cocos-mcp-server editor extension, vendored per project as a git submodule at
extensions/cocos-mcp-server. Every project pins its own SHA, so manage_prefab behaviour is
pin-relative. Read the SHA, never package.json’s version (it reads "2.0.0" on both the 2026-04 template pin and upstream main):
git -C extensions/cocos-mcp-server log -1 --format='%h %ad %s' --date=shorteditor-doctor.cjs already answers the comparison — mcp.pin.floor reports every known fix floor the pin predates, FAIL with the SHA to move to (verdict table: references/editor-doctor-contract.md). Run it rather than deriving this by eye. Move the pin to the latest upstream fix level before diagnosing any call result; a target at or past upstream #137 is an auth boundary — follow § “Crossing #137 (auth)” in references/prefab-mcp-pin-and-upstream-fixes.md. Upstream pin comparison detail: references/protocol-step-detail.md § “Pin comparison and upstream fixes”.
Then confirm identity — manage_project action=get_info and compare the returned path
against the working directory. Do not compare uuid: a project cloned from a template
inherits the template’s uuid. On mismatch, refuse and stop — manage_asset create still
returns success: true with a uuid while the server is bound to a different project, so a write
into the wrong repo has no error signal at all. The path check is the only one that can answer “which project is this session attached to”: a healthy connection that points at a different project fires no error anywhere (detail: references/protocol-step-detail.md § “The path check is load-bearing”).
Then confirm asset identity — the path check proves you’re in the right project; it does
NOT prove the scene or prefab you’re about to write is the one the caller named. Two editors on
the same project can hold different scenes open, and manage_scene/manage_prefab write to
whichever the editor has loaded. Before the first write to a scene or prefab asset, resolve the
open asset’s uuid via manage_asset action=get_info url=<target-url-or-uuid> and compare it to
the target. On mismatch, open the correct asset first or STOP — writing to the wrong scene
returns success: true and corrupts an unrelated file. Prefer manage_asset get_info over
query_uuid: the skill’s own known-lies table records query_uuid failing with UUID not found for valid db:// paths.
(b) Write through MCP
Section titled “(b) Write through MCP”First, the backup gate (any .scene/.prefab/.meta, also before a bulk execute_script): references/pre-write-backup-gate.md.
Scripts restored or deleted by git with the editor open? Refresh db://assets/scripts and verify the compiled classes BEFORE opening or saving a scene: references/stale-compiled-classes-after-git-restore.md.
Prefer ONE bulk manage_debug execute_script over per-property calls for a multi-node pass (these
made sessions run long); the per-field disk read-back in (c)/(d) attributes any drop. Two strikes on
one node is the limit (f). Then the editor-preview gate before any build: references/post-write-preview-gate.md.
A closed prefab has no MCP write path: write it to disk per references/on-disk-prefab-edit.md.
execute_script is pin-gated: before upstream #40 every script fails Scenario scripts do not exist: console (a hardcoded argument, not a missing asset). Step (a) settles the pin; on such a pin move it or use per-property calls (references/protocol-step-detail.md § “Execute script pin gate”).
(c) Save, reimport, then read the file back from DISK
Section titled “(c) Save, reimport, then read the file back from DISK”manage_scene action=save # or the prefab savemanage_asset action=reimport url=db://assets/<path>/<name>.prefabThe reimport target must be the exact file URL — never a folder. Reimporting a folder db://
URL reports success: true and reimports nothing inside it, leaving every child asset’s library/
artifact stale (known lies: reimport on a folder URL); per-file is the only form that
refreshes the artifact you are about to read back. A .scene/.prefab restored by git while the
editor was open needs the forced reimport before any read-back: references/scene-restored-by-git-not-reimported.md (detail: references/protocol-step-detail.md § “Reimport and the restored-by-git file”).
then Bash-read the .scene/.prefab JSON and compare the specific fields you asked for. A
field that is absent counts as a dropout, not as “already default”. Never accept as evidence:
get_current, soft_reload, manage_scene action=open, or any {"success": true} /
changeVerified: true return — the table below lists the calls that report exactly those and
change nothing.
A changed @property class default is NOT visible in that read-back, and an empty grep is not a
pass. Changing a default in the TypeScript class never reaches a component instance the open scene
already holds, and if the field was never authored the .scene has no key for it at all — so the
file reads clean while the preview runs the old value. Verify against the live value
(/scene/current_scene.json, or getComponentInChildren in the running game), then set it with
manage_component set_property and save: references/disk-edit-vs-editor-save.md.
“Completed” is a claim about disk, not about a task list. Before closing a prefab/scene fix, paste the read-back one-liner’s output: grep -c '<the string, uuid or field you wrote>' assets/<path>/<name>.prefab (or git diff --stat -- assets/<path>/<name>.prefab must be non-empty). A file whose history shows only the original commit was never fixed (detail: references/protocol-step-detail.md § “Completed is a claim about disk”).
Then prove the save changed nothing else with check-scene-save-scope.cjs: a save can rewrite
unrelated fields beside a correct read-back (#1736). See references/post-save-scope-check.md.
Stale-state preflight after a prefab-edit-mode save. Saving a prefab in prefab-edit mode with the parent scene open can drop the scene instance’s TargetOverrideInfo refs from editor memory while the disk stays clean. Diff http://localhost:<port>/scene/current_scene.json (memory) against …/scene/<sceneUuid>.json (disk) and count TargetOverrideInfo entries; a mismatch means the drop happened — reopen the scene from disk without saving. Full detail: references/protocol-step-detail.md § “Prefab-edit-mode stale-state preflight”.
The save is not optional and its absence is invisible. An MCP write lands in memory; the .scene/.prefab on disk is unchanged until the editor saves, so a read without a save is a false negative. A reimport with unsaved edits pending may also discard them (detail: references/protocol-step-detail.md § “The save is not optional”).
(d) Headless parse for orphan and empty references
Section titled “(d) Headless parse for orphan and empty references”After the last write, parse the asset JSON for empty/dangling refs — null on a __uuid__-carrying
field, and __id__ pointers that resolve to no entry in the file. A @property bound to an empty uuid is
silent: the component compiles, the scene opens, and the value is simply never applied. This
is the check that catches “wired in code, does nothing at runtime”, and it is the half of the
verification that no editor-side success string covers.
A non-null __uuid__ must also RESOLVE. Both checks above are claims about the document
against itself; neither sees a well-formed ref naming an asset that no longer exists — what a
manage_asset delete + manage_prefab create at the SAME path leaves behind (new uuid), which the
editor draws as a Missing Node. Strip any @subasset suffix; the bare uuid must be declared by
some assets/**/*.meta (top-level uuid or a subMetas entry), or be a db:// / builtin ref.
Run the detector — exit 1 dangling, 2 cannot run (never a pass):
bun .claude/skills/t1k-cocos-base-editor-mcp-truth/scripts/find-dangling-asset-refs.cjs <scene-or-prefab> <assets-root> --jsonRead an instance back by _prefab.asset uuid and the parent’s child count, NEVER by node name — a prefab-instance root serializes with no _name. Never delete-and-recreate a referenced asset; overwrite in place so the .meta uuid is kept. Clean near-misses, exit table and delete-ordering remedy: references/dangling-prefab-asset-refs.md (detail: references/protocol-step-detail.md § “Read an instance back by uuid”).
Lint the saved file for the defects the editor only shows at import or render time.
prefab-lint.cjs reads .prefab / .scene JSON (a file or a directory, never a game-specific path)
and runs --structure (out-of-range __id__, asymmetric _parent/_children, component back-refs,
PrefabInfo and fileId uniqueness; with --assets <root> it also runs the dangling-uuid detector),
--labels (a raw loc key such as Shop.Title or a bare ... shown to the player) and
--translucent-parent (an enabled cc.Sprite with alpha < 255 on a node with children dims every
descendant label and icon; tint a leaf child instead). No flag runs all three. Exit 1 findings, 2
cannot run (never a pass); --json for machines, --allow <json> for deliberate exceptions:
bun .claude/skills/t1k-cocos-base-editor-mcp-truth/scripts/prefab-lint.cjs --assets <assets-root> <assets-root>/resources/prefab --jsonAlso lint 9-slice borders. A SLICED sprite squeezed below half its insets, or a SIMPLE sprite on a bordered frame,
renders as a black lens / ellipse with every check above green. scripts/lint-nine-slice.cjs <assets-root> reads the
borders from the frame .meta (exit 1 finding, 2 cannot run): references/nine-slice-lint.md.
A non-empty ref is not automatically a correct one. A __id__ that resolves cleanly can still
resolve to the wrong object: a NODE reference written into a component-typed field
(@property(Component) / @property(SomeComponent)) resolves positionally to the node’s first
component — cc.UITransform in any UI hierarchy — and passes every null/dangling check above while
being the wrong type entirely. When the field’s declared type is a component, assert the resolved
entry’s __type__ is the expected script class (compressed uuid), not merely that the ref is
non-null — references/component-typed-property-node-ref-resolves-first-component.md.
Prefab-instance override exception: an inline null on an instance component may be live via targetOverrides; check before reporting a dropout: references/nested-prefab-instance-refs-unbindable.md.
(e) Never interleave MCP writes and file writes on one asset
Section titled “(e) Never interleave MCP writes and file writes on one asset”Do the MCP work, save, reimport, and only then touch the file — or the reverse, with a reimport in
between. Writing the .scene on disk while the editor holds it open means the next editor save
writes the cached state back over your edit, silently
(references/disk-edit-vs-editor-save.md).
(f) Two failed writes on the same node → stop
Section titled “(f) Two failed writes on the same node → stop”Report the node path, the call, the exact parameters, and the read-back diff to your spawner for
t1k-cocos-base-debugger. A third attempt with the same call is not a fix, and a fallback that
constructs the node at runtime is forbidden by rules/prefab-only-construction-cocos.md.
Reachability reads — a live component can show zero TS imports
Section titled “Reachability reads — a live component can show zero TS imports”Dead-code detection cannot rely on TypeScript references: a @ccclass wired only by scene/prefab attachment has zero TS imports, stored as a compressed uuid. Never shortcut with a 5-hex prefix match; decode the full token. Mechanism, the verdict matrix and the evidence: references/reachability-reads.md.
Known lies — calls that report success and do nothing
Section titled “Known lies — calls that report success and do nothing”Every call in the table reports success on a write that changed nothing, which is why the standing
advice is “ignore the success flag, read from disk” — it is only ever safe to ignore a success; do
NOT extend it to a failure flag (see the inverted section below). Rows marked pin-relative depend on
the cocos-mcp-server extension SHA (step (a) settles which range you are in; window in
prefab-mcp-pin-and-upstream-fixes.md). Before applying any workaround, look the call up in
references/known-lies-table.md (one row per shape: what happens, workaround, incident path) — it
covers manage_component set_property (falsy drops, Vec2, all array forms, [CustomCCClass]), manage_node (same-parent move, layer default, z~0 transform drop), manage_node_hierarchy paste of a copied node, manage_prefab create/update/instantiate, asset, scene save, set_fog, manage_render_pipeline, hand-authored .material/rotation, wrong-project binding, stale preview bundles, binary upload and menu-item calls.
Troubleshooting — a node that reads back fine and is invisible
Section titled “Troubleshooting — a node that reads back fine and is invisible”A node that reads back fine but is blank on screen, with no error: check _layer against the UI camera mask, anchors the owning component re-positions, and parent alpha cascades. Checklist: references/invisible-node-checklist.md.
Known lies, inverted — a call that reports failure while the write lands
Section titled “Known lies, inverted — a call that reports failure while the write lands”manage_prefab action=update can report failure while the write lands (same string for a genuine
failure on a never-linked instance, and for a destructive apply on one with mountedChildren).
Provenance disambiguates; never trust the flag either way — read the .prefab from disk, diff the
scene against the backup. Table and collateral-Apply caveat: references/known-lies-inverted-table.md.
Doctor — the deterministic half of (a) and (b)
Section titled “Doctor — the deterministic half of (a) and (b)”Steps (a) and (b) are facts about files on disk, not judgements to re-derive by hand each session, so they are a script:
cd <repo-root> && bun .claude/skills/t1k-cocos-base-editor-mcp-truth/scripts/editor-doctor.cjs <repo-root>/<GameFolder> --jsonExit 0 ok (warnings included) · 1 findings · 2 cannot run — never a pass. Four statuses:
pass · warn (wrong, but expected on a correct finished project) · fail · skip (NOT
measured — never a pass). A green run is a licence to begin, never evidence a write landed.
It checks what makes (a)–(f) unexecutable, and never writes: each finding carries its remedy as text, since confirming which project you are bound to is a decision. Per-check semantics and flags: references/editor-doctor-contract.md.
Executed by
Section titled “Executed by”The doctor is the deterministic half of the protocol. Routing SSOT: core orchestration-rules.md § “Task-Type → Agent Routing”.
Steps (a) and (b) run through t1k-cocos-base-editor-doctor (the doctor script and port resolver); manage_* writes and read-backs run through t1k-cocos-base-developer or t1k-cocos-base-editor-operator. Table: references/executed-by.md.
Related
Section titled “Related”Cross-references (incident index, rules, agents, every gotcha reference): references/related-index.md.
Related: #1013, #1002, #704, #1262, #726, #12, #21, #40, #129, #133, #139, #143, #144, #1386, #1736