dwarffortress-mcp 1.0.0

package/README.md

@@ -0,0 +1,26 @@
+# Dwarffortress
+
+Use this MCP server to the Dwarf Fortress wiki, !!FUN!! knowledge about the most complex game ever made.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_pages`: Search the Dwarf Fortress wiki.
+- `get_page`: Read a DF wiki page as plain text.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required unless the project explicitly says otherwise.
+
+## Try it
+
+After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `search_pages`.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare class DfError extends Error {
+}
+export interface WikiPage {
+    pageid: number;
+    title: string;
+    snippet?: string;
+}
+export declare function searchPages(query: string, limit?: number): Promise<WikiPage[]>;
+export declare function getPage(title: string, maxChars?: number): Promise<{
+    title: string;
+    wikitext: string;
+    url: string;
+} | null>;
+export declare function wikiTextToPlain(wt: string, maxChars?: number): string;

package/dist/api.js

@@ -0,0 +1,61 @@
+/**
+ * Dwarf Fortress wiki client (dwarffortresswiki.org). MediaWiki API,
+ * keyless. Contains the lore, !!FUN!!, adamantine, and magma knowledge.
+ */
+const BASE = "https://dwarffortresswiki.org/api.php";
+export class DfError extends Error {
+}
+async function getJson(params) {
+    const qs = new URLSearchParams({ format: "json", ...params });
+    const res = await fetch(`${BASE}?${qs.toString()}`, {
+        headers: { "User-Agent": "dwarffortress-mcp/1.0 (research)" },
+    });
+    if (!res.ok)
+        throw new DfError(`DF wiki error ${res.status}`);
+    return (await res.json());
+}
+export async function searchPages(query, limit = 8) {
+    const d = await getJson({
+        action: "query",
+        list: "search",
+        srsearch: query,
+        srlimit: String(limit),
+        srprop: "snippet",
+    });
+    return (d.query?.search ?? []).map((s) => ({
+        pageid: s.pageid,
+        title: s.title,
+        snippet: (s.snippet ?? "").replace(/<[^>]+>/g, ""),
+    }));
+}
+export async function getPage(title, maxChars = 15000) {
+    const d = await getJson({
+        action: "parse",
+        page: title,
+        prop: "wikitext",
+        formatversion: "2",
+    });
+    const p = d.parse;
+    if (!p)
+        return null;
+    const wt = typeof p.wikitext === "string" ? p.wikitext : (p.wikitext?.["*"] ?? "");
+    return {
+        title: p.title ?? title,
+        wikitext: wt.slice(0, maxChars),
+        url: `https://dwarffortresswiki.org/index.php/${encodeURIComponent(p.title ?? title).replace(/%2F/g, "/")}`,
+    };
+}
+export function wikiTextToPlain(wt, maxChars = 12000) {
+    return wt
+        .replace(/\{\{[^{}]*\}\}/g, "")
+        .replace(/<ref[^>]*>[\s\S]*?<\/ref>/gi, "")
+        .replace(/<[^>]+>/g, "")
+        .replace(/\[\[(?:[^|\]]*\|)?([^\]]*)\]\]/g, "$1")
+        .replace(/'''/g, "")
+        .replace(/''/g, "")
+        .replace(/\{\|[\s\S]*?\|\}/g, "[table]")
+        .replace(/={2,}([^=]+)={2,}/g, "\n$1\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .slice(0, maxChars);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

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,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DfError, getPage, searchPages, wikiTextToPlain } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "dwarffortress-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_pages", {
+        title: "Search pages",
+        description: "Search the Dwarf Fortress wiki.",
+        inputSchema: z.object({ query: z.string().describe("Search terms, e.g. 'adamantine' or 'vampire'") }),
+        annotations: READ_ONLY,
+    }, async ({ query }) => {
+        try {
+            const pages = await searchPages(query);
+            if (pages.length === 0)
+                return text(`No DF wiki pages match "${query}".`);
+            return text(`DF wiki results for "${query}":\n\n` +
+                pages
+                    .map((p, i) => `${i + 1}. ${p.title}\n   ${p.snippet ?? ""}\n   https://dwarffortresswiki.org/index.php/${encodeURIComponent(p.title).replace(/%2F/g, "/")}`)
+                    .join("\n\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_page", {
+        title: "Get page",
+        description: "Read a DF wiki page as plain text.",
+        inputSchema: z.object({
+            title: z.string().describe("Exact page title from search_pages"),
+            maxChars: z.number().int().min(500).max(30000).default(12000),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ title, maxChars }) => {
+        try {
+            const page = await getPage(title);
+            if (!page)
+                return text(`No DF wiki page "${title}".`);
+            const plain = wikiTextToPlain(page.wikitext, maxChars);
+            return text(`${page.title}\n${page.url}\n\n${plain || "(no readable content)"}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof DfError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dwarffortress-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to the Dwarf Fortress wiki, !!FUN!! knowledge about the most complex game ever made. Tools include search pages, get page",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/dwarffortress-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/dwarffortress-mcp.git"
+  },
+  "bin": {
+    "dwarffortress-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "dwarf",
+    "fortress",
+    "wiki",
+    "roguelike"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}