Xero MCP Server

Instructions

Implementation Reference

• src/tools/list/list-contact-groups.tool.ts:15-56 (handler)

  The handler function for the 'list-contact-groups' tool. It calls the Xero helper, handles errors, and formats the contact groups data into readable text blocks.

  async (args) => {
    const response = await listXeroContactGroups(args?.contactGroupId);
    
    if (response.error !== null) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error listing contact groups: ${response.error}`,
          },
        ],
      };
    }
  
    const contactGroups = response.result;
  
    return {
      content: [
        {
          type: "text" as const,
          text: `Found ${contactGroups?.length || 0} contact groups:`,
        },
        ...(contactGroups?.map((contactGroup) => ({
          type: "text" as const,
          text: [
            `Contact Group ID: ${contactGroup.contactGroupID}`,
            `Name: ${contactGroup.name}`,
            `Status: ${contactGroup.status}`,
            contactGroup.contacts
              ? contactGroup.contacts.map(contact => [
                  `Contact ID: ${contact.contactID}`,
                  `Name: ${contact.name}`,
                ].join('\n')
              ).join('\n')
              : "No contacts in this contact group.",            
          ]
            .filter(Boolean)
            .join("\n"),
        })) || []),
      ],
    };
  },

• src/tools/list/list-contact-groups.tool.ts:10-14 (schema)

  Input schema using Zod for the tool, defining optional contactGroupId parameter.

    contactGroupId: z
      .string()
      .optional()
      .describe("Optional ID of the contact group to retrieve"),    
  },

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

  Registers all tools from ListTools (including 'list-contact-groups') with the MCP server using server.tool().

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

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

  Imports the ListContactGroupsTool for inclusion in ListTools.

  import ListContactGroupsTool from "./list-contact-groups.tool.js";

• src/handlers/list-xero-contact-groups.handler.ts:31-49 (helper)

  Helper function that authenticates with Xero and retrieves contact groups (all or by ID), returning structured response or error.

  export async function listXeroContactGroups(contactGroupId?: string): Promise<
    XeroClientResponse<ContactGroup[]>
  > {
    try {
      const contactGroups = await getContactGroups(contactGroupId);
  
      return {
        result: contactGroups,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }