mercury_list_invoices

Instructions

Implementation Reference

• src/tools/invoices.ts:52-61 (handler)

  The actual handler function for mercury_list_invoices. It builds query parameters (limit, order, startAfter, endBefore), calls client.get('/ar/invoices', query), and returns the sanitized JSON result via textResult().

  async (args) => {
    const query: Record<string, string | number | undefined> = {
      limit: args.limit,
      order: args.order,
      start_after: args.startAfter,
      end_before: args.endBefore,
    };
    const data = await client.get("/ar/invoices", query);
    return textResult(data);
  },

• src/tools/invoices.ts:33-51 (schema)

  Zod input schema for mercury_list_invoices: optional 'limit' (int 1-1000), 'order' (asc/desc), 'startAfter' (UUID), and 'endBefore' (UUID).

    limit: z
      .number()
      .int()
      .min(1)
      .max(1000)
      .optional()
      .describe("Max results to return (1-1000). Default: 1000"),
    order: z.enum(["asc", "desc"]).optional().describe("Sort order. Default: asc"),
    startAfter: z
      .string()
      .uuid()
      .optional()
      .describe("Pagination: return invoices after this ID"),
    endBefore: z
      .string()
      .uuid()
      .optional()
      .describe("Pagination: return invoices before this ID"),
  },

• src/tools/invoices.ts:19-62 (registration)

  Registration: the tool 'mercury_list_invoices' is registered via defineTool() inside the registerInvoiceTools() function, which is called from registerAllTools() in src/tools/index.ts (line 33).

  export function registerInvoiceTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_list_invoices",
      [
        "List invoices in your Mercury workspace, with cursor-based pagination.",
        "",
        "USE WHEN: enumerating invoices for an AR audit, finding the ID of an invoice to update/cancel, or building a dunning report. Use `startAfter` / `endBefore` to page beyond the limit.",
        "",
        "DO NOT USE: for one invoice whose ID is known (prefer `mercury_get_invoice`). Mercury does not currently support filtering by status or customer at the API level — filter client-side after listing.",
        "",
        "RETURNS: `{ invoices: [{ id, status, amount, customerId, dueDate, ... }] }`.",
      ].join("\n"),
      {
        limit: z
          .number()
          .int()
          .min(1)
          .max(1000)
          .optional()
          .describe("Max results to return (1-1000). Default: 1000"),
        order: z.enum(["asc", "desc"]).optional().describe("Sort order. Default: asc"),
        startAfter: z
          .string()
          .uuid()
          .optional()
          .describe("Pagination: return invoices after this ID"),
        endBefore: z
          .string()
          .uuid()
          .optional()
          .describe("Pagination: return invoices before this ID"),
      },
      async (args) => {
        const query: Record<string, string | number | undefined> = {
          limit: args.limit,
          order: args.order,
          start_after: args.startAfter,
          end_before: args.endBefore,
        };
        const data = await client.get("/ar/invoices", query);
        return textResult(data);
      },
    );

• src/tools/_shared.ts:29-38 (registration)

  The defineTool() helper wraps the handler with middleware (rate-limit, audit, dry-run) via wrapToolHandler(), then registers it on the MCP server 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/client.ts:100-102 (helper)

  The MercuryClient.get() method — used by the handler to make the GET /ar/invoices request to the Mercury API with query parameters for pagination.

  get<T = unknown>(path: string, query?: Record<string, string | number | undefined>) {
    return this.request<T>("GET", path, { query });
  }