@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/lsp/lspLabels.js

@@ -0,0 +1,105 @@
+/** Severity number → human-readable label. */
+export function severityLabel(severity) {
+    switch (severity) {
+        case 1:
+            return "Error";
+        case 2:
+            return "Warning";
+        case 3:
+            return "Information";
+        case 4:
+            return "Hint";
+        default:
+            return "Unknown";
+    }
+}
+/**
+ * Map a raw {@link DiagnosticEntry} to its tool-response shape — the single
+ * source of the diagnostic-to-JSON contract shared by the single-file and
+ * project-wide diagnostics tools. Converts the LSP's 0-based line/character to
+ * 1-based for display, labels the numeric severity, and includes `code` only
+ * when the server supplied one.
+ */
+export function formatDiagnostic(d) {
+    return {
+        line: d.line + 1,
+        character: d.character + 1,
+        severity: severityLabel(d.severity),
+        message: d.message,
+        ...(d.code != null ? { code: d.code } : {}),
+    };
+}
+export function formatSymbol(sym) {
+    const s = sym;
+    const result = {
+        name: s.name ?? "",
+        kind: symbolKindLabel(s.kind),
+        start_line: (s.range?.start?.line ?? 0) + 1,
+        end_line: (s.range?.end?.line ?? 0) + 1,
+    };
+    if (s.children && s.children.length > 0) {
+        result.children = s.children.map(formatSymbol);
+    }
+    return result;
+}
+export function symbolKindLabel(kind) {
+    const kinds = {
+        1: "File",
+        2: "Module",
+        3: "Namespace",
+        4: "Package",
+        5: "Class",
+        6: "Method",
+        7: "Property",
+        8: "Field",
+        9: "Constructor",
+        10: "Enum",
+        11: "Interface",
+        12: "Function",
+        13: "Variable",
+        14: "Constant",
+        15: "String",
+        16: "Number",
+        17: "Boolean",
+        18: "Array",
+        19: "Object",
+        20: "Key",
+        21: "Null",
+        22: "EnumMember",
+        23: "Struct",
+        24: "Event",
+        25: "Operator",
+        26: "TypeParameter",
+    };
+    return kinds[kind ?? 0] ?? "Unknown";
+}
+export function completionKindLabel(kind) {
+    const kinds = {
+        1: "Text",
+        2: "Method",
+        3: "Function",
+        4: "Constructor",
+        5: "Field",
+        6: "Variable",
+        7: "Class",
+        8: "Interface",
+        9: "Module",
+        10: "Property",
+        11: "Unit",
+        12: "Value",
+        13: "Enum",
+        14: "Keyword",
+        15: "Snippet",
+        16: "Color",
+        17: "File",
+        18: "Reference",
+        19: "Folder",
+        20: "EnumMember",
+        21: "Constant",
+        22: "Struct",
+        23: "Event",
+        24: "Operator",
+        25: "TypeParameter",
+    };
+    return kinds[kind ?? 0] ?? "Unknown";
+}

package/dist/lsp/lspProjectScan.js

