list_set_cards

Instructions

Implementation Reference

• src/tools/sets.ts:24-41 (handler)

  The main tool definition: name 'list_set_cards', input schema, and handler that calls apiFetch to GET /api/v1/sets/{code}/cards with optional filters.

  export const listSetCardsTool = {
    name: "list_set_cards",
    description:
      "List all cards in a set, paginated. Supports the same filters as search_cards (rarity, type, format, legality).",
    inputSchema: z.object({
      code: z.string().describe("Set code."),
      rarity: z.enum(["common", "uncommon", "rare", "mythic"]).optional(),
      type: z.string().optional(),
      format: z.string().optional(),
      legality: z.enum(["legal", "banned", "restricted"]).optional(),
      page: z.number().int().min(1).optional(),
      limit: z.number().int().min(1).max(100).optional(),
    }),
    handler: ({ code, ...rest }: { code: string } & Record<string, unknown>) =>
      apiFetch({
        path: `/api/v1/sets/${encodeURIComponent(code)}/cards`,
        query: rest as Record<string, string | number | undefined>,
      }),

• src/tools/sets.ts:28-36 (schema)

  Zod schema defining inputs: required 'code', optional filters (rarity, type, format, legality), and optional pagination (page, limit).

  inputSchema: z.object({
    code: z.string().describe("Set code."),
    rarity: z.enum(["common", "uncommon", "rare", "mythic"]).optional(),
    type: z.string().optional(),
    format: z.string().optional(),
    legality: z.enum(["legal", "banned", "restricted"]).optional(),
    page: z.number().int().min(1).optional(),
    limit: z.number().int().min(1).max(100).optional(),
  }),

• src/tools/index.ts:48-88 (registration)

  Registration of listSetCardsTool in the tools array (line 56), making it available as a tool.

  export const tools: ToolDefinition[] = [
    // Read-only (no auth)
    searchCardsTool,
    getCardTool,
    getCardPricesTool,
    getCardPriceHistoryTool,
    searchSetsTool,
    getSetTool,
    listSetCardsTool,
    getSealedProductsTool,
    // Inventory (auth)
    listInventoryTool,
    getInventoryQuantitiesTool,
    addInventoryTool,
    updateInventoryTool,
    removeInventoryTool,
    // Transactions (auth)
    listTransactionsTool,
    recordTransactionTool,
    updateTransactionTool,
    deleteTransactionTool,
    getCostBasisTool,
    // Portfolio (auth; most are Premium-gated)
    getPortfolioSummaryTool,
    getPortfolioHistoryTool,
    getCardPerformanceTool,
    getCashFlowTool,
    getRealizedGainsTool,
    getPortfolioBreakdownTool,
    refreshPortfolioTool,
    // Price alerts (auth)
    listAlertsTool,
    createAlertTool,
    updateAlertTool,
    deleteAlertTool,
    // Notifications (auth)
    listNotificationsTool,
    getUnreadCountTool,
    markNotificationReadTool,
    markAllNotificationsReadTool,
  ];

• src/api-client.ts:26-67 (helper)

  Helper function apiFetch that builds the URL, adds query params, sets auth header if needed, and makes the HTTP request.

  export async function apiFetch<T = unknown>(req: ApiRequest): Promise<T> {
    const url = new URL(req.path, config.baseUrl);
    if (req.query) {
      for (const [k, v] of Object.entries(req.query)) {
        if (v !== undefined && v !== null && v !== "") {
          url.searchParams.set(k, String(v));
        }
      }
    }
  
    const headers: Record<string, string> = {
      Accept: "application/json",
      "User-Agent": "iwantmymtg-mcp/0.0.1",
    };
  
    if (req.authenticated) {
      const { requireApiKey } = await import("./config.js");
      headers["Authorization"] = `Bearer ${requireApiKey()}`;
    }
  
    if (req.body !== undefined) {
      headers["Content-Type"] = "application/json";
    }
  
    const res = await fetch(url, {
      method: req.method ?? "GET",
      headers,
      body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
    });
  
    if (!res.ok) {
      const text = await res.text();
      throw new ApiError(res.status, text, {
        limit: res.headers.get("X-RateLimit-Limit") ?? undefined,
        remaining: res.headers.get("X-RateLimit-Remaining") ?? undefined,
        reset: res.headers.get("X-RateLimit-Reset") ?? undefined,
      });
    }
  
    if (res.status === 204) return undefined as T;
    return (await res.json()) as T;
  }