Scryfall MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:508-512 (handler)

  The handler function registered for 'csb_build_card_index', which builds the index using buildCsbIndex and writes it using writeCsbIndex.

  async () => {
      const data = await buildCsbIndex();
      const path = await writeCsbIndex(data);
      return { structuredContent: { path, total: data.total, size: Object.keys(data.oracleToId).length, builtAtMs: data.builtAtMs } } as any;
  }

• src/mcp-server.ts:495-500 (schema)

  Output schema definition for the tool.

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

• src/mcp-server.ts:501-513 (registration)

  Registration of the 'csb_build_card_index' tool with MCP server.

  server.registerTool(
      "csb_build_card_index",
      {
          title: "CSB: Build card index",
          description: "Rebuild oracleId→CSB id index and write cache.",
          outputSchema: csbBuildIndexOutput
      },
      async () => {
          const data = await buildCsbIndex();
          const path = await writeCsbIndex(data);
          return { structuredContent: { path, total: data.total, size: Object.keys(data.oracleToId).length, builtAtMs: data.builtAtMs } } as any;
      }
  );

• src/csb-index.ts:36-56 (helper)

  Core helper function that paginates through all CSB cards and builds the oracleId to CSB ID mapping.

  export async function buildCsbIndex(): Promise<CsbCardIndex> {
      const oracleToId: Record<string, number> = Object.create(null);
      const limit = 100;
      let offset = 0;
      let total = 0;
      while (true) {
          const page: any = await CSB.cards({ limit, offset });
          const results: any[] = Array.isArray(page?.results) ? page.results : [];
          total = Number(page?.count ?? total);
          for (const c of results) {
              const oid = c?.oracleId;
              const id = c?.id;
              if (typeof oid === "string" && typeof id === "number") {
                  if (!(oid in oracleToId)) oracleToId[oid] = id;
              }
          }
          if (!page?.next || results.length === 0) break;
          offset += limit;
      }
      return { builtAtMs: Date.now(), total, oracleToId };
  }

• src/csb-index.ts:30-34 (helper)

  Helper function to write the built index to cache file.

  export async function writeCsbIndex(data: CsbCardIndex, cachePath = DEFAULT_CACHE_PATH): Promise<string> {
      await ensureDirFor(cachePath);
      await writeFile(cachePath, JSON.stringify(data, null, 2), "utf8");
      return cachePath;
  }