list-credit-notes

Instructions

Implementation Reference

• src/tools/list/list-credit-notes.tool.ts:5-73 (handler)

  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"),
          })) || []),
        ],
      };
    },
  );

• src/handlers/list-xero-credit-notes.handler.ts:27-49 (handler)

  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),
      };
    }
  }

• src/tools/list/list-credit-notes.tool.ts:14-17 (schema)

  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),
    );