@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/security/pathGuard.js

@@ -0,0 +1,97 @@
+/** Convenience: the ubiquitous `file_path → res://` declaration. */
+export const PROJECT_FILE_PATH = { param: "file_path", guard: "project" };
+/** Resolve a PathGuard's allowed prefixes. */
+export function guardPrefixes(g) {
+    if ("prefixes" in g)
+        return g.prefixes;
+    return g.guard === "user" ? ["user://"] : ["res://"];
+}
+/**
+ * Validate a single path string against the allowed prefixes — the syntactic
+ * half of FileGuard.resolve_safe. Empty/whitespace is rejected here (the
+ * validator contract); callers that treat an absent optional param as "skip"
+ * use checkPathGuard, which defers empties to the toolkit instead.
+ */
+export function checkPath(input, prefixes) {
+    if (input.trim().length === 0)
+        return { ok: false, reason: "empty path" };
+    const normalized = input.replace(/\\/g, "/");
+    // Reject exact `..` segments (directory traversal). Match the SEGMENT, never
+    // a substring — so `a..b` and `a.b.c` pass (the classic over-block bug).
+    for (const seg of normalized.split("/")) {
+        if (seg === "..")
+            return { ok: false, reason: `path contains '..': ${input}` };
+    }
+    // Reject absolute OS paths: drive letter (`X:`), then any leading `/` that
+    // is not the res://‑/user:// scheme. After `\`→`/`, UNC `\\host\share`
+    // becomes `//host/share` and is caught by the leading-`/` rule.
+    if (normalized.length >= 2 && normalized[1] === ":") {
+        return { ok: false, reason: `absolute OS path: ${input}` };
+    }
+    if (normalized.startsWith("/") && !normalized.startsWith("res://") && !normalized.startsWith("user://")) {
+        return { ok: false, reason: `absolute OS path: ${input}` };
+    }
+    // Require an allowed prefix.
+    if (!prefixes.some((p) => normalized.startsWith(p))) {
+        return { ok: false, reason: `path must start with one of [${prefixes.join(", ")}] (got ${input})` };
+    }
+    return { ok: true };
+}
+/**
+ * Apply a PathGuard to an input value. Skips absent / empty / whitespace-only
+ * values (an unprovided optional param defers to the toolkit — e.g.
+ * editor_save_scene with no file_path = save-in-place). Validates every element
+ * of an array param (editor_refresh.file_paths-style, if ever declared).
+ */
+export function checkPathGuard(g, value) {
+    const prefixes = guardPrefixes(g);
+    const values = Array.isArray(value) ? value : [value];
+    for (const v of values) {
+        if (typeof v !== "string" || v.trim().length === 0)
+            continue; // absent/empty → defer to toolkit
+        const r = checkPath(v, prefixes);
+        if (!r.ok)
+            return r;
+    }
+    return { ok: true };
+}
+/**
+ * Shared subset fixture — the SAME path cases are mirrored in the toolkit's
+ * FileGuard unit-test group. This file is the source of truth; keep the
+ * GDScript mirror in sync. The cross-repo invariant the duplication
+ * enforces: NO path is server-deny / toolkit-allow (a false rejection). Both
+ * suites assert their own guard against `allow` (→ ok) and `deny` (→ rejected).
+ *
+ * Note: OS-symlink escapes are NOT here — symlink resolution is out of scope
+ * on both sides (lexical canonicalization only; single-user localhost threat
+ * model), so no fixture case can express one.
+ * @internal
+ */
+export const PATH_FIXTURE = {
+    /** [path, prefixes] both layers must ALLOW (no false rejections). */
+    allow: [
+        ["res://x.gd", ["res://"]],
+        ["res://a/b/c.tscn", ["res://"]],
+        ["res://addons/foo/bar.gd", ["res://"]],
+        ["res://my..thing/x.gd", ["res://"]], // dots, not an exact `..` segment
+        ["res://a.b.c/d.gd", ["res://"]],
+        ["res://a/b/", ["res://"]], // trailing-slash dir
+        ["user://saves/x.json", ["user://"]],
+        ["user://screenshots/shot.png", ["res://", "user://screenshots/"]],
+        ["res://shot.png", ["res://", "user://screenshots/"]],
+    ],
+    /** [path, prefixes] both layers must DENY (no escapes). */
+    deny: [
+        ["res://../escape.gd", ["res://"]],
+        ["res://a/../../../escape", ["res://"]],
+        ["../../etc/passwd", ["res://"]],
+        ["/etc/passwd", ["res://"]],
+        ["C:/Windows/x", ["res://"]],
+        ["\\\\server\\share\\x", ["res://"]], // UNC
+        ["random/x.gd", ["res://"]], // non-allowed prefix
+        ["file:///etc/passwd", ["res://"]],
+        ["user://x.json", ["res://"]], // wrong prefix for a project tool
+        ["res://x.gd", ["user://"]], // wrong prefix for a user tool
+        ["", ["res://"]], // empty
+    ],
+};

