list-tracking-categories

Instructions

Implementation Reference

• src/tools/list/list-tracking-categories.tool.ts:6-47 (handler)

  Creates and exports the 'list-tracking-categories' MCP tool, including input schema, execution logic that fetches data from Xero handler and formats response as text.

  const ListTrackingCategoriesTool = CreateXeroTool(
    "list-tracking-categories",
    "List all tracking categories in Xero, along with their associated tracking options.",
    {
      includeArchived: z.boolean().optional()
        .describe("Determines whether or not archived categories will be returned. By default, no archived categories will be returned.")
    },
    async ({ includeArchived }) => {
      const response = await listXeroTrackingCategories(includeArchived);
  
      if (response.isError) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing tracking categories: ${response.error}`
            }
          ]
        };
      }
  
      const trackingCategories = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Found ${trackingCategories?.length || 0} tracking categories:`
          },
          ...(trackingCategories?.map((category) => ({
            type: "text" as const,
            text: [
              `Tracking Category ID: ${category.trackingCategoryID}`,
              `Name: ${category.name}`,
              `Status: ${category.status}`,
              `Found ${category.options?.length || 0} tracking options:\n${category.options?.map(formatTrackingOption)}`
            ].filter(Boolean).join("\n")
          })) || [])
        ]
      };
    }
  );

• src/tools/list/index.ts:28-58 (registration)

  Imports the ListTrackingCategoriesTool and registers it in the ListTools array for use in the MCP server.

  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,
    ListTrialBalanceTool,
    ListPaymentsTool,
    ListProfitAndLossTool,
    ListBankTransactionsTool,
    ListPayrollEmployeesTool,
    ListReportBalanceSheetTool,
    ListOrganisationDetailsTool,
    ListPayrollEmployeeLeaveTool,
    ListPayrollLeavePeriodsToolTool,
    ListPayrollEmployeeLeaveTypesTool,
    ListPayrollEmployeeLeaveBalancesTool,
    ListPayrollLeaveTypesTool,
    ListAgedReceivablesByContact,
    ListAgedPayablesByContact,
    ListPayrollTimesheetsTool,
    ListContactGroupsTool,
    ListTrackingCategoriesTool
  ];

• src/handlers/list-xero-tracking-categories.handler.ts:23-41 (helper)

  Core helper function that calls the Xero API to list tracking categories, handling authentication, API request, and errors.

  export async function listXeroTrackingCategories(
    includeArchived?: boolean
  ): Promise<XeroClientResponse<TrackingCategory[]>> {
    try {
      const trackingCategories = await getTrackingCategories(includeArchived);
  
      return {
        result: trackingCategories,
        isError: false,
        error: null
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error)
      };
    }
  }

• src/helpers/format-tracking-option.ts:1-9 (helper)

  Helper function to format tracking option details for inclusion in the tool's text response.

  import { TrackingOption } from "xero-node";
  
  export const formatTrackingOption = (option: TrackingOption): string => {
    return [
      `Option ID: ${option.trackingOptionID}`,
      `Name: ${option.name}`,
      `Status: ${option.status}`
    ].join("\n");
  };

• src/tools/list/list-tracking-categories.tool.ts:10-12 (schema)

  Zod schema defining the optional 'includeArchived' input parameter for the tool.

    includeArchived: z.boolean().optional()
      .describe("Determines whether or not archived categories will be returned. By default, no archived categories will be returned.")
  },