list-credit-notes
Retrieve and manage credit notes from Xero accounting software, enabling users to view specific contact records or browse all entries with paginated results.
Instructions
List credit notes in Xero. Ask the user if they want to see credit notes for a specific contact, or to see all credit notes before running. Ask the user if they want the next page of credit notes after running this tool if 10 credit notes are returned. If they want the next page, call this tool again with the next page number and the contact if one was provided in the previous call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| contactId | No |
Implementation Reference
- Primary tool implementation: creates the 'list-credit-notes' tool with schema (page, optional contactId), description, and handler that calls listXeroCreditNotes, handles errors, and formats credit note details into text response.const ListCreditNotesTool = CreateXeroTool( "list-credit-notes", `List credit notes in Xero. Ask the user if they want to see credit notes for a specific contact, or to see all credit notes before running. Ask the user if they want the next page of credit notes after running this tool if 10 credit notes are returned. If they want the next page, call this tool again with the next page number and the contact if one was provided in the previous call.`, { page: z.number(), contactId: z.string().optional(), }, async ({ page, contactId }) => { const response = await listXeroCreditNotes(page, contactId); if (response.error !== null) { return { content: [ { type: "text" as const, text: `Error listing credit notes: ${response.error}`, }, ], }; } const creditNotes = response.result; return { content: [ { type: "text" as const, text: `Found ${creditNotes?.length || 0} credit notes:`, }, ...(creditNotes?.map((creditNote) => ({ type: "text" as const, text: [ `Credit Note ID: ${creditNote.creditNoteID}`, `Credit Note Number: ${creditNote.creditNoteNumber}`, creditNote.reference ? `Reference: ${creditNote.reference}` : null, `Type: ${creditNote.type || "Unknown"}`, `Status: ${creditNote.status || "Unknown"}`, creditNote.contact ? `Contact: ${creditNote.contact.name} (${creditNote.contact.contactID})` : null, creditNote.date ? `Date: ${creditNote.date}` : null, creditNote.lineAmountTypes ? `Line Amount Types: ${creditNote.lineAmountTypes}` : null, creditNote.subTotal ? `Sub Total: ${creditNote.subTotal}` : null, creditNote.totalTax ? `Total Tax: ${creditNote.totalTax}` : null, `Total: ${creditNote.total || 0}`, creditNote.currencyCode ? `Currency: ${creditNote.currencyCode}` : null, creditNote.currencyRate ? `Currency Rate: ${creditNote.currencyRate}` : null, creditNote.updatedDateUTC ? `Last Updated: ${creditNote.updatedDateUTC}` : null, ] .filter(Boolean) .join("\n"), })) || []), ], }; }, );
- Core handler function listXeroCreditNotes that authenticates with Xero, fetches credit notes using accountingApi.getCreditNotes with pagination and optional contact filter, handles errors./** * List all credit notes from Xero */ export async function listXeroCreditNotes( page: number = 1, contactId?: string, ): Promise<XeroClientResponse<CreditNote[]>> { try { const creditNotes = await getCreditNotes(contactId, page); return { result: creditNotes, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- Input schema for the tool: requires page number, optional contactId.{ page: z.number(), contactId: z.string().optional(), },
- src/tools/list/index.ts:32-58 (registration)Registers ListCreditNotesTool in the ListTools array for batch registration.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-25 (registration)Imports ListTools and registers all list tools (including list-credit-notes) to the MCP server using server.tool().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), ); UpdateTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), );