How xeroapi/xero-mcp-server works
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.