Scryfall MCP Server

Instructions

Implementation Reference

• index.ts:271-279 (handler)

  The handler function that implements the get_rulings tool logic. It constructs the Scryfall API URL for rulings by card ID, fetches the data, and processes the response using the shared helper.

  async function handleGetRulings(id: string) {
    // Scryfall docs: /cards/{id}/rulings
    // Also works with /cards/{oracle_id}/rulings
    const url = `https://api.scryfall.com/cards/${encodeURIComponent(
      id
    )}/rulings`;
    const response = await fetch(url);
    return handleScryfallResponse(response);
  }

• index.ts:135-151 (schema)

  The Tool object definition including name, description, and inputSchema for validating the 'id' parameter.

  const GET_RULINGS_TOOL: Tool = {
    name: "get_rulings",
    description:
      "Retrieve official rulings for a specified card by Scryfall ID or Oracle ID. " +
      "Returns an array of rulings. Each ruling has a 'published_at' date and a 'comment' field.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description:
            "A Scryfall ID or Oracle ID. Example: 'c09c71fb-7acb-4ffb-a47b-8961a0cf4990'"
        }
      },
      required: ["id"]
    }
  };

• index.ts:186-194 (registration)

  The array of all tools that is returned by the listTools handler, registering get_rulings among them.

  const SCRYFALL_TOOLS = [
    SEARCH_CARDS_TOOL,
    GET_CARD_BY_ID_TOOL,
    GET_CARD_BY_NAME_TOOL,
    RANDOM_CARD_TOOL,
    GET_RULINGS_TOOL,
    GET_PRICES_BY_ID_TOOL,
    GET_PRICES_BY_NAME_TOOL
  ] as const;

• index.ts:389-392 (registration)

  The switch case in the CallToolRequest handler that dispatches calls to 'get_rulings' to the handleGetRulings function.

  case "get_rulings": {
    const { id } = args as { id: string };
    return await handleGetRulings(id);
  }

• index.ts:197-239 (helper)

  Shared helper function used by get_rulings (and other tools) to handle Scryfall API responses, including error parsing and JSON formatting.

  async function handleScryfallResponse(response: Response) {
    if (!response.ok) {
      // Attempt to parse Scryfall error
      let errorObj: ScryfallError | null = null;
      try {
        errorObj = (await response.json()) as ScryfallError;
      } catch {
        // fall back to generic
      }
      if (errorObj && errorObj.object === "error") {
        return {
          content: [
            {
              type: "text",
              text: `Scryfall error: ${errorObj.details} (code=${errorObj.code}, status=${errorObj.status})`
            }
          ],
          isError: true
        };
      } else {
        return {
          content: [
            {
              type: "text",
              text: `HTTP error ${response.status}: ${response.statusText}`
            }
          ],
          isError: true
        };
      }
    }
    // If okay, parse JSON
    const data = await response.json();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2)
        }
      ],
      isError: false
    };
  }