Xero MCP Server

Instructions

Implementation Reference

• src/tools/update/update-credit-note.tool.ts:14-93 (handler)

  Primary handler implementation for the 'update-credit-note' MCP tool. Defines the tool using CreateXeroTool, including schema, description, and the async executor that calls the Xero-specific handler and formats the MCP response with deep link.

  const UpdateCreditNoteTool = CreateXeroTool(
    "update-credit-note",
    "Update a credit note in Xero. Only works on draft credit notes.\
    All line items must be provided. Any line items not provided will be removed. Including existing line items.\
    Do not modify line items that have not been specified by the user.\
   When a credit note is updated, a deep link to the credit note in Xero is returned.\
   This deep link can be used to view the credit note in Xero directly.\
   This link should be displayed to the user.",
    {
      creditNoteId: z.string(),
      lineItems: z.array(lineItemSchema).optional().describe(
        "All line items must be provided. Any line items not provided will be removed. Including existing line items.\
        Do not modify line items that have not been specified by the user",
      ),
      reference: z.string().optional(),
      date: z.string().optional(),
      contactId: z.string().optional(),
    },
    async (
      {
        creditNoteId,
        lineItems,
        reference,
        date,
        contactId,
      }: {
        creditNoteId: string;
        lineItems?: Array<{
          description: string;
          quantity: number;
          unitAmount: number;
          accountCode: string;
          taxType: string;
        }>;
        reference?: string;
        date?: string;
        contactId?: string;
      },
    ) => {
      const result = await updateXeroCreditNote(
        creditNoteId,
        lineItems,
        reference,
        contactId,
        date,
      );
      if (result.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error updating credit note: ${result.error}`,
            },
          ],
        };
      }
  
      const creditNote = result.result;
  
      const deepLink = creditNote.creditNoteID
        ? await getDeepLink(DeepLinkType.CREDIT_NOTE, creditNote.creditNoteID)
        : null;
  
      return {
        content: [
          {
            type: "text" as const,
            text: [
              "Credit note updated successfully:",
              `ID: ${creditNote?.creditNoteID}`,
              `Contact: ${creditNote?.contact?.name}`,
              `Total: ${creditNote?.total}`,
              `Status: ${creditNote?.status}`,
              deepLink ? `Link to view: ${deepLink}` : null,
            ].join("\n"),
          },
        ],
      };
    },
  );

• src/handlers/update-xero-credit-note.handler.ts:60-105 (handler)

  Core business logic handler updateXeroCreditNote: authenticates, checks if credit note is DRAFT, updates via Xero API, handles errors.

  export async function updateXeroCreditNote(
    creditNoteId: string,
    lineItems?: CreditNoteLineItem[],
    reference?: string,
    contactId?: string,
    date?: string,
  ): Promise<XeroClientResponse<CreditNote>> {
    try {
      const existingCreditNote = await getCreditNote(creditNoteId);
  
      const creditNoteStatus = existingCreditNote?.status;
  
      // Only allow updates to DRAFT credit notes
      if (creditNoteStatus !== CreditNote.StatusEnum.DRAFT) {
        return {
          result: null,
          isError: true,
          error: `Cannot update credit note because it is not a draft. Current status: ${creditNoteStatus}`,
        };
      }
  
      const updatedCreditNote = await updateCreditNote(
        creditNoteId,
        lineItems,
        reference,
        contactId,
        date,
      );
  
      if (!updatedCreditNote) {
        throw new Error("Credit note update failed.");
      }
  
      return {
        result: updatedCreditNote,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  } 

• src/tools/update/update-credit-note.tool.ts:6-12 (schema)

  Zod schema for credit note line items used in the tool input validation.

  const lineItemSchema = z.object({
    description: z.string(),
    quantity: z.number(),
    unitAmount: z.number(),
    accountCode: z.string(),
    taxType: z.string(),
  });

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

  Registration of the UpdateCreditNoteTool in the UpdateTools array, which collects all update tools for further registration in tool-factory.ts.

  export const UpdateTools = [
    UpdateContactTool,
    UpdateCreditNoteTool,
    UpdateInvoiceTool,
    UpdateManualJournalTool,
    UpdateQuoteTool,
    UpdateItemTool,
    UpdateBankTransactionTool,
    ApprovePayrollTimesheetTool,
    AddTimesheetLineTool,
    UpdatePayrollTimesheetLineTool,
    RevertPayrollTimesheetTool,
    UpdateTrackingCategoryTool,
    UpdateTrackingOptionsTool
  ];

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

  Final registration of UpdateTools (including update-credit-note) into the main tools list in tool-factory.ts, which is likely used by the MCP server.

  UpdateTools.map((tool) => tool()).forEach((tool) =>