Xero MCP Server

Instructions

Implementation Reference

• src/handlers/revert-xero-payroll-timesheet.handler.ts:22-40 (handler)

  Core handler function that calls the internal revertTimesheet helper to interact with Xero Payroll NZ API and wraps the result in a standard XeroClientResponse.

  export async function revertXeroPayrollTimesheet(timesheetID: string): Promise<
    XeroClientResponse<Timesheet | null>
  > {
    try {
      const revertedTimesheet = await revertTimesheet(timesheetID);
  
      return {
        result: revertedTimesheet,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }

• src/handlers/revert-xero-payroll-timesheet.handler.ts:7-17 (handler)

  Low-level helper that authenticates and directly calls Xero's revertTimesheet API endpoint.

  async function revertTimesheet(timesheetID: string): Promise<Timesheet | null> {
    await xeroClient.authenticate();
  
    // Call the revertTimesheet endpoint from the PayrollNZApi
    const revertedTimesheet = await xeroClient.payrollNZApi.revertTimesheet(
      xeroClient.tenantId,
      timesheetID,
    );
  
    return revertedTimesheet.body.timesheet ?? null;
  }

• src/tools/update/revert-payroll-timesheet.tool.ts:8-40 (registration)

  Creates and exports the MCP tool definition for 'revert-timesheet', including Zod input schema, description, and execution handler that wraps the core logic and formats MCP response.

  const RevertPayrollTimesheetTool = CreateXeroTool(
    "revert-timesheet",
    `Revert a payroll timesheet to draft in Xero by its ID.`,
    {
      timesheetID: z.string().describe("The ID of the timesheet to revert."),
    },
    async (params: { timesheetID: string }) => {
      const { timesheetID } = params;
      const response = await revertXeroPayrollTimesheet(timesheetID);
  
      if (response.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error reverting timesheet: ${response.error}`,
            },
          ],
        };
      }
  
      const timesheet = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Successfully reverted timesheet with ID: ${timesheet?.timesheetID} to draft.`,
          },
        ],
      };
    },
  );

• src/tools/update/index.ts:1-30 (registration)

  Aggregates and exports the revert-timesheet tool (imported as RevertPayrollTimesheetTool) in the UpdateTools array for higher-level tool registration.

  import ApprovePayrollTimesheetTool from "./approve-payroll-timesheet.tool.js";
  import RevertPayrollTimesheetTool from "./revert-payroll-timesheet.tool.js";
  import UpdateBankTransactionTool from "./update-bank-transaction.tool.js";
  import UpdateContactTool from "./update-contact.tool.js";
  import UpdateCreditNoteTool from "./update-credit-note.tool.js";
  import UpdateInvoiceTool from "./update-invoice.tool.js";
  import UpdateItemTool from "./update-item.tool.js";
  import AddTimesheetLineTool from "./update-payroll-timesheet-add-line.tool.js";
  import UpdatePayrollTimesheetLineTool
    from "./update-payroll-timesheet-update-line.tool.js";
  import UpdateManualJournalTool from "./update-manual-journal-tool.js";
  import UpdateQuoteTool from "./update-quote.tool.js";
  import UpdateTrackingCategoryTool from "./update-tracking-category.tool.js";
  import UpdateTrackingOptionsTool from "./update-tracking-options.tool.js";
  
  export const UpdateTools = [
    UpdateContactTool,
    UpdateCreditNoteTool,
    UpdateInvoiceTool,
    UpdateManualJournalTool,
    UpdateQuoteTool,
    UpdateItemTool,
    UpdateBankTransactionTool,
    ApprovePayrollTimesheetTool,
    AddTimesheetLineTool,
    UpdatePayrollTimesheetLineTool,
    RevertPayrollTimesheetTool,
    UpdateTrackingCategoryTool,
    UpdateTrackingOptionsTool
  ];

• src/helpers/create-xero-tool.ts:5-17 (helper)

  Generic factory function used to standardize creation of MCP ToolDefinition objects from name, description, Zod schema, and handler callback.

  export const CreateXeroTool =
    <Args extends ZodRawShapeCompat>(
      name: string,
      description: string,
      schema: Args,
      handler: ToolCallback<Args>,
    ): (() => ToolDefinition<ZodRawShapeCompat>) =>
    () => ({
      name: name,
      description: description,
      schema: schema,
      handler: handler,
    });