Scryfall MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:529-535 (handler)

  Inline handler function for csb_read_card_index tool: computes cache path, reads index using readCsbIndex helper, computes size, returns structured content with path/total/size/cachedAtMs or text error if not found.

  async () => {
      const cachePath = process.env.CSB_CARD_INDEX_PATH || require('node:path').join(process.cwd(), 'cache', 'csb-card-index.json');
      const disk = await readCsbIndex(cachePath);
      if (!disk) return { content: [{ type: "text", text: "No CSB card index cache found" }] } as any;
      const size = Object.keys(disk.data.oracleToId || {}).length;
      return { structuredContent: { path: cachePath, total: disk.data.total, size, cachedAtMs: disk.at } } as any;
  }

• src/mcp-server.ts:516-521 (schema)

  Output schema definition for csb_read_card_index tool using zod schemas.

  const csbReadIndexOutput = {
      path: z.string(),
      total: z.number().int().nonnegative(),
      size: z.number().int().nonnegative(),
      cachedAtMs: z.number()
  } as const;

• src/mcp-server.ts:522-536 (registration)

  Registers the csb_read_card_index tool on the MCP server with title, description, output schema, and handler.

  server.registerTool(
      "csb_read_card_index",
      {
          title: "CSB: Read card index",
          description: "Read oracleId→CSB id index from local cache.",
          outputSchema: csbReadIndexOutput
      },
      async () => {
          const cachePath = process.env.CSB_CARD_INDEX_PATH || require('node:path').join(process.cwd(), 'cache', 'csb-card-index.json');
          const disk = await readCsbIndex(cachePath);
          if (!disk) return { content: [{ type: "text", text: "No CSB card index cache found" }] } as any;
          const size = Object.keys(disk.data.oracleToId || {}).length;
          return { structuredContent: { path: cachePath, total: disk.data.total, size, cachedAtMs: disk.at } } as any;
      }
  );

• src/csb-index.ts:20-28 (helper)

  Helper function readCsbIndex reads the JSON cache file, parses it as CsbCardIndex, returns data with mtimeMs or null on error.

  export async function readCsbIndex(cachePath = DEFAULT_CACHE_PATH): Promise<{ data: CsbCardIndex; at: number } | null> {
      try {
          const [buf, st] = await Promise.all([readFile(cachePath, "utf8"), stat(cachePath)]);
          const data = JSON.parse(buf) as CsbCardIndex;
          return { data, at: st.mtimeMs };
      } catch {
          return null;
      }
  }