joywaygamess/server-deploy

Fork 0

Files

Joywayer 18e24d40f0 新增godot mcp github copilot

2026-05-28 21:00:39 +08:00

42 KiB

Raw Blame History

Changelog

All notable changes to Godot MCP Pro will be documented in this file.

v1.14.1 — 2026-05-24

Patch — assert_node_state regression fix

Fixed

assert_node_state "Unknown command" regression: The game-side handler in mcp_game_inspector_service.gd had been removed during the v1.7.0 refactor (4ea3989, 2026-03-29) that introduced batch_add_nodes / watch_signals / setup_control. The TypeScript server and editor-side GDScript still routed the call, but the runtime match statement no longer recognized it — so assert_node_state (and any type:"assert" step inside run_test_scenario) returned Unknown command: assert_node_state on every call from v1.7.0 through v1.14.0. Restored the handler with all 8 operators (eq, neq, gt, lt, gte, lte, contains, type_is) and sub-property access via get_indexed() (e.g. position:y). Reported by Z_runner [CRWN] on Discord.

v1.14.0 — 2026-05-18

Feature / Safety — File-conflict safety overhaul (community contribution)

This release is a coordinated overhaul of how the addon interacts with editor-owned resources. It prevents the "external change" dialog and silent in-memory/disk divergence that could occur when MCP commands wrote scenes, scripts, shaders, or resources while Godot still had them open. Contributed by @aallnneess (PR #31), with the design and patch reviewed and tested locally with GitHub Copilot using GPT-5.5 xhigh. Reported and validated against the previous v1.13.x behavior.

Added — safety primitives in `base_command.gd`

guard_offline_scene_save(path): blocks ResourceSaver.save(...) to a .tscn/.scn path when that scene is currently open in the editor. Returns a structured conflict error (JSON-RPC code -32009) including the path, open-scenes list, and a recovery suggestion.
guard_text_resource_write(path, force): blocks writes to a script/shader file that is currently open in Godot's script editor (or, for shaders, currently loaded/cached in ResourceLoader). Override with force=true.
add_child_with_undo(...) / set_property_with_undo(...): register live scene mutations through EditorUndoRedoManager with correct add_do_reference / add_undo_reference retention for Resource values so they survive GC across the undo history.
get_open_scene_paths() / is_scene_path_open() / is_active_scene_path() / is_text_resource_open_in_script_editor(): shared checks so per-command code never re-implements the same logic.
normalize_project_path(): consistent comparison key for res://, project-relative, and absolute paths.

Changed — scene saves go through `EditorInterface`

save_scene: when the target path matches the active edited scene, calls EditorInterface.save_scene(); when the target differs or the active scene has no path yet, calls EditorInterface.save_scene_as(path). Refuses to save an inactive open scene tab. No more silent ResourceSaver.save to an open path.
create_scene / create_theme / edit_resource: all guarded against accidentally targeting an open scene path.

Changed — broad cross-scene edits are opt-in

cross_scene_set_property defaults to dry_run=true (breaking change). Real writes now require dry_run=false and force=true. The response includes a per-scene mode field (dry_run / offline_saved / live_open_scene) and a skipped_open_scenes list so callers can see exactly what happened.
The active open scene is live-edited via EditorUndoRedoManager instead of being offline-overwritten, so changes are visible in the editor and undoable.
Inactive open scenes are skipped and reported rather than silently overwritten.

Changed — live scene mutations participate in UndoRedo

batch_add_nodes, batch_set_property: routed through the shared UndoRedo helpers.
node_commands: node creation, set_anchor_preset (computed on a duplicate Control before applying), signal connect/disconnect, group add/remove — all undoable.
animation_commands: animation create/remove, track add, and keyframe edits. _upsert_animation_key / _restore_animation_key give round-trip undo for keyframe edits (including the previously-present-key replacement case) using is_equal_approx time matching.
animation_tree_commands: AnimationTree create, state machine state/transition edits, blend tree node changes, tree parameter edits.
tilemap_commands: single-cell set, rect fill, and clear capture the affected cells' old state and apply via UndoRedo. Round-trip undoable.
theme_commands: color, constant, font-size, and stylebox theme overrides; setup_control computes target state on a duplicate Control before applying.
audio_commands, navigation_commands, particle_commands: node creation and resource assignment go through UndoRedo. Navigation bake also marks the active scene unsaved.
shader_commands: shader material assignment via set_property_with_undo.

Fixed — open script/shader writes

create_script / edit_script: refuse to write when the target is open in the script editor, unless force=true is explicitly passed. Also restricted to .gd / .cs extensions — scene and shader paths are rejected with a clear suggestion (added in 6d8d650).
edit_script now actually implements the 1-based inclusive start_line / end_line range replacement that the CLI had been advertising. The TypeScript edit_script schema and CLI script edit both expose the new parameters.
create_shader / edit_shader: same open-file guard, with force=true to override.
Shader cache refresh fixed: _refresh_loaded_shader uses take_over_path() + emit_changed() to update any cached/live Shader resource, replacing the unreliable Shader.reload_from_file() call. Live materials referencing the shader now pick up edits immediately.

Fixed — `execute_editor_script` escape hatch

Submitted code is scanned for direct file/resource write APIs (ResourceSaver.save, FileAccess WRITE, ProjectSettings.save, ConfigFile.save, DirAccess filesystem mutations). If present, the call is refused with a structured conflict error unless allow_unsafe_editor_io=true is explicitly passed. Closes the obvious workaround where an AI client could route around the per-command guards by submitting raw script.

Changed — server schemas

create_script / edit_script / create_shader / edit_shader: added optional force parameter and updated tool descriptions.
cross_scene_set_property: added optional dry_run / force parameters and a description that reflects the new dry-run-by-default semantics.
execute_editor_script: added optional allow_unsafe_editor_io parameter.
cli.ts: script create and script edit accept --force flag.

Migration notes

Breaking: scripts/agents that previously relied on cross_scene_set_property writing on first call now need to add dry_run=false force=true to perform writes. Without those, the call returns a dry-run preview. This is intentional — silent project-wide writes were a footgun.
Soft-breaking: scripts/agents that previously overwrote open files (scenes, scripts, shaders) without checking now hit a -32009 conflict error. The fix is to either close the file in the editor first, save through the editor (for scenes), or pass force=true (for scripts/shaders, when you've verified no buffer holds unsaved changes).
Existing wire-compatible calls that did not target open resources continue to work unchanged.

v1.13.2 — 2026-05-13

Bug Fix — Port allocation race when multiple Claude Code sessions start at the same time

Fixed

Parallel-session port collision (Discord report by CrusherEAGLE): Two Claude Code sessions starting nearly simultaneously could both pre-check port 6505 as free, both attempt to bind, the loser would get EADDRINUSE and give up without retrying the next port. The session that lost the race had a server that never started, so every tool call failed for the remainder of that session with no way to recover short of restart. The fallback path in index.ts claimed it would "retry on first command" but no such retry existed.
The fix replaces the racy pre-check + single bind with a proper bind-retry loop: each port in 6505–6509 is tried in turn, and EADDRINUSE triggers a fall-through to the next port. Only when the entire range is exhausted does connect() reject, with a clear error message and remediation hint.
Cleaned up the misleading "will retry on first command" log line in index.ts.

Tests

New tests/godot-connection.test.ts covers: first-port allocation, sequential fall-through, simultaneous parallel connects (the exact regression scenario), range exhaustion, and fixedPort=true fail-fast behavior. 5 new tests, 62 total.

v1.13.1 — 2026-05-12

Bug Fix — Silent disconnect / dead-connection recovery

Fixed

Heartbeat now actually detects dead connections (Discord report by CrusherEAGLE): The ping/pong heartbeat was being sent every 10s but neither side tracked whether responses were arriving, so a half-open TCP connection (common on Windows after sleep/wake, VPN toggle, or a brief editor hang) left both sides holding a dead socket. isConnected() continued to return true, every command timed out at 30s, and the only way back was to restart Claude Code and the Godot editor. Fixed on both sides:
- Server: tracks the last pong timestamp; if 30s passes with no pong, forcibly destroys the socket (terminate(), vs close() which waits for a FIN ack that never comes on a dead link). Pending requests are rejected immediately rather than hanging for 30s.
- Editor: sends its own ping every 5s, tracks per-port inactivity, and after 30s of inbound silence force-closes the peer so the existing 3s reconnect cycle takes over.
- OS-level TCP keepalive enabled on the server socket (5s initial delay), surfacing half-open links faster than Windows' ~2-hour default.
Status panel surfaces stale state: New yellow ⚠ indicator when a port is reconnecting from a stale state, plus per-port idle time (seconds since last received message) in the Clients tab. No more "looks fine while everything is broken" UI.

Notes

Recovery is automatic within ~30s after the connection dies. Watch the Output panel for [MCP] Port NNNN silent for X.Xs — forcing reconnect if you want to see it happen.
No API or tool changes — same 172 tools, same behavior in the healthy path.

v1.13.0 — 2026-05-05

Bug Fixes & Polish — Mouse motion dispatch, setup config, site pricing

Fixed

simulate_mouse_move honors explicit unhandled: false (#24, #25): Drag motions (button_mask > 0) auto-promote to push_input so camera-pan use cases bypass GUI consumption. But callers writing UI drag-and-drop tests need events to reach the GUI dispatcher (so _get_drag_data / _drop_data fire). Now: if the caller explicitly passes unhandled: false, that wins; auto-promotion only happens when unhandled was omitted. Default behavior preserved.
v1.12.0 build blocker: Restored missing mcp/server/src/utils/load-instructions.ts referenced by index.ts since v1.12.0. Fresh clones of v1.12.0 failed npm run build with Cannot find module './utils/load-instructions.js'. v1.13.0 now builds clean.

Changed

setup no longer pins GODOT_MCP_PORT (#27): Generated MCP client config (Claude Desktop, Cursor, etc.) omits the GODOT_MCP_PORT env var so the server can auto-scan ports 6505–6509. Pinning a fixed port caused silent failures when a stale process held the port. Users who need a fixed port can still set it manually.
Site JSON-LD price → $15 (#26): Structured data on the landing page now reflects the current price.

Improved

README clarity (issue #7 follow-up): More prominent note that the public repo ships the addon only — the MCP server is distributed via Buy Me a Coffee / itch.io.
build-release.sh portability: Falls back to system zip and python3 when 7-Zip is not on PATH.

v1.12.0 — 2026-04-19

Feature — Android Remote Deploy · Bug Fix — Runtime IPC on custom user dirs

Added

Android Remote Deploy (3 tools, Full mode only — #20):
- list_android_devices — wraps adb devices -l, returns serial/state/model/product. Resolves adb from Editor Settings > Export > Android > Adb, falling back to adb on PATH.
- get_android_preset_info — reads metadata (package name, export path, runnable) from an Android preset in export_presets.cfg.
- deploy_to_android — one-shot pipeline: Godot CLI export → adb install -r → adb shell monkey launch. Options: preset_name, device_serial, debug, launch, skip_export. Synchronous; export step can take tens of seconds.
Full mode tool count: 169 → 172. LITE / 3D / MINIMAL modes are unchanged.

Fixed

get_game_user_dir() (commands/base_command.gd) — #21: Runtime IPC commands (get_game_scene_tree, get_game_node_properties, simulate_*, etc.) failed with Could not create game request file when the project used application/config/use_custom_user_dir=true, or when application/config/name contained characters illegal on the host OS (e.g. : on Windows). Editor and game now resolve to the same dir: early-return OS.get_user_data_dir() for custom user dirs, and sanitize config/name via xml_unescape().validate_filename().replace(".", "_") — matching Godot's own logic in ProjectSettings::_init. Thanks @asim9834 for the detailed repro + patch.

v1.11.0 — 2026-04-15

Feature — New --3d mode for 100-tool-limit clients

Added

--3d mode: Registers exactly 100 tools — the 81 core LITE tools plus Physics (6), AnimationTree (8), and Navigation (5). Designed for clients with a 100-tool cap (e.g. Google Antigravity with Claude Code proxy) that need full 3D game development capabilities. Usage: node build/index.js --3d

Improved

Troubleshooting docs: Clarified port conflict advice in INSTALL.md — recommends letting the server auto-scan ports 6505–6509 instead of setting a fixed GODOT_MCP_PORT, which can cause silent failures with stale processes

Mode comparison

Flag	Tools	Use case
(none)	169	Full mode — all tools
`--3d`	100	3D game dev under 100-tool limit
`--lite`	81	Tight tool limits (Cursor, etc.)
`--minimal`	35	Ultra-tight limits (local LLMs)

v1.10.3 — 2026-04-11

Bug Fixes — Autoload preservation, Windows build, port conflict warning

Fixed

Autoload deletion on --import / shutdown: Plugin no longer removes pre-existing MCP autoloads from project.godot. Previously, _remove_autoloads() deleted all managed autoload keys unconditionally — even if they were project-owned. Now only autoloads injected by the current plugin session are removed. (#17)
Windows build failure: Removed Unix-only chmod -R a+x build || true from the build script in package.json. The chmod and true commands don't exist on Windows cmd/PowerShell, causing node build/setup.js install to fail with "Build failed" even though TypeScript compilation succeeded. The fix is simply "build": "tsc" — execute permissions are not needed since the server runs via node. (#Discord)

Improved

Port conflict warning for explicit port: When GODOT_MCP_PORT is set and the port is already occupied (e.g. by a stale process), the server now logs a clear warning with remediation steps instead of silently failing to bind. (#15)

v1.10.2 — 2026-04-11

Fix — Linux permission issue for build files

Fixed

Linux permission denied: Added chmod -R a+x to build process so that build/index.js and other compiled files have execute permission out of the box on Linux/macOS. Previously, users had to manually run chmod -R a+x build after installation. (Thanks to kflamsted for reporting!)

v1.10.1 — 2026-04-08

UX Improvement — Bottom panel renamed, INSTALL.md rewritten

Improved

Bottom panel renamed: "MCP Server" → "MCP Pro" for consistency with the product name. Status label also updated.
INSTALL.md rewritten: Added zip structure diagram, clear separation of addon vs server, Claude Desktop config paths, and better troubleshooting. Clarified that configure must be run from the Godot project directory.

v1.10.0 — 2026-04-07

New Tools & Quality Sweep — Editor camera control, 169 tools, comprehensive audit fixes

New Tools

get_editor_camera: Get the 3D editor viewport camera position, rotation, and FOV. Useful for understanding the current view before taking screenshots.
set_editor_camera: Move the 3D editor viewport camera to a specific position and orientation. Supports position, rotation, look_at target, and FOV. Use this to frame a view before screenshots to validate changes visually.

Fixed

plugin.gd version display: Was hardcoded to "v1.6.0" since initial release. Now dynamically reads from plugin.cfg — always shows the correct version.
Tool count inconsistency: Was showing 162/163/167 across different files. All references now correctly say 169.
node setup.js path: All docs and help text now correctly say node build/setup.js.
configure cwd issue: INSTALL.md now clearly separates install (run from server/) and configure (run from Godot project root) to avoid .mcp.json being placed in the wrong directory.
INSTALL.md: Fixed step numbering skip, stale tool count (49→169), port range (6505-6514).
README.md: Replaced hardcoded dev paths with /path/to/ placeholders.

Improved

"v1.x" wording removed: All pricing and marketing text now says "lifetime updates" without version scope.
Plugin port range: WebSocket comment and connection range expanded to 6505-6514 (6510-6514 reserved for CLI).
Pre-built JS in release zip: build/setup.js and build/cli.js work immediately after extract + npm install.
Claude Desktop support: Confirmed working, added to configure auto-detection.

v1.9.4 — 2026-04-06

Bug Fixes — State enum type regression, zip plugin version

Fixed

mcp_game_inspector_service.gd State enum type error (regression): var _state: State = State.IDLE caused "Cannot assign a value of type mcp_game_inspector_service.gd.State to variable with specified type State" in some Godot versions. Changed back to var _state := State.IDLE (type inference). This was originally fixed in v1.6.4 but regressed. (Thanks @kalish)
Release zip contained wrong plugin version: v1.9.3 zip shipped with plugin.cfg showing v1.9.2 due to a build order issue. Fixed build pipeline to ensure public repo is synced before zip creation.

v1.9.3 — 2026-04-06

Improvement — Pre-built JS in release zip, docs cleanup

Improved

Pre-built JS files included in release zip: build/setup.js, build/cli.js, and all other compiled files are now included. Users can run node build/setup.js install immediately after extracting — no need to manually run npm run build first.
CLI naming unified in docs: Removed godot-cli shorthand. All docs consistently use node build/cli.js. Added note that server must be built before CLI use.
CLI help port range fixed: --help output now correctly shows 6510-6514 (CLI range), not 6505-6509 (MCP server range).

v1.9.2 — 2026-04-06

New Features — Setup CLI, code-to-inspector workflow, CLI click fix

New Features

Setup CLI (setup.js): One-command server setup and management. Commands: install (npm install + build), check-update (GitHub release check with semver comparison), configure (auto-detect AI client and generate .mcp.json), doctor (environment diagnostics).
Code-to-inspector migration workflow: New guideline in AGENTS.md and skills.md instructing AI to prefer update_property over hardcoded GDScript for visual properties (colors, sizes, theme overrides). Includes step-by-step migration pattern.

Fixed

CLI input click --button mapping: The CLI sent string values ("left", "right", "middle") but the plugin expects numeric indices (1, 2, 3). Now correctly maps left→1, right→2, middle→3. (Thanks @Gogomy)

Improved

INSTALL.md: Added quick setup flow using setup.js for both fresh install and updates.
Instruction files: All 12 client instruction files updated with new workflow patterns.

v1.9.1 — 2026-04-05

Bug Fix — GODOT_MCP_PORT env var now respected + Cursor Full mode

Fixed

GODOT_MCP_PORT env var ignored: The server always scanned ports 6505-6509 for the first free port, ignoring the explicitly configured port. Now when GODOT_MCP_PORT is set, the server uses that port directly without scanning. (Fixes #13)

Changed

Cursor moved to Full mode: Cursor removed its 40-tool limit with Dynamic Context Discovery — all 167 tools now work in Full mode. (Thanks to @CrossBread for PR #14)

v1.9.0 — 2026-04-05

Universal Compatibility — Minimal mode, CLI tool, and test suite

New Features

Minimal mode (--minimal): Registers only 35 essential tools for clients with tight tool limits (Cursor ~40, OpenCode, local LLMs with small context windows). Covers project info, scene management, node CRUD, script editing, editor errors, input simulation, and runtime inspection.
CLI tool (godot-cli): Command-line interface for controlling Godot directly from a terminal. LLMs discover capabilities progressively via --help instead of loading all tool definitions upfront — zero context overhead, works with any client that has bash/terminal access. 7 command groups: project, scene, node, script, editor, input, runtime.
Test suite: Added vitest with 47 unit tests covering tool-filter, error utilities, zod coercion, and CLI help/error handling.

Improved

Client compatibility guide: README and landing page now include a compatibility matrix for 12+ MCP clients with recommended mode for each (Full/Lite/Minimal/CLI).
Landing page: Added "Choose Your Mode" setup step, CLI documentation, and new FAQ entry for tool count limits.
print_verbose for connect/disconnect: WebSocket connect/disconnect messages in the Godot plugin now use print_verbose() instead of print(), eliminating terminal spam during normal operation.
Per-client instruction files: instructions/ folder with ready-to-copy instruction files for 12 AI clients (Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Codex CLI, OpenCode, Roo Code, JetBrains/Junie, Amazon Q, Continue, Augment). Includes CLI usage documentation.

v1.8.1 — 2026-04-04

Bug Fix — @export node reference support in update_property

Fixed

update_property @export node references: Setting @export var node references (e.g. @export var hud: HUD) via update_property now correctly resolves string paths to actual node references. Previously, typeof(old_value) returned TYPE_NIL for unset exports and TYPE_OBJECT for set ones, neither of which resolved the path string to a node. The fix checks PROPERTY_HINT_NODE_TYPE from the property's metadata to detect node reference exports and resolve accordingly. (Fixes #12)

v1.8.0 — 2026-04-02

New Features — HTTP transport, screenshot file saving, custom class support

New Features

Streamable HTTP transport: New --http and --http-port flags for MCP clients that need HTTP instead of stdio. Starts an HTTP server at http://127.0.0.1:8001/mcp (default port).
Screenshot save_path option: get_editor_screenshot and get_game_screenshot now accept an optional save_path parameter (e.g. res://screenshot.png) to save directly to disk instead of returning base64, avoiding MCP response cache bloat.
add_node custom class support: add_node now resolves script-defined classes (class_name) in addition to built-in ClassDB types via ProjectSettings.get_global_class_list().

Improved

INSTALL.md: Added "Updating to a New Version" section with step-by-step upgrade instructions.

v1.7.2 — 2026-03-31

Bug Fixes & Improvements — execute_game_script robustness + auto-dismiss control

Fixed

execute_game_script mixed indentation error: User code with space indentation was prepended with tabs, causing "Mixed use of tabs and spaces" parse errors. Now auto-detects indent width and normalizes all leading spaces to tabs before wrapping.
execute_game_script standalone lambda error: Top-level func definitions in user code were nested inside the wrapper's run() function, triggering "Standalone lambdas cannot be accessed" parse errors. Now extracts top-level functions to class level.
command_router crash on missing config section: _load_tool_config() called get_section_keys("disabled_tools") without checking if the section exists, causing "Cannot get keys from nonexistent section" errors on fresh installs.

Changed

Auto-dismiss dialogs now opt-in: Previously auto-dismissed blocking editor dialogs whenever an MCP client was connected. Now disabled by default — AI must explicitly enable via the new set_auto_dismiss tool before operations that trigger reload/save dialogs.

New Tools

set_auto_dismiss: Enable or disable automatic dismissal of blocking editor dialogs (e.g., "Reload from disk?", "Save changes?"). Use before external file modifications, disable when done.

v1.7.1 — 2026-03-30

Bug Fixes — Scene transition crash fix and deprecated API cleanup

Fixed

click_button_by_text crash on scene transition: Clicking a button that triggers a scene change (e.g., navigating from main menu to options) caused "Cannot get path of node as it is not in a scene tree" errors. Now caches button info before emitting the pressed signal and guards with is_instance_valid() / is_inside_tree() after the click.
Deprecated push_unhandled_input() warning: Replaced with push_input() in mcp_input_service.gd per Godot 4.x API updates.

v1.7.0 — 2026-03-29

New Tools & Multi-Client Support — 3 new tools for faster scene building, runtime signal debugging, and UI layout + instructions for non-Claude AI clients

New Tools

batch_add_nodes: Add multiple nodes in a single call. Nodes are processed in order so earlier nodes can be referenced as parents — build entire node trees in one shot instead of calling add_node repeatedly.
watch_signals: Monitor signal emissions on specified nodes in the running game for a set duration. Returns a timestamped log of every signal fired with arguments — great for debugging event flow and verifying signal connections.
setup_control: Configure a Control/Container node's layout in one call: anchor preset, min size, size flags, margins (MarginContainer), separation (VBox/HBoxContainer), and grow direction. Replaces 5+ update_property calls.

New

AGENTS.md template: Custom instructions for non-Claude AI clients (OpenAI Codex, opencode/ollama, Cursor, etc.). Includes editor vs runtime tool categorization, workflow patterns, formatting rules, and common pitfalls. Included in release zip.

v1.6.5 — 2026-03-27

assert_node_state Fix — Game-side handler was missing, causing "Unknown command" error

Fixed

assert_node_state missing game-side handler: The command was registered in the TypeScript server and editor-side GDScript, but mcp_game_inspector_service.gd had no handler — returning "Unknown command" at runtime. This also broke node assertions within run_test_scenario. All 8 operators (eq, neq, gt, lt, gte, lte, contains, type_is) now work correctly.
Sub-property access in assertions: Properties like position:y now use get_indexed() instead of get(), enabling assertions on vector components and nested properties.

v1.6.4 — 2026-03-25

Enum Type Fix — Fixes script error on play in certain Godot versions

Fixed

mcp_game_inspector_service.gd State enum type error: Explicit State type annotation on _state variable caused "Cannot assign a value of type mcp_game_inspector_service.gd.State to variable with specified type State" errors in some Godot versions. Changed to type inference (:=) which resolves the mismatch.

v1.6.3 — 2026-03-24

Camera Pan Fix — Mouse drag events now bypass GUI layer to reach _unhandled_input()

Fixed

Mouse drag not reaching _unhandled_input(): simulate_mouse_move with button_mask (drag simulation) was consumed by GUI Controls (mouse_filter=STOP) before reaching _unhandled_input(). Camera pan, drag-to-select, and other drag-based mechanics that rely on _unhandled_input() now work correctly. Events with button_mask > 0 automatically use push_unhandled_input() to bypass the GUI layer.

New

simulate_mouse_move unhandled parameter: Optional unhandled flag to force any mouse motion event to bypass GUI and go directly to _unhandled_input(). Auto-enabled when button_mask > 0.
simulate_sequence unhandled support: Sequence mouse_motion events also support the unhandled flag.

v1.6.2 — 2026-03-24

Animation Easing & Mouse Drag Simulation — Community-requested fixes

New

set_animation_keyframe easing parameter: Optional easing param (default 1.0) to control keyframe transition curves. Values: 1.0=linear, <1.0=ease-in, >1.0=ease-out, negative=in-out variants.
get_animation_info easing field: Each keyframe now returns its easing value.
simulate_mouse_move button_mask: New button_mask parameter (1=left, 2=right, 4=middle) enables drag simulation. Required for games that check InputEventMouseMotion.button_mask (e.g. camera pan with mouse drag).
simulate_sequence button_mask: Sequence events also support button_mask for drag operations.

Fixed

Mouse sequence events: simulate_sequence now correctly handles flat key format (relative_x, relative_y, x, y) in addition to nested format. Previously, mouse motion events in sequences had relative=(0,0) because the flat-to-nested conversion was missing.

v1.6.1 — 2026-03-21

Permission Presets — Auto-approve tool permissions for Claude Code

New

settings.local.json (conservative): Pre-configured permission file that auto-approves 152 of 163 tools. Destructive tools (delete_node, delete_scene, execute_editor_script, etc.) still require manual approval.
settings.local.permissive.json: Allows all 163 tools and all Bash commands, with an explicit deny list for dangerous shell commands (rm -rf, git push --force, git reset --hard, etc.) and destructive MCP tools.
Copy either file to ~/.claude/settings.local.json to skip per-tool permission prompts.

v1.6.0 — 2026-03-21

Enhanced Editor Panel — Activity log with response details, client monitor, and tool management

New

Activity tab: Full command log showing method name, status, port, and timestamp. Toggle "Show Response Details" to inspect the JSON responses sent back to AI clients. Clear button to reset the log.
Clients tab: Real-time view of all 5 WebSocket ports (6505-6509) with connection status and elapsed time since connection.
Tools tab: Searchable list of all 163 tools with individual enable/disable checkboxes. Bulk "Enable All" / "Disable All" buttons. Disabled tools are persisted across sessions (user://mcp_tool_config.cfg) and return a clear error message to AI clients.

Changed

Status panel rebuilt with TabContainer (Activity / Clients / Tools)
WebSocket server now emits command_completed signal with full response data and source port
Connection time tracking per port for uptime display

v1.5.3 — 2026-03-15

New tool — record_frames for long-running debug observation

New

record_frames: Capture up to 600 screenshots saved as PNG files to user://mcp_recorded_frames/. Unlike capture_frames (which returns base64 images directly, max 30), this tool saves to disk and returns file paths — ideal for long-running debug sessions without flooding the AI context with image data. Supports optional node_data tracking for per-frame property snapshots (position, velocity, etc.).

v1.5.2 — 2026-03-13

Bugfix — Screenshot capture now works when the SceneTree is paused

Fixed

mcp_screenshot_service.gd: Added process_mode = Node.PROCESS_MODE_ALWAYS so the file-polling loop in _process() keeps running during pause. The other two autoloads (mcp_input_service.gd, mcp_game_inspector_service.gd) already had this — screenshot service was the only one missing it.
mcp_screenshot_service.gd: Replaced await get_tree().process_frame with await get_tree().create_timer(0.05).timeout — process_frame never fires when the tree is paused, but create_timer() with default process_always=true does.

Thanks to mrkielbasa for reporting this bug!

v1.5.1 — 2026-03-08

Patch release — AI Skills file for better out-of-the-box experience

New

skills.md: Added addons/godot_mcp/skills.md — a comprehensive guide for AI assistants covering all 162 tools, 10 practical workflows, best practices, and common pitfalls. Users can copy this to .claude/skills.md in their project root so Claude Code knows how to use the MCP tools effectively from the start.
README: Added setup step for copying skills.md to .claude/skills.md.

v1.5.0 — 2026-03-04

Feature — Lite mode for MCP clients with tool count limits

New Features

Lite mode (--lite): Launch with --lite flag to register only 76 core tools instead of 162. Designed for MCP clients with tool count limits (Windsurf: 100, Cursor: ~40, Antigravity: 100).
- Core categories (always loaded): project, scene, node, script, editor, input, runtime, input_map
- Extended categories (Full mode only): animation, animation_tree, audio, batch, export, navigation, particle, physics, profiling, resource, scene_3d, shader, test, theme, tilemap, analysis
- Usage: Add "--lite" to args in your MCP config

v1.4.5 — 2026-03-04

Patch release — Godot 4.3 compatibility fix

Bug Fixes

Godot 4.3 compatibility: Fixed scene_3d_commands.gd parse error caused by Environment.TONE_MAPPER_AGX enum (added in Godot 4.4). Now uses integer value for backward compatibility. This was a blocking error that prevented the entire plugin from loading on Godot 4.3.

v1.4.4 — 2026-03-04

Patch release — Revert Output panel filter expansion

Bug Fixes

get_editor_errors: Removed W , WARN, GDScript Output panel filters added in v1.4.3 — these patterns don't actually appear in Godot's Output panel (push_warning uses WARNING: prefix) and caused false positives on normal text.

v1.4.3 — 2026-03-04

Patch release — Comprehensive error/warning detection

Improvements

get_editor_errors: Now reads runtime errors from the debugger Errors tab (ScriptEditorDebugger), returned with DEBUGGER: prefix including stack traces. Previously only static analysis and Output panel errors were captured.

Bug Fixes

get_editor_errors: Fixed debugger Errors tab not being found because the tab name includes a count suffix (e.g. "Errors (1)") — now uses prefix matching.

v1.4.2 — 2026-03-04

Patch release — Improved error detection in script editor

Improvements

get_editor_errors: Now reads GDScript analyzer errors and warnings from the script editor's error/warning panels (VSplitContainer RichTextLabels), in addition to the Output panel and CodeEdit line highlights. Catches static analysis messages like type mismatches and autoload name conflicts that were previously missed.

v1.4.1 — 2026-03-02

Patch release — Bug fixes found during comprehensive tool audit

Bug Fixes

replay_recording: Fixed false crash recovery error (_pending_command flag not cleared for async replay loop)
wait_for_node: Fixed false crash recovery error when polling for node appearance
apply_particle_preset: Fixed editor crash in gl_compatibility renderer caused by immediate GradientTexture1D assignment — now uses set_deferred and reduced texture width

v1.4.0 — 2026-03-01

162 tools across 23 categories (+15 new tools)

New Tools

move_to — Autopilot: automatically walk a character to target coordinates using pathfinding
navigate_to — High-level navigation command for AI-driven movement
find_nearby_nodes — Find nodes within a radius of a given position
get_node_groups / set_node_groups — Read and write node group memberships
find_nodes_in_group — Query all nodes belonging to a specific group
get_output_log — Retrieve Godot's Output panel contents
get_input_actions / set_input_action — Read and configure Input Map actions
search_in_files — Full-text search across project files
validate_script — Check GDScript for errors without running
get_resource_preview — Get thumbnail previews of resources
get_scene_exports — List exported variables in a scene's root script
add_autoload / remove_autoload — Manage autoload singletons

Bug Fixes & Improvements

Crash recovery: capture_frames no longer triggers false crash recovery (_pending_command flag fix)
capture_frames node_data: Optional per-frame property snapshots via node_data parameter
Debugger auto-continue: Automatically presses Continue when runtime errors pause the debugger
simulate_key duration: Now accepts fractional seconds (e.g., 0.3s) for precise movement
Command router fix: All 8 command classes now properly registered (~47 tools were previously unreachable)

v1.3.1 — 2026-02-27

Patch release

Bug Fixes

get_editor_errors: Now reads from Output panel and CodeEdit error gutter (previously returned empty results)
Tonemap enum: Fixed environment tonemap mode enum name mapping

v1.3.0 — 2026-02-26

147 tools across 23 categories (+63 new tools)

New Tool Categories

AnimationTree & State Machine (8 tools)

create_animation_tree, get_animation_tree_structure, set_tree_parameter
add_state_machine_state, remove_state_machine_state
add_state_machine_transition, remove_state_machine_transition
set_blend_tree_node

Physics & Collision (6 tools)

setup_collision, setup_physics_body, get_collision_info
get_physics_layers, set_physics_layers, add_raycast

3D Scene (6 tools)

add_mesh_instance, setup_lighting, set_material_3d
setup_environment, setup_camera_3d, add_gridmap

Particles (5 tools)

create_particles, set_particle_material, set_particle_color_gradient
get_particle_info, apply_particle_preset (8 built-in presets: fire, smoke, sparks, rain, snow, explosion, magic, dust)

setup_navigation_region, bake_navigation_mesh, setup_navigation_agent
set_navigation_layers, get_navigation_info

Audio (6 tools)

get_audio_bus_layout, add_audio_bus, set_audio_bus
add_audio_bus_effect, add_audio_player, get_audio_info

Testing & QA (5 tools)

run_test_scenario, assert_node_state, assert_screen_text
run_stress_test, get_test_report

Project Analysis (6 tools)

find_unused_resources, analyze_signal_flow, analyze_scene_complexity
detect_circular_dependencies, get_scene_dependencies, get_project_statistics

Expanded: Runtime Analysis

find_ui_elements, click_button_by_text, wait_for_node
Runtime tools expanded from 4 to 15 tools

Other Additions

add_resource, create_resource, edit_resource, read_resource — Resource management tools

v1.2.0 — 2026-02-24

84 tools across 14 categories (+34 new tools)

New Tool Categories

Animation (6 tools)

list_animations, create_animation, add_animation_track
set_animation_keyframe, get_animation_info, remove_animation

TileMap (6 tools)

tilemap_set_cell, tilemap_fill_rect, tilemap_get_cell
tilemap_clear, tilemap_get_info, tilemap_get_used_cells

Theme & UI (6 tools)

create_theme, set_theme_color, set_theme_constant
set_theme_font_size, set_theme_stylebox, get_theme_info

Profiling (2 tools)

get_performance_monitors, get_editor_performance

Batch Operations & Refactoring (5 tools)

find_nodes_by_type, find_signal_connections, batch_set_property
find_node_references, get_scene_dependencies

Shader (6 tools)

create_shader, read_shader, edit_shader
assign_shader_material, set_shader_param, get_shader_params

Export (3 tools)

list_export_presets, export_project, get_export_info

Bug Fixes

Fixed game IPC connection when project name changes
Added set_project_setting tool for safe project.godot modifications via EditorSettings API
Fixed script reload behavior

v1.1.0 — 2026-02-23

49 tools across 8 categories (+16 new tools)

New Tool Categories

Input Simulation (4 tools)

simulate_key, simulate_mouse_click, simulate_mouse_move, simulate_sequence

Runtime Analysis (4 tools)

play_scene, stop_scene, get_game_scene_tree, get_game_screenshot
execute_game_script, get_game_node_properties, set_game_node_property
monitor_properties, capture_frames

Other

Added build-release.sh for reproducible release packaging
start_recording / stop_recording / replay_recording for input recording

v1.0.0 — 2026-02-22

~33 tools across 6 categories — Initial release

Tool Categories

Scene Management: create_scene, open_scene, save_scene, get_scene_tree, delete_scene, get_scene_file_content, add_scene_instance
Node Operations: add_node, delete_node, rename_node, move_node, duplicate_node, update_property, get_node_properties, batch_get_properties, connect_signal, disconnect_signal, get_signals
Script: create_script, read_script, edit_script, attach_script, list_scripts, find_nodes_by_script, find_script_references, get_open_scripts
Editor: get_editor_screenshot, get_editor_errors, clear_output, execute_editor_script, reload_plugin
Project: get_project_info, get_project_settings, get_filesystem_tree, search_files
UI: Anchor presets (set_anchor_preset)

Architecture

WebSocket-based communication between Godot editor plugin and MCP TypeScript server
Supports Claude Code, Cursor, Windsurf, and any MCP-compatible AI coding tool
Screenshot capture from both editor and game viewports

42 KiB Raw Blame History Unescape Escape

Changelog

v1.14.1 — 2026-05-24

Fixed

v1.14.0 — 2026-05-18

Added — safety primitives in base_command.gd

Changed — scene saves go through EditorInterface

Changed — broad cross-scene edits are opt-in

Changed — live scene mutations participate in UndoRedo

Fixed — open script/shader writes

Fixed — execute_editor_script escape hatch

Changed — server schemas

Migration notes

v1.13.2 — 2026-05-13

Fixed

Tests

v1.13.1 — 2026-05-12

Fixed

Notes

v1.13.0 — 2026-05-05

Fixed

Changed

Improved

v1.12.0 — 2026-04-19

Added

Fixed

v1.11.0 — 2026-04-15

Added

Improved

Mode comparison

v1.10.3 — 2026-04-11

Fixed

Improved

v1.10.2 — 2026-04-11

Fixed

v1.10.1 — 2026-04-08

Improved

v1.10.0 — 2026-04-07

New Tools

Fixed

Improved

v1.9.4 — 2026-04-06

Fixed

v1.9.3 — 2026-04-06

Improved

v1.9.2 — 2026-04-06

New Features

Fixed

Improved

v1.9.1 — 2026-04-05

Fixed

Changed

v1.9.0 — 2026-04-05

New Features

Improved

v1.8.1 — 2026-04-04

Fixed

v1.8.0 — 2026-04-02

New Features

Improved

v1.7.2 — 2026-03-31

Fixed

Changed

New Tools

v1.7.1 — 2026-03-30

Fixed

v1.7.0 — 2026-03-29

New Tools

New

v1.6.5 — 2026-03-27

Fixed

v1.6.4 — 2026-03-25

Fixed

v1.6.3 — 2026-03-24

Fixed

New

v1.6.2 — 2026-03-24

New

Fixed

v1.6.1 — 2026-03-21

42 KiB

Raw Blame History

Added — safety primitives in `base_command.gd`

Changed — scene saves go through `EditorInterface`

Fixed — `execute_editor_script` escape hatch