[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80328":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":36,"readmeContent":37,"aiSummary":38,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":39,"discoverSource":40},80328,"godot-devtool","wangdiandao\u002Fgodot-devtool","wangdiandao","Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation.","https:\u002F\u002Fgithub.com\u002Fwangdiandao\u002Fgodot-devtool#readme",null,"TypeScript",75,6,64,2,0,1,10,2.54,"MIT License",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35],"ai","ai-assisted-development","automation","developer-tools","game-development","gamedev","godot","godot-engine","mcp","model-context-protocol","typescript","2026-06-12 02:04:01","# godot-devtool\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg)](LICENSE)\n[![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-3.2.0-blue.svg)](CHANGELOG.md)\n[![Godot](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGodot-4.x-478cbf.svg)](https:\u002F\u002Fgodotengine.org\u002F)\n[![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-server-111827.svg)](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.x-3178c6.svg)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n\nEnglish | [中文](README.zh-CN.md)\n\n[Buy me a coffee on Patreon](https:\u002F\u002Fpatreon.com\u002Fwangdiandao) if this project helps you. I am not very familiar with editing Patreon pages yet; thanks for your understanding.\n\n`godot-devtool` is a Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation. The stdio MCP server starts without binding the WebSocket bridge port; bridge tools open the local bridge on demand, keep it alive while `run_project` is active or a runtime client is connected, and otherwise release the port after tool-call cleanup.\n\n## Architecture\n\n```text\nMCP client\n  -> node build\u002Findex.js over stdio\n  -> native\u002Fheadless Godot tools\n  -> optional ws:\u002F\u002F127.0.0.1:8766 bridge\n  -> addons\u002Fgodot_devtool editor plugin\n  -> runtime autoload bridge\n```\n\n- The MCP server always runs over stdio.\n- Native routes inspect and edit project files without opening the editor.\n- Headless routes call Godot for scene\u002Fresource\u002Fscript operations.\n- Editor routes use the bundled WebSocket plugin for live selection, Inspector writes, UndoRedo scene mutations, scene save, and plugin reload.\n- Runtime routes use the installed autoload bridge for running-game scene tree, properties, input simulation, screenshots, and QA checks.\n- Browser visualizer routes serve a local read-only HTTP dashboard for bridge\u002Fclient status and live-route orientation.\n- The local WebSocket listener is a shared broker, so multiple MCP clients or AI agents can use the same bridge port instead of each spawning an exclusive listener.\n- Editor and runtime sessions are identified by `projectPath`, `context`, `sessionId`, and `runId`; ambiguous live targets return candidates instead of guessing.\n- `run_project` creates tracked run instances. Use `list_run_instances`, `get_debug_output`, `stop_project`, and `stop_run_instance` with `runId` when multiple game instances are active.\n- `get_capabilities` supports focused workflow filters such as `project_setup`, `live_editor`, `runtime_test`, `multi_instance`, and `release_verify` to keep assistant context small.\n- `tools\u002Flist` is router-only: it exposes only entry tools plus tool category metadata, with no cursor pagination or environment-variable mode switch. Load full tool input schemas through filtered `get_capabilities` calls.\n\n## Requirements\n\n- Node.js 18 or newer.\n- Godot 4.x. Set `GODOT_PATH` unless `godot` is already on `PATH`.\n- An MCP client such as Codex, Claude Code, Cursor, Cline, Roo Code, VS Code Copilot, or another client that can launch stdio MCP servers.\n- A Godot project containing `project.godot`.\n\n## Codex And Claude Plugin Bundle\n\nThe repository is also packaged like an IDE plugin bundle for agentic coding tools:\n\n- [plugin.json](plugin.json) exposes the shared plugin metadata, `agents\u002F`, and `skills\u002F`.\n- [.codex-plugin\u002Fplugin.json](.codex-plugin\u002Fplugin.json) exposes Codex marketplace\u002Finterface metadata.\n- [.claude-plugin\u002Fplugin.json](.claude-plugin\u002Fplugin.json) exposes Claude Code plugin metadata.\n- [agents\u002Fgodot-dev.agent.md](agents\u002Fgodot-dev.agent.md) is the user-invocable `godot-dev` Agent. It routes work through [skills\u002Fgodot-devtool\u002FSKILL.md](skills\u002Fgodot-devtool\u002FSKILL.md) and the focused workflow skills.\n\n`npm run build` copies these manifests, the Agent, and all Skills into `build\u002F` so a release zip contains the MCP server plus the IDE-style guidance layer.\n\n## Install From Local Build\n\n1. Build from source, or extract a published release zip to a stable path. The release asset name for this version is `godot-devtool-build-3.2.0.zip`.\n\n   ```powershell\n   Expand-Archive \".\\godot-devtool-build-3.2.0.zip\" \"E:\\godot-devtool\" -Force\n   ```\n\n2. Confirm the server entry exists:\n\n   ```powershell\n   Test-Path \"E:\\godot-devtool\\build\\index.js\"\n   Test-Path \"E:\\godot-devtool\\build\\addons\\godot_devtool\\plugin.gd\"\n   ```\n\n3. Add this MCP server to your client configuration:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"godot-devtool\": {\n         \"command\": \"node\",\n         \"args\": [\"E:\u002Fgodot-devtool\u002Fbuild\u002Findex.js\"],\n         \"env\": {\n           \"GODOT_PATH\": \"D:\u002FProgram Files\u002FGodot\u002FGodot_v4.x.exe\",\n           \"GODOT_DEVTOOL_WS_PORT\": \"8766\"\n         }\n       }\n     }\n   }\n   ```\n\n   Codex Desktop uses TOML in `config.toml`:\n\n   ```toml\n   [mcp_servers.godot-devtool]\n   command = \"node\"\n   args = [\"E:\u002Fgodot-devtool\u002Fbuild\u002Findex.js\"]\n   env = { GODOT_PATH = \"D:\u002FProgram Files\u002FGodot\u002FGodot_v4.x.exe\", GODOT_DEVTOOL_WS_PORT = \"8766\" }\n   ```\n\n4. Restart the MCP client and ask it to call:\n\n   ```text\n   get_godot_version\n   get_capabilities\n   get_capabilities {\"toolNames\":[\"plugin_install\",\"plugin_status\",\"plugin_cleanup_port\"],\"includeSchemas\":true}\n   ```\n\n`GODOT_DEVTOOL_WS_PORT` defaults to `8766`. The stdio MCP server starts without opening that port. Bridge tools open it on demand; editor-only calls release it during cleanup, while a project launched through `run_project` or an already connected runtime client keeps the listener open so runtime commands do not depend on a one-call reconnect window. If another `godot-devtool` process already owns the same port, broker-aware calls can forward through that listener instead of killing it.\n\nIf another listener already holds the port while a bridge tool runs, use `plugin_status` and `plugin_cleanup_port` to inspect it. Only call `plugin_cleanup_port` with `kill=true` after confirming the listener is stale; switching ports creates a separate bridge and does not adopt editor clients connected to the old one.\n\n## Build From Source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fwangdiandao\u002Fgodot-devtool.git\ncd godot-devtool\nnpm install\nnpm run build\n```\n\nUse `build\u002Findex.js` as the MCP server entry. The bundled Godot addon is copied into `build\u002Faddons\u002Fgodot_devtool` during `npm run build`.\n\n## Install The Godot Plugin\n\nThe plugin is included in the release\u002Fbuild package. It still must be installed into each Godot project that needs live editor or runtime routes.\n\n1. Start your MCP client with `godot-devtool` configured.\n2. Ask the AI or call the tool directly:\n\n   ```text\n   plugin_install\n   ```\n\n   Arguments:\n\n   ```json\n   {\n     \"projectPath\": \"E:\u002Fmy-godot-project\",\n     \"overwrite\": true,\n     \"websocketPort\": 8766\n   }\n   ```\n\n3. Open the Godot project.\n4. Enable the plugin:\n\n   ```text\n   Project > Project Settings > Plugins > godot-devtool > Enable\n   ```\n\n5. Check installation and connection:\n\n   ```text\n   plugin_status\n   ```\n\nFor runtime routes, `plugin_install` also registers:\n\n```text\nautoload\u002FDevtoolRuntime = *res:\u002F\u002Faddons\u002Fgodot_devtool\u002Fruntime_bridge.gd\n```\n\nRun the project from Godot before using `runtime_ws` tools. The editor plugin connects while the editor is open; the runtime bridge connects while the game is running.\n\n## Ask AI To Install It\n\nAfter adding the MCP server to your client, you can paste this prompt into the AI assistant:\n\n```text\nUse the godot-devtool MCP server to install and verify the Godot plugin for my project.\n\nProject path: \"E:\u002Fmy-godot-project\"\nWebSocket port: 8766\n\nSteps:\n1. Call get_godot_version and get_capabilities for the lightweight tool catalog.\n2. Confirm plugin_install, plugin_status, plugin_reload, and plugin_cleanup_port are available.\n3. If you need input schemas, call get_capabilities with toolNames=[\"plugin_install\",\"plugin_status\",\"plugin_reload\",\"plugin_cleanup_port\"] and includeSchemas=true.\n4. Call plugin_install with overwrite=true for the project path above.\n5. Call plugin_status and summarize installed files, autoload registration, bridge mode, and WebSocket port.\n6. Tell me exactly how to enable the plugin in Godot.\n7. If runtime routes are needed, tell me to run the project and then verify runtime bridge status.\nDo not edit unrelated files.\n```\n\nChinese prompt:\n\n```text\n请使用 `godot-devtool` MCP server 帮我安装并验收 Godot 插件。\n\n项目路径: \"E:\u002Fmy-godot-project\"\nWebSocket 端口: 8766\n\n步骤:\n1. 调用 get_godot_version 和 get_capabilities，先获取轻量工具目录。\n2. 确认 plugin_install、plugin_status、plugin_reload、plugin_cleanup_port 可用。\n3. 如果需要输入 schema，调用 get_capabilities，传入 toolNames=[\"plugin_install\",\"plugin_status\",\"plugin_reload\",\"plugin_cleanup_port\"] 和 includeSchemas=true。\n4. 对上述项目路径调用 plugin_install，overwrite=true。\n5. 调用 plugin_status，总结已安装文件、autoload 注册、bridge mode 和 WebSocket 端口。\n6. 告诉我在 Godot 编辑器里如何启用插件。\n7. 如果需要 runtime 路由，提醒我运行项目后再验证 runtime bridge 状态。\n不要修改无关文件。\n```\n\n## What It Can Do\n\nUse `get_capabilities` as the source of truth. The MCP `tools\u002Flist` response is a context-budget-safe router surface: it exposes only `get_capabilities`, `get_godot_version`, and `list_projects`, plus `_meta.toolCategories` summaries for route groups, workflows, transports, and risk levels. It does not support cursor pagination and does not provide an environment-variable switch back to full-schema `tools\u002Flist`. The default `get_capabilities` call returns a lightweight catalog with `routeGroup`, `transport`, `riskLevel`, `requiresEditor`, `requiresRuntime`, and `canonicalName` when a tool is implemented through a shared capability. It does not include input schemas by default. To load full input schemas, narrow the request with `workflow`, `routeGroup`, `transport`, `riskLevel`, `toolNames`, or `query`, then set `includeSchemas=true`; unfiltered schema requests are rejected to keep the response small.\n\nCore project tools inspect `project.godot`, list projects, read and update project settings with dry-run support, configure InputMap actions with native Godot syntax, run the project, stop the current run, export configured presets, update Godot 4.4+ UIDs, and run release-friendly project checks. Scene and node tools create\u002Fopen\u002Fsave scenes, inspect scene trees, add\u002Fdelete\u002Frename\u002Fduplicate\u002Fmove nodes, update properties with structured Variant values, manage groups, inspect dependencies, and apply cross-scene edits.\n\nScript, filesystem, and resource tools index GDScript files, read\u002Fwrite scripts, create and attach scripts, run syntax checks, read\u002Fwrite\u002Flist\u002Fsearch\u002Fdelete project files, load\u002Fsave resources, build dependency graphs, inspect export presets, and preview resource content. Visual workflow tools cover shaders, materials, particles, UI themes\u002Ftemplates, physics bodies and collision layers, navigation regions\u002Fagents\u002Fmeshes, lighting\u002Fenvironment setup, TileMap edits, animation tracks\u002Fkeyframes, and AnimationTree state machine operations.\n\nEditor tools install and verify the bundled `godot-devtool` plugin, reload it through the WebSocket bridge, read the live editor selection, select nodes, perform UndoRedo, read\u002Fwrite Inspector properties, and add\u002Fdelete\u002Frename\u002Fmove\u002Fduplicate nodes in the currently open scene without forcing an external disk reload. The `GDT` dock shows connection state, the active edited scene, current selection, live-edit availability, save mode, runtime session diagnostics, and the latest command result. Runtime tools work while the game is running: they can read the live scene tree and node properties, set runtime properties, capture screenshots\u002Fframes, simulate input actions, inspect UI text\u002Fbuttons, wait for nodes, navigate agents, monitor properties, record\u002Freplay interactions, and run QA-style assertions and stress checks.\n\nBrowser visualizer tools start, inspect, and stop a local read-only dashboard. Use `browser_visualizer_start` to open a `http:\u002F\u002F127.0.0.1:\u003Cport>\u002F` page that refreshes bridge status, connected editor\u002Fruntime clients, pending command count, and the existing screenshot\u002Fscene\u002Finput route names to call from the MCP client.\n\nThe table below is generated from the actual tool definitions so the README stays aligned with the MCP server.\n\n## All 235 Tools\n\n### Project Tools (18)\n| Tool | Description |\n|------|-------------|\n| `add_autoload` | Exact-name compatibility route for add_autoload. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `export_project` | Run a controlled Godot export for a configured preset |\n| `get_autoload` | Exact-name compatibility route for get_autoload. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_input_actions` | Get input actions using the project_input_action implementation. |\n| `get_project_info` | Retrieve metadata about a Godot project |\n| `get_project_statistics` | Get project statistics using the get_project_info implementation. |\n| `list_projects` | List Godot projects in a directory |\n| `project_get_settings` | Read Godot project.godot settings by section or section\u002Fkey list |\n| `project_input_action` | List or update project InputMap actions in project.godot |\n| `project_set_setting` | Update Godot project.godot settings with dry-run preview and audit logging |\n| `reload_project` | Exact-name compatibility route for reload_project. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `remove_autoload` | Exact-name compatibility route for remove_autoload. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `run_project` | Run the Godot project and capture output |\n| `run_project_checks` | Run stable project checks for CI, review, and release workflows |\n| `set_input_action` | Set input action using the project_input_action implementation. |\n| `stop_project` | Stop the currently running Godot project |\n| `uid_to_project_path` | Exact-name compatibility route for uid_to_project_path. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `update_project_uids` | Update UID references in a Godot project by resaving resources (for Godot 4.4+) |\n\n### Scene Tools (51)\n| Tool | Description |\n|------|-------------|\n| `add_animation_track` | Add animation track using the animation implementation. |\n| `add_audio_bus` | Exact-name compatibility route for add_audio_bus. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_audio_bus_effect` | Exact-name compatibility route for add_audio_bus_effect. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_audio_player` | Add audio player using the audio implementation. |\n| `add_scene_instance` | Exact-name compatibility route for add_scene_instance. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `analyze_scene_complexity` | Exact-name compatibility route for analyze_scene_complexity. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `analyze_signal_flow` | Exact-name compatibility route for analyze_signal_flow. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `animation` | Create, inspect, remove, and edit AnimationPlayer tracks and keyframes |\n| `animation_state_machine` | Create, inspect, and configure AnimationTree state machines |\n| `audio` | Create and list AudioStreamPlayer nodes with basic playback configuration |\n| `bake_navigation_mesh` | Bake navigation mesh using the navigation implementation. |\n| `connect_signal` | Connect signal using the signal implementation. |\n| `create_animation` | Create animation using the animation implementation. |\n| `create_animation_tree` | Create animation tree using the animation_state_machine implementation. |\n| `create_scene` | Create a new Godot scene file |\n| `cross_scene_set_property` | Exact-name compatibility route for cross_scene_set_property. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `disconnect_signal` | Disconnect signal using the signal implementation. |\n| `find_signal_connections` | Exact-name compatibility route for find_signal_connections. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_animation_info` | Get animation info using the animation implementation. |\n| `get_animation_tree_structure` | Exact-name compatibility route for get_animation_tree_structure. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_audio_bus_layout` | Get audio bus layout using the audio implementation. |\n| `get_audio_info` | Get audio info using the audio implementation. |\n| `get_collision_info` | Get collision info using the physics implementation. |\n| `get_navigation_info` | Get navigation info using the navigation implementation. |\n| `get_physics_layers` | Exact-name compatibility route for get_physics_layers. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_scene_dependencies` | Exact-name compatibility route for get_scene_dependencies. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_scene_tree` | Return the node tree for a Godot scene |\n| `get_signals` | Get signals using the signal implementation. |\n| `list_animations` | List animations using the animation implementation. |\n| `navigation` | Create, inspect, configure, bake, query, and debug NavigationRegion and NavigationAgent nodes |\n| `physics` | Create, inspect, configure, template, and analyze physics bodies, areas, collision layers, and shapes |\n| `remove_animation` | Remove animation using the animation implementation. |\n| `save_scene` | Save changes to a scene file |\n| `scene_get_current` | Return the current scene tracked by this MCP session, if one was opened |\n| `scene_open` | Open a scene in the MCP session using headless\u002Ffile-based scene access |\n| `set_animation_keyframe` | Set animation keyframe using the animation implementation. |\n| `set_audio_bus` | Exact-name compatibility route for set_audio_bus. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_navigation_layers` | Exact-name compatibility route for set_navigation_layers. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_physics_layers` | Set physics layers using the physics implementation. |\n| `setup_collision` | Set up collision using the physics implementation. |\n| `setup_navigation_agent` | Set up navigation agent using the navigation implementation. |\n| `setup_navigation_region` | Set up navigation region using the navigation implementation. |\n| `setup_physics_body` | Set up physics body using the physics implementation. |\n| `signal` | List, connect, or disconnect node signals in a scene |\n| `tilemap` | Create, list, and edit TileMapLayer or legacy TileMap nodes |\n| `tilemap_clear` | Clear TileMap using the tilemap implementation. |\n| `tilemap_fill_rect` | Fill TileMap rect using the tilemap implementation. |\n| `tilemap_get_cell` | Get TileMap cell using the tilemap implementation. |\n| `tilemap_get_info` | Get TileMap info using the tilemap implementation. |\n| `tilemap_get_used_cells` | Get TileMap used cells using the tilemap implementation. |\n| `tilemap_set_cell` | Set TileMap cell using the tilemap implementation. |\n\n### Node Tools (17)\n| Tool | Description |\n|------|-------------|\n| `add_node` | Add a node to an existing scene |\n| `delete_node` | Delete a non-root node from a Godot scene |\n| `find_node_references` | Exact-name compatibility route for find_node_references. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `find_nodes_by_type` | Find nodes by type using the node_find implementation. |\n| `find_nodes_in_group` | Exact-name compatibility route for find_nodes_in_group. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_node_groups` | Exact-name compatibility route for get_node_groups. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_node_properties` | Read selected properties from a node in a Godot scene |\n| `group` | List, add, or remove node groups |\n| `move_node` | Move node using the node_move implementation. |\n| `node_duplicate` | Duplicate a node in a Godot scene |\n| `node_find` | Find nodes in a scene by name, type, or path substring |\n| `node_get` | Get node information from a Godot scene |\n| `node_move` | Move a node by setting its position or reparenting it in a Godot scene |\n| `rename_node` | Rename a node in a Godot scene |\n| `set_blend_tree_node` | Exact-name compatibility route for set_blend_tree_node. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_node_groups` | Exact-name compatibility route for set_node_groups. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `update_node_properties` | Update properties on a node in a Godot scene |\n\n### Script Tools (11)\n| Tool | Description |\n|------|-------------|\n| `analyze_script_references` | Analyze a GDScript file for class, functions, exports, node paths, and resource references |\n| `check_gdscript_syntax` | Run Godot --check-only against a GDScript file and return diagnostics |\n| `edit_script` | Edit script using the script_write implementation. |\n| `execute_editor_script` | Exact-name compatibility route for execute_editor_script. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `find_nodes_by_script` | Exact-name compatibility route for find_nodes_by_script. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `find_script_references` | Exact-name compatibility route for find_script_references. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_open_scripts` | Exact-name compatibility route for get_open_scripts. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_script_index` | Return GDScript files with class, base class, exported variables, and functions |\n| `script_attach` | Attach a GDScript resource to a node in a scene |\n| `script_create` | Create a GDScript file inside a Godot project |\n| `script_write` | Write full GDScript content with overwrite protection |\n\n### Editor Tools (17)\n| Tool | Description |\n|------|-------------|\n| `editor_add_node` | Add a node to the currently open editor scene through UndoRedo without externally rewriting the scene file |\n| `editor_delete_node` | Delete a non-root node from the currently open editor scene through UndoRedo |\n| `editor_duplicate_node` | Duplicate a node in the currently open editor scene through UndoRedo |\n| `editor_get_selection` | Return the current editor selection when a live editor bridge is available |\n| `editor_inspector_get_properties` | Read Inspector properties from the selected or addressed node through the live editor bridge |\n| `editor_inspector_set_properties` | Write Inspector properties on the selected or addressed node through the live editor bridge |\n| `editor_move_node` | Move or reparent a node in the currently open editor scene through UndoRedo |\n| `editor_rename_node` | Rename a node in the currently open editor scene through UndoRedo |\n| `editor_save_scene` | Save the currently open editor scene through the live editor bridge |\n| `editor_select_node` | Select a node in the live Godot editor when an editor bridge is available |\n| `editor_undo_redo` | Perform undo or redo in the live Godot editor when an editor bridge is available |\n| `plugin_cleanup_port` | Explicitly inspect and optionally stop stale godot-devtool WebSocket bridge listeners on a local port |\n| `plugin_dock_status` | Return machine-readable godot-devtool Dock labels, tooltips, status dots, buttons, visibility, and bridge diagnostics from the live editor |\n| `plugin_install` | Install the godot-devtool WebSocket editor\u002Fruntime plugin into a Godot project |\n| `plugin_reload` | Reload the godot-devtool editor plugin through the WebSocket bridge |\n| `plugin_status` | Read godot-devtool plugin installation status, WebSocket bridge configuration, connected clients, and occupied-port diagnostics |\n| `reload_plugin` | Exact-name compatibility route for reload_plugin. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n\n### Filesystem Tools (11)\n| Tool | Description |\n|------|-------------|\n| `delete_scene` | Delete scene using the filesystem_delete implementation. |\n| `filesystem_delete` | Delete a project-local file or directory with explicit confirmation |\n| `filesystem_list` | List files and directories inside a Godot project |\n| `filesystem_preview_delete` | Preview a project-local delete operation without deleting files |\n| `filesystem_read` | Read a UTF-8 text file inside a Godot project |\n| `filesystem_write` | Write a UTF-8 text file inside a Godot project |\n| `get_filesystem_tree` | Get filesystem tree using the filesystem_list implementation. |\n| `get_scene_file_content` | Get scene file content using the filesystem_read implementation. |\n| `read_script_file` | Read a GDScript file from a Godot project |\n| `search_files` | Exact-name compatibility route for search_files. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `search_in_files` | Exact-name compatibility route for search_in_files. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n\n### Resource Tools (16)\n| Tool | Description |\n|------|-------------|\n| `add_resource` | Add resource using the resource_create implementation. |\n| `check_export_presets` | Inspect Godot export presets and report pre-export issues |\n| `edit_resource` | Edit resource using the resource_save implementation. |\n| `export_matrix` | Summarize export targets, platform families, signing\u002Ftemplate status, and CI steps |\n| `export_mesh_library` | Export a scene as a MeshLibrary resource |\n| `find_unused_resources` | Find unused resources using the resource_dependency_graph implementation. |\n| `get_export_info` | Get export info using the export_matrix implementation. |\n| `get_export_presets` | Read configured Godot export presets |\n| `get_resource_index` | Return a categorized resource index for a Godot project |\n| `get_resource_preview` | Exact-name compatibility route for get_resource_preview. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_uid` | Get the UID for a specific file in a Godot project (for Godot 4.4+) |\n| `resource_create` | Create a simple structured Godot resource file |\n| `resource_dependency_graph` | Build a resource dependency graph and identify orphan resources |\n| `resource_load` | Load a text-based Godot resource from the project |\n| `resource_save` | Save text-based Godot resource content with overwrite protection |\n| `update_export_preset` | Update fields or options for a configured Godot export preset |\n\n### Visual Tools (25)\n| Tool | Description |\n|------|-------------|\n| `apply_particle_preset` | Exact-name compatibility route for apply_particle_preset. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `assign_shader_material` | Assign shader material using the material implementation. |\n| `create_particles` | Create particles using the particle implementation. |\n| `create_shader` | Create shader using the shader implementation. |\n| `create_theme` | Create theme using the ui implementation. |\n| `edit_shader` | Exact-name compatibility route for edit_shader. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_particle_info` | Exact-name compatibility route for get_particle_info. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_shader_params` | Get shader params using the shader implementation. |\n| `get_theme_info` | Exact-name compatibility route for get_theme_info. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `lighting` | Create and list basic Godot light and environment nodes |\n| `material` | Create, read, update, and apply Godot material resources |\n| `particle` | Create and list basic Godot particle emitter nodes |\n| `read_shader` | Read shader using the shader implementation. |\n| `set_material_3d` | Set material 3d using the material implementation. |\n| `set_particle_color_gradient` | Exact-name compatibility route for set_particle_color_gradient. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_particle_material` | Exact-name compatibility route for set_particle_material. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_shader_param` | Set shader param using the shader implementation. |\n| `set_theme_color` | Exact-name compatibility route for set_theme_color. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_theme_constant` | Exact-name compatibility route for set_theme_constant. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_theme_font_size` | Exact-name compatibility route for set_theme_font_size. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_theme_stylebox` | Exact-name compatibility route for set_theme_stylebox. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `setup_environment` | Set up environment using the lighting implementation. |\n| `setup_lighting` | Set up lighting using the lighting implementation. |\n| `shader` | Create, read, inspect, and configure ShaderMaterial parameters |\n| `ui` | Create Control nodes, reusable UI templates, themes, and automatic signal wiring |\n\n### Runtime Tools (30)\n| Tool | Description |\n|------|-------------|\n| `assert_node_state` | Exact-name compatibility route for assert_node_state. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `assert_screen_text` | Exact-name compatibility route for assert_screen_text. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `capture_frames` | Runtime WebSocket compatibility route. Executes capture_frames through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `click_button_by_text` | Runtime WebSocket compatibility route. Executes click_button_by_text through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `compare_screenshots` | Exact-name compatibility route for compare_screenshots. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `create_workflow_test_scene` | Create a small Godot scene for validating MCP scene\u002Fscript\u002Fcheck workflows |\n| `execute_game_script` | Runtime WebSocket compatibility route. Executes execute_game_script through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `find_nearby_nodes` | Runtime WebSocket compatibility route. Executes find_nearby_nodes through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `find_ui_elements` | Runtime WebSocket compatibility route. Executes find_ui_elements through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `get_editor_screenshot` | Exact-name compatibility route for get_editor_screenshot. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_game_node_properties` | Runtime WebSocket compatibility route. Executes get_game_node_properties through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `get_game_scene_tree` | Runtime WebSocket compatibility route. Executes get_game_scene_tree through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `get_game_screenshot` | Runtime WebSocket compatibility route. Executes get_game_screenshot through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `get_performance_monitors` | Runtime WebSocket compatibility route. Executes get_performance_monitors through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `get_test_report` | Exact-name compatibility route for get_test_report. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `monitor_properties` | Runtime WebSocket compatibility route. Executes monitor_properties through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `move_to` | Runtime WebSocket compatibility route. Executes move_to through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `navigate_to` | Runtime WebSocket compatibility route. Executes navigate_to through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `replay_recording` | Runtime WebSocket compatibility route. Executes replay_recording through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `run_stress_test` | Exact-name compatibility route for run_stress_test. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `run_test_scenario` | Exact-name compatibility route for run_test_scenario. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_game_node_property` | Runtime WebSocket compatibility route. Executes set_game_node_property through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `simulate_action` | Runtime WebSocket compatibility route. Executes simulate_action through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `simulate_key` | Runtime WebSocket compatibility route. Executes simulate_key through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `simulate_mouse_click` | Runtime WebSocket compatibility route. Executes simulate_mouse_click through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `simulate_mouse_move` | Runtime WebSocket compatibility route. Executes simulate_mouse_move through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `simulate_sequence` | Runtime WebSocket compatibility route. Executes simulate_sequence through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `start_recording` | Runtime WebSocket compatibility route. Executes start_recording through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `stop_recording` | Runtime WebSocket compatibility route. Executes stop_recording through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n| `wait_for_node` | Runtime WebSocket compatibility route. Executes wait_for_node through the running Godot runtime bridge and returns a failed receipt when DevtoolRuntime is not connected. |\n\n### Core Tools (39)\n| Tool | Description |\n|------|-------------|\n| `add_gridmap` | Exact-name compatibility route for add_gridmap. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_mesh_instance` | Exact-name compatibility route for add_mesh_instance. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_raycast` | Exact-name compatibility route for add_raycast. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_state_machine_state` | Exact-name compatibility route for add_state_machine_state. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `add_state_machine_transition` | Exact-name compatibility route for add_state_machine_transition. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `batch_get_properties` | Exact-name compatibility route for batch_get_properties. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `batch_set_property` | Exact-name compatibility route for batch_set_property. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `broker_cleanup_idle` | Stop the transient shared broker listener only when no clients, runs, or pending commands require it |\n| `broker_status` | Read the shared godot-devtool 3.0 WebSocket broker status, connected clients, pending commands, and leases |\n| `browser_visualizer_start` | Start a local read-only browser dashboard for Godot editor\u002Fruntime bridge status and live-route guidance |\n| `browser_visualizer_status` | Read the local Browser visualizer URL, project filter, and connected editor\u002Fruntime bridge clients |\n| `browser_visualizer_stop` | Stop the local Browser visualizer HTTP dashboard |\n| `clear_debug_output` | Clear buffered output for the currently running Godot project |\n| `create_gameplay_prototype` | Create a high-level block-based gameplay prototype scaffold in a Godot project |\n| `detect_circular_dependencies` | Exact-name compatibility route for detect_circular_dependencies. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `generate_ci_snippet` | Generate GitHub Actions or GitLab CI snippets for Godot headless checks, export preflight, release export, and artifact archiving |\n| `geometry` | Create and list basic 2D geometry\u002Fdebug drawing nodes |\n| `get_audit_log` | Read godot-devtool project audit log entries |\n| `get_audit_replay` | Summarize godot-devtool audit log entries into replay steps, counters, and risk highlights |\n| `get_capabilities` | Return a lightweight godot-devtool tool catalog by default, with optional filtered input schemas by route group, transport, risk level, tool name, or query |\n| `get_debug_output` | Get the current debug output and errors |\n| `get_editor_errors` | Exact-name compatibility route for get_editor_errors. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_editor_performance` | Exact-name compatibility route for get_editor_performance. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `get_godot_version` | Get the installed Godot version |\n| `get_rollback_suggestions` | Return honest rollback guidance for an operation, audit entry, or changed paths |\n| `get_safety_policy` | Read the project-local godot-devtool safety policy and default enforcement state |\n| `launch_editor` | Reuse an already connected Godot editor for a project, launch one only when no bridge is connected, and refuse to open a replacement editor when the configured bridge port is occupied by another listener |\n| `list_bridge_sessions` | List connected editor\u002Fruntime bridge sessions with sessionId, runId, project path, context, and last-seen time |\n| `list_run_instances` | List Godot game\u002Feditor run instances managed by this MCP server |\n| `load_sprite` | Load a sprite into a Sprite2D node |\n| `preview_write_safety` | Preview safety policy and diff summary metadata for proposed writes or deletes |\n| `remove_state_machine_state` | Exact-name compatibility route for remove_state_machine_state. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `remove_state_machine_transition` | Exact-name compatibility route for remove_state_machine_transition. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `resolve_bridge_target` | Resolve the editor\u002Fruntime bridge target for a project and report ambiguity candidates without sending a command |\n| `set_anchor_preset` | Exact-name compatibility route for set_anchor_preset. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `set_safety_policy` | Configure project write allowlists and blocked paths in .godot-devtool\u002Fsafety.json |\n| `set_tree_parameter` | Exact-name compatibility route for set_tree_parameter. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `setup_camera_3d` | Exact-name compatibility route for setup_camera_3d. Executes through its registered compatibility implementation and returns a structured error when required project, editor, or runtime state is unavailable. |\n| `stop_run_instance` | Stop one Godot run instance by runId |\n\n## Which Route Should I Use?\n\n- Use `native` routes for project inspection, file edits, settings, indexes, safety policy, and dependency checks.\n- Use `headless_godot` routes when Godot must load or mutate scenes\u002Fresources\u002Fscripts correctly.\n- Use `editor_ws` only when the current open editor state matters.\n- Use `runtime_ws` only after the game is running and you need live game state, input, screenshots, or QA assertions.\n- Use `get_capabilities` before automating unfamiliar workflows. Request schemas only for the active workflow, route group, or exact tools; do not rely on `tools\u002Flist` for full schemas.\n\n## Verification\n\nStatic and package checks:\n\n```bash\nnpx.cmd tsc --noEmit\nnpm.cmd run build\nnpm.cmd run verify:tools\nnpm.cmd run verify:gdscripts\nnpm.cmd run verify:visualizer\nnpm.cmd run verify:plugin\n```\n\nFull release checks require `GODOT_PATH` and a local Godot runtime:\n\n```bash\nnpm.cmd run verify:runtime\nnpm.cmd run verify:process\nnpm.cmd run verify:security\nnpm.cmd run verify:all\nnpm.cmd run check:project -- \"C:\u002Fpath\u002Fto\u002Fyour-godot-project\"\n```\n\nAfter a development branch passes the required verification gates, merge it into `main` before treating the branch as complete.\n\n## Troubleshooting\n\n- `get_godot_version` fails: set `GODOT_PATH` to the exact Godot executable.\n- `plugin_status` says not installed: run `plugin_install` for the correct project path.\n- Editor routes time out: open the project in Godot and enable the plugin.\n- Runtime routes time out: run the game so the `DevtoolRuntime` autoload can connect.\n- Port conflict: inspect the owner with `plugin_cleanup_port`; stop only a verified stale listener, or deliberately set a matching alternate `GODOT_DEVTOOL_WS_PORT` and reinstall with the same `websocketPort`.\n- MCP client cannot start the server: confirm `node` is available and `build\u002Findex.js` exists.\n\n## Skill\n\nAgent operating guidance is bundled at:\n\n[skills\u002Fgodot-devtool\u002FSKILL.md](skills\u002Fgodot-devtool\u002FSKILL.md)\n\nFeed this `SKILL.md` to your AI assistant before asking it to operate on a Godot project. In clients that support file context, attach or reference the file directly; otherwise paste its contents into the chat and tell the AI to follow it when using the `godot-devtool` MCP server.\n\nThe skill maps common Godot operations to the correct MCP tools, teaches assistants to inspect project state first, use stdio\u002Fheadless routes for repeatable edits, install\u002Fuse the WebSocket plugin only when live editor or runtime state is required, and validate changes before finishing.\n\n","`godot-devtool` 是一个基于 Godot 4 的 MCP 服务器，用于 AI 辅助的项目检查、编辑、验证和运行时自动化。该项目通过 TypeScript 编写，支持多种开发工具和 AI 客户端，能够实现无需打开编辑器即可进行项目文件的检查与修改，并且可以通过 WebSocket 插件实现实时选择、属性修改、撤销重做等操作。此外，它还提供了运行时自动化功能，如场景树访问、属性获取、输入模拟及截图等。适用于游戏开发过程中需要提高效率和质量保证的场景，特别是对于那些希望利用 AI 技术来辅助开发的团队来说，`godot-devtool` 是一个非常实用的工具。","2026-06-11 04:00:20","CREATED_QUERY"]