package/dist/security/profiles.js

@@ -0,0 +1,104 @@
+/**
+ * Tool visibility — eager tools are always registered up front; read-only mode
+ * (GODOT_MCP_READ_ONLY=1) filters out mutating tools.
+ */
+/** 34 eager tools (discover_tools + extensions_refresh added programmatically → 36 total). */
+export const EAGER_TOOLS = [
+    // Scene (5)
+    "scene_get_tree",
+    "scene_create_node",
+    "scene_delete_node",
+    "scene_create",
+    "scene_open",
+    // Node (8) — node_manage, node_groups, autoload_manage are eager rather than
+    // in the node_management group: dynamic activation via tools/list_changed is
+    // not robust across MCP clients, so keeping them eager is the stable choice.
+    // control_set_layout is eager too — layout is needed broadly enough that lazy
+    // activation isn't worth it.
+    "node_get_property",
+    "node_set_property",
+    "node_get_property_list",
+    "node_set_script",
+    "node_manage",
+    "node_groups",
+    "autoload_manage",
+    "control_set_layout",
+    // Script (3)
+    "script_read",
+    "script_write",
+    "script_edit",
+    // Editor (4) — editor_screenshot lives in the editor_advanced group;
+    // there is no editor_get_errors (use editor_get_console with level_filter).
+    "editor_save_scene",
+    "editor_get_console",
+    "project_get_settings",
+    "project_set_setting",
+    // Playtest (6) — these runtime tools are eager, not in the lazy runtime group.
+    // runtime_set_property is intentionally NOT listed here: it is a
+    // runtime_advanced group tool, and MODULE_ALLOWED subtracts group tools from
+    // the eager set, so listing it would be dead.
+    "game_start",
+    "game_stop",
+    "runtime_screenshot",
+    "input_simulate",
+    "runtime_get_script_vars",
+    "debugger_get_log",
+    // Signals (2) — eager rather than in the signals group: signal wiring is
+    // needed broadly enough to warrant always-on availability.
+    "signal_list",
+    "signal_manage",
+    // Assets (1) — asset_list lives in the asset_ops group, not eager.
+    "folder_create",
+    // Script diagnostics (1)
+    "script_check",
+    // Scene query (1)
+    "scene_query",
+    // Spatial (1) — eager read-only scene layout map. MUST be listed here: eager
+    // registration is gated by EAGER_TOOLS, NOT by ALL_TOOL_DEFS (which only feeds
+    // --tools-count and the static catalogue checks). Omitting it makes the tool
+    // counted-but-unregistered — absent from tools/list on every session, with no
+    // client-side fix. The test/structural.ts reachability check guards against
+    // recurrence.
+    "scene_spatial_map",
+    // High-risk tools — always eagerly registered. Risk communicated
+    // via MCP annotations (destructiveHint); agent-side filtering recommended.
+    "execute_code",
+    "node_call_method",
+];
+/**
+ * Centralized read-only predicate. A tool is allowed in read-only mode iff
+ * its annotations declare readOnlyHint: true. Strict inclusion — unannotated
+ * tools default to excluded (safe).
+ *
+ * Runtime invariant: readOnlyHint + destructiveHint is a contradiction.
+ * When detected, log a warning and treat the tool as mutating (never crash).
+ */
+export function isAllowedInReadOnly(annotations) {
+    if (!annotations?.readOnlyHint)
+        return false;
+    if (annotations.destructiveHint) {
+        process.stderr.write("[godot-mcp] WARNING: tool has both readOnlyHint and destructiveHint — treating as mutating\n");
+        return false;
+    }
+    return true;
+}
+/**
+ * Combined read-only check: returns true when a tool should be excluded.
+ * Wraps both the mode check and the annotation check into a single call
+ * so callers don't repeat `if (readOnly && !isAllowedInReadOnly(...))`.
+ */
+export function isExcludedByReadOnly(readOnly, annotations) {
+    return readOnly && !isAllowedInReadOnly(annotations);
+}
+/** Whether read-only mode is active. */
+export function isReadOnly() {
+    return process.env.GODOT_MCP_READ_ONLY === "1";
+}
+/**
+ * Build the allowed-tool set for initial registration.
+ * Returns all eager tools. Read-only filtering happens at point-of-use
+ * via isAllowedInReadOnly() — no pre-computed subtraction needed.
+ */
+export function resolveAllowedTools() {
+    return new Set(EAGER_TOOLS);
+}

