get_portfolio_history

Instructions

Implementation Reference

• src/tools/portfolio.ts:12-21 (handler)

  The handler function for the get_portfolio_history tool. It takes an optional 'days' parameter (1-3650) and makes an authenticated GET request to /api/v1/portfolio/history. This is the core execution logic.

  export const getPortfolioHistoryTool = {
    name: "get_portfolio_history",
    description:
      "Get portfolio value history. Premium-gated - free tier receives 403. Requires IWMM_API_KEY.",
    inputSchema: z.object({
      days: z.number().int().min(1).max(3650).optional().describe("How many days of history. Server default applies if omitted."),
    }),
    handler: ({ days }: { days?: number }) =>
      apiFetch({ path: "/api/v1/portfolio/history", query: { days }, authenticated: true }),
  };

• src/tools/portfolio.ts:16-17 (schema)

  Input validation schema using Zod. Accepts an optional 'days' parameter (integer, 1-3650) that specifies how many days of history to retrieve.

  inputSchema: z.object({
    days: z.number().int().min(1).max(3650).optional().describe("How many days of history. Server default applies if omitted."),

• src/tools/index.ts:21-72 (registration)

  The tool is imported from './portfolio.js' and registered in the tools array at line 72 of src/tools/index.ts. It is listed in the 'Portfolio (auth; most are Premium-gated)' section.

    getPortfolioHistoryTool,
    getCardPerformanceTool,
    getCashFlowTool,
    getRealizedGainsTool,
    getPortfolioBreakdownTool,
    refreshPortfolioTool,
  } from "./portfolio.js";
  import {
    listAlertsTool,
    createAlertTool,
    updateAlertTool,
    deleteAlertTool,
  } from "./alerts.js";
  import {
    listNotificationsTool,
    getUnreadCountTool,
    markNotificationReadTool,
    markAllNotificationsReadTool,
  } from "./notifications.js";
  
  export interface ToolDefinition {
    name: string;
    description: string;
    inputSchema: z.ZodTypeAny;
    handler: (input: any) => Promise<unknown>;
  }
  
  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,

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

  The tools array is converted to a name-indexed lookup map (toolsByName) which the server uses to dispatch tool calls by name.

  export const toolsByName: Record<string, ToolDefinition> = Object.fromEntries(

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

  The apiFetch helper function used by the handler to make the actual HTTP request to the external IWMM API. It constructs the URL with query params, adds auth headers, and handles errors.

  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;
  }