Scryfall MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:569-591 (handler)

  Handler function that resolves card names to CSB IDs via Scryfall oracle lookup and index, then finds combos using CSB.findMyCombos.

  async ({ names, fuzzy = true, limit, offset }: { names: string[]; fuzzy?: boolean; limit?: number; offset?: number }) => {
      // Resolve names to oracle_ids via Scryfall
      const oracleIds: string[] = [];
      for (const name of names) {
          try {
              const card: any = await Scryfall.getCardNamed(name, fuzzy);
              const oid = (card as any)?.oracle_id || (card as any)?.oracleId || (card as any)?.oracleID;
              if (typeof oid === "string") oracleIds.push(oid);
          } catch {
              // ignore individual failures
          }
      }
      const uniqOids = Array.from(new Set(oracleIds));
      if (uniqOids.length === 0) return { content: [{ type: "text", text: "No oracle IDs resolved from names" }] } as any;
  
      const mapRes = await lookupCsbIdsByOracle(uniqOids);
      const ids = Object.values(mapRes.found);
      if (ids.length === 0) {
          return { structuredContent: { mapping: mapRes, results: null } } as any;
      }
      const combos = await CSB.findMyCombos(ids, limit, offset);
      return { structuredContent: { mapping: mapRes, results: combos } } as any;
  }

• src/mcp-server.ts:556-561 (schema)

  Input schema definition for the csb_find_combos_by_names tool.

  const csbFindByNamesInput = {
      names: z.array(z.string()).min(1),
      fuzzy: z.boolean().optional().describe("Use Scryfall fuzzy name matching; default true"),
      limit: z.number().int().min(1).max(100).optional(),
      offset: z.number().int().min(0).optional()
  } as const;

• src/mcp-server.ts:562-592 (registration)

  Registration of the csb_find_combos_by_names tool with McpServer, including schema and handler.

  server.registerTool(
      "csb_find_combos_by_names",
      {
          title: "CSB: Find combos by card names",
          description: "Resolve names via Scryfall → oracle_id, map to CSB IDs via cached index, then call find-my-combos.",
          inputSchema: csbFindByNamesInput
      },
      async ({ names, fuzzy = true, limit, offset }: { names: string[]; fuzzy?: boolean; limit?: number; offset?: number }) => {
          // Resolve names to oracle_ids via Scryfall
          const oracleIds: string[] = [];
          for (const name of names) {
              try {
                  const card: any = await Scryfall.getCardNamed(name, fuzzy);
                  const oid = (card as any)?.oracle_id || (card as any)?.oracleId || (card as any)?.oracleID;
                  if (typeof oid === "string") oracleIds.push(oid);
              } catch {
                  // ignore individual failures
              }
          }
          const uniqOids = Array.from(new Set(oracleIds));
          if (uniqOids.length === 0) return { content: [{ type: "text", text: "No oracle IDs resolved from names" }] } as any;
  
          const mapRes = await lookupCsbIdsByOracle(uniqOids);
          const ids = Object.values(mapRes.found);
          if (ids.length === 0) {
              return { structuredContent: { mapping: mapRes, results: null } } as any;
          }
          const combos = await CSB.findMyCombos(ids, limit, offset);
          return { structuredContent: { mapping: mapRes, results: combos } } as any;
      }
  );