@npgamedev/godot-mcp-server 1.0.1 → 1.0.3

package/README.md

@@ -201,8 +201,8 @@ Everything works with zero configuration; the registry handles discovery. The va
 | `GODOT_MCP_TOKEN_PATH` | auto | Auth-token file override (default: the path the plugin publishes in the registry) |
 | `GODOT_MCP_READ_ONLY` | `0` | Set to `1` to hide every mutating tool (server-enforced) |
 | `GODOT_MCP_RATE_LIMIT` | `0` | Max tool calls per second (`0` = unlimited) |
-| `GODOT_MCP_SCRIPT_READ_LIMIT` | built-in cap | Size cap (bytes) on script-read responses |
-| `GODOT_MCP_WS_BUFFER_LIMIT` | built-in cap | Size cap (bytes) on the WebSocket receive buffer |
+| `GODOT_MCP_SCRIPT_READ_LIMIT` | the project's setting | Overrides the editor's cap on script-read responses, in bytes (minimum 65536) |
+| `GODOT_MCP_WS_BUFFER_LIMIT` | the project's setting | Overrides the editor's per-connection WebSocket buffer size, in bytes (minimum 262144). Applies to connections the editor accepts after the server pushes it, so it takes effect from the next connection |
 | `GODOT_MCP_CONFIG_VERSION` | written by the plugin | Config-schema version stamp in `.mcp.json`; the server warns on stderr if it is missing or does not match |
 
 ### CLI flags

package/dist/index.js

@@ -16,7 +16,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createBridge } from "./transport/bridge.js";
+import { capKb, createBridge } from "./transport/bridge.js";
 import { isReadOnly } from "./security/profiles.js";
 import { toolRefCount } from "./registration/toolRefs.js";
 import { createHookPipeline } from "./startup/hooks.js";
