xero_invoices_list

Instructions

Implementation Reference

• src/domains/invoices.ts:153-195 (handler)

  The handler for xero_invoices_list tool. It extracts page/Status/Type args, optionally elicits a date range from the user if no filters provided, builds a 'where' clause, calls client.get('Invoices', params), and returns the JSON response.

  case "xero_invoices_list": {
    const { page, Status, Type } = args as {
      page?: number;
      Status?: string;
      Type?: string;
    };
    let startDate: string | undefined;
    let endDate: string | undefined;
  
    // If no filters provided, ask the user for a date range
    if (!Status && !Type && page === undefined) {
      const from = await elicitText(
        "Would you like to filter invoices by date range? Enter a start date, or leave blank to list all.",
        "startDate",
        "Start date (YYYY-MM-DD)"
      );
      if (from) {
        startDate = from;
        const to = await elicitText(
          "Enter an end date for the invoice filter.",
          "endDate",
          "End date (YYYY-MM-DD)"
        );
        if (to) endDate = to;
      }
    }
  
    const params: Record<string, string> = {};
    if (page !== undefined) params.page = String(page);
  
    // Build where clause from filters
    const filters: string[] = [];
    if (Status) filters.push(`Status=="${Status}"`);
    if (Type) filters.push(`Type=="${Type}"`);
    if (startDate) filters.push(`Date >= DateTime(${startDate.replace(/-/g, ",")})`);
    if (endDate) filters.push(`Date <= DateTime(${endDate.replace(/-/g, ",")})`);
    if (filters.length > 0) params.where = filters.join(" AND ");
  
    const response = await client.get("Invoices", params);
    return {
      content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
    };
  }

• src/domains/invoices.ts:13-37 (schema)

  The input schema definition for xero_invoices_list tool, part of the invoiceTools array. Defines optional parameters: page (number), Status (enum: DRAFT/SUBMITTED/AUTHORISED/PAID/VOIDED/DELETED), and Type (enum: ACCREC/ACCPAY).

  {
    name: "xero_invoices_list",
    description:
      "List invoices in Xero with pagination. Optionally filter by status and type (ACCREC for sales, ACCPAY for bills).",
    inputSchema: {
      type: "object",
      properties: {
        page: {
          type: "number",
          description: "Page number (1-based, default: 1). Each page returns up to 100 invoices.",
        },
        Status: {
          type: "string",
          enum: ["DRAFT", "SUBMITTED", "AUTHORISED", "PAID", "VOIDED", "DELETED"],
          description: "Filter by invoice status",
        },
        Type: {
          type: "string",
          enum: ["ACCREC", "ACCPAY"],
          description:
            "Filter by invoice type: ACCREC (accounts receivable / sales invoices) or ACCPAY (accounts payable / bills)",
        },
      },
    },
  },

• src/index.ts:258-259 (registration)

  The routing registration in the MCP server's CallToolRequestSchema handler. Tools starting with 'xero_invoices_' are dispatched to handleInvoiceTool(name, toolArgs).

  if (name.startsWith("xero_invoices_")) {
    return await handleInvoiceTool(name, toolArgs);

• src/index.ts:195-198 (registration)

  The ListTools handler that registers all invoice tools (including xero_invoices_list) as available. They are collected via getAllDomainTools() which merges domain tool arrays.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    const domainTools = getAllDomainTools();
    return { tools: [navigateTool, statusTool, backTool, ...domainTools] };
  });

• src/utils/client.ts:83-84 (helper)

  The XeroClient.get() method used by the invoices_list handler to make the GET request to the Xero API 'Invoices' endpoint with query params.

  async get(path: string, params?: Record<string, string>): Promise<unknown> {
    return this.request("GET", path, params);