@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/tools/tileset.js

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { coercedBoolean, jsonCoerce } from "../shared/schemaCoercion.js";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+// ── tileset group (structural) ──────────────────────────────────────
+// Every tileset tool guards its res:// file_path; texture_path is NOT guarded
+// (toolkit load() is res://-scoped). Declared uniformly via .map below.
+const tilesetStructuralDefs = [
+    {
+        name: "tileset_create",
+        method: "tileset.create",
+        description: "Create a TileSet .tres from a texture. Generates atlas tiles " +
+            "with full-tile rectangular collision (physics on by default). Returns " +
+            "source_id + grid dims — use these with tilemap_set_cells.",
+        inputSchema: {
+            file_path: z.string().describe("Output path, e.g. 'res://resources/tileset.tres'"),
+            texture_path: z.string().describe("Texture for the atlas source, e.g. 'res://assets/tiles.png'"),
+            tile_size: z
+                .object({
+                x: z.coerce.number().int().positive(),
+                y: z.coerce.number().int().positive(),
+            })
+                .optional()
+                .describe("Tile size in pixels. Default {x:16, y:16}"),
+            physics: coercedBoolean().optional().describe("Add physics layer. Default true"),
+            collision_layer: z
+                .union([z.coerce.number().int(), z.array(z.union([z.coerce.number().int(), z.string()]))])
+                .optional()
+                .describe("Physics collision layer. Integer bitmask OR array of layer numbers [1,6] or names ['player','walls']. Default 1"),
+            collision_mask: z
+                .union([z.coerce.number().int(), z.array(z.union([z.coerce.number().int(), z.string()]))])
+                .optional()
+                .describe("Physics collision mask. Integer bitmask OR array of layer numbers [2,4] or names ['enemies','collectibles']. Default 1"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Use tileset_add_source to add more atlas textures, then tileset_setup_layers to configure " +
+            "physics/terrain/navigation layers. For per-tile properties (collision polygons, terrain, navigation), " +
+            "use discover_tools(request: 'tileset_edit') to activate the per-tile editing group.",
+    },
+    {
+        name: "tileset_add_source",
+        method: "tileset.add_source",
+        description: "Add an atlas source to an existing TileSet. Auto-creates tiles for every " +
+            "grid cell in the texture. Returns the new source_id.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            texture_path: z.string().describe("Texture for the new atlas source"),
+            tile_size: z
+                .object({
+                x: z.coerce.number().int().positive(),
+                y: z.coerce.number().int().positive(),
+            })
+                .optional()
+                .describe("Tile size in pixels. Defaults to the TileSet's tile_size"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Source added. Use tileset_setup_layers to configure physics/terrain/navigation layers if not done yet.",
+    },
+    {
+        name: "tileset_remove_source",
+        method: "tileset.remove_source",
+        description: "Remove an atlas source from a TileSet. This deletes all tile data for that source.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().describe("Atlas source id to remove"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+    },
+    {
+        name: "tileset_add_alternative",
+        method: "tileset.add_alternative",
+        description: "Create an alternative tile variant (flip, rotate, recolor) for a base tile.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            atlas_x: z.coerce.number().int().describe("Base tile X coordinate in the atlas"),
+            atlas_y: z.coerce.number().int().describe("Base tile Y coordinate in the atlas"),
+            flip_h: coercedBoolean().optional().describe("Flip horizontally"),
+            flip_v: coercedBoolean().optional().describe("Flip vertically"),
+            transpose: coercedBoolean().optional().describe("Transpose (swap X/Y)"),
+            modulate: z
+                .object({
+                r: z.coerce.number().optional(),
+                g: z.coerce.number().optional(),
+                b: z.coerce.number().optional(),
+                a: z.coerce.number().optional(),
+            })
+                .optional()
+                .describe("Color modulation {r, g, b, a} — each 0.0–1.0"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Alternative created. Use tilemap_set_cells with alternative_tile to place it.",
+    },
+    {
+        name: "tileset_remove_alternative",
+        method: "tileset.remove_alternative",
+        description: "Remove an alternative tile variant from a base tile.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            atlas_x: z.coerce.number().int().describe("Base tile X coordinate in the atlas"),
+            atlas_y: z.coerce.number().int().describe("Base tile Y coordinate in the atlas"),
+            alternative_id: z.coerce.number().int().describe("Alternative tile id to remove"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+    },
+    {
+        name: "tileset_setup_layers",
+        method: "tileset.setup_layers",
+        description: "Configure TileSet layers: terrain sets (with named terrains), custom data layers, " +
+            "and physics/navigation/occlusion layer counts.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            terrain_sets: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                mode: z
+                    .enum(["match_corners_and_sides", "match_corners", "match_sides"])
+                    .optional()
+                    .describe("Terrain matching mode. Default match_corners_and_sides"),
+                terrains: z.array(z.string()).optional().describe("Named terrains in this set"),
+            })))
+                .optional()
+                .describe("Terrain sets to add"),
+            custom_data: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                name: z.string().describe("Layer name"),
+                type: z
+                    .enum(["int", "float", "bool", "string", "vector2", "vector2i", "vector3", "color"])
+                    .optional()
+                    .describe("Data type. Default int"),
+            })))
+                .optional()
+                .describe("Custom data layers to add"),
+            navigation_layers: z.coerce.number().int().optional().describe("Desired navigation layer count"),
+            occlusion_layers: z.coerce.number().int().optional().describe("Desired occlusion layer count"),
+            physics_layers: z.coerce.number().int().optional().describe("Desired physics layer count"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Layers configured. Use discover_tools(request: 'tileset_edit') to set per-tile properties.",
+    },
+];
+export const tilesetStructuralTools = tilesetStructuralDefs.map((t) => ({
+    ...t,
+    pathParams: [PROJECT_FILE_PATH],
+}));
+// ── tileset_edit group (per-tile properties) ─────────────────────────
+const tileArraySchema = z
+    .preprocess(jsonCoerce, z.array(z.record(z.string(), z.unknown())))
+    .describe("Per-tile edits: [{atlas_x, atlas_y, ...domain-specific params}]");
+const tilesetEditDefs = [
+    {
+        name: "tileset_edit_physics",
+        method: "tileset.edit_physics",
+        description: "Set collision polygons on TileSet tiles. Supports shortcuts ('full', 'none', 'one_way') " +
+            "or custom polygon arrays [{x, y}].",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            tiles: tileArraySchema.describe("Per-tile edits: [{atlas_x, atlas_y, physics_polygon: 'full'|'none'|'one_way'|[{x,y}], " +
+                "physics_layer?: int, one_way_collision?: bool}]"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Collision set. Other per-tile tools in this group: tileset_edit_terrain, " +
+            "tileset_edit_navigation, tileset_edit_visuals, tileset_edit_custom_data.",
+    },
+    {
+        name: "tileset_edit_terrain",
+        method: "tileset.edit_terrain",
+        description: "Assign terrain sets and peering bits to TileSet tiles for auto-tiling.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            tiles: tileArraySchema.describe("Per-tile edits: [{atlas_x, atlas_y, terrain_set: int, terrain?: int, " +
+                "terrain_peering?: {right?: int, bottom?: int, left?: int, top?: int, ...}}]"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Terrain assigned. Set up terrain sets first with tileset_setup_layers if needed.",
+    },
+    {
+        name: "tileset_edit_navigation",
+        method: "tileset.edit_navigation",
+        description: "Set navigation polygons on TileSet tiles. Supports 'full', 'none', or custom polygon arrays.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            tiles: tileArraySchema.describe("Per-tile edits: [{atlas_x, atlas_y, navigation_polygon: 'full'|'none'|[{x,y}], " + "navigation_layer?: int}]"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Navigation polygon set. Other per-tile tools: tileset_edit_physics, tileset_edit_terrain.",
+    },
+    {
+        name: "tileset_edit_visuals",
+        method: "tileset.edit_visuals",
+        description: "Set occlusion polygons, tile animations, and probability weights on TileSet tiles.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            tiles: tileArraySchema.describe("Per-tile edits: [{atlas_x, atlas_y, occlusion_polygon?: 'full'|'none'|[{x,y}], " +
+                "occlusion_layer?: int, animation?: {frame_count, columns?, frame_duration?, separation?}, " +
+                "probability?: number}]"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+        successHint: "Visual properties set. Other per-tile tools: tileset_edit_physics, tileset_edit_terrain.",
+    },
+    {
+        name: "tileset_edit_custom_data",
+        method: "tileset.edit_custom_data",
+        description: "Set custom data values on TileSet tiles. Custom data layers must be " +
+            "configured first with tileset_setup_layers.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing .tres TileSet"),
+            source_id: z.coerce.number().int().optional().describe("Atlas source id. Default 0"),
+            tiles: tileArraySchema.describe('Per-tile edits: [{atlas_x, atlas_y, custom_data: {"layer_name": value, ...}}]'),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Custom data set. Configure layers first with tileset_setup_layers if needed.",
+    },
+];
+export const tilesetEditTools = tilesetEditDefs.map((t) => ({
+    ...t,
+    pathParams: [PROJECT_FILE_PATH],
+}));
+export const tilesetTools = [...tilesetStructuralTools, ...tilesetEditTools];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, tilesetTools, allowedTools);
+}

package/dist/transport/authHandshake.js

@@ -0,0 +1,43 @@
+import { BridgeError } from "../shared/errors.js";
+import { getServerVersion } from "../shared/version.js";
+const AUTH_TIMEOUT_MS = 5_000;
+/**
+ * Send the auth handshake and wait for {"authed": true} or a close frame.
+ * Resolves with the full auth response.
+ */
+export function authenticate(ws, token) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new BridgeError("AUTH_FAILED", "auth handshake timed out"));
+        }, AUTH_TIMEOUT_MS);
+        function cleanup() {
+            clearTimeout(timer);
+            ws.removeListener("message", onMessage);
+            ws.removeListener("close", onClose);
+        }
+        function onMessage(data) {
+            try {
+                const msg = JSON.parse(String(data));
+                if (msg.authed === true) {
+                    cleanup();
+                    resolve({
+                        godotVersion: msg.godot_version,
+                        toolkitVersion: msg.version,
+                        headless: msg.headless,
+                    });
+                }
+            }
+            catch {
+                // Not JSON — ignore, keep waiting.
+            }
+        }
+        function onClose(_code, reason) {
+            cleanup();
+            reject(new BridgeError("AUTH_FAILED", `server closed connection during auth: ${reason.toString()}`));
+        }
+        ws.on("message", onMessage);
+        ws.on("close", onClose);
+        ws.send(JSON.stringify({ auth: token, version: getServerVersion() }));
+    });
+}

