# HaloPSA MCP Server Architecture

This document outlines the architecture of the HaloPSA MCP Server, describing its components and how they interact.

## Overview

The HaloPSA MCP Server is a middleware that exposes HaloPSA API functionality via the Model Context Protocol (MCP). It allows MCP-compatible clients, such as Claude Desktop, to interact with HaloPSA's ticketing and service management features.

## Components

### Server Core

The main entry point (`src/index.js`) that sets up the MCP server, registers tools, and handles connections.

### API Client

Located in `src/client/api-client.js`, this component handles direct communication with the HaloPSA API. It:

- Manages authentication via API keys
- Abstracts API endpoints into easy-to-use methods
- Handles error management and retry logic
- Provides a clean interface for the service layer

### Service Layer

The service layer (`src/services/`) contains the business logic for interacting with HaloPSA resources:

- **Ticket Service**: Handles ticket CRUD operations and comments
- **User Service**: Manages user-related operations
- **Asset Service**: Provides asset management functionality

### MCP Tools

The tools directory (`src/tools/`) defines MCP tools that are exposed to clients:

- **Ticket Tools**: Tools for ticket operations
- **User Tools**: Tools for user operations
- **Asset Tools**: Tools for asset operations
- **Tools Registry**: Consolidates all tools and registers them with the server

### Configuration

The configuration module (`src/config/index.js`) manages server settings and provides them to other components. It loads settings from environment variables with sensible defaults.

### Utilities

The utils directory (`src/utils/`) contains shared utilities:

- **Logger**: Configures and provides a winston logger instance

## Data Flow

1. A client connects to the MCP server via STDIO transport.
2. The client requests a list of available tools.
3. The client invokes a tool, providing arguments.
4. The tool handler processes the arguments and calls the appropriate service function.
5. The service function calls the API client to interact with the HaloPSA API.
6. The API client handles authentication and makes the actual HTTP request.
7. The response travels back through the chain to the client.

## Authentication

The server uses the HaloPSA API key for authentication. This key is provided via the `HALOPSA_API_KEY` environment variable.

## Error Handling

Error handling occurs at multiple levels:

1. **API Client**: Handles HTTP errors and retries
2. **Service Layer**: Adds business logic context to errors
3. **Tool Handlers**: Formats errors for MCP clients
4. **Server Core**: Handles process-level errors and termination signals

## Future Enhancements

Potential areas for improvement include:

- Adding more sophisticated ticket routing logic
- Implementing analytics capabilities
- Adding support for MCP resources to expose data like ticket metrics
- Supporting MCP prompts for common HaloPSA operations