@arhend/godot-mcp 1.0.0

package/README.md

@@ -0,0 +1,40 @@
+# godot-mcp
+
+> https://github.com/Arhend/godot-mcp
+
+I wanted a simple MCP server for Godot 4 to help with development — mainly searching the class reference docs and reading project files without having to manually paste things into the chat.
+
+## What it does
+
+**Docs & API lookup** — pulls from the Godot engine's XML class reference on GitHub and caches it locally:
+
+- `search_godot_class` — look up any class (Node, CharacterBody2D, etc.) and get its methods, properties, and signals
+- `get_class_method` — full details on a specific method
+- `get_class_property` — full details on a specific property
+- `list_godot_classes` — browse all ~570 classes, filter by name prefix or parent class
+- `search_godot_docs` — free-text search across all class descriptions, method names, and more
+
+**Project file analysis** — reads your local Godot project files directly:
+
+- `read_scene` — parses a `.tscn` file into a node tree
+- `read_resource` — parses a `.tres` resource file
+- `read_script` — reads a `.gd` script
+- `get_project_info` — reads `project.godot` for name, main scene, autoloads
+- `find_project_files` — find files by extension in your project directory
+
+## Setup
+
+```bash
+git clone https://github.com/Arhend/godot-mcp
+cd godot-mcp
+npm install
+npm run build
+```
+
+Add to Claude Code as an MCP server:
+
+```bash
+claude mcp add godot -- npx github:Arhend/godot-mcp
+```
+
+The first time you use a docs tool, it fetches and caches the Godot class reference from GitHub (~30 seconds). After that it loads from the local cache in `cache/` and is instant. The cache refreshes automatically after 7 days.

package/dist/cache/docs-cache.d.ts

@@ -0,0 +1,2 @@
+export declare function readCache<T>(key: string): Promise<T | null>;
+export declare function writeCache<T>(key: string, data: T): Promise<void>;

package/dist/cache/docs-cache.js