package/dist/security/untrusted.js

@@ -0,0 +1,23 @@
+import { randomBytes } from "crypto";
+/**
+ * Untrusted-content envelope wrapper — TypeScript mirror of
+ * addons/godot_mcp_toolkit/untrusted.gd.
+ *
+ * Wraps user-authored / project-authored content before it reaches the
+ * LLM in a nonce-tagged envelope to prevent tag-breakout injection.
+ * Most wrapping happens GDScript-side, but this is available for
+ * server-originated wrapping.
+ */
+/** Matches any <untrusted...> or </untrusted...> tag variant. */
+const ENVELOPE_TAG_RE = /<\s*\/?\s*untrusted(?:-[0-9a-f]*)?(?:\s[^>]*)?\s*>/gi;
+function generateNonce() {
+    return randomBytes(4).toString("hex");
+}
+function scrubEnvelopeTags(text) {
+    return text.replace(ENVELOPE_TAG_RE, "[scrubbed-envelope-tag]");
+}
+export function untrustedWrap(kind, source, body) {
+    const nonce = generateNonce();
+    const scrubbed = scrubEnvelopeTags(body);
+    return `<untrusted-${nonce} kind="${kind}" source="${source}">\n${scrubbed}\n</untrusted-${nonce}>`;
+}

package/dist/shared/errorContract.js

