Xero MCP Server

Instructions

Implementation Reference

• src/tools/update/update-item.tool.ts:17-85 (handler)

  Defines the 'update-item' tool using CreateXeroTool, providing the name, description, Zod input schema, and async execution handler that delegates to updateXeroItem and formats the MCP response.

  const UpdateItemTool = CreateXeroTool(
    "update-item",
    "Update an item in Xero.",
    {
      itemId: z.string(),
      code: z.string(),
      name: z.string(),
      description: z.string().optional(),
      purchaseDescription: z.string().optional(),
      purchaseDetails: purchaseDetailsSchema.optional(),
      salesDetails: salesDetailsSchema.optional(),
      isTrackedAsInventory: z.boolean().optional(),
      inventoryAssetAccountCode: z.string().optional(),
    },
    async ({
      itemId,
      code,
      name,
      description,
      purchaseDescription,
      purchaseDetails,
      salesDetails,
      isTrackedAsInventory,
      inventoryAssetAccountCode,
    }) => {
      const result = await updateXeroItem(
        itemId,
        {
          code,
          name,
          description,
          purchaseDescription,
          purchaseDetails,
          salesDetails,
          isTrackedAsInventory,
          inventoryAssetAccountCode,
        }
      );
  
      if (result.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error updating item: ${result.error}`,
            },
          ],
        };
      }
  
      const item = result.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: [
              "Item updated successfully:",
              `ID: ${item?.itemID}`,
              `Code: ${item?.code}`,
              `Name: ${item?.name}`,
            ]
              .filter(Boolean)
              .join("\n"),
          },
        ],
      };
    },
  );

• src/handlers/update-xero-item.handler.ts:26-84 (handler)

  Core handler functions: updateItem performs the Xero API call to update the item, updateXeroItem wraps it with error handling and standard response format.

  async function updateItem(
    itemId: string,
    itemDetails: ItemDetails
  ): Promise<Item | null> {
    await xeroClient.authenticate();
  
    const item: Partial<Item> = {
      code: itemDetails.code,
      name: itemDetails.name,
      description: itemDetails.description,
      purchaseDescription: itemDetails.purchaseDescription,
      purchaseDetails: itemDetails.purchaseDetails,
      salesDetails: itemDetails.salesDetails,
      isTrackedAsInventory: itemDetails.isTrackedAsInventory,
      inventoryAssetAccountCode: itemDetails.inventoryAssetAccountCode,
    };
  
    const items: Items = {
      items: [item as Item],
    };
  
    const response = await xeroClient.accountingApi.updateItem(
      xeroClient.tenantId,
      itemId,
      items,
      undefined, // unitdp
      undefined, // idempotencyKey
      getClientHeaders()
    );
  
    return response.body.items?.[0] ?? null;
  }
  
  /**
   * Update an item in Xero
   * @param itemId - The ID of the item to update
   * @param itemDetails - The details to update on the item
   * @returns A response containing the updated item or error details
   */
  export async function updateXeroItem(
    itemId: string,
    itemDetails: ItemDetails
  ): Promise<XeroClientResponse<Item | null>> {
    try {
      const item = await updateItem(itemId, itemDetails);
  
      return {
        result: item,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  } 

• src/handlers/update-xero-item.handler.ts:7-24 (schema)

  TypeScript interface defining the structure of item details for the update operation, matching the tool's input schema.

  interface ItemDetails {
    code: string;
    name: string;
    description?: string;
    purchaseDescription?: string;
    purchaseDetails?: {
      unitPrice?: number;
      taxType?: string;
      accountCode?: string;
    };
    salesDetails?: {
      unitPrice?: number;
      taxType?: string;
      accountCode?: string;
    };
    isTrackedAsInventory?: boolean;
    inventoryAssetAccountCode?: string;
  }

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

  Includes the UpdateItemTool in the UpdateTools array, which is used for batch registration of update tools.

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

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

  Batch registers all tools from UpdateTools (including update-item) with the MCP server by calling server.tool for each.

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