mercury_list_treasury_statements

Instructions

Implementation Reference

• src/tools/treasury.ts:53-71 (handler)

  The handler function for 'mercury_list_treasury_statements'. It accepts accountId (a UUID), calls GET /treasury/{accountId}/statements via MercuryClient, and returns the result as a text response.

  defineTool(
    server,
    "mercury_list_treasury_statements",
    [
      "List monthly statements for a Mercury Treasury account.",
      "",
      "USE WHEN: fetching the URL of a past Treasury statement for tax/audit export. PDF URL is short-lived — fetch it shortly before download.",
      "",
      "DO NOT USE: for deposit-account statements (use `mercury_list_statements`). IO Credit statements are not exposed via the API.",
      "",
      "RETURNS: `{ statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }`.",
    ].join("\n"),
    {
      accountId: z.uuid().describe("Treasury account ID"),
    },
    async ({ accountId }) => {
      const data = await client.get(`/treasury/${accountId}/statements`);
      return textResult(data);
    },

• src/tools/treasury.ts:65-66 (schema)

  Input schema for the tool: a single required 'accountId' field validated as a UUID.

  {
    accountId: z.uuid().describe("Treasury account ID"),

• src/tools/treasury.ts:53-74 (registration)

  The tool is registered via defineTool() called inside registerTreasuryTools(), which is invoked from registerAllTools() in src/tools/index.ts (line 28), which is called from createServer() in src/server.ts (line 193).

    defineTool(
      server,
      "mercury_list_treasury_statements",
      [
        "List monthly statements for a Mercury Treasury account.",
        "",
        "USE WHEN: fetching the URL of a past Treasury statement for tax/audit export. PDF URL is short-lived — fetch it shortly before download.",
        "",
        "DO NOT USE: for deposit-account statements (use `mercury_list_statements`). IO Credit statements are not exposed via the API.",
        "",
        "RETURNS: `{ statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }`.",
      ].join("\n"),
      {
        accountId: z.uuid().describe("Treasury account ID"),
      },
      async ({ accountId }) => {
        const data = await client.get(`/treasury/${accountId}/statements`);
        return textResult(data);
      },
      { title: "List Treasury Statements", readOnlyHint: true, openWorldHint: true },
    );
  }

• src/tools/_shared.ts:28-54 (helper)

  defineTool() is the generic registration helper that wraps the handler with middleware (wrapToolHandler) and registers it on the MCP server with schema and annotations.

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
    annotations: ToolAnnotations,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    // MCP behavioral annotations (readOnlyHint / destructiveHint /
    // idempotentHint / openWorldHint) — declared machine-readable so
    // hosts and rubrics (TDQS / Glama Behavior dimension) can detect
    // tool semantics without scraping the prose description. Required
    // (not optional) so every new tool ships with explicit semantics —
    // forgetting the annotation now fails typecheck instead of
    // silently shipping a tool with no hint set.
    // The MCP SDK overloads `registerTool` with shape narrowing the runtime
    // strict-schema and the wrapped callback can't satisfy through generics.
    // Both casts are runtime-safe — the signatures only diverge at the type
    // level. Asserted by the existing tool-registration tests.
    (server.registerTool as unknown as (...a: unknown[]) => unknown)(
      name,
      { description, inputSchema: strictSchema, annotations },
      wrapped,
    );
  }

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

  registerTreasuryTools() is called from registerAllTools() in the tools index, connecting the treasury module (including mercury_list_treasury_statements) to the server.

  registerStatementTools(server, client);
  registerTreasuryTools(server, client);