dnd5e-mcp 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# dnd5e mcp
+
+MCP server for the **D&D 5e SRD** (dnd5eapi.co), monsters, spells, classes, equipment.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_monster` | Full stat block by index slug (`adult-red-dragon`, `goblin`…) |
+| `get_spell` | Spell by index slug (`fireball`, `wish`…), full text + components |
+| `list_monsters` | A, Z monster list to find valid slugs |
+| `get_class` | Class overview, hit die, skill choices, starting equipment |
+
+## Usage
+
+```bash
+npm run build && node dist/index.js
+```
+
+Example:
+
+```
+get_monster { index: "adult-red-dragon" }
+get_spell { index: "fireball" }
+```
+
+Keyless (community hosted SRD endpoint). Stat blocks include AC/HP/speed, all six ability scores, actions, and special abilities.
+
+## 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
+
+- `get_monster`: Get a D&D 5e monster by index slug (e.g.
+- `get_spell`: Get a D&D 5e spell by index slug (e.g.
+- `list_monsters`: List D&D 5e SRD monsters by name (a-z), useful for finding valid slugs.
+- `get_class`: Get a D&D 5e class overview - hit die, proficiencies, starting equipment.
+
+## 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 `get_monster`.

package/dist/api.d.ts

@@ -0,0 +1,81 @@
+export declare class DndError extends Error {
+}
+export interface Monster {
+    index: string;
+    name: string;
+    size?: string;
+    type?: string;
+    alignment?: string;
+    armor_class?: {
+        value?: number;
+        type?: string;
+    }[];
+    hit_points?: number;
+    hit_dice?: string;
+    speed?: Record<string, string>;
+    strength?: number;
+    dexterity?: number;
+    constitution?: number;
+    intelligence?: number;
+    wisdom?: number;
+    charisma?: number;
+    challenge_rating?: number;
+    languages?: string;
+    xp?: number;
+    actions?: {
+        name?: string;
+        desc?: string;
+    }[];
+    special_abilities?: {
+        name?: string;
+        desc?: string;
+    }[];
+    image?: string;
+}
+export interface Spell {
+    index: string;
+    name: string;
+    level?: number;
+    school?: {
+        name?: string;
+    };
+    casting_time?: string;
+    range?: string;
+    components?: string[];
+    duration?: string;
+    ritual?: boolean;
+    concentration?: boolean;
+    material?: string;
+    desc?: string[];
+    higher_level?: string[];
+}
+export interface ClassInfo {
+    index: string;
+    name: string;
+    hit_die?: number;
+    proficiency_choices?: {
+        from?: {
+            options?: {
+                item?: {
+                    name?: string;
+                };
+            }[];
+        };
+    }[];
+    starting_equipment?: {
+        equipment?: {
+            name?: string;
+        };
+        quantity?: number;
+    }[];
+}
+export declare function listMonsters(limit?: number): Promise<{
+    index: string;
+    name: string;
+}[]>;
+export declare function getMonster(index: string): Promise<Monster | null>;
+export declare function getSpell(index: string): Promise<Spell | null>;
+export declare function getClassInfo(index: string): Promise<ClassInfo | null>;
+export declare function fmtSpeed(speed?: Record<string, string>): string;
+export declare function formatMonster(m: Monster): string;
+export declare function formatSpell(s: Spell): string;

package/dist/api.js

@@ -0,0 +1,97 @@
+/**
+ * D&D 5e SRD client — dnd5eapi.co, keyless.
+ * Docs: https://www.dnd5eapi.co/docs — free community-hosted SRD data.
+ * (The official API moved; we pin the stable community endpoint.)
+ */
+const BASE = "https://www.dnd5eapi.co/api";
+export class DndError extends Error {
+}
+async function getJson(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: { Accept: "application/json", "User-Agent": "dnd5e-mcp/1.0" },
+        redirect: "follow",
+    });
+    if (!res.ok)
+        throw new DndError(`dnd5eapi error ${res.status}: ${res.statusText}`);
+    return (await res.json());
+}
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+export async function listMonsters(limit = 30) {
+    const d = await getJson(`/monsters?limit=${limit}`);
+    return (d.results ?? []).map((r) => ({ index: r.index ?? "", name: r.name ?? "?" }));
+}
+export async function getMonster(index) {
+    try {
+        return (await getJson(`/monsters/${encodeURIComponent(index)}`));
+    }
+    catch (e) {
+        if (e instanceof DndError && String(e).includes("404"))
+            return null;
+        throw e;
+    }
+}
+export async function getSpell(index) {
+    try {
+        return (await getJson(`/spells/${encodeURIComponent(index)}`));
+    }
+    catch (e) {
+        if (e instanceof DndError && String(e).includes("404"))
+            return null;
+        throw e;
+    }
+}
+export async function getClassInfo(index) {
+    try {
+        return (await getJson(`/classes/${encodeURIComponent(index)}`));
+    }
+    catch (e) {
+        if (e instanceof DndError && String(e).includes("404"))
+            return null;
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+export function fmtSpeed(speed) {
+    if (!speed)
+        return "";
+    return Object.entries(speed)
+        .map(([k, v]) => `${k} ${v}`)
+        .join(", ");
+}
+export function formatMonster(m) {
+    const ac = m.armor_class?.map((a) => `${a.value ?? "?"}${a.type ? ` (${a.type})` : ""}`).join(" / ");
+    const stats = ["STR", "DEX", "CON", "INT", "WIS", "CHA"]
+        .map((s, i) => `${s} ${[m.strength, m.dexterity, m.constitution, m.intelligence, m.wisdom, m.charisma][i] ?? "?"}`)
+        .join(" ");
+    const lines = [
+        `${m.name} — ${m.size ?? ""} ${m.type ?? ""}${m.alignment ? `, ${m.alignment}` : ""}`,
+        `AC ${ac ?? "?"} · HP ${m.hit_points ?? "?"} (${m.hit_dice ?? ""}) · Speed ${fmtSpeed(m.speed) || "?"}`,
+        `CR ${m.challenge_rating ?? "?"}${m.xp ? ` (${m.xp} XP)` : ""} · ${m.languages ?? "no languages"}`,
+        stats,
+        m.special_abilities?.length
+            ? `\nAbilities:\n` +
+                m.special_abilities.map((a) => `• ${a.name}: ${(a.desc ?? "").slice(0, 220)}`).join("\n")
+            : "",
+        m.actions?.length
+            ? `\nActions:\n` + m.actions.map((a) => `• ${a.name}: ${(a.desc ?? "").slice(0, 220)}`).join("\n")
+            : "",
+        m.image ? `\nhttps://www.dnd5eapi.co${m.image}` : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function formatSpell(s) {
+    const lines = [
+        `${s.name} — level ${s.level ?? 0} ${s.school?.name ?? ""}${s.ritual ? " (ritual)" : ""}`,
+        `Casting: ${s.casting_time ?? "?"} · Range: ${s.range ?? "?"} · Components: ${(s.components ?? []).join(", ") || "?"}${s.material ? ` (${s.material})` : ""}`,
+        `Duration: ${s.duration ?? "?"}${s.concentration ? " (concentration)" : ""}`,
+        "",
+        ...(s.desc ?? []).map((d) => d),
+        s.higher_level?.length ? `\nAt higher levels: ${s.higher_level.join(" ")}` : "",
+        `\nhttps://www.dnd5eapi.co/api/spells/${s.index}`,
+    ];
+    return lines.join("\n");
+}

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,103 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DndError, formatMonster, formatSpell, getClassInfo, getMonster, getSpell, listMonsters, } 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: "dnd5e-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("get_monster", {
+        title: "Get monster",
+        description: "Get a D&D 5e monster by index slug (e.g. 'aboleth', 'adult-red-dragon', 'goblin').",
+        inputSchema: z.object({ index: z.string().describe("Monster index slug") }),
+        annotations: READ_ONLY,
+    }, async ({ index }) => {
+        try {
+            const m = await getMonster(index);
+            if (!m)
+                return text(`No monster "${index}". Try list_monsters for valid slugs.`);
+            return text(formatMonster(m));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_spell", {
+        title: "Get spell",
+        description: "Get a D&D 5e spell by index slug (e.g. 'fireball', 'magic-missile', 'wish').",
+        inputSchema: z.object({ index: z.string().describe("Spell index slug") }),
+        annotations: READ_ONLY,
+    }, async ({ index }) => {
+        try {
+            const s = await getSpell(index);
+            if (!s)
+                return text(`No spell "${index}".`);
+            return text(formatSpell(s));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("list_monsters", {
+        title: "List monsters",
+        description: "List D&D 5e SRD monsters by name (a-z), useful for finding valid slugs.",
+        inputSchema: z.object({ limit: z.number().int().min(5).max(100).default(30) }),
+        annotations: READ_ONLY,
+    }, async ({ limit }) => {
+        try {
+            const monsters = await listMonsters(limit);
+            return text(`SRD monsters (${monsters.length}):\n` +
+                monsters.map((m, i) => `${i + 1}. ${m.name} [${m.index}]`).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_class", {
+        title: "Get class",
+        description: "Get a D&D 5e class overview — hit die, proficiencies, starting equipment.",
+        inputSchema: z.object({ index: z.string().describe("Class index slug, e.g. 'barbarian', 'wizard'") }),
+        annotations: READ_ONLY,
+    }, async ({ index }) => {
+        try {
+            const c = await getClassInfo(index);
+            if (!c)
+                return text(`No class "${index}".`);
+            const lines = [
+                `${c.name} — hit die d${c.hit_die ?? "?"}`,
+                c.proficiency_choices?.length
+                    ? `Skill choices:\n` +
+                        c.proficiency_choices
+                            .map((pc, i) => `  ${i + 1}. ` +
+                            (pc.from?.options ?? [])
+                                .map((o) => o.item?.name ?? "?")
+                                .slice(0, 8)
+                                .join(", "))
+                            .join("\n")
+                    : "",
+                c.starting_equipment?.length
+                    ? `Starting equipment:\n` +
+                        c.starting_equipment
+                            .map((e) => `  • ${e.quantity ?? 1}× ${e.equipment?.name ?? "?"}`)
+                            .join("\n")
+                    : "",
+                `https://www.dnd5eapi.co/api/classes/${c.index}`,
+            ].filter(Boolean);
+            return text(lines.join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof DndError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dnd5e-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to the D&D 5e SRD, monsters, spells, classes, and equipment. Tools include get monster, get spell, list monsters",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/dnd5e-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/dnd5e-mcp.git"
+  },
+  "bin": {
+    "dnd5e-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",
+    "dnd",
+    "dungeons",
+    "dragons",
+    "ttrpg"
+  ],
+  "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"
+  }
+}