pokemon-tcg-mcp 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# pokemon tcg mcp
+
+The Pokémon TCG via [TCGdex](https://www.tcgdex.dev/), open database, no key.
+
+## Tools
+
+- `search_cards`, search by name, filter by rarity
+- `get_card`, full card: HP, types, abilities, attacks, weakness, market prices
+- `list_sets`, all sets, newest first
+- `get_set`, a set with its full card list
+
+## Run
+
+```bash
+npm install && npm run build && node dist/index.js
+```
+
+## Example
+
+> "Show me Charizard's Vivid Voltage card"
+> `search_cards("charizard")` → `get_card("swsh4-25")`
+
+## 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_cards`: Search Pokémon TCG cards by name, optionally filtered by rarity.
+- `get_card`: Get a single card
+- `list_sets`: List Pokémon TCG sets (newest first).
+- `get_set`: Get a Pokémon TCG set and its card list.
+
+## 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_cards`.

package/dist/api.d.ts

@@ -0,0 +1,73 @@
+/**
+ * TCGdex API v2 client — the open Pokémon TCG database.
+ * Docs: https://www.tcgdex.dev/  (free, no key)
+ */
+export declare class TcgError extends Error {
+}
+export interface CardSummary {
+    id: string;
+    localId: string;
+    name: string;
+    image?: string;
+    category?: string;
+    rarity?: string;
+    set?: {
+        id?: string;
+        name?: string;
+    };
+}
+export interface CardDetail {
+    id: string;
+    name: string;
+    category?: string;
+    hp?: string;
+    types?: string[];
+    rarity?: string;
+    illustrator?: string;
+    abilities?: {
+        name?: string;
+        effect?: string;
+    }[];
+    attacks?: {
+        name?: string;
+        cost?: string[];
+        damage?: string;
+        effect?: string;
+    }[];
+    weakness?: {
+        type?: string;
+        value?: string;
+    }[];
+    resistances?: {
+        type?: string;
+        value?: string;
+    }[];
+    retreat?: number;
+    image?: string;
+    set?: {
+        id?: string;
+        name?: string;
+    };
+    variants?: {
+        firstEdition?: boolean;
+        holo?: boolean;
+        reverse?: boolean;
+    };
+    prices?: Record<string, Record<string, number>>;
+}
+export interface SetSummary {
+    id: string;
+    name: string;
+    releaseDate?: string;
+    cardCount?: number;
+    logo?: string;
+}
+export declare function searchCards(name: string, rarity?: string, limit?: number): Promise<CardSummary[]>;
+export declare function getCard(id: string): Promise<CardDetail | null>;
+export declare function listSets(): Promise<SetSummary[]>;
+export declare function getSet(id: string): Promise<SetSummary & {
+    cards: CardSummary[];
+} | null>;
+export declare function formatCardSummary(c: CardSummary): string;
+export declare function formatCardDetail(c: CardDetail): string;
+export declare function formatSet(s: SetSummary): string;

package/dist/api.js

@@ -0,0 +1,104 @@
+/**
+ * TCGdex API v2 client — the open Pokémon TCG database.
+ * Docs: https://www.tcgdex.dev/  (free, no key)
+ */
+const BASE = "https://api.tcgdex.net/v2/en";
+export class TcgError extends Error {
+}
+async function getJson(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: { Accept: "application/json", "User-Agent": "pokemon-tcg-mcp/1.0" },
+    });
+    if (!res.ok)
+        throw new TcgError(`TCGdex API error ${res.status}: ${res.statusText}`);
+    return (await res.json());
+}
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+export async function searchCards(name, rarity, limit = 12) {
+    const rarityParam = rarity ? `&rarity=${encodeURIComponent(rarity)}` : "";
+    const data = await getJson(`/cards?name=${encodeURIComponent(name)}${rarityParam}`);
+    return (data ?? []).slice(0, limit);
+}
+export async function getCard(id) {
+    const data = await getJson(`/cards/${id}`);
+    return data && data.id ? data : null;
+}
+export async function listSets() {
+    const data = await getJson("/sets");
+    return (data ?? []).sort((a, b) => (b.releaseDate ?? "").localeCompare(a.releaseDate ?? ""));
+}
+export async function getSet(id) {
+    const data = await getJson(`/sets/${id}`);
+    if (!data || !data.id)
+        return null;
+    return {
+        id: data.id,
+        name: data.name ?? "?",
+        releaseDate: data.releaseDate,
+        cardCount: data.cardCount?.total ?? data.cards?.length,
+        logo: data.logo,
+        cards: (data.cards ?? []).map((c) => ({
+            id: c.id,
+            localId: c.localId,
+            name: c.name,
+            category: c.category,
+            rarity: c.rarity,
+            image: c.image,
+        })),
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+export function formatCardSummary(c) {
+    return (`[${c.id}] ${c.name}` +
+        (c.rarity ? ` (${c.rarity})` : "") +
+        (c.category ? ` — ${c.category}` : "") +
+        (c.set?.name ? `\n   Set: ${c.set.name}` : "") +
+        (c.image ? `\n   ${c.image}` : ""));
+}
+export function formatCardDetail(c) {
+    const lines = [
+        `[${c.id}] ${c.name}${c.rarity ? ` (${c.rarity})` : ""}`,
+        `${c.category ?? "?"}${c.hp ? ` | HP ${c.hp}` : ""}` +
+            (c.types?.length ? ` | Types: ${c.types.join("/")}` : "") +
+            (c.retreat ? ` | Retreat: ${c.retreat}` : ""),
+    ];
+    for (const a of c.abilities ?? []) {
+        lines.push(`\nAbility: ${a.name}\n${a.effect ?? ""}`);
+    }
+    for (const atk of c.attacks ?? []) {
+        lines.push(`\nAttack: ${atk.name}${atk.damage ? ` (${atk.damage})` : ""}` +
+            (atk.cost?.length ? ` [${atk.cost.join(" ")}]` : "") +
+            (atk.effect ? `\n${atk.effect}` : ""));
+    }
+    if (c.weakness?.length) {
+        lines.push(`Weakness: ${c.weakness.map((w) => `${w.type} ${w.value ?? ""}`.trim()).join(", ")}`);
+    }
+    if (c.prices) {
+        const entries = Object.entries(c.prices)
+            .map(([variant, p]) => {
+            const low = p.low ? `low $${p.low}` : "";
+            const mid = p.average ? `avg $${p.average}` : "";
+            const high = p.high ? `high $${p.high}` : "";
+            return `${variant}: ${[low, mid, high].filter(Boolean).join(" / ")}`;
+        })
+            .join(", ");
+        if (entries)
+            lines.push(`Market prices: ${entries}`);
+    }
+    if (c.illustrator)
+        lines.push(`Illustrator: ${c.illustrator}`);
+    if (c.set?.name)
+        lines.push(`Set: ${c.set.name}`);
+    if (c.image)
+        lines.push(`\n${c.image}`);
+    return lines.join("\n");
+}
+export function formatSet(s) {
+    return (`[${s.id}] ${s.name}` +
+        (s.releaseDate ? ` — ${s.releaseDate}` : "") +
+        (s.cardCount ? ` (${s.cardCount} cards)` : ""));
+}

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("Pokemon TCG 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,98 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { TcgError, formatCardDetail, formatCardSummary, formatSet, getCard, getSet, listSets, searchCards, } 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: "pokemon-tcg-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_cards", {
+        title: "Search cards",
+        description: "Search Pokémon TCG cards by name, optionally filtered by rarity.",
+        inputSchema: z.object({
+            name: z.string().describe("Card name, e.g. 'Charizard' or 'Pikachu'"),
+            rarity: z.string().optional().describe("e.g. 'Rare Holo', 'Common', 'Rare Holo EX'"),
+            limit: z.number().int().min(1).max(25).default(12).describe("Max results"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ name, rarity, limit }) => {
+        try {
+            const cards = await searchCards(name, rarity, limit);
+            if (cards.length === 0) {
+                return text(`No cards found for "${name}"${rarity ? ` (${rarity})` : ""}.`);
+            }
+            return text(`Cards matching "${name}":\n` +
+                cards.map((c, i) => `${i + 1}. ${formatCardSummary(c)}`).join("\n\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_card", {
+        title: "Get card",
+        description: "Get a single card's full detail: attacks, abilities, weakness, " +
+            "variants, and market prices when available.",
+        inputSchema: z.object({ id: z.string().describe("Card id from search_cards, e.g. 'swsh4-25'") }),
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            const card = await getCard(id);
+            if (!card)
+                return text(`No card with id "${id}".`);
+            return text(formatCardDetail(card));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("list_sets", {
+        title: "List sets",
+        description: "List Pokémon TCG sets (newest first).",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            const sets = await listSets();
+            if (sets.length === 0)
+                return text("No sets found.");
+            return text(`Pokémon TCG sets (${sets.length}):\n` +
+                sets.slice(0, 20).map((s, i) => `${i + 1}. ${formatSet(s)}`).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_set", {
+        title: "Get set",
+        description: "Get a Pokémon TCG set and its card list.",
+        inputSchema: z.object({ id: z.string().describe("Set id from list_sets, e.g. 'swsh4' or 'base1'") }),
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            const set = await getSet(id);
+            if (!set)
+                return text(`No set with id "${id}".`);
+            const head = `${formatSet(set)} (${set.cards.length} cards)\n`;
+            const body = set.cards
+                .slice(0, 25)
+                .map((c) => `• #${c.localId} ${c.name}${c.rarity ? ` (${c.rarity})` : ""}`)
+                .join("\n");
+            const tail = set.cards.length > 25 ? `\n…and ${set.cards.length - 25} more` : "";
+            return text(head + body + tail);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof TcgError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pokemon-tcg-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to the Pok\u00e9mon TCG, search cards, sets, rarities via TCGdex. Tools include search cards, get card, list sets",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/pokemon-tcg-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/pokemon-tcg-mcp.git"
+  },
+  "bin": {
+    "pokemon-tcg-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",
+    "pokemon",
+    "tcg",
+    "cards",
+    "trading-cards",
+    "tcgdex"
+  ],
+  "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"
+  }
+}