mercury_list_statements

Instructions

Implementation Reference

• src/tools/statements.ts:24-27 (handler)

  The async handler function for mercury_list_statements. It calls client.get with the account ID and optional query params (start/end) and returns the result via textResult.

  async ({ accountId, ...query }) => {
    const data = await client.get(`/account/${accountId}/statements`, query);
    return textResult(data);
  },

• src/tools/statements.ts:19-22 (schema)

  Input schema for mercury_list_statements: accountId (required UUID), start (optional ISO date), end (optional ISO date).

  {
    accountId: z.string().uuid().describe("The Mercury account ID"),
    start: z.iso.date().optional().describe("Filter statements from this date (YYYY-MM-DD)"),
    end: z.iso.date().optional().describe("Filter statements to this date (YYYY-MM-DD)"),

• src/tools/statements.ts:6-28 (registration)

  Registration of mercury_list_statements via defineTool in registerStatementTools, called from src/tools/index.ts registerAllTools.

  export function registerStatementTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_list_statements",
      [
        "List monthly statements for a Mercury deposit account. Each statement has a downloadable PDF URL.",
        "",
        "USE WHEN: fetching the URL of a past statement (e.g. for accounting export, audit, or sharing with a CPA). The PDF URL is short-lived — re-fetch it shortly before download.",
        "",
        "DO NOT USE: for IO Credit account statements (Mercury exposes them only via the dashboard, not the API). For Treasury statements use `mercury_list_treasury_statements`.",
        "",
        "RETURNS: `{ statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }`.",
      ].join("\n"),
      {
        accountId: z.string().uuid().describe("The Mercury account ID"),
        start: z.iso.date().optional().describe("Filter statements from this date (YYYY-MM-DD)"),
        end: z.iso.date().optional().describe("Filter statements to this date (YYYY-MM-DD)"),
      },
      async ({ accountId, ...query }) => {
        const data = await client.get(`/account/${accountId}/statements`, query);
        return textResult(data);
      },
    );

• src/tools/_shared.ts:29-39 (helper)

  defineTool helper that wraps the handler with middleware and registers the tool on the McpServer via server.registerTool.

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    server.registerTool(name, { description, inputSchema: strictSchema }, wrapped);
  }

• src/tools/_shared.ts:17-27 (helper)

  textResult helper used by the handler to format the API response into a ToolResult with sanitized JSON.

  export function textResult(data: unknown): ToolResult {
    // Walk the payload once, reuse the sanitized value for both the
    // LLM-display JSON string and the `structuredContent` object.
    // Calling sanitizeJsonForLlm(data) + sanitizeJsonValues(data)
    // separately would run the walker twice on the same input.
    const sanitized = sanitizeJsonValues(data);
    return {
      content: [{ type: "text", text: JSON.stringify(sanitized, null, 2) }],
      structuredContent: (sanitized ?? {}) as Record<string, unknown>,
    };
  }