Xero MCP Server

Instructions

Implementation Reference

• src/handlers/list-aged-payables-by-contact.handler.ts:27-55 (handler)

  Core handler function that calls the internal Xero API helper, handles errors, and returns standardized XeroClientResponse with the aged payables report.

  export async function listXeroAgedPayablesByContact(
    contactId: string,
    reportDate?: string,
    invoicesFromDate?: string,
    invoicesToDate?: string
  ): Promise<XeroClientResponse<ReportWithRow>> {
    try {
      const agedPayables = await listAgedPayablesByContact(contactId, reportDate, invoicesFromDate, invoicesToDate);
  
      if (!agedPayables) {
        return {
          result: null,
          isError: true,
          error: "Failed to get aged payables by contact from Xero."
        };
      }
  
      return {
        result: agedPayables,
        isError: false,
        error: null
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }

• src/handlers/list-aged-payables-by-contact.handler.ts:7-25 (helper)

  Internal helper function that authenticates with Xero client and makes the API call to retrieve the aged payables report by contact ID.

  async function listAgedPayablesByContact(
    contactId: string,
    reportDate?: string,
    invoicesFromDate?: string,
    invoicesToDate?: string
  ): Promise<ReportWithRow | undefined> {
    await xeroClient.authenticate();
  
    const response = await xeroClient.accountingApi.getReportAgedPayablesByContact(
      xeroClient.tenantId, // xeroTenantId
      contactId, // contactId
      reportDate, // date
      invoicesFromDate, // fromDate
      invoicesToDate, // toDate
      getClientHeaders()
    );
  
    return response.body.reports?.[0];
  }

• src/tools/list/list-aged-payables-by-contact.tool.ts:6-59 (registration)

  Defines the MCP tool 'list-aged-payables-by-contact' using CreateXeroTool, including schema, description, and execution logic that calls the handler and formats the MCP response.

  const ListAgedPayablesByContact = CreateXeroTool(
    "list-aged-payables-by-contact",
    `Lists the aged payables in Xero.
    This shows aged payables for a certain contact up to a report date.`,
    {
      contactId: z.string(),
      reportDate: z.string().optional()
        .describe("Optional date to retrieve aged payables in YYYY-MM-DD format. If none is provided, defaults to end of the current month."),
      invoicesFromDate: z.string().optional()
        .describe("Optional from date in YYYY-MM-DD format. If provided, will only show payable invoices after this date for the contact."),
      invoicesToDate: z.string().optional()
        .describe("Optional to date in YYYY-MM-DD format. If provided, will only show payable invoices before this date for the contact."),
    },
    async ({ contactId, reportDate, invoicesFromDate, invoicesToDate }) => {
      const response = await listXeroAgedPayablesByContact(contactId, reportDate, invoicesFromDate, invoicesToDate);
      
      if (response.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing aged payables by contact: ${response.error}`,
            },
          ],
        };
      }
  
      const agedPayablesReport = response.result;
      const filter = formatAgedReportFilter(invoicesFromDate, invoicesToDate);
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Report Name: ${agedPayablesReport.reportName || "Not specified"}`,
          },
          {
            type: "text" as const,
            text: `Report Date: ${agedPayablesReport.reportDate || "Not specified"}`
          },
          {
            type: "text" as const,
            text: filter ?? "Showing all relevant invoices"
          },
          {
            type: "text" as const,
            text: JSON.stringify(agedPayablesReport.rows, null, 2),
          }
        ],
      };
    }
  );
  
  export default ListAgedPayablesByContact;

• src/tools/list/list-aged-payables-by-contact.tool.ts:10-18 (schema)

  Zod schema defining the input parameters for the tool: contactId (required), and optional date filters.

  {
    contactId: z.string(),
    reportDate: z.string().optional()
      .describe("Optional date to retrieve aged payables in YYYY-MM-DD format. If none is provided, defaults to end of the current month."),
    invoicesFromDate: z.string().optional()
      .describe("Optional from date in YYYY-MM-DD format. If provided, will only show payable invoices after this date for the contact."),
    invoicesToDate: z.string().optional()
      .describe("Optional to date in YYYY-MM-DD format. If provided, will only show payable invoices before this date for the contact."),
  },

• src/tools/list/index.ts:32-58 (registration)

  Registers ListAgedPayablesByContact (imported on line 2) in the ListTools array, likely for server-side tool exposure.

  export const ListTools = [
    ListAccountsTool,
    ListContactsTool,
    ListCreditNotesTool,
    ListInvoicesTool,
    ListItemsTool,
    ListManualJournalsTool,
    ListQuotesTool,
    ListTaxRatesTool,
    ListTrialBalanceTool,
    ListPaymentsTool,
    ListProfitAndLossTool,
    ListBankTransactionsTool,
    ListPayrollEmployeesTool,
    ListReportBalanceSheetTool,
    ListOrganisationDetailsTool,
    ListPayrollEmployeeLeaveTool,
    ListPayrollLeavePeriodsToolTool,
    ListPayrollEmployeeLeaveTypesTool,
    ListPayrollEmployeeLeaveBalancesTool,
    ListPayrollLeaveTypesTool,
    ListAgedReceivablesByContact,
    ListAgedPayablesByContact,
    ListPayrollTimesheetsTool,
    ListContactGroupsTool,
    ListTrackingCategoriesTool
  ];