@@ -0,0 +1,24 @@
+import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CACHE_DIR = join(__dirname, "../../cache");
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export async function readCache(key) {
+    const filePath = join(CACHE_DIR, `${key}.json`);
+    try {
+        const s = await stat(filePath);
+        if (Date.now() - s.mtimeMs > CACHE_TTL_MS)
+            return null;
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCache(key, data) {
+    await mkdir(CACHE_DIR, { recursive: true });
+    const filePath = join(CACHE_DIR, `${key}.json`);
+    await writeFile(filePath, JSON.stringify(data), "utf-8");
+}

package/dist/godot/class-reference.d.ts

@@ -0,0 +1,47 @@
+export interface GodotParam {
+    index: number;
+    name: string;
+    type: string;
+    default?: string;
+}
+export interface GodotMethod {
+    name: string;
+    returnType: string;
+    qualifiers?: string;
+    params: GodotParam[];
+    description: string;
+}
+export interface GodotProperty {
+    name: string;
+    type: string;
+    default?: string;
+    description: string;
+    setter?: string;
+    getter?: string;
+    enum?: string;
+}
+export interface GodotSignal {
+    name: string;
+    params: GodotParam[];
+    description: string;
+}
+export interface GodotConstant {
+    name: string;
+    value: string;
+    description: string;
+    enum?: string;
+}
+export interface GodotClass {
+    name: string;
+    inherits?: string;
+    briefDescription: string;
+    description: string;
+    methods: GodotMethod[];
+    properties: GodotProperty[];
+    signals: GodotSignal[];
+    constants: GodotConstant[];
+}
+type ClassIndex = Record<string, GodotClass>;
+export declare function getClassIndex(): Promise<ClassIndex>;
+export declare function getClass(name: string): Promise<GodotClass | null>;
+export {};

package/dist/godot/class-reference.js

@@ -0,0 +1,140 @@
+import { XMLParser } from "fast-xml-parser";
+import { readCache, writeCache } from "../cache/docs-cache.js";
+const GODOT_BRANCH = "master";
+const CLASSES_API_URL = `https://api.github.com/repos/godotengine/godot/contents/doc/classes?ref=${GODOT_BRANCH}`;
+const RAW_BASE = `https://raw.githubusercontent.com/godotengine/godot/${GODOT_BRANCH}/doc/classes/`;
+const CACHE_KEY = "godot-classes";
+const BATCH_SIZE = 20;
+let _index = null;
+function stripBBCode(text) {
+    if (!text)
+        return "";
+    return text
+        .replace(/\[(?:b|i|u|s|code|codeblock|kbd|center|url)[^\]]*\]/g, "")
+        .replace(/\[\/(?:b|i|u|s|code|codeblock|kbd|center|url)\]/g, "")
+        .replace(/\[(?:method|member|signal|constant|enum|param|constructor|operator|theme_item) ([^\]]+)\]/g, "$1")
+        .replace(/\[([A-Z][A-Za-z0-9_]*)\]/g, "$1")
+        .replace(/\$DOCS_URL/g, "https://docs.godotengine.org/en/stable")
+        .trim();
+}
+function toArray(val) {
+    if (!val)
+        return [];
+    return Array.isArray(val) ? val : [val];
+}
+function parseParam(p) {
+    return {
+        index: Number(p["@_index"] ?? 0),
+        name: String(p["@_name"] ?? ""),
+        type: String(p["@_type"] ?? "Variant"),
+        ...(p["@_default"] !== undefined ? { default: String(p["@_default"]) } : {}),
+    };
+}
+function parseMethod(m) {
+    const ret = m["return"];
+    return {
+        name: String(m["@_name"] ?? ""),
+        returnType: ret ? String(ret["@_type"] ?? "void") : "void",
+        ...(m["@_qualifiers"] ? { qualifiers: String(m["@_qualifiers"]) } : {}),
+        params: toArray(m["param"]).map(parseParam),
+        description: stripBBCode(String(m["description"] ?? "")),
+    };
+}
+function parseProperty(p) {
+    return {
+        name: String(p["@_name"] ?? ""),
+        type: String(p["@_type"] ?? "Variant"),
+        ...(p["@_default"] !== undefined ? { default: String(p["@_default"]) } : {}),
+        ...(p["@_setter"] ? { setter: String(p["@_setter"]) } : {}),
+        ...(p["@_getter"] ? { getter: String(p["@_getter"]) } : {}),
+        ...(p["@_enum"] ? { enum: String(p["@_enum"]) } : {}),
+        description: stripBBCode(String(p["#text"] ?? "")),
+    };
+}
+function parseSignal(s) {
+    return {
+        name: String(s["@_name"] ?? ""),
+        params: toArray(s["param"]).map(parseParam),
+        description: stripBBCode(String(s["description"] ?? "")),
+    };
+}
+function parseConstant(c) {
+    return {
+        name: String(c["@_name"] ?? ""),
+        value: String(c["@_value"] ?? ""),
+        ...(c["@_enum"] ? { enum: String(c["@_enum"]) } : {}),
+        description: stripBBCode(String(c["#text"] ?? "")),
+    };
+}
+function parseClassXml(xml) {
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_", textNodeName: "#text" });
+    try {
+        const doc = parser.parse(xml);
+        const cls = doc["class"];
+        if (!cls)
+            return null;
+        const methods = cls["methods"];
+        const members = cls["members"];
+        const signals = cls["signals"];
+        const constants = cls["constants"];
+        return {
+            name: String(cls["@_name"] ?? ""),
+            ...(cls["@_inherits"] ? { inherits: String(cls["@_inherits"]) } : {}),
+            briefDescription: stripBBCode(String(cls["brief_description"] ?? "")),
+            description: stripBBCode(String(cls["description"] ?? "")),
+            methods: toArray(methods?.["method"]).map(parseMethod),
+            properties: toArray(members?.["member"]).map(parseProperty),
+            signals: toArray(signals?.["signal"]).map(parseSignal),
+            constants: toArray(constants?.["constant"]).map(parseConstant),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchAllClasses() {
+    process.stderr.write("Fetching Godot class list from GitHub...\n");
+    const listRes = await fetch(CLASSES_API_URL, {
+        headers: { "User-Agent": "godot-mcp", "Accept": "application/vnd.github+json" },
+    });
+    if (!listRes.ok)
+        throw new Error(`GitHub API error: ${listRes.status} ${listRes.statusText}`);
+    const files = (await listRes.json());
+    const xmlFiles = files.filter((f) => f.name.endsWith(".xml"));
+    process.stderr.write(`Downloading ${xmlFiles.length} class files...\n`);
+    const index = {};
+    for (let i = 0; i < xmlFiles.length; i += BATCH_SIZE) {
+        const batch = xmlFiles.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(batch.map(async (f) => {
+            const res = await fetch(RAW_BASE + encodeURIComponent(f.name));
+            if (!res.ok)
+                return null;
+            return { name: f.name.replace(".xml", ""), xml: await res.text() };
+        }));
+        for (const r of results) {
+            if (!r)
+                continue;
+            const cls = parseClassXml(r.xml);
+            if (cls)
+                index[cls.name] = cls;
+        }
+        process.stderr.write(`  ${Math.min(i + BATCH_SIZE, xmlFiles.length)}/${xmlFiles.length}\n`);
+    }
+    return index;
+}
+export async function getClassIndex() {
+    if (_index)
+        return _index;
+    const cached = await readCache(CACHE_KEY);
+    if (cached) {
+        _index = cached;
+        return _index;
+    }
+    _index = await fetchAllClasses();
+    await writeCache(CACHE_KEY, _index);
+    return _index;
+}
+export async function getClass(name) {
+    const index = await getClassIndex();
+    return index[name] ?? index[name.toLowerCase()] ?? null;
+}

package/dist/godot/scene-parser.d.ts

@@ -0,0 +1,26 @@
+export interface SceneNode {
+    name: string;
+    type?: string;
+    instance?: string;
+    parent?: string;
+    script?: string;
+    properties: Record<string, string>;
+    children: SceneNode[];
+}
+export interface ParsedScene {
+    format: number;
+    uid?: string;
+    externalResources: Array<{
+        id: string;
+        type: string;
+        path: string;
+    }>;
+    nodes: SceneNode[];
+    rootNode?: SceneNode;
+}
+export interface ParsedResource {
+    type?: string;
+    properties: Record<string, string>;
+}
+export declare function parseScene(content: string): ParsedScene;
+export declare function parseResource(content: string): ParsedResource;

package/dist/godot/scene-parser.js

@@ -0,0 +1,135 @@
+// Parse a single header line like: [node name="Foo" type="Bar" parent="."]
+function parseHeader(line) {
+    const attrs = {};
+    // Extract section type
+    const typeMatch = line.match(/^\[(\w+)/);
+    if (typeMatch)
+        attrs["__section__"] = typeMatch[1];
+    // Extract key="value" or key=value pairs
+    const re = /(\w+)=(?:"([^"]*?)"|([^\s\]]+))/g;
+    let m;
+    while ((m = re.exec(line)) !== null) {
+        attrs[m[1]] = m[2] !== undefined ? m[2] : m[3];
+    }
+    return attrs;
+}
+// Parse key=value property lines below a section header
+function parseProperty(line) {
+    const idx = line.indexOf(" = ");
+    if (idx === -1)
+        return null;
+    return [line.slice(0, idx).trim(), line.slice(idx + 3).trim()];
+}
+function buildTree(nodes) {
+    const byPath = {};
+    let root;
+    for (const node of nodes) {
+        const path = node.parent === undefined
+            ? "."
+            : node.parent === "."
+                ? node.name
+                : `${node.parent}/${node.name}`;
+        byPath[path] = node;
+        if (node.parent === undefined)
+            root = node;
+    }
+    for (const node of nodes) {
+        if (node.parent === undefined)
+            continue;
+        const parentPath = node.parent === "." ? "." : node.parent;
+        const parent = byPath[parentPath];
+        if (parent)
+            parent.children.push(node);
+    }
+    return root;
+}
+export function parseScene(content) {
+    const lines = content.split("\n");
+    const result = {
+        format: 0,
+        externalResources: [],
+        nodes: [],
+    };
+    let currentSection = null;
+    let currentNodeIndex = -1;
+    let currentProps = {};
+    const flushSection = () => {
+        if (!currentSection)
+            return;
+        const section = currentSection["__section__"];
+        if (section === "ext_resource") {
+            result.externalResources.push({
+                id: currentSection["id"] ?? "",
+                type: currentSection["type"] ?? "",
+                path: currentSection["path"] ?? "",
+            });
+        }
+        else if (section === "node") {
+            const node = {
+                name: currentSection["name"] ?? "",
+                ...(currentSection["type"] ? { type: currentSection["type"] } : {}),
+                ...(currentSection["instance"] ? { instance: currentSection["instance"] } : {}),
+                ...(currentSection["parent"] !== undefined ? { parent: currentSection["parent"] } : {}),
+                properties: { ...currentProps },
+                children: [],
+            };
+            // Extract script from properties if present
+            const scriptProp = currentProps["script"];
+            if (scriptProp) {
+                const extRes = result.externalResources.find((r) => scriptProp.includes(`"${r.id}"`) || scriptProp.includes(`(${r.id})`));
+                if (extRes)
+                    node.script = extRes.path;
+            }
+            result.nodes.push(node);
+            currentNodeIndex = result.nodes.length - 1;
+        }
+        currentProps = {};
+    };
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(";"))
+            continue;
+        if (line.startsWith("[")) {
+            flushSection();
+            currentSection = parseHeader(line);
+            if (currentSection["__section__"] === "gd_scene" || currentSection["__section__"] === "gd_resource") {
+                result.format = Number(currentSection["format"] ?? 0);
+                result.uid = currentSection["uid"];
+            }
+        }
+        else if (currentSection) {
+            const prop = parseProperty(line);
+            if (prop) {
+                currentProps[prop[0]] = prop[1];
+            }
+            else if (currentProps && Object.keys(currentProps).length > 0) {
+                // Multi-line value continuation — append to last key
+                const lastKey = Object.keys(currentProps).at(-1);
+                if (lastKey)
+                    currentProps[lastKey] += "\n" + line;
+            }
+        }
+    }
+    flushSection();
+    result.rootNode = buildTree(result.nodes);
+    return result;
+}
+export function parseResource(content) {
+    const lines = content.split("\n");
+    const result = { properties: {} };
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(";"))
+            continue;
+        if (line.startsWith("[gd_resource")) {
+            const header = parseHeader(line);
+            result.type = header["type"];
+        }
+        else if (!line.startsWith("[")) {
+            const prop = parseProperty(line);
+            if (prop)
+                result.properties[prop[0]] = prop[1];
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerDocsTools } from "./tools/docs.js";
+import { registerProjectTools } from "./tools/project.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "godot-mcp",
+        version: "1.0.0",
+    });
+    registerDocsTools(server);
+    registerProjectTools(server);
+    return server;
+}