@@ -0,0 +1,154 @@
+/**
+ * Error contract — shape every failure into the canonical MCP error
+ * response with the right code and hint. A near-pure leaf: the runtime
+ * crash-context helpers take the Bridge as a parameter, so this module
+ * depends on neither registration nor dispatch.
+ */
+import { BridgeError } from "./errors.js";
+import { PAGE_FIELD } from "./pagination.js";
+// ── Error utilities ─────────────────────────────────────────────────
+/**
+ * Canonical MCP failure response. Plugin emits
+ * {success: false, error, code} inside the JSON-RPC result payload;
+ * transport-level failures surface as BridgeError and are translated
+ * here. String `code` is accepted (in addition to the ErrorCode union)
+ * because bridge errors (RPC_ERROR etc.) aren't statically typed at
+ * every call site.
+ */
+export function toolError(code, message, hint) {
+    const payload = { success: false, error: message, code };
+    if (hint)
+        payload.hint = hint;
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError: true,
+    };
+}
+/**
+ * If the plugin returned {success: false, ...} inside the JSON-RPC
+ * result, translate it to an MCP isError response. Non-error successes
+ * (including idempotent create returns) have success absent or
+ * truthy and pass through unchanged.
+ */
+export function toolErrorFromPayload(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const obj = result;
+    if (obj.success !== false)
+        return undefined;
+    const code = typeof obj.code === "string" ? obj.code : "INTERNAL";
+    const error = typeof obj.error === "string" ? obj.error : "unknown error";
+    const hint = typeof obj.hint === "string" ? obj.hint : undefined;
+    return toolError(code, error, hint);
+}
+/**
+ * Default hints for transport-level codes thrown as a `BridgeError`.
+ *
+ * Membership invariant: only codes that can arrive as a thrown `BridgeError`
+ * (transport-level, where the toolkit never ran to attach a hint) belong here.
+ * Application-level codes the toolkit emits as `{ success: false, … }` payloads
+ * carry their own hint — do not add them: those flow through `toolErrorFromPayload`,
+ * which relays the toolkit's hint verbatim, so the toolkit is the SSOT for their
+ * wording. `LOG_BUSY` / `LOG_UNAVAILABLE` are such payload codes — their recovery
+ * advice is version-gated on the editor's Godot version (only the toolkit knows it),
+ * so a fixed server default would be stale for half the versions. `COMPILATION_FAILED`
+ * stays: it is handled as a thrown code in `runtimeErrorWithCrashContext`.
+ */
+const EXCEPTION_HINTS = {
+    TIMEOUT: "The editor or game may be busy, or the game failed to compile/start. " +
+        "For editor calls, try editor.wait_for_idle. For runtime calls, " +
+        "debugger_get_log returns cached output after a crash. If empty, call editor_get_console without level_filter.",
+    COMPILATION_FAILED: "The game failed to compile. Fix the script errors listed above, then call game_start again. " +
+        "If no errors are shown, call editor_refresh to retrigger them, then editor_get_console for the full log.",
+    DISCONNECTED: "Plugin WebSocket not connected. Ensure Godot is running with the plugin enabled. If running headless, launch with: godot --headless --editor --path <project>",
+    CONNECT_FAILED: "Could not connect to the Godot editor plugin. Ensure Godot is running with the plugin enabled. If running headless, launch with: godot --headless --editor --path <project>",
+    GAME_NOT_RUNNING: "No running game. Call editor_get_console(level_filter:['error']) for crash diagnostics. " +
+        "If empty, the game may have crashed — debugger_get_log serves cached output from log file after a real crash (OS signal). " +
+        "To restart: fix the errors, then game_start.",
+};
+/**
+ * Hint for a TIMEOUT that fired while the call sat in the toolkit's mutation
+ * queue (serialized behind other mutations), not because anything stalled. The
+ * generic EXCEPTION_HINTS.TIMEOUT "editor or game may be busy" advice is
+ * actively misleading here — the call was healthy, just waiting its fair-FIFO
+ * turn — so this replaces it and surfaces the duplicate-on-retry risk.
+ */
+const SERIALIZED_QUEUE_TIMEOUT_HINT = "The command was accepted and queued behind other scene mutations, then exceeded its timeout while waiting its turn. " +
+    "Issue scene mutations sequentially rather than in parallel. A retry may re-apply an already-applied change — " +
+    "re-check state before re-issuing (duplicate-on-retry risk).";
+/**
+ * Map a thrown BridgeError (or any Error) to a toolError response.
+ * Preserves the bridge's transport-layer code (TIMEOUT, DISCONNECTED,
+ * GAME_NOT_RUNNING, CONNECT_FAILED, ...) so the client-facing response
+ * is specific enough to retry-or-give-up on.
+ */
+export function toolErrorFromException(err) {
+    const code = err instanceof BridgeError ? err.code : "INTERNAL";
+    const message = err?.message ?? String(err);
+    const hint = err instanceof BridgeError && err.serializedQueueTimeout ? SERIALIZED_QUEUE_TIMEOUT_HINT : EXCEPTION_HINTS[code];
+    return toolError(code, message, hint);
+}
+// ── Runtime crash context ───────────────────────────────────────────
+/**
+ * When a runtime call fails, try to auto-fetch recent errors from the
+ * debugger bridge (game-session-specific errors + log file cache), with
+ * fallback to editor_get_console for pre-game-start scenarios.
+ */
+async function fetchCrashContext(bridge) {
+    // Primary: debugger.get_log has error_buffer (debugger bridge) + log file lines.
+    try {
+        const result = (await bridge.call("debugger.get_log", { limit: 15 }, 5_000));
+        const parts = [];
+        const errorBuffer = Array.isArray(result?.error_buffer) ? result.error_buffer : [];
+        for (const entry of errorBuffer) {
+            const e = entry;
+            const msg = typeof e.message === "string" ? e.message : "";
+            const src = typeof e.source === "string" ? e.source : "";
+            const line = typeof e.line === "number" ? e.line : 0;
+            if (msg) {
+                parts.push(src && line ? `${msg} (${src}:${line})` : msg);
+            }
+        }
+        const lines = Array.isArray(result?.lines) ? result.lines : [];
+        for (const line of lines) {
+            parts.push(String(line));
+        }
+        if (parts.length > 0)
+            return parts.join("\n");
+    }
+    catch {
+        // debugger.get_log failed — fall through to editor_get_console
+    }
+    // Fallback: editor console (e.g., no game session was ever started).
+    try {
+        const result = (await bridge.call("editor.get_console", { limit: 15, level_filter: ["error"] }, 5_000));
+        const returned = result?.[PAGE_FIELD.returned];
+        if (typeof returned === "number" && returned === 0)
+            return "";
+        const entries = result?.entries;
+        if (typeof entries === "string" && entries.length > 0)
+            return entries;
+    }
+    catch {
+        // Editor might be down too — fall through to generic hint
+    }
+    return "";
+}
+/**
+ * Handle runtime errors (TIMEOUT / GAME_NOT_RUNNING) with auto-fetched
+ * crash context from editor_get_console. Exported for custom handlers
+ * (runtime_screenshot, debugger_get_log) that don't use callAndWrap.
+ */
+export async function runtimeErrorWithCrashContext(bridge, err) {
+    if (err instanceof BridgeError &&
+        (err.code === "TIMEOUT" || err.code === "GAME_NOT_RUNNING" || err.code === "COMPILATION_FAILED")) {
+        const crashContext = await fetchCrashContext(bridge);
+        if (crashContext) {
+            return toolError(err.code, err.message, "Game crashed or failed to compile. Recent errors from editor console:\n" +
+                crashContext +
+                "\nFix the script errors, then game_stop + game_start to retry. " +
+                "If errors are stale, call editor_refresh to retrigger them.");
+        }
+    }
+    return toolErrorFromException(err);
+}

