list-tax-rates

Instructions

Implementation Reference

• src/tools/list/list-tax-rates.tool.ts:4-59 (handler)

  Main handler implementation for the 'list-tax-rates' tool. Creates the tool using CreateXeroTool with empty input schema and formats the tax rates into a detailed text response.

  const ListTaxRatesTool = CreateXeroTool(
    "list-tax-rates",
    "Lists all tax rates in Xero. Use this tool to get the tax rates to be used when creating invoices in Xero",
    {},
    async () => {
      const response = await listXeroTaxRates();
      if (response.error !== null) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing tax rates: ${response.error}`,
            },
          ],
        };
      }
  
      const taxRates = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Found ${taxRates?.length || 0} tax rates:`,
          },
          ...(taxRates?.map((taxRate) => ({
            type: "text" as const,
            text: [
              `Tax Rate: ${taxRate.name || "Unnamed"}`,
              `Tax Type: ${taxRate.taxType || "No tax type"}`,
              `Status: ${taxRate.status || "Unknown status"}`,
              `Display Tax Rate: ${taxRate.displayTaxRate || "0.0000"}%`,
              `Effective Rate: ${taxRate.effectiveRate || "0.0000"}%`,
              taxRate.taxComponents?.length
                ? `Tax Components:\n${taxRate.taxComponents
                    .map(
                      (comp) =>
                        `  - ${comp.name}: ${comp.rate}%${comp.isCompound ? " (Compound)" : ""}${comp.isNonRecoverable ? " (Non-recoverable)" : ""}`,
                    )
                    .join("\n")}`
                : null,
              `Can Apply To:${[
                taxRate.canApplyToAssets ? " Assets" : "",
                taxRate.canApplyToEquity ? " Equity" : "",
                taxRate.canApplyToExpenses ? " Expenses" : "",
                taxRate.canApplyToLiabilities ? " Liabilities" : "",
                taxRate.canApplyToRevenue ? " Revenue" : "",
              ].join("")}`,
            ]
              .filter(Boolean)
              .join("\n"),
          })) || []),
        ],
      };
    },
  );

• src/handlers/list-xero-tax-rates.handler.ts:22-40 (handler)

  Core handler function that performs the actual API call to Xero to list tax rates, handles errors, and returns structured response.

  export async function listXeroTaxRates(): Promise<
    XeroClientResponse<TaxRate[]>
  > {
    try {
      const taxRates = await getTaxRates();
  
      return {
        result: taxRates,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }

• src/tools/list/index.ts:27-40 (registration)

  Imports the ListTaxRatesTool and includes it in the exported ListTools array for grouping list-related tools.

  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,

• src/helpers/create-xero-tool.ts:5-17 (helper)

  Helper factory function used to standardize the creation of all Xero MCP tools, including schema and handler binding.

  export const CreateXeroTool =
    <Args extends ZodRawShapeCompat>(
      name: string,
      description: string,
      schema: Args,
      handler: ToolCallback<Args>,
    ): (() => ToolDefinition<ZodRawShapeCompat>) =>
    () => ({
      name: name,
      description: description,
      schema: schema,
      handler: handler,
    });

• src/handlers/list-xero-tax-rates.handler.ts:7-17 (helper)

  Internal helper function that handles Xero client authentication and API call to retrieve tax rates.

  async function getTaxRates(): Promise<TaxRate[]> {
    await xeroClient.authenticate();
  
    const taxRates = await xeroClient.accountingApi.getTaxRates(
      xeroClient.tenantId,
      undefined, // where
      undefined, // order
      getClientHeaders(),
    );
    return taxRates.body.taxRates ?? [];
  }