@@ -0,0 +1,156 @@
+/**
+ * Project-wide GDScript enumeration + scan-result aggregation for the
+ * `lsp_project_diagnostics` tool. Two separable concerns kept apart so the
+ * shaping is unit-testable without a filesystem or a live LSP:
+ *
+ *   1. {@link enumerateGdFiles} — a `node:fs` recursive walk that lists the
+ *      `.gd` files the Godot editor would index. A disk walk (not `asset.list`)
+ *      is deliberate: the LSP subsystem is bridge-free, and a walk also sees
+ *      just-written files the EditorFileSystem has not rescanned yet.
+ *   2. {@link aggregateScan} — folds per-file classification records into the
+ *      compact response payload and asserts the scan invariant.
+ *
+ * @module
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { formatDiagnostic } from "./lspLabels.js";
+// LSP diagnostic severity 1 = Error (2 = Warning, 3 = Information, 4 = Hint).
+// The errors-only default keeps a file with only warnings classified as clean.
+const SEVERITY_ERROR = 1;
+// ── File enumeration ───────────────────────────────────────────────────
+/**
+ * List every `.gd` file under `projectRoot` that Godot's editor would index,
+ * as `res://`-relative paths. Pure I/O — no LSP, no bridge.
+ *
+ * Exclusions mirror the engine's own indexing so the scan targets exactly the
+ * files the LSP can compile:
+ * - `.gd` only — shaders (no real LSP diagnostics) and `.cs` (external
+ *   toolchain) are skipped.
+ * - Dot-directories (`.godot/`, `.git/`, `.import/`, …) — never indexed.
+ * - Any directory holding a `.gdignore` file — engine parity
+ *   (`EditorFileSystem` skips these subtrees).
+ * - The top-level `res://addons/` unless `includeAddons` is true (a nested
+ *   `foo/addons/` is not special).
+ * - Symlinked/junction directory entries — not followed (avoids cycles and
+ *   walking outside the project).
+ *
+ * @param projectRoot absolute path to the Godot project root
+ * @param opts.includeAddons also scan the top-level `res://addons/` subtree
+ * @returns deduplicated `res://`-relative paths, order-insensitive
+ */
+export async function enumerateGdFiles(projectRoot, opts) {
+    const found = new Set();
+    await walkDir(projectRoot, "", found, opts.includeAddons, true);
+    return [...found];
+}
+/**
+ * Recurse one directory, appending discovered `.gd` files to `found`.
+ * `relPrefix` is the `res://`-relative path of `dirAbs` (empty at the root).
+ * `atRoot` marks the project root so the `addons/` exclusion applies only to
+ * the top-level directory.
+ */
+async function walkDir(dirAbs, relPrefix, found, includeAddons, atRoot) {
+    let entries;
+    try {
+        entries = await readdir(dirAbs, { withFileTypes: true });
+    }
+    catch {
+        // An unreadable directory (permissions, vanished mid-walk) contributes no
+        // files — the scan continues rather than failing wholesale.
+        return;
+    }
+    // A `.gdignore` anywhere in this directory excludes the whole subtree, per
+    // EditorFileSystem — so decide before descending into any child.
+    if (entries.some((e) => e.isFile() && e.name === ".gdignore"))
+        return;
+    for (const entry of entries) {
+        const name = entry.name;
+        const rel = relPrefix ? `${relPrefix}/${name}` : name;
+        if (entry.isDirectory()) {
+            if (name.startsWith("."))
+                continue; // .godot/, .git/, .import/, …
+            if (atRoot && name === "addons" && !includeAddons)
+                continue;
+            await walkDir(join(dirAbs, name), rel, found, includeAddons, false);
+        }
+        else if (entry.isFile()) {
+            // Shaders (.gdshader/.gdshaderinc) and .cs are intentionally excluded —
+            // the LSP produces no real diagnostics for them.
+            if (name.endsWith(".gd"))
+                found.add(`res://${rel}`);
+        }
+        // Symlink/junction dirents fall through here: isDirectory()/isFile() are
+        // both false for a symlink Dirent (withFileTypes does not stat-follow), so
+        // they are skipped without a stat that would follow the link.
+    }
+}
+/**
+ * Fold per-file scan results into the compact response payload.
+ *
+ * Classification is already decided per file (the caller applied the
+ * `include_warnings` filter before building each record, so a `diagnostics`
+ * record here is non-empty and non-clean by construction). This function only
+ * counts and shapes: `clean` counts clean files, dirty files carry their
+ * mapped diagnostics, and `timed_out`/`read_failed` collect their paths.
+ *
+ * @returns the payload with empty `timed_out`/`read_failed`/`note` omitted
+ * @throws Error if the scan invariant
+ *   `scanned === clean + files_with_diagnostics.length + timed_out.length + read_failed.length`
+ *   does not hold — a programming error in the caller's bookkeeping
+ */
+export function aggregateScan(results, timeoutSeconds) {
+    const filesWithDiagnostics = [];
+    const timedOut = [];
+    const readFailed = [];
+    let clean = 0;
+    let totalDiagnostics = 0;
+    for (const r of results) {
+        switch (r.kind) {
+            case "clean":
+                clean++;
+                break;
+            case "diagnostics":
+                filesWithDiagnostics.push({ file_path: r.filePath, diagnostics: r.diagnostics.map(formatDiagnostic) });
+                totalDiagnostics += r.diagnostics.length;
+                break;
+            case "timed_out":
+                timedOut.push(r.filePath);
+                break;
+            case "read_failed":
+                readFailed.push(r.filePath);
+                break;
+        }
+    }
+    const scanned = results.length;
+    const accounted = clean + filesWithDiagnostics.length + timedOut.length + readFailed.length;
+    if (scanned !== accounted) {
+        throw new Error(`project scan invariant violated: scanned ${scanned} != accounted ${accounted}`);
+    }
+    const payload = {
+        success: true,
+        scanned,
+        clean,
+        files_with_diagnostics: filesWithDiagnostics,
+        total_diagnostics: totalDiagnostics,
+    };
+    if (timedOut.length > 0) {
+        payload.timed_out = timedOut;
+        payload.note = `${timedOut.length} file(s) produced no diagnostics notification within ${timeoutSeconds}s — status unknown, NOT clean.`;
+    }
+    if (readFailed.length > 0)
+        payload.read_failed = readFailed;
+    return payload;
+}
+/**
+ * Keep only Error-severity diagnostics when warnings are not requested.
+ * A file left with zero entries after this filter classifies as clean.
+ *
+ * @param diagnostics the raw diagnostics for one file
+ * @param includeWarnings when false, drop Warning/Info/Hint (severity > 1)
+ */
+export function filterBySeverity(diagnostics, includeWarnings) {
+    if (includeWarnings)
+        return diagnostics;
+    return diagnostics.filter((d) => d.severity === SEVERITY_ERROR);
+}

