v1.1.2

[1.1.2] - 2026-10-29

Fixed

• game_start with wait_for_runtime now finds the playtest's runtime within about a second of the game registering its port, on Linux and macOS. Before, the server's watch on the editor's project registry went quiet once the editor had rewritten the file, so the server found the port only at its next registry poll, up to 30 seconds later. Until then game_start returned without runtime_ready and runtime tools answered GAME_NOT_RUNNING. On every platform, game_start also returned without runtime_ready when the server started before the registry file existed. A runtime call no longer fails with CLOSED when the server finds the game while that call is in flight. Reported by @pragmabits (NPGameDev/godot-mcp-toolkit#128).

Full Changelog: v1.1.1...v1.1.2

v1.1.1

[1.1.1] - 2026-10-28

Fixed

• The resource_write properties description now names the tagged form for an existing resource file, {type:'Resource', path:'res://...'}, and says that a bare path (a res://, uid:// or user:// String) on a top-level Resource property is not set and the response warns. The warning needs toolkit 1.1.1; an older toolkit drops or saves the bare path without one. Reported by @benfeather (NPGameDev/godot-mcp-toolkit#48).
• debugger_get_log now answers at once while the game sits at an error break or a breakpoint pause. The server asks the editor's debugger first, and at a break it reads the editor side and skips the game, which can't answer there. Before, each of these calls first waited for the game to time out, up to about 10 seconds. On Windows the answer carries the debugger state with toolkit 1.1.1, and at an error break the file and line the editor's debugger reports for the break. An older toolkit returns LOG_BUSY there on Godot 4.4 and later, and on 4.2 and 4.3 a note that the log file was not found. Reported by @pragmabits (NPGameDev/godot-mcp-toolkit#97).
• When the game can't answer debugger_get_log and the editor's own read returns an error, the tool now passes on the editor's error code and hint. Before, it returned the game's GAME_NOT_RUNNING with its hint about a stopped game, even while the game sat at a break.
• A runtime tool call that can't connect to the game, as at an error break, no longer logs an uncaughtException to the server's stderr. The call still returns the same error.
• game_start with wait_for_runtime now returns within about a second of the editor's debugger stopping the game before the runtime connects, as a parse error in a game script does. Before, it waited the full 10 seconds and then said the runtime did not connect. At an error break the hint says waiting won't help and reports the error, file and line the editor's debugger gives for the break and, with them, names the preloaded script when a script preload failed; at a breakpoint pause it says to call debug_continue. The error, file, line and preloaded script need toolkit 1.1.1. Reported by @pragmabits (NPGameDev/godot-mcp-toolkit#95).
• With the runtime port pinned for the server (GODOT_MCP_RUNTIME_PORT or --runtime-port), game_start with wait_for_runtime always waited 10 seconds and then said the runtime did not connect within 10s, even though the game was running. It now returns as soon as the game answers on the pinned port, and still gives up after 10 seconds if nothing does. Found by @pragmabits while testing #102.

Full Changelog: v1.1.0...v1.1.1

v1.1.0

[1.1.0] - 2026-10-25

Added

• The auth handshake now sends server_version and min_toolkit (this server's declared toolkit floor, 1.0) and reads the toolkit's min_server. When either side is below the other's floor, the connect-time message says which side to update and how. The existing version messages are unchanged, and none of them refuses the connection.
• GODOT_MCP_SKIP_VERSION_CHECK=1 turns the connect-time version check off, floor messages included, and the server prints one line saying so. The toolkit writes it into the .mcp.json entry it builds for a local server build, whose version says nothing about what it supports.
• input_map_action has a rename action. {"action": "rename", "name": "old", "new_name": "new"} moves a project input action to the new name with its events and deadzone, and the response gives the old name as old_name. Each of add, remove and rename now returns its own hint; rename's reminds the agent that scripts and scenes keep the old name. Needs the toolkit release that adds the rename handler; an older toolkit answers INVALID_PARAMS. Thanks to @benfeather (NPGameDev/godot-mcp-toolkit#18, #15).
• script_edit declares an optional edits array of old_string/new_string/replace_all objects. The toolkit applies them in order in one call and writes nothing if one fails. old_string and new_string are now optional, so a call can pass edits alone. Needs the toolkit release that handles edits; an older toolkit answers INVALID_PARAMS. Thanks to @benfeather (NPGameDev/godot-mcp-toolkit#44, #19).
• input_map_list, a read-only tool in the input_map group, lists input actions with their events. By default it returns the project actions and the built-in actions whose events or deadzone differ from their default; include_builtin: true adds the rest, and name returns one action. A changed built-in action has can_revert: true and its default. A dotted name such as jump.macos is listed with its feature tag, and a built-in action's feature entry is read-only. The tool stays available in read-only mode. Needs the toolkit release that adds input_map.list; an older toolkit answers that the method is unknown.
• input_map_action has a revert action. {"action": "revert", "name": "ui_accept"} puts a built-in action back to its default events and deadzone, and project.godot drops its line. Needs the matching toolkit release; an older toolkit answers INVALID_PARAMS.
• The input_map_event description now lists the fields an event takes: key_kind and location (Godot 4.3+) on a key, the modifiers and command_or_control on a key or a mouse button, double_click on a mouse button, and device on every event. An event read from input_map_list can be passed back to unbind as it is, and a response lists in warnings any field the toolkit accepted but ignored.

Changed

• scene_instantiate's description now names the files it takes: a .tscn or .scn, or a 3D model imported as a scene (.glb, .gltf, .dae...). A toolkit before 1.1.0 still refuses every file but a .tscn. Thanks to @benfeather (NPGameDev/godot-mcp-toolkit#39, NPGameDev/godot-mcp-toolkit#40).

Fixed

• game_start no longer reports a game as ready when the game had already exited by the time the bridge read its registry entry, and the bridge now picks up a game relaunched on the same runtime port when no editor cleared the old entry.
• The node_set_script description now says that on Godot 4.2.2 and later it reloads a .gd that changed on disk since the editor loaded it, for every node running the script. The toolkit does the reload, and only when the new source compiles; otherwise the response carries valid: false and a hint that says so and points at script_check. With an older toolkit, or on Godot 4.2.0 and 4.2.1, where reloading a script in place can crash the editor, node_set_script still sets the version the editor loaded first. Thanks to @benfeather (NPGameDev/godot-mcp-toolkit#43, #20).
• With the matching toolkit, input_map_event matches events the way Godot does when it checks an action. A mouse button's pressed no longer splits a binding or misses on unbind, a joypad motion matches on its axis and direction, an event with no device matches any device, and the logical keys of a built-in action, such as ui_accept's Enter, can be unbound.
• The script_check and editor_get_console descriptions now say what holds on the connected Godot version: on 4.5+ every compile error carries its line and the console is the live editor output, and on older versions they say what is missing and where --log-file applies. Until the editor reports its version they give the text that is true on every version, and they update when the editor reconnects on another Godot version. The server also stops reading min_godot_version and max_godot_version from extension commands, which the toolkit never sent.
• With zod 4.6.7, lsp_completion lists limit as optional in tools/list, as its default of 10 implies; before, the schema marked it required. Calls that omit it behave as before.
• The tool reference and the token figures now come from the entries tools/list sends. The reference lists visibility (node_get_property_list and runtime_get_script_vars) and game_start's wait_for_runtime as optional, as the server already advertised them. The token figures now count discover_tools' full group list and, in read-only mode, the two meta tools: the startup surface is about 9,500 tokens (was 9,000), the full surface about 29,100 (was 29,700) and read-only mode about 8,700 (was 8,100).

Security

• zod moves from 4.3.6 to 4.6.7, outside the affected range of GHSA-mrhx-c7xc-m3w5. The vulnerable validation runs on array arguments in the connected client's tool calls. 1.0.4 pinned an affected version, so every install carried it.

Full Changelog: v1.0.4...v1.1.0

v1.0.4

[1.0.4] - 2026-10-14

Security

• The MCP TypeScript SDK moves from 1.29.0 to 1.32.1, past GHSA-6qxp-vccf-f47h. The flaw is in the SDK's OAuth client, which the server never runs, but 1.0.3 pinned the affected version, so every install carried it.

Changed

• When a tool call has an invalid parameter, the error now lists one problem per line, as <message> at <parameter>, instead of a JSON array of the validation issues.

Fixed

• An editor that comes back on a different port now receives the limits set by GODOT_MCP_SCRIPT_READ_LIMIT and GODOT_MCP_WS_BUFFER_LIMIT.
• Restarting the MCP client without a limit variable now clears the env override the editor held, with toolkit 1.0.4 or later.
• A playtest call whose runtime port another program took after the game crashed now reports that the game is not running, instead of an authentication failure.
• An empty GODOT_MCP_PROJECT_PATH is now treated as unset, so the server uses its working directory instead of naming a project that can never connect.
• The dock's LSP line now shows the server's verdict (active, conflict or unavailable) as soon as the server connects to the editor. Before, it waited for the first LSP tool call or a reconnect, so after a fresh start a conflict over the LSP port went unflagged.

What's Changed

• fix(server): move the MCP SDK to 1.32.1 and clear three npm advisories by @NPGameDev in #12
• ci: run the npm audit drift check daily; name and time-box the unit jobs by @NPGameDev in #13
• fix(server): push env overrides on every auth, check cached port by @NPGameDev in #14
• docs: re-attest the LSP figures, complete the error table, reword the Windows npx note by @NPGameDev in #16
• fix(bridge): push the registry LSP verdict on the editor's first connect by @NPGameDev in #17
• docs: bring the docs in line with what 1.0.4 ships by @NPGameDev in #18

Full Changelog: v1.0.3...v1.0.4

1.0.4 pins zod 4.3.6, which GHSA-mrhx-c7xc-m3w5 affects through array arguments in your MCP client's tool calls; upgrade to 1.1.0, which moves zod to 4.6.7.

v1.0.3

[1.0.3] - 2026-10-05

Fixed

• The server no longer resets the editor's response limits (the script read cap and the WebSocket buffer) to their defaults every time it connects. Limits set in the dock or in Project Settings now stay in force while a client is connected, and saving project settings no longer drops them from project.godot. GODOT_MCP_SCRIPT_READ_LIMIT and GODOT_MCP_WS_BUFFER_LIMIT still override them when set. The server ignores an invalid value in either, with a warning, instead of falling back to the default.

What's Changed

• fix(server): push only the response caps the env actually sets by @NPGameDev in #7
• chore: remove leaked markup and an iteration id from comments by @NPGameDev in #8
• Release script: non-interactive mode, a paginated CI check and --verify exit codes by @NPGameDev in #9
• docs(arch): re-attest the stale architecture diagrams by @NPGameDev in #10

Full Changelog: v1.0.2...v1.0.3

v1.0.2

Full Changelog: v1.0.1...v1.0.2

v1.0.1

[1.0.1] - 2026-09-21

Fixed

• The server no longer outlives its MCP client, and no longer spins a CPU core at 100%
  when the client exits without a signal (a crash, a closed terminal, a hard kill).
  Before, the first stderr write after the client's pipes closed raised EPIPE, the
  crash handler reported that failure to the same dead stderr, and the process
  re-entered that handler forever; with an editor connected the orphan idled until the
  editor closed, then spun. The server now shuts down when its stdin ends or its stdout
  becomes unwritable (closing the editor connection politely, bounded to 2 s), treats a
  dead stderr as a lost log sink rather than a reason to exit, and never exits from its
  crash handlers. Reported and first fixed by @nickkurkan
  (#2,
  #3).
  If you ran 1.0.0: orphans from earlier sessions may still be running. macOS/Linux:
  pgrep -fl godot-mcp-server, then kill -9 <pid>; Windows: end the node processes
  running godot-mcp-server in Task Manager. From 1.0.1 on the server exits on its own.

Added

• npm run probe:departure — a hand-run probe (test/probes/client-departure-probe.ts)
  that drives a built server through the client-departure scenarios, with or without an
  editor; part of the release checklist (§1 B9).

Changed

• The connect-time version check no longer warns when the server and the toolkit differ
  only by a patch version. A minor-version difference still warns; a major-version
  difference still errors.
• Refreshed five transitive dependencies of @modelcontextprotocol/sdk —
  brace-expansion, fast-uri, hono, ip-address and qs — to versions without open
  npm advisories. None of the advisories were reachable from this server: they concern the
  SDK's HTTP-server surface, which a stdio-only bridge never instantiates. Nothing about
  the server's behaviour changes; this is dependency hygiene, not a security fix.

Full Changelog: v1.0.0...v1.0.1

v1.0.0

[1.0.0] - 2026-07-26

Breaking Changes

These are pre-1.0 clean breaks with no aliases or deprecation shims. Update any
.mcp.json, shell environment, or scripts that use the old names.

• Renamed the editor-port environment variable GODOT_MCP_PORT to
  GODOT_MCP_EDITOR_PORT, so all three channels (editor, runtime, LSP) now use a
  consistent GODOT_MCP_*_PORT scheme.
• Changed the default ports: the editor channel now uses 6550 (was 6505) and
  the runtime channel uses 6570 (was 6525).
• Canonicalized tool parameter names in a single pass so every tool uses one
  clear name for the same idea (for example, folder tools now take path, not
  folder_path; project_set_setting takes setting, not key; input_map
  takes name, not action_name). There are no aliases for the old names.
• Removed the profile system. The GODOT_MCP_PROFILE environment variable is no
  longer read, the no-op --lite flag is gone, and there is no custom-tool list
  (GODOT_MCP_CUSTOM_TOOLS). Set GODOT_MCP_READ_ONLY=1 for a read-only tool
  surface; the full tool surface is otherwise always available and expands
  on demand.
• Removed the feature-gate system, including the GODOT_MCP_ALLOW_* environment
  variables. Tools are no longer gated behind allow flags.
• Removed the enable_tool_group tool. Use discover_tools to find and activate
  the tool group you need.

Added

• Language-server tools backed by each project's GDScript language server:
  diagnostics, document symbols, go-to-definition, find-references, hover, and
  completion, plus a project-wide lsp_project_diagnostics error scan. LSP ports
  are discovered per project, and a port collision is reported instead of silently
  reaching the wrong editor.
• A debugger tool group: set and clear breakpoints, step through code, and inspect
  debug state.
• A discover_tools meta-tool that finds and activates on-demand tool groups by
  keyword. It reports honestly when a group is already loaded, returns each newly
  available tool's schema in the activation response, and matches on keywords
  rather than exact names.
• On-demand extension tools: tools registered by third-party addons appear and
  disappear live as extensions are loaded, reloaded, or removed, with an
  extensions_refresh tool to resync on demand.
• New tool groups mirroring the toolkit's expanded command surface: TileSet
  authoring, theme editing, AnimationTree editing, project layer-name management,
  3D scene helpers, Path2D curve editing, collision-shape generation from a
  texture, inherited-scene creation, audio-bus editing, SpriteFrames editing, GPU
  particle systems, navigation, and a filtered scene_query.
• execute_code, which runs a snippet in the editor or in the running game
  (selected by context, defaulting to the running game).
• scene_spatial_map, reporting node positions and bounds, plus
  texture_generate and sound_generate for placeholder assets, and
  script_edit for targeted edits to a script instead of whole-file rewrites.
• A send_text event on input_simulate for typing into a focused text field,
  and support for passing a single input event instead of only an array.
• CLI flags --editor-port, --runtime-port, --lsp-port, --lsp-host, and
  --help, resolved with the precedence CLI flag > environment variable >
  registry discovery > default. --tools-count and --list-eager print the tool
  surface (counts and the eager tool list) and exit without needing an editor.
• A generated tool-reference document (docs/tool-reference/) covering every
  built-in tool and its operations, kept in sync with the catalogue by the
  docs:tools script.
• Startup diagnostics: each channel logs its resolved port and where the value
  came from (CLI, environment, discovery, or default), and pinned ports are
  validated as integers in range so an invalid value exits with a precise error
  instead of crashing at first connection.
• A fail-fast desync check: a pinned editor port that cannot connect, or whose
  handshake fails because another server occupies it, now reports exactly which
  port is wrong instead of hanging on a dead socket.
• A version handshake between the server and the plugin, reporting a clear
  incompatibility message when the two are out of sync.
• Client-side cancellation of in-flight tool calls.
• runtime_poll on game_start to re-probe the running game's connection
  without restarting it, and wait_for_runtime so a single game_start call
  waits for the game to be ready and reports the precise stage and hint if it is
  not.
• scene_close reports whether it discarded unsaved changes, and gains a
  destructive marker in its tool metadata.
• A root_name input parameter on scene_create.
• Next-step successHint suggestions on many tools, and per-tool path validation
  that reports a clear PATH_DENIED error for a path outside the project.
• A clear error at startup when the Node.js version is below the supported
  minimum.

Changed

• Renamed game_eval to execute_code and editor_reload_scripts to
  editor_refresh.
• Screenshot tools take an image_detail option (replacing size) to choose
  between an inline downscaled image and a save-to-disk path, and clearly report
  when a viewport cannot be captured instead of returning a blank image.
• game_start waits for the running game to actually be ready in a single call
  and reports the precise failure stage and a recovery hint when it is not.
• Real pagination (offset, limit, and total) on class-browsing, script and save
  reads, and scene queries, with configurable size caps.
• Read-only visibility is derived from each tool's own annotations, so
  GODOT_MCP_READ_ONLY=1 consistently hides every mutating tool.
• The eager tool set was re-tiered as tools landed, so the most commonly needed
  tools (including runtime screenshot, input, and log tools, and node and group
  management) are available immediately on connect.
• Schemas were tightened across several tools: wait_for_runtime defaults to
  true, animation track_type is a fixed enum, and node-group inputs are stricter.
• Raised the supported Godot version ceiling to 4.7.
• Simplified the macOS setup guidance: the standard npx invocation works with
  modern clients, and fallbacks are documented only where they are actually needed.
• Error hints no longer mention retired concepts (feature gates, profiles, or
  documentation that does not ship).

Fixed

• A startup race that could omit extension or version-gated tools from the first
  tool list, and a double-registration crash that could occur when the client
  reconnected.
• .gdshader files are no longer mis-parsed as GDScript by the language tools.
• Windows LSP paths are returned as res:// paths rather than leaking a raw
  filesystem path.
• Optional parameters that take a JSON-encoded string are no longer advertised as
  required.
• A false "the toolkit did not report its version" warning that could appear when
  launching the game.
• Crash-context and error reporting: the correct error code and richer hints are
  returned, log reads distinguish a transient lock from a missing log and fall
  back to the debug log, and LOG_BUSY and LOG_UNAVAILABLE hints point at the
  real cause. Console and log tools gain source, text_filter, and is_regex
  options.
• debug_set_breakpoint handles its enabled and line parameters correctly.
• Many tool descriptions and schemas were corrected to match actual behavior.

Removed

• The placeholder security gates (os_execute, outbound_http) and the
  never-enforced user-scope allowlist.

Full Changelog: https://github.com/NPGameDev/godot-mcp-server/commits/v1.0.0