Xero MCP Server

Instructions

Implementation Reference

• src/index.ts:99-125 (schema)

  Tool definition and input schema for xero_navigate - defines the tool name, description, and the domain enum (contacts, invoices, payments, accounts, reports) with required 'domain' parameter

  const navigateTool: Tool = {
    name: "xero_navigate",
    description:
      "Navigate to a specific domain in Xero. Call this first to select which area you want to work with. After navigation, domain-specific tools will be available.",
    inputSchema: {
      type: "object",
      properties: {
        domain: {
          type: "string",
          enum: [
            "contacts",
            "invoices",
            "payments",
            "accounts",
            "reports",
          ],
          description: `The domain to navigate to:
  - contacts: ${domainDescriptions.contacts}
  - invoices: ${domainDescriptions.invoices}
  - payments: ${domainDescriptions.payments}
  - accounts: ${domainDescriptions.accounts}
  - reports: ${domainDescriptions.reports}`,
        },
      },
      required: ["domain"],
    },
  };

• src/index.ts:181-196 (handler)

  Tool handler logic for xero_navigate - updates the server state's currentDomain, retrieves domain-specific tools, and returns a message listing available tools for the selected domain

  if (name === "xero_navigate") {
    const { domain } = args as { domain: Domain };
    state.currentDomain = domain;
  
    const domainTools = getDomainTools(domain);
    const toolNames = domainTools.map((t) => t.name).join(", ");
  
    return {
      content: [
        {
          type: "text",
          text: `Navigated to ${domain} domain. Available tools: ${toolNames}`,
        },
      ],
    };
  }

• src/index.ts:158-171 (registration)

  ListTools request handler that conditionally includes xero_navigate when currentDomain is null (at root level) and hides it when inside a domain

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    const tools: Tool[] = [];
  
    if (state.currentDomain === null) {
      // At root - show navigation tool only
      tools.push(navigateTool);
    } else {
      // In a domain - show domain tools plus back navigation
      tools.push(backTool);
      tools.push(...getDomainTools(state.currentDomain));
    }
  
    return { tools };
  });

• src/index.ts:176-196 (registration)

  CallTool request handler that routes xero_navigate invocations through the name check on line 181 to execute the navigation logic

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    try {
      // Handle navigation
      if (name === "xero_navigate") {
        const { domain } = args as { domain: Domain };
        state.currentDomain = domain;
  
        const domainTools = getDomainTools(domain);
        const toolNames = domainTools.map((t) => t.name).join(", ");
  
        return {
          content: [
            {
              type: "text",
              text: `Navigated to ${domain} domain. Available tools: ${toolNames}`,
            },
          ],
        };
      }