package/dist/lsp/lspSession.js

@@ -0,0 +1,139 @@
+/**
+ * LSP session layer — the stateful connection core behind the LSP tools.
+ *
+ * Owns the lazy singleton {@link LspClient}, the verified-verdict status reporter
+ * wired by the status-reporter module, the connect prologue (ensureLsp) with its
+ * code/hint mapping, and the file-read + document-open helpers the tool handlers
+ * build on. The thin LSP tool surface sits over {@link withLspDoc}.
+ *
+ * @module
+ */
+import { readFile } from "node:fs/promises";
+import { toolError } from "../shared/errorContract.js";
+import { LspClient, LspResolutionError } from "./lspClient.js";
+import { resToAbsolute, absoluteToFileUri } from "./lspUri.js";
+// ── Shared validation ──────────────────────────────────────────────
+function validateGdscriptPath(filePath) {
+    if (!filePath.startsWith("res://")) {
+        return toolError("INVALID_PATH", "file_path must start with res://");
+    }
+    if (filePath.endsWith(".gd") || filePath.endsWith(".gdshader") || filePath.endsWith(".gdshaderinc")) {
+        return undefined; // Supported.
+    }
+    // Unsupported file type — Godot's built-in LSP only serves GDScript and shaders.
+    if (filePath.endsWith(".cs")) {
+        return toolError("UNSUPPORTED_FILE_TYPE", "Godot's built-in LSP only covers GDScript (.gd) and shaders (.gdshader). " +
+            "C# (.cs) diagnostics come from the .NET language server in your IDE (VS Code, Rider).");
+    }
+    return toolError("UNSUPPORTED_FILE_TYPE", "Godot's built-in LSP only covers .gd and .gdshader/.gdshaderinc files. " +
+        "Other languages (C++, Rust, Python via GDExtension) use external toolchains with no Godot LSP integration.");
+}
+// ── Connection state ───────────────────────────────────────────────
+/** Singleton LSP client (lazy, shared across all LSP tool calls). */
+let lspClient = undefined;
+function getLspClient(projectPath) {
+    if (!lspClient)
+        lspClient = new LspClient(projectPath);
+    return lspClient;
+}
+/** Set by index.ts to push the VERIFIED LSP verdict (the actual connection
+ *  result) to the editor dock after each connection attempt — so the dock
+ *  reflects reality on actual use: it flips to active once a closed editor frees
+ *  the port and this LSP rebinds (4.5 only), or to unavailable on every other
+ *  version, which has no bind retry. */
+let statusReporter = undefined;
+/** Inject the dock status reporter (startup wiring). @internal */
+export function setLspStatusReporter(cb) {
+    statusReporter = cb;
+}
+// ── Connection prologue ────────────────────────────────────────────
+/**
+ * Build the connect-failure hint for the LSP_UNAVAILABLE branch below. Causes
+ * are ordered by likelihood given the editor is usually up — the calling agent
+ * is already using other MCP tools that need it — so the "editor not running"
+ * theory (the cause most callers can already rule out) comes LAST. The common
+ * real cause is the GDScript LSP not listening on the port we tried: the editor
+ * may have been launched with --lsp-port (which the registry can't see), so the
+ * server connected to the default and got ECONNREFUSED. Pure + exported so the
+ * ordering/contents are unit-testable without a live client.
+ * @internal
+ */
+export function lspConnectFailureHint(port) {
+    return (`Could not reach the GDScript LSP on port ${port}. Most likely the LSP is listening on a ` +
+        `different port — the editor may have been launched with --lsp-port, or its ` +
+        `network/language_server/remote_port setting differs from ${port}; set GODOT_MCP_LSP_PORT to ` +
+        `the actual LSP port to match. The LSP may also still be initializing — retry shortly. ` +
+        `Only if no other MCP tool works at all is the editor not running.`);
+}
+/** Connect prologue: return the connected singleton {@link LspClient}, or a
+ *  tool-error result carrying the LSP failure code + hint. Exported for the
+ *  project-scan handler, which drives the client directly over many files. @internal */
+export async function ensureLsp(projectPath) {
+    const client = getLspClient(projectPath);
+    try {
+        await client.ensureConnected();
+        const ep = client.getEndpoint();
+        statusReporter?.({ state: "active", host: ep.host, port: ep.port, detail: "Connected and verified." });
+        return client;
+    }
+    catch (err) {
+        // Resolution errors carry a specific code + hint (LSP_PORT_CONFLICT /
+        // LSP_UNAVAILABLE); a raw connect failure is a generic LSP_UNAVAILABLE.
+        if (err instanceof LspResolutionError) {
+            statusReporter?.({
+                state: err.code === "LSP_PORT_CONFLICT" ? "conflict" : "unavailable",
+                host: "127.0.0.1",
+                port: err.port,
+                detail: err.message,
+            });
+            return toolError(err.code, err.message, err.hint);
+        }
+        // Connect failure (e.g. ECONNREFUSED) — report the endpoint we actually tried.
+        const ep = client.getEndpoint();
+        statusReporter?.({ state: "unavailable", host: ep.host, port: ep.port, detail: err.message });
+        return toolError("LSP_UNAVAILABLE", `GDScript LSP unavailable: ${err.message}.`, lspConnectFailureHint(ep.port));
+    }
+}
+// ── Document I/O ───────────────────────────────────────────────────
+async function readFileContent(filePath, projectPath) {
+    const absPath = resToAbsolute(filePath, projectPath);
+    try {
+        return await readFile(absPath, "utf-8");
+    }
+    catch (err) {
+        return toolError("READ_FAILED", `Cannot read ${filePath}: ${err.message}`);
+    }
+}
+/** Read a `res://` file and open it in the LSP, returning its `file://` URI —
+ *  or a tool-error result if the read failed (e.g. the file vanished after the
+ *  walk). Exported for the project-scan handler's per-file open loop. @internal */
+export async function openDocInLsp(client, filePath, projectPath) {
+    const content = await readFileContent(filePath, projectPath);
+    if (typeof content !== "string")
+        return content; // Error result.
+    const absPath = resToAbsolute(filePath, projectPath);
+    const uri = absoluteToFileUri(absPath);
+    await client.openDocument(uri, content);
+    return { uri };
+}
+// ── Prologue fold ──────────────────────────────────────────────────
+/**
+ * The shared LSP-tool prologue, folded into a single call: validate the path,
+ * ensure the LSP connection, then open the document. Returns the connected
+ * client together with the opened document URI, or the first error result
+ * (checked in order: path → connect → open). Every LSP handler runs this before
+ * issuing its request.
+ */
+export async function withLspDoc(filePath, projectPath) {
+    const pathErr = validateGdscriptPath(filePath);
+    if (pathErr)
+        return pathErr;
+    const clientOrErr = await ensureLsp(projectPath);
+    if ("content" in clientOrErr)
+        return clientOrErr;
+    const client = clientOrErr;
+    const openResult = await openDocInLsp(client, filePath, projectPath);
+    if ("content" in openResult)
+        return openResult;
+    return { client, uri: openResult.uri };
+}

