haloapi-mcp-tools/README.md

Model Context Protocol (MCP) server for interacting with the HaloPSA API

# HaloPSA MCP Tools

Model Context Protocol (MCP) server for interacting with the HaloPSA API.

## Overview

This package provides a Model Context Protocol server implementation that allows AI assistants (like Claude) to interact with the HaloPSA API. It can be used in various configurations:

- As a standalone server
- Integrated with Claude Desktop
- As a library in Node.js applications
- As a TypeScript MCP server with direct implementation

## Features

- MCP server with support for multiple transport types (stdio, http, tcp)
- Tools for interacting with tickets, users, assets, and more
- Integration with Claude Desktop
- Configurable logging and error handling
- Robust security checks

## Installation

### NPM Global Installation

```bash
npm install -g haloapi-mcp-tools
```

### Local Installation

```bash
npm install haloapi-mcp-tools
```

## Configuration

Create a `.env` file in your project root with the following environment variables:

```env
# Required HaloPSA API Configuration
HALO_API_URL=https://yourhalo.haloservicedesk.com/api
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret

# Optional Configuration
HALO_API_VERSION=v3
HALO_SCOPE=all
HALO_TENANT=your_tenant_id
TRANSPORT=stdio
PORT=3000
DEBUG=false
```

Alternatively, you can use Claude Desktop's configuration if the tool is running as a Claude Desktop integration.

## Usage

### Using as a Standalone Server

```bash
# Start the server using stdio transport (default)
haloapi-mcp-server

# Start with HTTP transport
TRANSPORT=http PORT=3000 haloapi-mcp-server

# Start with debug mode
DEBUG=true haloapi-mcp-server
```

### Using with Claude Desktop

To use with Claude Desktop:

1. Install the package globally:
```bash
npm install -g haloapi-mcp-tools
```

2. Configure Claude Desktop to use this MCP server in the Claude Desktop settings (Settings > Extensions > Add MCP Server):
   - Name: HaloPSA
   - Command: haloapi-desktop-mcp
   - Environment Variables (optional):
     - HALO_API_URL: Your HaloPSA API URL
     - HALO_CLIENT_ID: Your client ID
     - HALO_CLIENT_SECRET: Your client secret

3. Start using the HaloPSA tools in your Claude conversations!

Alternatively, if you've cloned this repository, you can run:
```bash
# Run the MCP server for Claude Desktop
npm run claude

# Run with debug logging
npm run claude:debug
```

The MCP server will automatically detect and use the configuration from your Claude Desktop settings.

### Using as a Library

```javascript
const { startServer } = require('haloapi-mcp-tools');

async function main() {
  const server = await startServer({
    transport: 'stdio', // or 'http', 'tcp'
    port: 3000,
    debug: true,
    haloBaseUrl: 'https://yourhalo.haloservicedesk.com/api',
    haloClientId: 'your_client_id',
    haloClientSecret: 'your_client_secret'
  });
  
  // Server is now running
  console.log('Server started successfully');
  
  // To shut down the server
  // await server.close();
}

main().catch(console.error);
```

## MCP Tools

This package provides several tools for interacting with HaloPSA and implements standard MCP protocol methods required by Claude Desktop:

### Ticket Tools

- `get-tickets`: Get a list of tickets with optional filtering
- `get-ticket`: Get detailed information about a specific ticket
- `create-ticket`: Create a new ticket
- `update-ticket`: Update an existing ticket
- `delete-ticket`: Delete a ticket
- `get-ticket-comments`: Get comments for a specific ticket
- `add-comment`: Add a comment to a ticket

### User Tools

- `get-users`: Get a list of users with optional filtering
- `get-user`: Get detailed information about a specific user
- `create-user`: Create a new user
- `update-user`: Update an existing user
- `delete-user`: Delete a user
- `get-agents`: Get a list of agents

### Asset Tools

- `get-assets`: Get a list of assets with optional filtering
- `get-asset`: Get detailed information about a specific asset
- `create-asset`: Create a new asset
- `update-asset`: Update an existing asset
- `delete-asset`: Delete an asset
- `get-asset-types`: Get a list of all asset types

### Standard MCP Methods

- `resources/list`: List all available resources in the MCP server
- `prompts/list`: List all available prompts for Claude Desktop integration
- `tools/list`: List all available tools in the MCP server

## Developer Notes

### Module System Compatibility

