list_invoices

Instructions

Implementation Reference

• src/tools/invoices/listInvoices.ts:38-44 (handler)

  The handler function that executes the list_invoices tool logic. It parses args with Zod schema, validates them, then calls invoiceService.listInvoices.

  async function handler(client: Client, args: Record<string, unknown> | undefined) {
    const parsed = schema.safeParse(args);
    if (!parsed.success) {
      return errorResult(parsed.error.errors.map((e) => e.message).join("; "));
    }
    return handleToolCall(() => invoiceService.listInvoices(client, parsed.data));
  }

• src/tools/invoices/listInvoices.ts:7-16 (schema)

  Zod schema for list_invoices input validation: include, status, query, orderBy, sortBy, filterId, itemPerPage, pageNo (all optional).

  const schema = z.object({
    include: z.string().optional(),
    status: z.string().optional(),
    query: z.string().optional(),
    orderBy: z.string().optional(),
    sortBy: z.string().optional(),
    filterId: z.number().int().optional(),
    itemPerPage: z.number().int().min(1).optional(),
    pageNo: z.number().int().min(1).optional(),
  });

• src/tools/invoices/listInvoices.ts:18-36 (schema)

  MCP input schema definition for list_invoices with name, description, and JSON Schema properties (object type with optional fields).

  const definition = {
    name: "list_invoices",
    description:
      "List invoices. GET /invoices. Optional: include (detail, transactions, billruns, externalInvoices), status, query, orderBy, sortBy, filterId, itemPerPage, pageNo.",
    inputSchema: {
      type: "object" as const,
      properties: {
        include: { type: "string", description: "Comma-separated: detail, transactions, billruns, externalInvoices" },
        status: { type: "string", description: "Filter by status" },
        query: { type: "string", description: "Search query" },
        orderBy: { type: "string", description: "Sort column" },
        sortBy: { type: "string", description: "Sort direction" },
        filterId: { type: "number", description: "Filter ID" },
        itemPerPage: { type: "number", description: "Items per page" },
        pageNo: { type: "number", description: "Page number" },
      },
      required: [],
    },
  };

• src/services/invoiceServices.ts:95-110 (helper)

  Core service function that performs the actual HTTP GET /invoices request with query parameters built from the ListInvoicesParams.

  export async function listInvoices(
    client: Client,
    params?: ListInvoicesParams
  ): Promise<PaginatedResponse<unknown>> {
    const search = new URLSearchParams();
    if (params?.include) search.append("include", params.include);
    if (params?.status) search.append("status", params.status);
    if (params?.query) search.append("query", params.query);
    if (params?.orderBy) search.append("orderBy", params.orderBy ?? "");
    if (params?.sortBy) search.append("sortBy", params.sortBy ?? "");
    if (params?.filterId != null) search.append("filterId", String(params.filterId));
    if (params?.itemPerPage != null) search.append("itemPerPage", String(params.itemPerPage));
    if (params?.pageNo != null) search.append("pageNo", String(params.pageNo));
    const q = search.toString();
    return client.get<PaginatedResponse<unknown>>(`/invoices${q ? `?${q}` : ""}`);
  }

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

  Registration: listInvoicesTool is exported by registerInvoiceTools() as one of 8 invoice tools.

  export function registerInvoiceTools(): Tool[] {
    return [
      listInvoicesTool,
      getInvoiceTool,
      createInvoiceTool,
      updateInvoiceTool,
      deleteInvoiceTool,
      chargeInvoiceTool,
      chargeInvoiceExternalTool,
      voidInvoiceTool,
    ];
  }