list-payroll-employees

Instructions

Implementation Reference

• src/tools/list/list-payroll-employees.tool.ts:5-57 (handler)

  MCP tool definition for 'list-payroll-employees', including empty input schema, description, and the main handler function that fetches employees via listXeroPayrollEmployees and formats them into a readable text response.

  const ListPayrollEmployeesTool = CreateXeroTool(
    "list-payroll-employees",
    `List all payroll employees in Xero.
  This retrieves comprehensive employee details including names, User IDs, dates of birth, email addresses, gender, phone numbers, start dates, engagement types (Permanent, FixedTerm, or Casual), titles, and when records were last updated.
  The response presents a complete overview of all staff currently registered in your Xero payroll, with their personal and employment information. If there are many employees, ask the user if they would like to see more detailed information about specific employees before proceeding.`,
    {},
    async () => {
      const response = await listXeroPayrollEmployees();
  
      if (response.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing payroll employees: ${response.error}`,
            },
          ],
        };
      }
  
      const employees = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Found ${employees?.length || 0} payroll employees:`,
          },
          ...(employees?.map((employee: Employee) => ({
            type: "text" as const,
            text: [
              `Employee: ${employee.employeeID}`,
              employee.email ? `Email: ${employee.email}` : "No email",
              employee.gender ? `Gender: ${employee.gender}` : null,
              employee.phoneNumber ? `Phone: ${employee.phoneNumber}` : null,
              employee.startDate ? `Start Date: ${employee.startDate}` : null,
              employee.engagementType
                ? `Engagement Type: ${employee.engagementType}`
                : "No status", // Permanent, FixedTerm, Casual
              employee.title ? `Title: ${employee.title}` : null,
              employee.firstName ? `First Name: ${employee.firstName}` : null,
              employee.lastName ? `Last Name: ${employee.lastName}` : null,
              employee.updatedDateUTC
                ? `Last Updated: ${employee.updatedDateUTC}`
                : null,
            ]
              .filter(Boolean)
              .join("\n"),
          })) || []),
        ],
      };
    },
  );

• src/handlers/list-xero-payroll-employees.handler.ts:24-42 (helper)

  Core helper function that authenticates with Xero and retrieves the list of payroll employees using xeroClient.payrollNZApi.getEmployees, with error handling.

  export async function listXeroPayrollEmployees(): Promise<
    XeroClientResponse<Employee[]>
  > {
    try {
      const employees = await getPayrollEmployees();
  
      return {
        result: employees,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }

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

  Registers ListPayrollEmployeesTool (imported at line 19) in the ListTools array, which is used by tool-factory to register to MCP server.

  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
  ];

• src/tools/tool-factory.ts:20-22 (registration)

  Calls server.tool() to register all tools from ListTools (imported line 6), including 'list-payroll-employees', to the MCP server.

  ListTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );