# xeroapi/xero-mcp-server architecture

> Architecture diagram of the GitHub repository xeroapi/xero-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xeroapi/xero-mcp-server
- Repository: https://github.com/xeroapi/xero-mcp-server

## Overview

##### Main Components
- MCP Server Component: At the heart of the project is the MCP server implementation (see src/server/xero-mcp-server.ts). This handles the incoming MCP commands and routes them appropriately.
- Command Handlers: Located in src/handlers, these files (e.g., create-xero-contact.handler.ts, list-xero-invoices.handler.ts) are responsible for the business logic behind each MCP command. They translate protocol commands into operations on Xero’s API.
- API Client: The client implementation in src/clients/xero-client.ts is used to communicate with Xero’s API, handling OAuth2 authentication and API requests.
- Tools/Utilities: The src/tools directory contains CLI tools (such as create-contact.tool.ts, list-accounts.tool.ts) that offer command-line functionality, possibly for testing or extended usage beyond the MCP integration.
- Helpers and Types: Helper functions (in src/helpers) and type definitions (in src/types) support the overall operation by ensuring consistency and simplified error formatting, tool registration, and version management.

##### Component Relationships and Interactions
- The MCP Server receives commands (e.g., list-contacts, create-invoice) through the MCP protocol.
- Incoming commands are delegated to the appropriate Handler in the src/handlers directory.
- Handlers make use of the Xero API Client to perform the underlying operations (e.g., querying contacts, creating invoices) via OAuth2.
- Utilities and helper functions support these operations (e.g., error formatting or tool registration).
- The Tools serve as additional entry points for the same functionalities provided by the handlers, ensuring command line or scripting support.
- The overall flow follows a pattern where external inputs (MCP commands) are validated, processed by dedicated handlers, and then serviced via external API calls to Xero.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: Different directories manage different responsibilities (handlers for business logic, clients for API communication, tools for CLI support).
- Modularity: Each MCP command is implemented as an independent module, making it easy to maintain and extend the system.
- Protocol Compliance: The design emphasizes adherence to the MCP protocol, ensuring interoperability with platforms like Claude Desktop.
- Extendability: The use of type definitions and modular handlers allows for future expansion or adaptation to additional Xero API endpoints.

##### Relevant Technologies and Frameworks
- Node.js with TypeScript for server-side scripting.
- OAuth2 for secure authentication with Xero.
- MCP protocol as the core integration standard.
- Standard Node configuration tools (package.json, tsconfig.json, etc.) ensuring consistency across the development and build processes.

##### Final Detailed Steps for the Principal Software Engineer
- Demonstrate that each handler utilizes the Xero API Client (src/clients) to interact with Xero, and then returns responses back via the MCP Server.
- Optionally, illustrate parallel execution paths for CLI tools in the src/tools directory.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Layer
    subgraph "External Layer"
        ext["MCP Client (Claude Desktop)"]:::external
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        server["MCP Server"]:::server
        handlers["Command Handlers"]:::handlers
        tools["Tools/CLI"]:::tools
    end

    %% Integration Layer
    subgraph "Integration Layer"
        client["Xero API Client"]:::client
    end

    %% Support Layer
    subgraph "Support Layer"
        helpers["Helpers"]:::helpers
        types["Types Definitions"]:::types
    end

    %% Relationships
    ext -->|"sends_command"| server
    server -->|"dispatches_to"| handlers
    server -->|"invokes_tool"| tools
    handlers -->|"calls_api"| client
    tools -->|"calls_api"| client
    handlers -->|"uses_helper"| helpers
    handlers -->|"uses_types"| types
    tools -->|"uses_helper"| helpers
    tools -->|"uses_types"| types

    %% Click Events
    click server "https://github.com/xeroapi/xero-mcp-server/blob/main/src/server/xero-mcp-server.ts"
    click handlers "https://github.com/xeroapi/xero-mcp-server/tree/main/src/handlers"
    click client "https://github.com/xeroapi/xero-mcp-server/blob/main/src/clients/xero-client.ts"
    click tools "https://github.com/xeroapi/xero-mcp-server/tree/main/src/tools"
    click helpers "https://github.com/xeroapi/xero-mcp-server/tree/main/src/helpers"
    click types "https://github.com/xeroapi/xero-mcp-server/tree/main/src/types"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef server fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef handlers fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef tools fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef client fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef helpers fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef types fill:#ADD8E6,stroke:#333,stroke-width:2px;
```
