@npgamedev/godot-mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -4,7 +4,7 @@
 # Godot MCP Server
 
 [![CI](https://github.com/NPGameDev/godot-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/NPGameDev/godot-mcp-server/actions/workflows/ci.yml)
-![version](https://img.shields.io/badge/version-1.0.0-blue)
+[![npm](https://img.shields.io/npm/v/@npgamedev/godot-mcp-server)](https://www.npmjs.com/package/@npgamedev/godot-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 The npm bridge that connects AI coding assistants to the Godot 4.2+ editor over the [Model Context Protocol](https://modelcontextprotocol.io). Your assistant can create scenes, edit scripts, inspect nodes, run playtests, and read the results back, directly inside the editor while you watch. It pairs with the [Godot MCP Toolkit](https://github.com/NPGameDev/godot-mcp-toolkit) editor plugin, which hosts the WebSocket servers this bridge talks to.
@@ -118,7 +118,7 @@ Launch your MCP client from the project root. The server discovers the plugin th
 Then try the first prompt below. This is the kind of result it produces:
 
 <!-- captured: pre-1.0, Godot 4.7, 2026-07-24, human-recorded (editor + MCP dock, 1 peer connected, game running); image lives in the toolkit repo (docs/media/), absolute raw URL so it renders on npm. -->
-![The Godot 4.7 editor driving the toolkit: the brick-breaker scene open in the viewport, the game running in a debug window with a full wall of colored bricks, and the MCP dock reporting "Listening on 127.0.0.1:6550" with 1 connected peer](https://raw.githubusercontent.com/NPGameDev/godot-mcp-toolkit/main/docs/media/editor-dock-breakout.png)
+![The Godot 4.7 editor driving the toolkit: the brick-breaker scene open in the viewport, the game running in a debug window with a full wall of colored bricks, and the MCP dock reporting "Listening on 127.0.0.1:6550" with 1 connected peer](https://raw.githubusercontent.com/NPGameDev/godot-mcp-toolkit/main/docs/media/editor-dock-brick-breaker.png)
 
 If a step does not produce its "you should see", head to the [troubleshooting guide](https://github.com/NPGameDev/godot-mcp-toolkit/blob/main/docs/troubleshooting.md). It starts with a 60-second checklist and a connectivity probe.
 
@@ -132,7 +132,7 @@ If a step does not produce its "you should see", head to the [troubleshooting gu
 The last three run in seconds. The first one is a real project, the same kind of small game we build end-to-end when validating a release, in a single agent session. Larger games span multiple sessions, with or without MCP.
 
 <!-- captured: pre-1.0, Godot 4.5, 2026-07-24, via runtime_screenshot of the running brick-breaker (mid-flight); image lives in the toolkit repo (docs/media/). -->
-![The agent-built brick-breaker running: a full wall of red, orange, yellow, green, and blue bricks on a dark background, the ball mid-flight, a paddle at the bottom, and a Score and Lives readout](https://raw.githubusercontent.com/NPGameDev/godot-mcp-toolkit/main/docs/media/breakout-running.png)
+![The agent-built brick-breaker running: a full wall of red, orange, yellow, green, and blue bricks on a dark background, the ball mid-flight, a paddle at the bottom, and a Score and Lives readout](https://raw.githubusercontent.com/NPGameDev/godot-mcp-toolkit/main/docs/media/brick-breaker-running.png)
 
 *The brick-breaker from prompt 1 above.*
 

package/dist/shared/version.js

@@ -60,9 +60,14 @@ export function isVersionCompatible(connected, min, max) {
  *
  * Returns:
  *   "ok"      — versions match (all components equal)
- *   "minor"   — same major, different minor or patch
+ *   "patch"   — same major+minor, different patch
+ *   "minor"   — same major, different minor
  *   "major"   — different major version
  *   "unknown" — remote is undefined/empty (pre-handshake peer)
+ *
+ * A patch difference is its own severity because compatibility floors are declared
+ * at major.minor (ADR 0024) — the patch segment carries no compatibility meaning, so
+ * a patch-level difference between the two halves is not something to warn about.
  */
 export function compareVersions(local, remote) {
     if (remote == null || remote === "")
@@ -76,7 +81,9 @@ export function compareVersions(local, remote) {
     }
     if (localParts[0] !== remoteParts[0])
         return "major";
-    if (localParts[1] !== remoteParts[1] || localParts[2] !== remoteParts[2])
+    if (localParts[1] !== remoteParts[1])
         return "minor";
+    if (localParts[2] !== remoteParts[2])
+        return "patch";
     return "ok";
 }

package/dist/startup/lifecycle.js

@@ -1,22 +1,59 @@
-/** Install SIGINT/SIGTERM graceful shutdown (await bridge.close → exit 0) and the
- *  unhandledRejection / uncaughtException stderr loggers that keep the bridge alive. */
+/** Upper bound on the graceful close. A frozen editor makes the WebSocket close
+ *  handshake wait for ws's 30 s timeout; a departing server exits well before that. */
+export const SHUTDOWN_DEADLINE_MS = 2_000;
+/** Write a diagnostic line without ever throwing. A file-backed stderr can throw
+ *  synchronously; a pipe-backed one reports failure through its 'error' event, which
+ *  the muted listener in installProcessHandlers absorbs. Either way the caller continues. */
+export function logSafely(line) {
+    try {
+        process.stderr.write(line);
+    }
+    catch {
+        // The diagnostics sink is unusable; dropping the line is the only safe option.
+    }
+}
+/** Install the departure shutdown (stdin EOF, dead stdout, SIGINT/SIGTERM → await
+ *  bridge.close bounded by SHUTDOWN_DEADLINE_MS → exit 0), the muted stderr listener,
+ *  and the unhandledRejection / uncaughtException loggers that keep the bridge alive. */
 export function installProcessHandlers(bridge) {
-    async function shutdown() {
-        try {
-            await bridge.close();
-        }
-        finally {
-            process.exit(0);
-        }
+    let shuttingDown = false;
+    // The single exit path. First trigger wins: a dying client can deliver stdin EOF, a
+    // stream error and a signal within one tick, and bridge.close() must run once. The
+    // close races the deadline so a hung peer can never keep a departed server alive.
+    // Always exit 0: the server ended because its job ended, not because it failed.
+    function departureShutdown(reason) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logSafely(`[godot-mcp] shutting down: ${reason}\n`);
+        const deadline = setTimeout(() => process.exit(0), SHUTDOWN_DEADLINE_MS);
+        deadline.unref();
+        void bridge.close().then(() => process.exit(0), () => process.exit(0));
     }
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-    // Prevent unhandled errors from crashing the bridge process.
-    // Log to stderr for diagnostics; the bridge stays alive.
+    process.on("SIGINT", () => departureShutdown("SIGINT"));
+    process.on("SIGTERM", () => departureShutdown("SIGTERM"));
+    // Client departure: the client closed its end of our stdin. Fires whether or not we
+    // ever write again, and it is the only signal that fires while an editor socket keeps
+    // the event loop alive.
+    process.stdin.on("end", () => departureShutdown("stdin closed by the client"));
+    process.stdin.on("close", () => departureShutdown("stdin closed"));
+    // Transport dead: any stdout failure means no response can reach the client — not
+    // tied to one error code on purpose (an unlisted code would leave a zombie).
+    process.stdout.on("error", (err) => {
+        departureShutdown(`stdout unwritable (${err?.code ?? err?.message ?? "unknown"})`);
+    });
+    // Diagnostics gone: swallow. The listener's presence is the fix — an 'error' with
+    // no listener is thrown, lands in uncaughtException, gets logged to the same dead
+    // stderr, and so on forever. Nothing can be logged about a dead log sink.
+    process.stderr.on("error", () => {
+        /* muted */
+    });
+    // Stray errors never end the process (§7.6). Logging goes through logSafely so a
+    // dead stderr cannot re-enter these handlers.
     process.on("unhandledRejection", (reason) => {
-        process.stderr.write(`[godot-mcp] unhandledRejection: ${reason}\n`);
+        logSafely(`[godot-mcp] unhandledRejection: ${String(reason)}\n`);
     });
     process.on("uncaughtException", (err) => {
-        process.stderr.write(`[godot-mcp] uncaughtException: ${err?.stack ?? err}\n`);
+        logSafely(`[godot-mcp] uncaughtException: ${err?.stack ?? err}\n`);
     });
 }

package/dist/transport/channel.js

@@ -132,6 +132,9 @@ export function createChannel(url, projectPath, onAuthResolved, onNotification,
             if (!skipVersionCheck) {
                 const serverVer = getServerVersion();
                 const severity = compareVersions(serverVer, authResp.toolkitVersion);
+                // "patch" deliberately matches no branch below. Compatibility floors are declared at
+                // major.minor (ADR 0024), so a patch difference is compatible by construction and stays
+                // silent by fall-through — the omission is the behaviour, not an oversight.
                 if (severity === "major") {
                     process.stderr.write(`[bridge] ERROR: major version mismatch — server ${serverVer}, toolkit ${authResp.toolkitVersion}. Update both to the same major version.\n`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npgamedev/godot-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server that connects AI coding assistants to the Godot 4.2+ editor (scenes, nodes, scripts, ClassDB, playtests) via the companion godot-mcp-toolkit plugin.",
   "type": "module",
   "main": "dist/index.js",
@@ -49,6 +49,7 @@
     "test:integration:portpin": "tsx test/integration/port-pin-probe.ts",
     "repro:lsp-conflict": "tsx test/integration/lsp-conflict-repro.ts",
     "probe:screenshot": "tsx test/screenshot-window-probe.ts",
+    "probe:departure": "tsx test/probes/client-departure-probe.ts",
     "stress:dispatch": "tsx test/integration/dispatch-safety-stress.ts",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ test/ --fix",