list-timesheets
Retrieve comprehensive payroll timesheet details from Xero, including employee IDs, work periods, hours, and update timestamps for accurate workforce management.
Instructions
List all payroll timesheets in Xero. This retrieves comprehensive timesheet details including timesheet IDs, employee IDs, start and end dates, total hours, and the last updated date.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Defines and implements the 'list-timesheets' MCP tool handler, including empty input schema, description, and execution logic that fetches timesheets via helper and formats them into MCP text content blocks.const ListPayrollTimesheetsTool = CreateXeroTool( "list-timesheets", `List all payroll timesheets in Xero. This retrieves comprehensive timesheet details including timesheet IDs, employee IDs, start and end dates, total hours, and the last updated date.`, {}, async () => { const response = await listXeroPayrollTimesheets(); if (response.isError) { return { content: [ { type: "text" as const, text: `Error listing timesheets: ${response.error}`, }, ], }; } const timesheets = response.result; return { content: [ { type: "text" as const, text: `Found ${timesheets?.length || 0} timesheets:`, }, ...(timesheets?.map((timesheet: Timesheet) => ({ type: "text" as const, text: [ `Timesheet ID: ${timesheet.timesheetID}`, `Employee ID: ${timesheet.employeeID}`, `Start Date: ${timesheet.startDate}`, `End Date: ${timesheet.endDate}`, `Total Hours: ${timesheet.totalHours}`, `Last Updated: ${timesheet.updatedDateUTC}`, ] .filter(Boolean) .join("\n"), })) || []), ], }; }, );
- Helper function that authenticates with Xero, fetches payroll timesheets using the Xero NZ Payroll API, and returns structured result or formatted error.export async function listXeroPayrollTimesheets(): Promise< XeroClientResponse<Timesheet[]> > { try { const timesheets = await getTimesheets(); return { result: timesheets, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- src/tools/list/index.ts:23-58 (registration)Registers the list-timesheets tool by importing it and including it in the ListTools array, which is later used for MCP server registration.import ListPayrollTimesheetsTool from "./list-payroll-timesheets.tool.js"; import ListProfitAndLossTool from "./list-profit-and-loss.tool.js"; import ListQuotesTool from "./list-quotes.tool.js"; import ListReportBalanceSheetTool from "./list-report-balance-sheet.tool.js"; import ListTaxRatesTool from "./list-tax-rates.tool.js"; import ListTrackingCategoriesTool from "./list-tracking-categories.tool.js"; import ListTrialBalanceTool from "./list-trial-balance.tool.js"; import ListContactGroupsTool from "./list-contact-groups.tool.js"; 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:6-22 (registration)Final registration step where all ListTools, including 'list-timesheets', are registered to the MCP server via server.tool() calls.import { ListTools } from "./list/index.js"; import { UpdateTools } from "./update/index.js"; export function ToolFactory(server: McpServer) { DeleteTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), ); GetTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), ); CreateTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), ); ListTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), );