package/dist/tools/docs.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDocsTools(server: McpServer): void;

package/dist/tools/docs.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import { getClass, getClassIndex } from "../godot/class-reference.js";
+function formatMethod(m) {
+    const params = m.params
+        .sort((a, b) => a.index - b.index)
+        .map((p) => `${p.type} ${p.name}${p.default !== undefined ? ` = ${p.default}` : ""}`)
+        .join(", ");
+    const qualifiers = m.qualifiers ? ` ${m.qualifiers}` : "";
+    return `${m.returnType} ${m.name}(${params})${qualifiers}`;
+}
+function formatProperty(p) {
+    const def = p.default !== undefined ? ` [default: ${p.default}]` : "";
+    const enumVal = p.enum ? ` [enum: ${p.enum}]` : "";
+    return `${p.type} ${p.name}${def}${enumVal}`;
+}
+function classSummary(cls) {
+    const lines = [];
+    lines.push(`# ${cls.name}${cls.inherits ? ` (inherits ${cls.inherits})` : ""}`);
+    lines.push("");
+    lines.push(cls.briefDescription || cls.description.slice(0, 200));
+    if (cls.methods.length > 0) {
+        lines.push("\n## Methods");
+        for (const m of cls.methods)
+            lines.push(`- ${formatMethod(m)}`);
+    }
+    if (cls.properties.length > 0) {
+        lines.push("\n## Properties");
+        for (const p of cls.properties)
+            lines.push(`- ${formatProperty(p)}`);
+    }
+    if (cls.signals.length > 0) {
+        lines.push("\n## Signals");
+        for (const s of cls.signals) {
+            const params = s.params.map((p) => `${p.type} ${p.name}`).join(", ");
+            lines.push(`- ${s.name}(${params})`);
+        }
+    }
+    return lines.join("\n");
+}
+export function registerDocsTools(server) {
+    server.registerTool("search_godot_class", {
+        description: "Look up a Godot 4 class by name. Returns its description, inheritance chain, methods, properties, and signals.",
+        inputSchema: {
+            name: z.string().describe("Exact class name, e.g. Node, CharacterBody2D, Sprite2D"),
+        },
+    }, async ({ name }) => {
+        const cls = await getClass(name);
+        if (!cls) {
+            return { content: [{ type: "text", text: `Class "${name}" not found. Use list_godot_classes to browse available classes.` }], isError: true };
+        }
+        return { content: [{ type: "text", text: classSummary(cls) }] };
+    });
+    server.registerTool("get_class_method", {
+        description: "Get full details on a specific method of a Godot class: parameters, return type, and description.",
+        inputSchema: {
+            className: z.string().describe("Class name, e.g. Node"),
+            methodName: z.string().describe("Method name, e.g. add_child"),
+        },
+    }, async ({ className, methodName }) => {
+        const cls = await getClass(className);
+        if (!cls)
+            return { content: [{ type: "text", text: `Class "${className}" not found.` }], isError: true };
+        const method = cls.methods.find((m) => m.name === methodName);
+        if (!method) {
+            const similar = cls.methods.filter((m) => m.name.includes(methodName.toLowerCase())).map((m) => m.name);
+            const hint = similar.length > 0 ? `\nSimilar methods: ${similar.join(", ")}` : "";
+            return { content: [{ type: "text", text: `Method "${methodName}" not found on ${className}.${hint}` }], isError: true };
+        }
+        const lines = [
+            `## ${className}.${method.name}`,
+            `\`\`\``,
+            formatMethod(method),
+            `\`\`\``,
+            "",
+            method.description || "(no description)",
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("get_class_property", {
+        description: "Get full details on a specific property of a Godot class: type, default value, and description.",
+        inputSchema: {
+            className: z.string().describe("Class name, e.g. Node"),
+            propertyName: z.string().describe("Property name, e.g. process_mode"),
+        },
+    }, async ({ className, propertyName }) => {
+        const cls = await getClass(className);
+        if (!cls)
+            return { content: [{ type: "text", text: `Class "${className}" not found.` }], isError: true };
+        const prop = cls.properties.find((p) => p.name === propertyName);
+        if (!prop) {
+            const similar = cls.properties.filter((p) => p.name.includes(propertyName.toLowerCase())).map((p) => p.name);
+            const hint = similar.length > 0 ? `\nSimilar properties: ${similar.join(", ")}` : "";
+            return { content: [{ type: "text", text: `Property "${propertyName}" not found on ${className}.${hint}` }], isError: true };
+        }
+        const lines = [
+            `## ${className}.${prop.name}`,
+            `Type: ${prop.type}`,
+        ];
+        if (prop.default !== undefined)
+            lines.push(`Default: ${prop.default}`);
+        if (prop.enum)
+            lines.push(`Enum: ${prop.enum}`);
+        if (prop.setter || prop.getter)
+            lines.push(`Setter: ${prop.setter ?? "n/a"} | Getter: ${prop.getter ?? "n/a"}`);
+        lines.push("", prop.description || "(no description)");
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("list_godot_classes", {
+        description: "List all available Godot 4 classes, optionally filtered by name prefix or parent class.",
+        inputSchema: {
+            prefix: z.string().optional().describe("Filter classes whose name starts with this string (case-insensitive)"),
+            inherits: z.string().optional().describe("Filter classes that directly inherit from this class"),
+        },
+    }, async ({ prefix, inherits }) => {
+        const index = await getClassIndex();
+        let classes = Object.values(index);
+        if (prefix) {
+            const lc = prefix.toLowerCase();
+            classes = classes.filter((c) => c.name.toLowerCase().startsWith(lc));
+        }
+        if (inherits) {
+            classes = classes.filter((c) => c.inherits === inherits);
+        }
+        classes.sort((a, b) => a.name.localeCompare(b.name));
+        const lines = classes.map((c) => `${c.name}${c.inherits ? ` (extends ${c.inherits})` : ""}: ${c.briefDescription}`);
+        return {
+            content: [{ type: "text", text: `Found ${classes.length} classes:\n\n${lines.join("\n")}` }],
+        };
+    });
+    server.registerTool("search_godot_docs", {
+        description: "Full-text search across Godot 4 class names, method names, property names, and descriptions. Use this to find relevant classes/methods when you don't know the exact name.",
+        inputSchema: {
+            query: z.string().describe("Search terms, e.g. 'physics body collision' or 'play animation'"),
+            limit: z.number().optional().describe("Max results to return (default 20)"),
+        },
+    }, async ({ query, limit = 20 }) => {
+        const index = await getClassIndex();
+        const terms = query.toLowerCase().split(/\s+/);
+        const hits = [];
+        for (const cls of Object.values(index)) {
+            const clsText = `${cls.name} ${cls.briefDescription} ${cls.description}`.toLowerCase();
+            const clsScore = terms.filter((t) => clsText.includes(t)).length;
+            if (clsScore > 0) {
+                hits.push({ score: clsScore * 2, text: `[Class] ${cls.name}: ${cls.briefDescription}` });
+            }
+            for (const m of cls.methods) {
+                const mText = `${m.name} ${m.description}`.toLowerCase();
+                const mScore = terms.filter((t) => mText.includes(t)).length;
+                if (mScore > 0) {
+                    hits.push({ score: mScore, text: `[Method] ${cls.name}.${m.name}() — ${m.description.slice(0, 120)}` });
+                }
+            }
+            for (const p of cls.properties) {
+                const pText = `${p.name} ${p.description}`.toLowerCase();
+                const pScore = terms.filter((t) => pText.includes(t)).length;
+                if (pScore > 0) {
+                    hits.push({ score: pScore, text: `[Property] ${cls.name}.${p.name}: ${p.type} — ${p.description.slice(0, 100)}` });
+                }
+            }
+            for (const s of cls.signals) {
+                const sText = `${s.name} ${s.description}`.toLowerCase();
+                const sScore = terms.filter((t) => sText.includes(t)).length;
+                if (sScore > 0) {
+                    hits.push({ score: sScore, text: `[Signal] ${cls.name}.${s.name} — ${s.description.slice(0, 100)}` });
+                }
+            }
+        }
+        hits.sort((a, b) => b.score - a.score);
+        const top = hits.slice(0, limit);
+        if (top.length === 0) {
+            return { content: [{ type: "text", text: `No results found for "${query}".` }] };
+        }
+        return {
+            content: [{ type: "text", text: `Top ${top.length} results for "${query}":\n\n${top.map((h) => h.text).join("\n")}` }],
+        };
+    });
+}

package/dist/tools/project.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProjectTools(server: McpServer): void;

package/dist/tools/project.js

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { join, resolve, relative, extname } from "path";
+import { readdir } from "fs/promises";
+import { parseScene, parseResource } from "../godot/scene-parser.js";
+function safeResolvePath(projectRoot, filePath) {
+    // If absolute path given, use it; otherwise join with project root
+    const resolved = filePath.startsWith("/") || /^[A-Za-z]:/.test(filePath)
+        ? resolve(filePath)
+        : resolve(join(projectRoot, filePath));
+    return resolved;
+}
+// Convert res:// paths to absolute using project root
+function resolveResPath(resPath, projectRoot) {
+    if (resPath.startsWith("res://"))
+        return join(projectRoot, resPath.slice(6));
+    return resPath;
+}
+async function walkDir(dir, exts, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const sub = await walkDir(fullPath, exts, maxDepth, depth + 1);
+            results.push(...sub);
+        }
+        else if (exts.length === 0 || exts.includes(extname(entry.name))) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+function renderNodeTree(node, indent = 0) {
+    if (!node)
+        return "";
+    const lines = [];
+    const pad = "  ".repeat(indent);
+    const typeStr = node.type ? ` [${node.type}]` : node.instance ? ` [instance: ${node.instance}]` : "";
+    const scriptStr = node.script ? ` (script: ${node.script})` : "";
+    lines.push(`${pad}${node.name}${typeStr}${scriptStr}`);
+    for (const child of node.children) {
+        lines.push(renderNodeTree(child, indent + 1));
+    }
+    return lines.join("\n");
+}
+export function registerProjectTools(server) {
+    server.registerTool("read_scene", {
+        description: "Parse a Godot .tscn scene file and return its node tree with types, script assignments, and external resource references. Pass an absolute path or a res:// path with the project root.",
+        inputSchema: {
+            path: z.string().describe("Absolute file path or res:// path to the .tscn file"),
+            projectRoot: z.string().optional().describe("Absolute path to the Godot project root (required for res:// paths)"),
+        },
+    }, async ({ path, projectRoot }) => {
+        const absPath = path.startsWith("res://") && projectRoot
+            ? resolveResPath(path, projectRoot)
+            : safeResolvePath(projectRoot ?? ".", path);
+        let content;
+        try {
+            content = await readFile(absPath, "utf-8");
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read file: ${absPath}\n${e.message}` }], isError: true };
+        }
+        const scene = parseScene(content);
+        const lines = [
+            `# Scene: ${absPath}`,
+            `Format: ${scene.format}${scene.uid ? ` | UID: ${scene.uid}` : ""}`,
+            `Nodes: ${scene.nodes.length} | External resources: ${scene.externalResources.length}`,
+        ];
+        if (scene.externalResources.length > 0) {
+            lines.push("\n## External Resources");
+            for (const r of scene.externalResources) {
+                lines.push(`  [${r.id}] ${r.type}: ${r.path}`);
+            }
+        }
+        lines.push("\n## Node Tree");
+        lines.push(renderNodeTree(scene.rootNode));
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("read_resource", {
+        description: "Parse a Godot .tres resource file and return its type and key/value properties.",
+        inputSchema: {
+            path: z.string().describe("Absolute file path or res:// path to the .tres file"),
+            projectRoot: z.string().optional().describe("Absolute path to the Godot project root (required for res:// paths)"),
+        },
+    }, async ({ path, projectRoot }) => {
+        const absPath = path.startsWith("res://") && projectRoot
+            ? resolveResPath(path, projectRoot)
+            : safeResolvePath(projectRoot ?? ".", path);
+        let content;
+        try {
+            content = await readFile(absPath, "utf-8");
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read file: ${absPath}\n${e.message}` }], isError: true };
+        }
+        const res = parseResource(content);
+        const lines = [
+            `# Resource: ${absPath}`,
+            `Type: ${res.type ?? "unknown"}`,
+            "\n## Properties",
+            ...Object.entries(res.properties).map(([k, v]) => `  ${k} = ${v}`),
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("read_script", {
+        description: "Read a GDScript (.gd) file and return its source code.",
+        inputSchema: {
+            path: z.string().describe("Absolute file path or res:// path to the .gd script"),
+            projectRoot: z.string().optional().describe("Absolute path to the Godot project root (required for res:// paths)"),
+        },
+    }, async ({ path, projectRoot }) => {
+        const absPath = path.startsWith("res://") && projectRoot
+            ? resolveResPath(path, projectRoot)
+            : safeResolvePath(projectRoot ?? ".", path);
+        let content;
+        try {
+            content = await readFile(absPath, "utf-8");
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read file: ${absPath}\n${e.message}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: `# ${absPath}\n\n\`\`\`gdscript\n${content}\n\`\`\`` }] };
+    });
+    server.registerTool("get_project_info", {
+        description: "Read a Godot project.godot file and return the project display name, main scene, autoloads, and key settings.",
+        inputSchema: {
+            projectRoot: z.string().describe("Absolute path to the Godot project root directory"),
+        },
+    }, async ({ projectRoot }) => {
+        const configPath = join(resolve(projectRoot), "project.godot");
+        let content;
+        try {
+            content = await readFile(configPath, "utf-8");
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read project.godot at: ${configPath}\n${e.message}` }], isError: true };
+        }
+        // Parse INI-style project.godot
+        const sections = {};
+        let currentSection = "global";
+        sections[currentSection] = {};
+        for (const rawLine of content.split("\n")) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith(";"))
+                continue;
+            if (line.startsWith("[") && line.endsWith("]")) {
+                currentSection = line.slice(1, -1);
+                sections[currentSection] = {};
+            }
+            else {
+                const eqIdx = line.indexOf("=");
+                if (eqIdx !== -1) {
+                    const key = line.slice(0, eqIdx).trim();
+                    const val = line.slice(eqIdx + 1).trim();
+                    sections[currentSection][key] = val;
+                }
+            }
+        }
+        const appSection = sections["application"] ?? {};
+        const autoloads = sections["autoload"] ?? {};
+        const rendering = sections["rendering/renderer"] ?? {};
+        const lines = [
+            `# Project: ${appSection["config/name"]?.replace(/"/g, "") ?? "(unknown)"}`,
+            `Godot version required: ${(sections[""] ?? sections["global"])?.["config_version"] ?? "unknown"}`,
+        ];
+        if (appSection["run/main_scene"])
+            lines.push(`Main scene: ${appSection["run/main_scene"].replace(/"/g, "")}`);
+        if (appSection["config/description"])
+            lines.push(`Description: ${appSection["config/description"].replace(/"/g, "")}`);
+        if (Object.keys(autoloads).length > 0) {
+            lines.push("\n## Autoloads");
+            for (const [name, path] of Object.entries(autoloads)) {
+                lines.push(`  ${name}: ${path.replace(/"/g, "")}`);
+            }
+        }
+        const features = sections["editor_plugins"] ?? {};
+        if (Object.keys(features).length > 0) {
+            lines.push("\n## Editor Plugins");
+            for (const [k, v] of Object.entries(features))
+                lines.push(`  ${k}: ${v}`);
+        }
+        lines.push("\n## All Sections");
+        for (const [sec, props] of Object.entries(sections)) {
+            if (Object.keys(props).length === 0)
+                continue;
+            lines.push(`  [${sec}] — ${Object.keys(props).length} key(s)`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("find_project_files", {
+        description: "Find files in a Godot project directory matching given extensions. Useful for discovering scenes, scripts, and resources.",
+        inputSchema: {
+            projectRoot: z.string().describe("Absolute path to the Godot project root directory"),
+            extensions: z
+                .array(z.string())
+                .optional()
+                .describe("File extensions to find, e.g. [\".gd\", \".tscn\"]. Omit to list all files."),
+            maxDepth: z.number().optional().describe("Max directory depth to search (default 6)"),
+        },
+    }, async ({ projectRoot, extensions, maxDepth = 6 }) => {
+        const root = resolve(projectRoot);
+        let exts = extensions ?? [];
+        if (exts.length > 0) {
+            exts = exts.map((e) => (e.startsWith(".") ? e : `.${e}`));
+        }
+        let files;
+        try {
+            files = await walkDir(root, exts, maxDepth);
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Could not read directory: ${root}\n${e.message}` }], isError: true };
+        }
+        const relFiles = files.map((f) => relative(root, f));
+        const extSuffix = exts.length > 0 ? ` (${exts.join(", ")})` : "";
+        return {
+            content: [{ type: "text", text: `Found ${relFiles.length} files${extSuffix} in ${root}:\n\n${relFiles.join("\n")}` }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@arhend/godot-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Godot 4 — docs lookup and project file analysis",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "godot-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/build.js",
+    "prepare": "npm run build",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "godot", "gamedev"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-xml-parser": "^5.8.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}