@olaservo/scryfall-mcp-server 1.0.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools/index.js";
+const server = new McpServer({
+    name: "scryfall-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+    instructions: "Search and fetch Magic: The Gathering card data from Scryfall. " +
+        "Use the 'search' tool with Scryfall full-text query syntax to find cards, " +
+        "then use 'fetch' with a card ID to get full details.",
+});
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Scryfall MCP server running via stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/scryfall-api.d.ts

@@ -0,0 +1,36 @@
+export interface ScryfallCard {
+    id: string;
+    name: string;
+    scryfall_uri: string;
+    set: string;
+    set_name: string;
+    collector_number: string;
+    type_line: string;
+    mana_cost?: string;
+    oracle_text?: string;
+    colors?: string[];
+    rarity: string;
+    released_at: string;
+    prices: Record<string, string | null>;
+    image_uris?: Record<string, string>;
+    card_faces?: Array<{
+        name?: string;
+        type_line?: string;
+        mana_cost?: string;
+        oracle_text?: string;
+        image_uris?: Record<string, string>;
+    }>;
+    uri: string;
+}
+export interface ScryfallSearchResponse {
+    data: ScryfallCard[];
+    total_cards: number;
+    has_more: boolean;
+}
+export interface ScryfallError {
+    status: number;
+    body: string;
+}
+export declare function isScryfallError(result: ScryfallSearchResponse | ScryfallCard | ScryfallError): result is ScryfallError;
+export declare function searchCards(query: string): Promise<ScryfallSearchResponse | ScryfallError>;
+export declare function fetchCard(id: string): Promise<ScryfallCard | ScryfallError>;

package/dist/scryfall-api.js

@@ -0,0 +1,40 @@
+const BASE_URL = "https://api.scryfall.com";
+const USER_AGENT = "scryfall-mcp-server/1.0 (+https://github.com/olaservo/scryfall-mcp-app)";
+const MIN_DELAY_MS = 120; // ~8-9 rps (Scryfall asks for 50-100ms & <10 rps)
+let lastCall = 0;
+async function rateLimit() {
+    const now = Date.now();
+    const wait = Math.max(0, lastCall + MIN_DELAY_MS - now);
+    if (wait > 0) {
+        await new Promise((resolve) => setTimeout(resolve, wait));
+    }
+    lastCall = Date.now();
+}
+function headers() {
+    return {
+        "User-Agent": USER_AGENT,
+        Accept: "application/json",
+    };
+}
+export function isScryfallError(result) {
+    return "status" in result && "body" in result;
+}
+export async function searchCards(query) {
+    await rateLimit();
+    const url = new URL(`${BASE_URL}/cards/search`);
+    url.searchParams.set("q", query);
+    const res = await fetch(url.toString(), { headers: headers() });
+    if (!res.ok) {
+        return { status: res.status, body: await res.text() };
+    }
+    return (await res.json());
+}
+export async function fetchCard(id) {
+    await rateLimit();
+    const url = `${BASE_URL}/cards/${encodeURIComponent(id)}`;
+    const res = await fetch(url, { headers: headers() });
+    if (!res.ok) {
+        return { status: res.status, body: await res.text() };
+    }
+    return (await res.json());
+}

package/dist/tools/fetch.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const CARD_VIEWER_URI = "ui://scryfall/card-viewer.html";
+export declare const registerFetchTool: (server: McpServer) => void;