package/dist/transport/bridge.js

@@ -0,0 +1,225 @@
+import { BridgeError } from "../shared/errors.js";
+import { createChannel } from "./channel.js";
+import { createRuntimeConnection } from "./runtimeConnection.js";
+import { parseGodotVer } from "../shared/version.js";
+import { lookupProject } from "../registry.js";
+/**
+ * Build the bridge for one Godot project. Connection is lazy — the first
+ * {@link Bridge.call} performs the WebSocket connect + auth handshake; the runtime
+ * channel connects on demand when a playtest is discovered.
+ *
+ * @param editorUrl - the editor WebSocket URL (`ws://127.0.0.1:<port>`); the port
+ *   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
+ * @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
+ *   before the editor reported its version)
+ */
+export function createBridge(editorUrl, opts) {
+    const projectPath = opts?.projectPath;
+    let godotVersion = undefined;
+    // Editor display mode from the Mode-A auth ack. undefined until the editor
+    // authenticates — mirrors godotVersion's unknown state, and NOT pre-populated
+    // from the registry (no pre-auth consumer; the registry carries no display mode).
+    let headless = undefined;
+    let notificationHandler = undefined;
+    let versionKnownHandler = undefined;
+    // Record the connected Godot version. Fires the version-resolved hook on the
+    // unknown → known transition (and only then) so the composition root can
+    // complete a tool surface that was registered before the editor reported its
+    // version — version-gated tools (scene_close) and extension tools stranded on
+    // a server-before-editor cold start. Routing every version-set
+    // site through here keeps the unknown → known lifecycle owned in one place.
+    function setGodotVersion(v) {
+        const versionWasUnknown = godotVersion == null;
+        godotVersion = v;
+        if (versionWasUnknown && versionKnownHandler)
+            versionKnownHandler();
+    }
+    // Pre-populate version from registry entry (available before auth).
+    if (projectPath) {
+        const regEntry = lookupProject(projectPath);
+        if (regEntry) {
+            const regVer = regEntry.godot_version;
+            if (regVer != null && regVer.length > 0) {
+                godotVersion = regVer;
+            }
+        }
+    }
+    // After auth, push server-side response caps to the plugin so it can
+    // enforce them (server env var > dock UI ProjectSettings > defaults).
+    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 getNotificationHandler = () => notificationHandler;
+    let editor = createChannel(editorUrl, projectPath, ({ version, headless: h }) => {
+        setGodotVersion(version);
+        headless = h;
+        sendLimitsIfConfigured(editor);
+    }, getNotificationHandler);
+    let cachedEditorPort = Number(new URL(editorUrl).port);
+    // ── Editor-port re-discovery ─────────────────────────────────────
+    // When the editor channel fails with CONNECT_FAILED / DISCONNECTED,
+    // re-read the registry. If the port changed (plugin restarted on a
+    // different port), close the old channel, create a fresh one, and
+    // retry the call once. Skipped when the editor port is a pin
+    // (GODOT_MCP_EDITOR_PORT / --editor-port) or no projectPath is available for
+    // registry lookup. TTL prevents thrashing the registry file when the editor
+    // is truly unreachable.
+    const staticEditor = !!opts?.explicitEditorPort;
+    const EDITOR_REDISCOVER_TTL_MS = 5_000;
+    let lastRediscoverAt = 0;
+    async function rediscoverEditor() {
+        if (staticEditor || !projectPath)
+            return false;
+        const now = Date.now();
+        if (now - lastRediscoverAt < EDITOR_REDISCOVER_TTL_MS)
+            return false;
+        lastRediscoverAt = now;
+        const entry = lookupProject(projectPath);
+        if (!entry)
+            return false;
+        if (entry.port === cachedEditorPort)
+            return false;
+        const oldPort = cachedEditorPort;
+        cachedEditorPort = entry.port;
+        await editor.close();
+        editor = createChannel(`ws://127.0.0.1:${cachedEditorPort}`, projectPath, ({ version, headless: h }) => {
+            setGodotVersion(version);
+            headless = h;
+        }, getNotificationHandler);
+        process.stderr.write(`[bridge] editor port changed ${oldPort} → ${cachedEditorPort}\n`);
+        return true;
+    }
+    // ── Fail-fast desync cross-check (pinned editor) ─────────────────
+    // A pinned editor port skips re-discovery, so a stale or unsynced pin (the
+    // classic ".mcp.json sets the pin for the server only, the editor is launched
+    // separately" case) would otherwise surface only as a generic error. Two
+    // failure shapes reach here: a connection-level loss (nothing on the pinned
+    // port), and a FAILED AUTH HANDSHAKE — a foreign WebSocket server on the
+    // pinned port passes the TCP+WS upgrade and then stalls or drops the auth, so
+    // the desync surfaces as AUTH_FAILED, never CONNECT_FAILED. For either, read
+    // the registry ONCE — the toolkit publishes its real bound port even in pin
+    // mode — and synthesize a precise, actionable error naming the mismatch,
+    // PRESERVING the original transport code (retry semantics stay intact).
+    // Registry I/O stays on the FAILURE path only; the healthy path never reads
+    // it. Returns undefined when there is nothing to add — no projectPath for
+    // ground truth, or an auth failure with the registry AGREEING on the port
+    // (the real editor answered and rejected auth: a token problem, not a port
+    // desync) — leaving the original error to propagate.
+    function pinnedEditorDesyncError(original) {
+        if (!projectPath)
+            return undefined;
+        const authFailure = original.code === "AUTH_FAILED";
+        const entry = lookupProject(projectPath);
+        if (!entry) {
+            return new BridgeError(original.code, authFailure
+                ? `auth failed on pinned editor port ${cachedEditorPort} and no live editor is registered for this ` +
+                    `project — something else may be occupying the pinned port; launch the Godot editor with ` +
+                    `GODOT_MCP_EDITOR_PORT=${cachedEditorPort} so it binds the same port, or unset the pin to use ` +
+                    `registry discovery`
+                : `editor pinned to port ${cachedEditorPort}, but no live editor is registered for this project — ` +
+                    `launch the Godot editor (set GODOT_MCP_EDITOR_PORT=${cachedEditorPort} so it binds the same port), ` +
+                    `or unset the pin to use registry discovery`);
+        }
+        if (entry.port !== cachedEditorPort) {
+            return new BridgeError(original.code, authFailure
+                ? `auth failed on pinned editor port ${cachedEditorPort}, but the live editor for this project is ` +
+                    `listening on ${entry.port} — something else may be occupying the pinned port; launch the editor ` +
+                    `with the same GODOT_MCP_EDITOR_PORT, or unset the pin to use discovery`
+                : `editor pinned to port ${cachedEditorPort}, but the live editor for this project is listening on ` +
+                    `${entry.port} — launch the editor with the same GODOT_MCP_EDITOR_PORT, or unset the pin to use discovery`);
+        }
+        // Registry agrees with the pin. An auth failure here came from the real
+        // editor (token trouble, not a desync) — add nothing. A connection loss
+        // means the editor is down, restarting, or crashed — say so plainly.
+        if (authFailure)
+            return undefined;
+        return new BridgeError(original.code, `editor pinned to port ${cachedEditorPort} matches the registry, but the port is not accepting ` +
+            `connections — the editor may be starting or has stopped`);
+    }
+    // ── Runtime connection ───────────────────────────────────────────
+    // The playtest runtime-connection aggregate — discovery, the registry
+    // watcher, port-waiters, and the frozen-game heartbeat — lives in
+    // runtimeConnection.ts. The composition root builds one and delegates the
+    // runtime facade methods (callRuntime / waitForRuntimeConnection /
+    // clearRuntime) to it. It touches neither version state nor notifications.
+    const runtime = createRuntimeConnection({ projectPath, explicitRuntimePort: opts?.explicitRuntimePort });
+    return {
+        async call(method, params, timeoutMs, signal) {
+            try {
+                return await editor.call(method, params, timeoutMs, signal);
+            }
+            catch (err) {
+                if (err instanceof BridgeError) {
+                    const connectionLoss = err.code === "CONNECT_FAILED" || err.code === "DISCONNECTED";
+                    if (staticEditor) {
+                        // Pinned: no re-discovery. A connection loss OR a failed auth
+                        // handshake (a foreign server on the pinned port) gets the desync
+                        // diagnosis (one registry read, on the failure path only).
+                        if (connectionLoss || err.code === "AUTH_FAILED") {
+                            const desync = pinnedEditorDesyncError(err);
+                            if (desync)
+                                throw desync;
+                        }
+                    }
+                    else if (connectionLoss) {
+                        // On editor connection failure, re-read the registry. If the port
+                        // changed, retry once against the new channel.
+                        const changed = await rediscoverEditor();
+                        if (changed)
+                            return editor.call(method, params, timeoutMs, signal);
+                    }
+                }
+                throw err;
+            }
+        },
+        callRuntime(method, params, timeoutMs, signal) {
+            return runtime.callRuntime(method, params, timeoutMs, signal);
+        },
+        async close() {
+            // Runtime first: tearing it down resolves any outstanding port-waiters
+            // and stops the heartbeat/watcher before either socket closes. The editor
+            // and runtime are independent sockets, so their relative close order is
+            // unobservable.
+            await runtime.close();
+            await editor.close();
+        },
+        getGodotVersionString() {
+            return godotVersion;
+        },
+        getGodotVersion() {
+            if (!godotVersion)
+                return undefined;
+            return parseGodotVer(godotVersion);
+        },
+        isHeadless() {
+            return headless;
+        },
+        waitForRuntimeConnection(timeoutMs) {
+            return runtime.waitForRuntimeConnection(timeoutMs);
+        },
+        clearRuntime() {
+            runtime.clearRuntime();
+        },
+        onNotification(handler) {
+            notificationHandler = handler;
+        },
+        onGodotVersionKnown(handler) {
+            versionKnownHandler = handler;
+        },
+    };
+}