package/dist/lsp/lspStatusReporter.js

@@ -0,0 +1,76 @@
+/**
+ * LSP status reporter — pushes the GDScript-LSP verdict to the editor dock
+ * (editor.set_lsp_status). The editor can't read its own LSP bind status, so
+ * the server reports it.
+ *
+ * Two verdict sources share a single lastLspKey dedup so frequent LSP calls
+ * don't spam the bridge:
+ *   - Verified verdicts from actual LSP tool calls — wired via setLspStatusReporter
+ *     at construction (the real connection result, accurate across versions).
+ *   - The registry-derived verdict (reportRegistryVerdict) — no LSP handshake,
+ *     just resolution; pushed on bridge connect/reconnect so a freshly-connected
+ *     editor gets the current status, later refined by the verified result.
+ *
+ * Construction also wires the version-tailored conflict-hint getter
+ * (setGodotVersionGetter: 4.5 auto-rebind vs distinct-port everywhere else).
+ */
+import { getLspStatus, setGodotVersionGetter } from "./lspClient.js";
+import { setLspStatusReporter } from "../tools/lsp.js";
+/** Wires the verified-verdict reporter (setLspStatusReporter, de-duped via
+ *  lastLspKey) and the version-tailored conflict-hint getter (setGodotVersionGetter)
+ *  at construction, then returns the registry-verdict pusher. */
+export function createLspStatusReporter(deps) {
+    const { bridge, projectPath } = deps;
+    // Push the GDScript LSP verdict to the editor dock (editor.set_lsp_status) —
+    // the editor can't read its own LSP bind status, so the server reports it.
+    function sendLspStatus(s) {
+        try {
+            void bridge.call("editor.set_lsp_status", s, 3000).catch(() => { });
+        }
+        catch {
+            /* never let UI status reporting disrupt the bridge */
+        }
+    }
+    // Verified verdicts from actual LSP tool calls (the real connection result —
+    // accurate across versions), de-duped so frequent LSP calls don't spam the bridge.
+    let lastLspKey = "";
+    // Counts verified verdicts, NOT pushes: it is bumped before the de-dupe check, so
+    // a verdict that merely confirms the current key still registers. A registry
+    // verdict resolving later compares this to the value it captured at launch, which
+    // lastLspKey alone cannot express — a confirming verified verdict leaves the key
+    // byte-identical, and the registry verdict would then overwrite verified truth.
+    let verifiedVerdicts = 0;
+    setLspStatusReporter((s) => {
+        verifiedVerdicts++;
+        const key = `${s.state}:${s.host}:${s.port}`;
+        if (key === lastLspKey)
+            return;
+        lastLspKey = key;
+        sendLspStatus(s);
+    });
+    // Version-tailored LSP conflict hints (4.5 auto-rebind vs distinct-port everywhere else).
+    setGodotVersionGetter(() => bridge.getGodotVersion());
+    return {
+        /** On bridge connect/reconnect: push the registry verdict (resolution only, no
+         *  LSP handshake) so a freshly-connected editor gets the current status; later
+         *  LSP tool calls refine it with the verified result. */
+        reportRegistryVerdict() {
+            // Fire-and-forget: computing the verdict probes peer WS ports, so it is
+            // async, but a dock status push must never delay or fail the bridge connect
+            // that triggered it.
+            const verdictsAtLaunch = verifiedVerdicts;
+            void getLspStatus(projectPath)
+                .then((s) => {
+                // Any verified verdict that landed while the probes were in flight came
+                // from a real connection, so it outranks this one — drop ours rather than
+                // regress the dock to a registry-derived guess. A single fail-closed
+                // indeterminate probe is enough to turn this verdict into `conflict`.
+                if (verifiedVerdicts !== verdictsAtLaunch)
+                    return;
+                lastLspKey = `${s.state}:${s.host}:${s.port}`;
+                sendLspStatus(s);
+            })
+                .catch(() => { });
+        },
+    };
+}