package/dist/shared/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Runtime error classes. Kept out of types.ts so that module stays pure
+ * type/interface exports only.
+ */
+export class BridgeError extends Error {
+    code;
+    /**
+     * Set on a TIMEOUT that fired after the toolkit acknowledged the call with a
+     * `_queued` progress notification but before it ran (`_executing`) — i.e. the
+     * call was serialized behind other scene mutations and exhausted its window
+     * while waiting its fair-FIFO turn, not because the editor stalled. Lets the
+     * error mapper steer to a serialization-specific hint while the transport
+     * `code` stays TIMEOUT (contract-neutral).
+     */
+    serializedQueueTimeout = false;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "BridgeError";
+    }
+}

package/dist/shared/pagination.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/**
+ * Shared pieces of the self-describing pagination contract that the SERVER owns:
+ * the request-param zod fragments each paginating tool spreads into its input
+ * schema, the canonical envelope prose for tool descriptions, and the read-side
+ * field-name constants + type for the two summary handlers.
+ *
+ * REFLECT boundary — this module has NO response builder. The toolkit's
+ * `Pagination` class is the sole author of the paged response envelope; the
+ * bridge forwards `message.result` verbatim. The only server code that *reads*
+ * the paged fields is the two non-reflect summary handlers (editor console,
+ * debugger log), which read them through {@link PAGE_FIELD} — never string
+ * literals, and never by re-encoding the response.
+ *
+ * @remarks
+ * The request fragments are load-bearing: the catalogue's zod strips undeclared
+ * top-level params, so an `offset`/`limit` a paginating tool never spreads never
+ * reaches the toolkit handler. The coercion style differs per family — plain
+ * `z.number` for the index-window tools that predate coercion, `z.coerce` for
+ * the byte/line-window tools — so this module exposes one fragment per family
+ * rather than forcing a single shape.
+ */
+// ── Request-param zod fragments (spread into a tool's inputSchema) ────────────
+/**
+ * Index-window params (`offset`/`limit`) for LIST-family paginating tools
+ * (scene_query, classdb_search, classdb_get_info).
+ *
+ * @remarks
+ * `offset` floors at 0 — a negative skip is nonsensical, and a uniform floor
+ * keeps the whole surface validating the same way. Spread this into a tool's
+ * inputSchema so the catalogue zod forwards the params instead of stripping
+ * them. Per-tool defaults and caps differ; the prose stays generic here and the
+ * tool description names its own numbers.
+ */
+export const offsetLimitParams = {
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Skip the first N (default 0); pass next_offset back as offset until has_more is false."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Page size (default per tool); a request above the cap is clamped and limit_clamped is set."),
+};
+/**
+ * Byte-window params (`offset`/`max_bytes`) for the CONTENT-byte family
+ * (save_read). `offset` is a byte offset; `max_bytes` is the window size.
+ *
+ * @remarks
+ * These accept string input (`z.coerce`) because the byte-window tools have
+ * always coerced — keep that shipped behavior. `next_offset` from the prior
+ * response drives the next window.
+ */
+export const byteWindowParams = {
+    offset: z.coerce
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Byte offset to start at (default 0); pass next_offset back to page."),
+    max_bytes: z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max bytes this window (default 64 KB; cap configurable)."),
+};
+/**
+ * Line-window params (`start_line`/`end_line`, both 1-based inclusive) for the
+ * CONTENT-line family (script_read).
+ *
+ * @remarks
+ * These accept string input (`z.coerce`) to match the tool's shipped behavior.
+ * `next_start_line` from the prior response drives the next window.
+ */
+export const lineWindowParams = {
+    start_line: z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("1-based first line (default 1); pass next_start_line back as start_line to page."),
+    end_line: z.coerce.number().int().positive().optional().describe("1-based last line to read (inclusive)."),
+};
+/**
+ * Canonical envelope prose for a paginating tool's description, so every tool
+ * documents the same shape the toolkit emits instead of describing it a dozen
+ * different ways.
+ *
+ * @param unit - Names the total the count describes (e.g. "matches", "classes",
+ *   "bytes", "lines", "assets"); rendered as `total_<unit>`.
+ * @param opts - Toggles the resume-field sentence, the cursor-less nav phrase,
+ *   and the mutation caveat.
+ * @returns A sentence describing `returned`, `total_<unit>`, `has_more`, and the
+ *   tool's paging mechanism.
+ * @example
+ * ```ts
+ * paginationDoc("matches", { resumable: true, mutationCaveat: true });
+ * paginationDoc("assets", { resumable: false, cursorlessNav: "narrow filters or raise limit" });
+ * ```
+ */
+export function paginationDoc(unit, opts = {}) {
+    const { resumable = true, cursorlessNav, mutationCaveat = false } = opts;
+    let doc = `Paged: returned, total_${unit}, has_more. `;
+    if (resumable) {
+        // The line-window family resumes on next_start_line, not the byte/index
+        // families' next_offset — the prose must name the field the tool actually
+        // returns or the caller pages with the wrong key.
+        const resumeField = unit === "lines" ? "next_start_line" : "next_offset";
+        doc += `When has_more, page via ${resumeField} until has_more is false. `;
+    }
+    else {
+        doc += `Cursor-less — ${cursorlessNav ?? "narrow the query or raise limit"} for more. `;
+    }
+    if (mutationCaveat) {
+        doc += "Stable only if the source is unchanged between calls. ";
+    }
+    return doc;
+}
+// ── Read-side field names + type (for the two non-reflect handlers) ───────────
+/**
+ * The paged-response field names the two summary handlers read from
+ * `message.result`. Held in one place so a rename touches this module, not the
+ * handlers — the toolkit is the sole envelope author (REFLECT), so these mirror
+ * the toolkit field names exactly.
+ */
+export const PAGE_FIELD = {
+    returned: "returned",
+    hasMore: "has_more",
+    totalLines: "total_lines",
+};