@@ -72,9 +72,14 @@ const extensions = createExtensionManager({ server, bridge, getReadOnly: isReadO
 // discover is injected (extensions.discoverExtensions, a closure method — no
 // `this`) so reconcile.ts imports no other composition module (acyclic graph).
 const reconciler = createReconciler({ server, bridge, projectPath, discover: extensions.discoverExtensions });
+// A cap the env sets is shown as the KB value the bridge pushes; an unset one as
+// "project", because the editor's own setting governs it.
+function capLabel(bytes) {
+    return bytes === undefined ? "project" : `${capKb(bytes)}KB`;
+}
 function logStartup(extTimedOut = false) {
     const suffix = extTimedOut ? " (ext discovery timed out — extensions_refresh available)" : "";
-    process.stderr.write(`[godot-mcp] readOnly=${isReadOnly()} tools=${toolRefCount()} hooks=${hookPipeline.length} caps=${caps.scriptReadLimitBytes / 1024}KB/${caps.wsBufferLimitBytes / 1024}KB${suffix}\n`);
+    process.stderr.write(`[godot-mcp] readOnly=${isReadOnly()} tools=${toolRefCount()} hooks=${hookPipeline.length} caps=${capLabel(caps.scriptReadLimitBytes)}/${capLabel(caps.wsBufferLimitBytes)}${suffix}\n`);
 }
 // ── Initial registration ────────────────────────────────────────────
 // Snapshot whether the Godot version is unknown at eager registration. When it

package/dist/startup/lifecycle.js

@@ -42,9 +42,13 @@ export function installProcessHandlers(bridge) {
     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.
+    // Diagnostics gone: swallow, since nothing can be logged about a dead log sink. Once
+    // installed, this listener keeps every direct process.stderr.write in the server safe
+    // after the pipe dies, not only logSafely's, so it must not be dropped in favour of
+    // logSafely. A try/catch cannot replace it: the failure arrives as an asynchronous
+    // 'error' event after write() has already returned. With no listener that event is
+    // thrown into uncaughtException, whose handler writes to the same dead stderr and
+    // re-enters itself, pinning a core at 100% CPU.
     process.stderr.on("error", () => {
         /* muted */
     });

package/dist/startup/startupEnv.js

@@ -90,19 +90,21 @@ export function applyCliMetaGates(cli) {
         process.exit(0);
     }
 }
-// Defaults match the plugin-side ProjectSettings defaults.
-const SCRIPT_READ_LIMIT_DEFAULT = 262144; // 256 KB
-const WS_BUFFER_LIMIT_DEFAULT = 1048576; // 1 MB
+// Floors match the minimums the plugin clamps meta.set_limits values to.
 const SCRIPT_READ_LIMIT_FLOOR = 65536; // 64 KB
 const WS_BUFFER_LIMIT_FLOOR = 262144; // 256 KB
-function parseCapEnv(envName, defaultVal, floor) {
+/** Read one cap from the environment. Unset or empty yields undefined. An invalid
+ *  value is ignored with a warning instead of becoming a default, since a pushed
+ *  default would override the project's own setting. A value below the floor is
+ *  still a configured cap, so it is clamped up to the floor. */
+function parseCapEnv(envName, floor) {
     const raw = process.env[envName];
     if (!raw)
-        return defaultVal;
+        return undefined;
     const parsed = Number(raw);
     if (!Number.isFinite(parsed) || parsed <= 0) {
-        process.stderr.write(`[godot-mcp] WARNING: ${envName}=${raw} is not a valid positive number; using default ${defaultVal}\n`);
-        return defaultVal;
+        process.stderr.write(`[godot-mcp] WARNING: ${envName}=${raw} is not a valid positive number; ignoring it, so the project's own setting applies\n`);
+        return undefined;
     }
     if (parsed < floor) {
         process.stderr.write(`[godot-mcp] WARNING: ${envName}=${parsed} is below minimum ${floor}; clamping to ${floor}\n`);
@@ -110,11 +112,16 @@ function parseCapEnv(envName, defaultVal, floor) {
     }
     return parsed;
 }
-/** Parse + clamp GODOT_MCP_SCRIPT_READ_LIMIT / _WS_BUFFER_LIMIT against their floors/defaults. */
+/**
+ * Resolve the response caps from `GODOT_MCP_SCRIPT_READ_LIMIT` and
+ * `GODOT_MCP_WS_BUFFER_LIMIT`, both in bytes. A variable that is unset, empty or
+ * invalid leaves its cap undefined; a value below the floor is clamped to it.
+ */
 export function resolveResponseCaps() {
-    const scriptReadLimitBytes = parseCapEnv("GODOT_MCP_SCRIPT_READ_LIMIT", SCRIPT_READ_LIMIT_DEFAULT, SCRIPT_READ_LIMIT_FLOOR);
-    const wsBufferLimitBytes = parseCapEnv("GODOT_MCP_WS_BUFFER_LIMIT", WS_BUFFER_LIMIT_DEFAULT, WS_BUFFER_LIMIT_FLOOR);
-    return { scriptReadLimitBytes, wsBufferLimitBytes };
+    return {
+        scriptReadLimitBytes: parseCapEnv("GODOT_MCP_SCRIPT_READ_LIMIT", SCRIPT_READ_LIMIT_FLOOR),
+        wsBufferLimitBytes: parseCapEnv("GODOT_MCP_WS_BUFFER_LIMIT", WS_BUFFER_LIMIT_FLOOR),
+    };
 }
 // ── Config version check ─────────────────────────────────────────────
 const EXPECTED_CONFIG_VERSION = 1;

package/dist/transport/bridge.js

@@ -3,6 +3,15 @@ import { createChannel } from "./channel.js";
 import { createRuntimeConnection } from "./runtimeConnection.js";
 import { parseGodotVer } from "../shared/version.js";
 import { lookupProject } from "../registry.js";
+/**
+ * Convert a cap in bytes to the whole kilobytes `meta.set_limits` takes: the value
+ * the bridge pushes for it.
+ *
+ * @internal
+ */
+export function capKb(bytes) {
+    return Math.round(bytes / 1024);
+}
 /**
  * Build the bridge for one Godot project. Connection is lazy — the first
  * {@link Bridge.call} performs the WebSocket connect + auth handshake; the runtime
@@ -12,7 +21,7 @@ import { lookupProject } from "../registry.js";
  *   is re-discovered from the registry on disconnect unless `explicitEditorPort` is
  *   set or the project path is unknown
  * @param opts - see {@link BridgeOptions}: project path for registry discovery,
- *   static-port overrides, and the response/buffer caps pushed to the plugin after auth
+ *   static-port overrides, and the optional response/buffer caps pushed to the plugin
  * @returns the {@link Bridge}, augmented with `onNotification` (unsolicited plugin
  *   pushes) and `onGodotVersionKnown` (fires once on the unknown → known version
  *   transition, so the composition root can complete a tool surface registered
@@ -49,20 +58,25 @@ export function createBridge(editorUrl, opts) {
             }
         }
     }
-    // After auth, push server-side response caps to the plugin so it can
-    // enforce them (server env var > dock UI ProjectSettings > defaults).
+    // The project's mcp_toolkit/limits/* settings apply unless an env var sets a
+    // cap. Then only that cap is pushed, from the initial editor channel's auth
+    // callback below; the channel rediscoverEditor opens does not push. The plugin
+    // sets it in memory, where it stays in force until the editor restarts or the
+    // setting is changed, and the next settings save from any source persists it
+    // to project.godot. With none set nothing is sent, so a cap set in the dock or
+    // in Project Settings stays in force and stays in project.godot.
     function sendLimitsIfConfigured(channel) {
-        const scriptKb = opts?.scriptReadLimitBytes ? Math.round(opts.scriptReadLimitBytes / 1024) : 0;
-        const wsKb = opts?.wsBufferLimitBytes ? Math.round(opts.wsBufferLimitBytes / 1024) : 0;
-        if (scriptKb > 0 || wsKb > 0) {
-            const params = {};
-            if (scriptKb > 0)
-                params.script_read_cap_kb = scriptKb;
-            if (wsKb > 0)
-                params.ws_buffer_kb = wsKb;
-            // Fire-and-forget — failure here is non-fatal.
-            void channel.call("meta.set_limits", params, 5000).catch(() => { });
-        }
+        const scriptKb = opts?.scriptReadLimitBytes ? capKb(opts.scriptReadLimitBytes) : 0;
+        const wsKb = opts?.wsBufferLimitBytes ? capKb(opts.wsBufferLimitBytes) : 0;
+        const params = {};
+        if (scriptKb > 0)
+            params.script_read_cap_kb = scriptKb;
+        if (wsKb > 0)
+            params.ws_buffer_kb = wsKb;
+        if (Object.keys(params).length === 0)
+            return;
+        // Fire-and-forget: a failed push leaves the project's own setting in force.
+        void channel.call("meta.set_limits", params, 5000).catch(() => { });
     }
     const getNotificationHandler = () => notificationHandler;
     let editor = createChannel(editorUrl, projectPath, ({ version, headless: h }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npgamedev/godot-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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",