package/dist/lsp/lspUri.js

@@ -0,0 +1,68 @@
+/**
+ * Pure URI / path translation between Godot's `res://` virtual paths and
+ * `file://` URIs (and back), plus URI normalization for diagnostics map
+ * lookups. Leaf module — zero project dependencies; shared by the LSP tool
+ * layer and the LSP client.
+ */
+import { join } from "node:path";
+/** Translate a `res://` virtual path to an absolute filesystem path under the project root. */
+export function resToAbsolute(resPath, projectPath) {
+    // res://foo/bar.gd → <projectPath>/foo/bar.gd
+    const relative = resPath.replace(/^res:\/\//, "");
+    return join(projectPath, relative);
+}
+/** Convert an absolute filesystem path to a `file://` URI (drive-letter and POSIX forms). */
+export function absoluteToFileUri(absPath) {
+    // Windows: C:\foo\bar.gd → file:///C:/foo/bar.gd
+    // Unix: /foo/bar.gd → file:///foo/bar.gd
+    const normalized = absPath.replace(/\\/g, "/");
+    if (/^[A-Za-z]:/.test(normalized)) {
+        return `file:///${normalized}`;
+    }
+    return `file://${normalized}`;
+}
+/** Map a `file://` URI back to a `res://` path when it falls inside the project; return the input unchanged otherwise. */
+export function fileUriToRes(uri, projectPath) {
+    // file:///C:/project/foo.gd → res://foo.gd  (Windows)
+    // file:///home/project/foo.gd → res://foo.gd  (POSIX)
+    if (!uri.startsWith("file://")) {
+        return uri; // Not a file URI, return as-is.
+    }
+    let absPath = uri.slice(7); // Strip "file://"; a drive form keeps a leading "/".
+    // Decode percent-encoding BEFORE the drive-letter test below. Godot's LSP
+    // emits the Windows drive colon as %3A (file:///C%3A/…); decoding first
+    // makes it a literal ":" so the `/<letter>:` drive form is recognized.
+    // Testing the still-encoded URI would miss %3A, keep the spurious leading
+    // slash, and break the project-prefix match — leaking a raw file:// URI for
+    // an in-project file.
+    absPath = decodeURIComponent(absPath);
+    // A Windows drive-letter URI (file:///C:/…) carries a leading slash that a
+    // POSIX URI (file:///home/…) MUST keep — or the project-prefix test below
+    // never matches — but the drive form must shed. Drop it only for the drive
+    // form; host-independent, so the same URI converts identically on Windows
+    // and POSIX.
+    if (/^\/[A-Za-z]:/.test(absPath)) {
+        absPath = absPath.slice(1);
+    }
+    // Normalize slashes.
+    const normalizedProject = projectPath.replace(/\\/g, "/").replace(/\/$/, "");
+    const normalizedPath = absPath.replace(/\\/g, "/");
+    // Strip project prefix to get res:// path.
+    if (normalizedPath.toLowerCase().startsWith(normalizedProject.toLowerCase())) {
+        const relative = normalizedPath.slice(normalizedProject.length);
+        return "res:/" + relative; // normalizedPath starts with / after project path
+    }
+    return uri; // Outside project — return raw.
+}
+/**
+ * Normalize a file URI for map lookups. Godot's LSP may return URIs
+ * with different drive-letter casing or percent-encoding than we send.
+ */
+export function normalizeUri(uri) {
+    let norm = decodeURIComponent(uri).replace(/\\/g, "/");
+    // Lowercase Windows drive letter: file:///C: → file:///c:
+    if (/^file:\/\/\/[A-Z]:/.test(norm)) {
+        norm = "file:///" + norm[8].toLowerCase() + norm.slice(9);
+    }
+    return norm;
+}

package/dist/mcp/prompts.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/** Register the built-in prompt templates (`debug-scene`, `write-test`) on the server. */
+export function registerPrompts(server) {
+    // ── debug-scene ──────────────────────────────────────────────────────
+    server.prompt("debug-scene", "Inspect a scene subtree and diagnose common issues", { node_path: z.string().describe("Path to the root node to inspect (e.g. '.' for scene root)") }, async ({ node_path }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Inspect the scene subtree starting at node path "${node_path}".`,
+                        "",
+                        "Steps:",
+                        "1. Call scene_get_tree with depth 4 and include_properties true.",
+                        "2. Check for common issues:",
+                        "   - Nodes without scripts that probably need one",
+                        "   - Missing collision shapes on physics bodies",
+                        "   - Sprites without textures assigned",
+                        "   - Signals that are connected but point to missing methods",
+                        "3. Call editor_get_console to see if there are compile errors.",
+                        "4. Summarize findings with suggested fixes.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // ── write-test ───────────────────────────────────────────────────────
+    server.prompt("write-test", "Generate a GDScript test for a file using GUT or GdUnit4", {
+        file_path: z.string().describe("Path to the GDScript file to test (e.g. res://player.gd)"),
+        framework: z.enum(["gut", "gdunit4"]).optional().describe("Test framework (default: gut)"),
+    }, async ({ file_path, framework }) => {
+        const fw = framework ?? "gut";
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Generate a ${fw.toUpperCase()} test file for "${file_path}".`,
+                            "",
+                            "Steps:",
+                            `1. Read the source file with script_read.`,
+                            "2. Identify public functions, signals, and exported properties.",
+                            `3. Write a test file following ${fw.toUpperCase()} conventions:`,
+                            fw === "gut"
+                                ? "   - Extend GutTest, prefix test functions with test_"
+                                : "   - Extend GdUnitTestSuite, use assert_that() matchers",
+                            "4. Cover at least: initialization, each public method, edge cases.",
+                            `5. Save the test file next to the source with a _test suffix.`,
+                            "6. Run editor_get_console to verify no syntax issues.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        };
+    });
+}