This package supports both CommonJS and ESM modules. The core implementation uses CommonJS, but it can work with ESM-based dependencies through careful handling of imports.

If you encounter issues with the module system, you can:

1. Use the `.cjs` extension for CommonJS files
2. Use dynamic imports for ESM dependencies
3. Update package.json with appropriate `type` and `exports` fields

### Minimal MCP Implementation

The package includes a minimal MCP server implementation that handles basic protocol features without requiring external dependencies. This makes it compatible with both CommonJS and ESM environments.

### Security Considerations

- All API credentials are validated before use
- HTTPS connections are enforced for API communication
- Environment variable checks ensure proper configuration

## Troubleshooting

### Common Issues

#### Module Imports

If you encounter errors related to imports or module systems:

```
SyntaxError: Cannot use import statement outside a module
```

Solution: Check that you're using the correct import syntax for your project configuration. This package primarily uses CommonJS, so use `require()` statements.

#### Authentication Errors

If you see errors related to HaloPSA authentication:

```
Error: Invalid client credentials
```

Solution: Verify your client ID and client secret in the environment variables or configuration.

#### Transport Issues

If the server fails to start with a specific transport type:

```
Error: Unsupported transport
```

Solution: Ensure you're using one of the supported transport types: 'stdio', 'http', or 'tcp'.

#### Claude Desktop Integration Issues

If Claude Desktop is unable to connect to your MCP server or shows errors about unsupported methods:

```
Error: Method not supported: tools/list
```

Solution: Make sure you're using version 1.1.0 or later of this package which includes the standard MCP methods required by Claude Desktop (`resources/list`, `prompts/list`, and `tools/list`).

#### JSON Parsing Errors

If you're seeing JSON parsing errors in the MCP server logs like:

```
Error parsing JSON message: Unexpected non-whitespace character after JSON at position X
```

Solution: Version 1.1.0 and later includes enhanced JSON handling that automatically fixes common issues with malformed messages. If you're still experiencing problems, enable debug mode to see more details:

```bash
DEBUG=true haloapi-mcp-server
```

#### Zod Validation Errors

If you see errors related to Zod validation in the logs:

```
ZodError: Invalid input
```

Solution: This is fixed in version 1.1.0 with improved response formatting. Update to the latest version or check that your response format matches the JSON-RPC 2.0 specification with the appropriate MCP protocol extensions.

### Debugging

To enable detailed debugging information, set the DEBUG environment variable:

```bash
DEBUG=true haloapi-mcp-server
```

You can also increase the log level for even more detailed information:

```bash
LOG_LEVEL=trace haloapi-mcp-server
```

For Claude Desktop integration, you can find logs in the following locations:

- macOS: `~/Library/Logs/Claude/mcp-server-halopsa.log`
- Windows: `%APPDATA%\Claude\Logs\mcp-server-halopsa.log`
- Linux: `~/.local/share/claude/logs/mcp-server-halopsa.log`

## TypeScript MCP Implementation

This package also includes a TypeScript implementation of the MCP server for those who prefer a more type-safe approach. The TypeScript implementation is located in the `src/haloapi` directory and can be built separately.

### Building and Testing the TypeScript Implementation

```bash
# Build the TypeScript implementation
npm run build:ts

# Build only the HaloAPI MCP server
npm run build:haloapi

# Test the TypeScript implementation
npm run test:ts
```

### Using the TypeScript MCP Server with Claude Desktop

To use the TypeScript implementation with Claude Desktop:

1. Build the TypeScript implementation
```bash
npm run build:haloapi
```

2. Use the integration script to configure Claude Desktop:
   ```bash
   # Set your HaloPSA API credentials as environment variables
   export HALO_API_URL=https://yourhalo.haloservicedesk.com/api
   export HALO_API_KEY=your-api-key
   
   # Run the integration script
   npm run integrate
   ```

   This will automatically configure Claude Desktop to use both the CommonJS and TypeScript implementations.

   Alternatively, you can manually configure Claude Desktop (Settings > Extensions > Add MCP Server):
   - Name: HaloAPI-TS
   - Command: node
   - Args: /path/to/haloapi-mcp-tools/src/haloapi/dist/index.js
   - Environment Variables:
     - HALO_API_URL: Your HaloPSA API URL
     - HALO_API_KEY: Your API key

## License

MIT License Copyright (c) 2025 sulemanji.com MCP Team

## Contributors

- Suleman Manji ([@ssmanji89](https://github.com/ssmanji89))