package/dist/tools/fetch.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { fetchCard, isScryfallError } from "../scryfall-api.js";
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+export const CARD_VIEWER_URI = "ui://scryfall/card-viewer.html";
+const FetchInputShape = {
+    id: z
+        .string()
+        .uuid()
+        .describe("Scryfall card UUID (obtained from the search tool results)"),
+};
+const FetchSchema = z.object(FetchInputShape);
+function formatCardText(card) {
+    const parts = [];
+    // Card faces or single card text
+    if (card.card_faces && card.card_faces.length > 0) {
+        parts.push(card.card_faces
+            .map((face) => `${face.name || ""}\n${face.type_line || ""}\n${face.mana_cost || ""}\n\n${face.oracle_text || ""}`)
+            .join("\n\n---\n\n"));
+    }
+    else {
+        parts.push(`${card.name}\n${card.type_line}\n${card.mana_cost || ""}\n\n${card.oracle_text || ""}`);
+    }
+    // Metadata
+    parts.push(`Set: ${card.set_name} (${card.set.toUpperCase()}) #${card.collector_number}`);
+    parts.push(`Rarity: ${card.rarity}`);
+    parts.push(`Released: ${card.released_at}`);
+    if (card.colors && card.colors.length > 0) {
+        parts.push(`Colors: ${card.colors.join(", ")}`);
+    }
+    // Prices
+    const priceEntries = Object.entries(card.prices)
+        .filter(([, v]) => v != null && v !== "")
+        .map(([k, v]) => `${k}: $${v}`);
+    if (priceEntries.length > 0) {
+        parts.push(`Prices: ${priceEntries.join(", ")}`);
+    }
+    // Image URI for non-UI hosts
+    const imageUri = card.image_uris?.normal ?? card.card_faces?.[0]?.image_uris?.normal;
+    if (imageUri) {
+        parts.push(`Image: ${imageUri}`);
+    }
+    parts.push(`ID: ${card.id}`);
+    parts.push(`Scryfall: ${card.scryfall_uri}`);
+    parts.push(`API: ${card.uri}`);
+    return parts.join("\n");
+}
+export const registerFetchTool = (server) => {
+    registerAppTool(server, "fetch", {
+        title: "Fetch Card",
+        description: "Fetch detailed information for a single Magic: The Gathering card by its Scryfall UUID. " +
+            "Returns the card's full oracle text, type line, mana cost, colors, set info, rarity, " +
+            "prices, and image URIs. Handles double-faced cards (e.g., transform, modal DFC).",
+        inputSchema: FetchInputShape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        _meta: {
+            ui: { resourceUri: CARD_VIEWER_URI },
+        },
+    }, async (args) => {
+        const { id } = FetchSchema.parse(args);
+        const result = await fetchCard(id);
+        if (isScryfallError(result)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: true,
+                            status: result.status,
+                            body: result.body,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const structured = {
+            name: result.name,
+            type_line: result.type_line,
+            mana_cost: result.mana_cost,
+            oracle_text: result.oracle_text,
+            set_name: result.set_name,
+            set: result.set,
+            rarity: result.rarity,
+            collector_number: result.collector_number,
+            released_at: result.released_at,
+            colors: result.colors,
+            prices: result.prices,
+            scryfall_uri: result.scryfall_uri,
+            image_uris: result.image_uris,
+            card_faces: result.card_faces,
+        };
+        return {
+            content: [{ type: "text", text: formatCardText(result) }],
+            structuredContent: structured,
+        };
+    });
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const registerTools: (server: McpServer) => void;

package/dist/tools/index.js

@@ -0,0 +1,42 @@
+import { registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { registerSearchTool } from "./search.js";
+import { registerFetchTool, CARD_VIEWER_URI } from "./fetch.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function getDistDir() {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    // When running from dist/, thisDir is dist/tools/
+    // When running from src/ via tsx, thisDir is src/tools/
+    if (thisDir.includes("dist")) {
+        return path.resolve(thisDir, "..");
+    }
+    return path.resolve(thisDir, "..", "..", "dist");
+}
+export const registerTools = (server) => {
+    registerSearchTool(server);
+    registerFetchTool(server);
+    registerAppResource(server, CARD_VIEWER_URI, CARD_VIEWER_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const distDir = getDistDir();
+        const html = await fs.readFile(path.join(distDir, "card-viewer.html"), "utf-8");
+        return {
+            contents: [
+                {
+                    uri: CARD_VIEWER_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                    _meta: {
+                        ui: {
+                            csp: {
+                                resourceDomains: [
+                                    "https://cards.scryfall.io",
+                                    "https://svgs.scryfall.io",
+                                ],
+                            },
+                        },
+                    },
+                },
+            ],
+        };
+    });
+};

package/dist/tools/search.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const registerSearchTool: (server: McpServer) => void;

package/dist/tools/search.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { searchCards, isScryfallError } from "../scryfall-api.js";
+const SearchSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("Scryfall full-text search query. Supports Scryfall syntax " +
+        '(e.g., "c:red t:creature cmc=3", "set:mkm", "o:\\"draw a card\\"")'),
+});
+export const registerSearchTool = (server) => {
+    server.registerTool("search", {
+        title: "Search Cards",
+        description: "Search for Magic: The Gathering cards using Scryfall full-text query syntax. " +
+            "Returns a list of matching cards with their Scryfall IDs, names, and URLs. " +
+            "Use Scryfall search syntax: color (c:), type (t:), CMC (cmc=), set (set:), " +
+            'oracle text (o:"..."), power/toughness (pow=, tou=), rarity (r:), etc.',
+        inputSchema: SearchSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const { query } = SearchSchema.parse(args);
+        const result = await searchCards(query);
+        if (isScryfallError(result)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: true,
+                            status: result.status,
+                            body: result.body,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const results = {
+            results: result.data.map((card) => ({
+                id: card.id,
+                title: card.name,
+                url: card.scryfall_uri ||
+                    `https://scryfall.com/card/${card.set}/${card.collector_number}`,
+            })),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(results) }],
+        };
+    });
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@olaservo/scryfall-mcp-server",
+  "version": "1.0.0",
+  "description": "Community MCP server to search and fetch Magic: The Gathering card data from Scryfall with a rich card viewer UI. Not affiliated with or endorsed by Scryfall.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "scryfall-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "magic-the-gathering",
+    "mtg",
+    "scryfall",
+    "cards",
+    "search",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olaservo/scryfall-mcp-app.git"
+  },
+  "homepage": "https://github.com/olaservo/scryfall-mcp-app#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build:ui": "cross-env INPUT=src/ui/card-viewer.html vite build",
+    "build:server": "tsc",
+    "build": "npm run build:ui && npm run build:server",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "pack": "npm run build && rm -rf node_modules && npm install --omit=dev --omit=optional && npx --yes @anthropic-ai/mcpb -- pack . scryfall-mcp-server.mcpb; npm install"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "cross-env": "^10.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.1",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}