mingyuansi
b65a4f22c3
Bug fixes (verified against Cocos Creator 3.8.8): - diagnostics: shell:true for .cmd/.bat on Windows (T125/T126) - prefabs: duplicatePrefab target resolves under assets/ (T420) - cocos-project: add preview.open candidate for 3.8.8 (T444) - assets-advanced: detect directory assets in inspectAssetDependencies (T110) - scene: improve component-not-found errors with compilation hint (T429) Documentation improvements: - tool-registry: add enum and injected vars to execute_javascript, path format examples, asset ref limitation note - resources: add cocos://mcp/execute-context resource with variables, patterns, pitfalls New tools (core 37->38, full 101->110): - scene-management: create_scene, query_scene_state (core), copy_paste_node, rename_node, reparent_node - scripts: create_script with component/plain templates - prefabs: create_prefab - assets-advanced: batch_asset_ops, find_unused_assets
245 lines
19 KiB
Markdown
245 lines
19 KiB
Markdown
# Tool Reference
|
|
|
|
<!-- This file is generated by `npm run docs:generate`. Do not edit by hand. -->
|
|
|
|
Generated from `lib/tool-registry.js`. The default `core` profile exposes 38 tools; the `full` profile exposes 110 tools.
|
|
|
|
## Profile Summary
|
|
|
|
| Profile | Tool Count | Purpose |
|
|
|---|---:|---|
|
|
| `core` | 38 | Focused default surface for common editor automation. |
|
|
| `full` | 110 | All built-in tools, including destructive and low-level helpers. |
|
|
|
|
## Core Tools
|
|
|
|
`capture_editor_screenshot`, `capture_preview_screenshot`, `capture_scene_screenshot`, `check_for_updates`, `clear_logs`, `execute_editor_script`, `execute_javascript`, `execute_scene_script`, `get_build_status`, `get_editor_state`, `get_hierarchy`, `get_performance_snapshot`, `get_project_info`, `get_recent_logs`, `get_runtime_state`, `get_scene_info`, `get_script_diagnostic_context`, `get_selection`, `get_tool_catalog`, `inspect_asset`, `inspect_asset_dependencies`, `inspect_prefab`, `inspect_prefab_instance`, `list_assets`, `list_editor_windows`, `list_project_instructions`, `list_scenes`, `open_asset`, `open_scene`, `query_scene_state`, `read_project_instruction`, `run_script_diagnostics`, `search_project_logs`, `select_asset`, `set_selection`, `validate_asset_dependencies`, `validate_prefab_references`, `validate_scene`
|
|
|
|
## Tools By Category
|
|
|
|
### Animation
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `add_animation_clip` | `full` | stateful | Add an AnimationClip asset to a node Animation component. |
|
|
| `list_animations` | `full` | read-only | [core] List Animation components in the active scene or under one node. |
|
|
| `play_animation` | `full` | stateful | [core] Play an Animation component clip on a node. |
|
|
| `stop_animation` | `full` | stateful | [core] Stop an Animation component clip on a node. |
|
|
|
|
### Assets
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `batch_asset_ops` | `full` | mutating | [core] Batch import or delete assets in the Cocos asset database. |
|
|
| `create_scene` | `full` | stateful | [core] Create a new scene asset in the Cocos project and optionally open it. |
|
|
| `delete_asset` | `full` | mutating | Delete an asset from asset-db by uuid, db url, or path. |
|
|
| `find_unused_assets` | `full` | read-only | [core] Find assets not referenced by any scene, prefab, or animation in the project. |
|
|
| `inspect_asset` | `core`, `full` | read-only | [specialist] Inspect asset-db info, metadata, and serialized asset data by uuid or path. Prefer this when you need a precise structured asset read. |
|
|
| `inspect_asset_dependencies` | `core`, `full` | read-only | [specialist] Inspect UUID-style dependencies referenced by a serialized Cocos asset. |
|
|
| `list_assets` | `core`, `full` | read-only | [specialist] Query project assets from asset-db by pattern or asset type. Prefer this when you need exact asset discovery; otherwise use execute_javascript for broader automation. |
|
|
| `list_scenes` | `core`, `full` | read-only | [specialist] List scene assets in the project. Prefer this when you need exact scene discovery before opening one; otherwise stay in execute_javascript for broader workflows. |
|
|
| `open_asset` | `core`, `full` | stateful | [specialist] Open an asset inside Cocos Creator by uuid, db url, or path. Use this only when opening the asset itself is the explicit next step. |
|
|
| `open_scene` | `core`, `full` | stateful | [specialist] Open a scene asset in Cocos Creator by uuid, db url, or path. Use this when scene switching is the explicit goal; otherwise keep execute_javascript as the main planning tool. |
|
|
| `run_scene_asset` | `full` | mutating | Load a scene asset by uuid directly into the current runtime scene context. |
|
|
| `select_asset` | `core`, `full` | stateful | [specialist] Select an asset in the Cocos editor. Use this when editor selection state matters; otherwise keep execute_javascript as the primary workflow. |
|
|
|
|
### Broadcast
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `broadcast_editor_message` | `full` | stateful | [core] Send or broadcast a Cocos editor message for advanced editor automation. |
|
|
|
|
### Build
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_build_status` | `core`, `full` | read-only | [specialist] Query Cocos build/preview status using known builder message variants. |
|
|
| `open_build_panel` | `full` | stateful | [core] Open the Cocos build panel, defaulting to the builder panel id. |
|
|
| `run_project_preview` | `full` | stateful | [core] Start Cocos preview/run using known preview and builder message variants. |
|
|
| `save_current_scene` | `full` | stateful | [core] Save the currently open Cocos scene using available editor scene messages. |
|
|
|
|
### Camera
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `create_camera` | `full` | stateful | Create a Camera node in the active scene. |
|
|
| `list_cameras` | `full` | read-only | [core] List Camera components in the active scene. |
|
|
| `set_camera_properties` | `full` | mutating | Set selected Camera component properties. |
|
|
|
|
### Components
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `add_component` | `full` | stateful | Add a component to a node by component class name. |
|
|
| `inspect_component` | `full` | read-only | [core] Inspect a component attached to a node. |
|
|
| `invoke_component_method` | `full` | mutating | [core] Invoke a method on a component for runtime validation and test hooks. |
|
|
| `list_components` | `full` | read-only | [core] List components attached to a scene node. |
|
|
| `remove_component` | `full` | mutating | Remove a component from a node by name or index. |
|
|
| `reset_component_property` | `full` | mutating | Reset or clear a component property by dot path. |
|
|
| `set_component_property` | `full` | mutating | Set a component property by dot path using a JSON value. |
|
|
|
|
### Diagnostics
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_script_diagnostic_context` | `core`, `full` | read-only | [specialist] Run TypeScript diagnostics and attach source snippets for each error. This is a preferred specialist tool for compile-error triage before repair. |
|
|
| `run_script_diagnostics` | `core`, `full` | stateful | [specialist] Run a TypeScript no-emit check for the current Cocos project and return parsed diagnostics. This is a preferred specialist tool for script errors when diagnostics are needed. |
|
|
| `validate_asset_dependencies` | `core`, `full` | read-only | [specialist] Validate UUID-style dependencies for one asset or a project asset query. |
|
|
| `validate_prefab_references` | `core`, `full` | read-only | [specialist] Validate prefab asset references by checking serialized UUID references against asset-db. |
|
|
| `validate_scene` | `core`, `full` | read-only | [specialist] Run a compact validation pass over the active scene, runtime state, TypeScript diagnostics, and recent project log errors. |
|
|
|
|
### Events
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `bind_button_click_event` | `full` | stateful | [core] Bind a Cocos Button click event to a target node component method. |
|
|
| `emit_node_event` | `full` | mutating | [core] Emit a custom event on a target scene node with an optional JSON payload. |
|
|
| `list_button_click_events` | `full` | read-only | [core] List click event bindings on a Cocos Button component. |
|
|
| `simulate_button_click` | `full` | mutating | [core] Simulate a Cocos Button click by emitting click events on the target button node. |
|
|
|
|
### Execution
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `execute_editor_script` | `core`, `full` | mutating | [compat] Execute JavaScript in the editor/browser context. Prefer execute_javascript with context="editor" as the main unified tool; use this when you specifically want the editor-only compatibility entrypoint. |
|
|
| `execute_javascript` | `core`, `full` | mutating | [primary] Execute JavaScript in either the scene or editor context. Use context="scene" for live scene/runtime inspection and mutation, or context="editor" for Editor APIs, asset-db workflows, MCP orchestration, local filesystem access, and higher-level automation. Prefer this as the main flexible tool when many narrow tools would be noisy. |
|
|
|
|
### Files
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `exists` | `full` | read-only | [core] Check whether a project file or directory exists. |
|
|
| `get_file_snippet` | `full` | read-only | [core] Read a focused snippet around a file line number. |
|
|
| `list_directory` | `full` | read-only | [core] List files and directories inside a project directory. |
|
|
| `read_file` | `full` | read-only | [core] Read a file from the Cocos project. |
|
|
| `refresh_assets` | `full` | stateful | [core] Best-effort asset database refresh for a file or the assets root. |
|
|
| `replace_in_file` | `full` | mutating | [core] Replace text in a file, useful for script auto-fix loops. |
|
|
| `search_files` | `full` | read-only | [core] Search project files by simple wildcard pattern. |
|
|
| `write_file` | `full` | mutating | [core] Write or overwrite a file in the Cocos project. |
|
|
|
|
### Input
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `simulate_key_combo` | `full` | mutating | [core] Send a low-level Electron modified key press such as Ctrl+S or Cmd+P. |
|
|
| `simulate_key_press` | `full` | mutating | [core] Send a low-level Electron key press to the editor, preview, or simulator window. |
|
|
| `simulate_mouse_click` | `full` | mutating | [core] Send a low-level Electron mouse click to the editor, preview, or simulator window. |
|
|
| `simulate_mouse_drag` | `full` | mutating | [core] Send a low-level Electron mouse drag to the editor, preview, or simulator window. |
|
|
| `simulate_preview_input` | `full` | mutating | [core] Convenience wrapper for low-level preview/simulator input. Uses mouse click by default or key press when keyCode is provided. |
|
|
|
|
### Instructions
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `create_cocos_mcp_project_skill` | `full` | stateful | [core] Create a recommended local Codex project skill for Funplay Cocos MCP workflows. |
|
|
| `create_project_skill` | `full` | stateful | [core] Create a local Codex project skill under .codex/skills/{skillName}/SKILL.md. |
|
|
| `list_project_instructions` | `core`, `full` | read-only | [specialist] List project AI instruction files and local Codex project skills. |
|
|
| `read_project_instruction` | `core`, `full` | read-only | [specialist] Read a project AI instruction file such as AGENTS.md, CLAUDE.md, or a .codex skill SKILL.md. |
|
|
| `write_project_instruction` | `full` | mutating | [core] Create or update a project AI instruction file inside the Cocos project. |
|
|
|
|
### Logs
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `clear_logs` | `core`, `full` | mutating | [specialist] Clear in-memory MCP logs and, only with explicit confirmation, truncate common project log files. |
|
|
| `get_recent_logs` | `core`, `full` | read-only | [specialist] Return recent MCP runtime logs, recent tool interactions, and tails of common project log files. |
|
|
| `search_project_logs` | `core`, `full` | read-only | [specialist] Search common Cocos project log files for a string or regular expression. |
|
|
|
|
### Other
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `create_script` | `full` | stateful | [core] Create a new TypeScript component script with a standard Cocos template. |
|
|
| `get_performance_snapshot` | `core`, `full` | read-only | [specialist] Return scene scale and runtime performance-oriented counters such as node/component counts, UI counts, depth, memory, and warnings. |
|
|
| `list_editor_windows` | `core`, `full` | read-only | [specialist] List available Electron windows so screenshots or input-targeting can choose the correct window. Use this when window targeting is the explicit problem. |
|
|
|
|
### Prefabs
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `apply_prefab_instance` | `full` | stateful | [core] Apply a scene prefab instance back to its associated prefab asset using the Cocos editor scene apply-prefab message. |
|
|
| `create_prefab` | `full` | stateful | [core] Create a prefab asset from a scene node. |
|
|
| `create_prefab_instance` | `full` | stateful | [core] Create a linked prefab instance in the editor hierarchy using Cocos scene create-node when available. |
|
|
| `duplicate_prefab` | `full` | stateful | [core] Create a new prefab asset by duplicating an existing prefab file without copying its .meta UUID. |
|
|
| `edit_prefab_json` | `full` | stateful | [core] Edit a prefab JSON file by JSON path assignment or literal search/replace, then validate references. |
|
|
| `inspect_prefab` | `core`, `full` | read-only | [specialist] Inspect a prefab asset, its metadata, serialized file path, and UUID-like asset references. |
|
|
| `inspect_prefab_instance` | `core`, `full` | read-only | [specialist] Inspect whether a scene node is linked to a prefab instance and return prefab metadata when available. |
|
|
| `instantiate_prefab` | `full` | stateful | Instantiate a prefab into the active scene by prefab uuid. |
|
|
| `list_prefabs` | `full` | read-only | [core] List prefab assets in the project. |
|
|
| `revert_prefab_instance` | `full` | stateful | [core] Revert a scene prefab instance from its associated prefab asset using available Cocos editor prefab revert messages. |
|
|
|
|
### Preferences
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_editor_preference` | `full` | read-only | [core] Read a Cocos editor preference through Editor.Profile when available. |
|
|
| `set_editor_preference` | `full` | mutating | [core] Write a Cocos editor preference through Editor.Profile when available. |
|
|
|
|
### Project
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_editor_state` | `core`, `full` | read-only | [specialist] Return a structured editor-state snapshot including project info, runtime server status, current selection, and visible Electron windows. Prefer this when you want one compact editor summary. |
|
|
| `get_project_info` | `core`, `full` | read-only | [specialist] Return the active Cocos project path, version, and MCP server configuration. Prefer this for a fast structured project summary; use execute_javascript when you need to inspect and act in one step. |
|
|
| `get_tool_catalog` | `core`, `full` | read-only | [specialist] Return every built-in MCP tool with profile, category, and current exposure state. Use this before changing custom tool exposure. |
|
|
|
|
### Runtime
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_runtime_state` | `core`, `full` | read-only | [specialist] Return structured Cocos runtime state including pause state, frame count, and scheduler time scale. Prefer this when you want a compact validation snapshot. |
|
|
| `pause_runtime` | `full` | stateful | [core] Pause Cocos director game logic execution. |
|
|
| `resume_runtime` | `full` | stateful | [core] Resume Cocos director game logic execution. |
|
|
| `set_time_scale` | `full` | mutating | [core] Set Cocos scheduler time scale for runtime validation. |
|
|
|
|
### Scene
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `copy_paste_node` | `full` | stateful | [core] Copy, cut, or paste scene nodes via the Cocos editor clipboard. |
|
|
| `create_node` | `full` | stateful | Create a new node under the active scene or a specified parent path. |
|
|
| `delete_node` | `full` | mutating | Delete a node by path, uuid, or name. |
|
|
| `execute_scene_script` | `core`, `full` | mutating | [compat] Execute JavaScript in the active Cocos scene context. Prefer execute_javascript with context="scene" as the main unified tool; use this when you specifically want the scene-only compatibility entrypoint. |
|
|
| `find_nodes` | `full` | read-only | [core] Find scene nodes by exact name, partial path, or component type. |
|
|
| `get_hierarchy` | `core`, `full` | read-only | [specialist] Return a structured hierarchy tree from the active scene or a specific node path. Prefer execute_javascript for broader reasoning or repair; use this when you want a predictable hierarchy snapshot. |
|
|
| `get_scene_info` | `core`, `full` | read-only | [specialist] Return a structured summary of the active Cocos scene. Prefer execute_javascript for multi-step inspection or mutation; use this when you specifically want a compact scene snapshot. |
|
|
| `inspect_node` | `full` | read-only | [core] Inspect a specific node by path, uuid, or name. |
|
|
| `query_scene_state` | `core`, `full` | stateful | [specialist] Query scene state: dirty (unsaved changes), ready, or soft-reload. |
|
|
| `rename_node` | `full` | stateful | [core] Rename a scene node. |
|
|
| `reparent_node` | `full` | stateful | [core] Move a node to a new parent in the scene hierarchy. |
|
|
| `set_node_transform` | `full` | mutating | Update node position, rotation, scale, or active state. |
|
|
|
|
### Screenshots
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `capture_desktop_screenshot` | `full` | read-only | [core] Capture a screenshot from the local desktop and return it as an MCP image payload. |
|
|
| `capture_editor_screenshot` | `core`, `full` | read-only | [specialist] Capture the focused Cocos Creator editor window and return it as an MCP image payload. Prefer screenshot tools only when visual verification is explicitly needed. |
|
|
| `capture_game_screenshot` | `full` | read-only | [core] Capture the Game/Preview panel region from the editor window with panel-level cropping when available. |
|
|
| `capture_preview_screenshot` | `core`, `full` | read-only | [specialist] Capture the preview or simulator window as an MCP image payload. Prefer this only when you need visual proof of game or preview output. |
|
|
| `capture_scene_screenshot` | `core`, `full` | read-only | [specialist] Capture the Scene panel region from the editor window with panel-level cropping when available. Prefer this only for visual validation of scene-side results. |
|
|
|
|
### Selection
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `get_editor_selection` | `full` | read-only | [compat] Return the current node and asset selection in the Cocos editor. Prefer get_selection as the primary structured selection read tool. |
|
|
| `get_selection` | `core`, `full` | read-only | [specialist] Return the current editor selection in a compact structured form. Prefer this when selection state matters for the next action. |
|
|
| `set_selection` | `core`, `full` | mutating | [specialist] Set or clear the current editor selection for an asset or node. Use this when downstream editor workflows depend on selection state. |
|
|
|
|
### Ui
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `create_button` | `full` | stateful | Create a UI Button node with child Label. |
|
|
| `create_canvas` | `full` | stateful | Create a Cocos Canvas node with UITransform. |
|
|
| `create_label` | `full` | stateful | Create a UI Label node under a parent. |
|
|
| `create_sprite` | `full` | stateful | Create a UI Sprite node, optionally assigning a SpriteFrame asset uuid. |
|
|
|
|
### Updates
|
|
|
|
| Tool | Profiles | Access | Description |
|
|
|---|---|---|---|
|
|
| `check_for_updates` | `core`, `full` | read-only | [specialist] Check the latest Funplay Cocos MCP GitHub release and compare it with the installed extension version. |
|
|
|