haloapi-mcp-tools/docs/CLAUDE_DESKTOP.md

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

# HaloPSA Integration for Claude Desktop

This guide explains how to set up and use the HaloPSA API MCP tools with Claude Desktop.

## Overview

The HaloPSA MCP tools provide a way for Claude Desktop to interact with the HaloPSA API, allowing you to perform operations like ticket management, user management, and asset management directly from Claude.

## Installation

### Prerequisites

- Node.js v18 or higher
- Claude Desktop application
- HaloPSA API credentials (Client ID and Client Secret, or API Key)

### Installation Steps

1. Install the package globally:

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

Or clone the repository and install locally:

```bash
git clone https://github.com/sulemanmanji/haloapi-mcp-tools.git
cd haloapi-mcp-tools
npm install
```

2. Make the desktop MCP script executable:

```bash
chmod +x bin/desktop-mcp
```

## Configuration

### Option 1: Using Claude Desktop Configuration (Recommended)

Claude Desktop stores configuration in `~/Library/Application Support/Claude/claude_desktop_config.json` (on macOS). The MCP server will automatically read HaloPSA API credentials from this file.

#### Standard Configuration (mcpServers Object)

1. Open the Claude Desktop configuration file in a text editor
2. Add the HaloPSA MCP server to the configuration:

```json
{
  "mcpServers": {
    "halopsa": {
      "command": "node",
      "args": ["/absolute/path/to/haloapi-mcp-tools/bin/desktop-mcp"],
      "env": {
        "HALOPSA_API_URL": "https://your-instance.haloservicedesk.com/api",
        "HALOPSA_AUTH_URL": "https://your-instance.haloservicedesk.com/auth/token",
        "HALOPSA_CLIENT_ID": "your-client-id",
        "HALOPSA_CLIENT_SECRET": "your-client-secret",
        "HALOPSA_SCOPE": "all",
        "DEBUG": "false"
      }
    }
  }
}
```

3. Save the file and restart Claude Desktop

#### Alternative Configuration (haloapi Object)

This is an alternative format that's also supported:

```json
{
  "haloapi": {
    "url": "https://your-instance.haloservicedesk.com/api",
    "tokenUrl": "https://your-instance.haloservicedesk.com/auth/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scope": "all"
  }
}
```

#### API Key Authentication

If you're using API key authentication instead of OAuth, use this format:

```json
{
  "mcpServers": {
    "halopsa": {
      "command": "node",
      "args": ["/absolute/path/to/haloapi-mcp-tools/bin/desktop-mcp"],
      "env": {
        "HALOPSA_API_URL": "https://your-instance.haloservicedesk.com/api",
        "HALOPSA_API_KEY": "your-api-key-here",
        "DEBUG": "false"
      }
    }
  }
}
```

### Option 2: Using Environment Variables

You can also configure the MCP server using environment variables. Create a `.env` file in the root directory with the following variables:

```
HALO_API_URL=https://your-instance.haloservicedesk.com/api
HALO_TOKEN_URL=https://your-instance.haloservicedesk.com/auth/token
HALO_CLIENT_ID=your-client-id
HALO_CLIENT_SECRET=your-client-secret
HALO_SCOPE=all
```

Or for API key authentication:

```
HALO_API_URL=https://your-instance.haloservicedesk.com/api
HALO_API_KEY=your-api-key-here
```

## Running with Claude Desktop

1. Configure Claude Desktop to use this MCP tool:
   - Open Claude Desktop settings
   - Go to the "Tools" or "Integrations" section
   - Add a new MCP server with the path to the `bin/desktop-mcp` executable

2. Start using HaloPSA tools in your conversations with Claude.

## Available Tools

### Ticket Management

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

### User Management

- `halo-get-users`: Get a list of users
- `halo-get-user`: Get detailed information about a specific user

### Asset Management

- `halo-get-assets`: Get a list of assets
- `halo-get-asset`: Get detailed information about a specific asset

## Examples

Here are some examples of how to use the tools with Claude:

### Get Tickets

```
Could you get a list of my open tickets from HaloPSA?
```

Claude will use the `halo-get-tickets` tool with the appropriate parameters.

### Create a Ticket

```
Please create a new ticket in HaloPSA with the subject "Network printer offline" and description "The printer on the second floor is not responding".
```

Claude will use the `halo-create-ticket` tool to create the ticket.

## Troubleshooting

### Authentication Issues

If you encounter authentication issues:

1. Verify your API credentials are correct (Client ID/Secret or API Key)
2. Ensure the API URL and auth URL are correctly specified
3. Check if your API credentials have the necessary permissions

### Tool Not Found

If Claude cannot find the tools:

1. Ensure the `desktop-mcp` script is executable
2. Verify the path to the executable in Claude Desktop settings
3. Try restarting Claude Desktop

### Debug Mode

To run the MCP server in debug mode for troubleshooting, add the following to your Claude Desktop configuration:

```json
"env": {
  "DEBUG": "true",
  ...
}
```

Or run the MCP server directly with:

```bash
DEBUG=true bin/desktop-mcp
```

### Houston Tech Dev Configuration

If you're connecting to the Houston Tech Dev HaloPSA instance, your configuration would look like:

```json
{
  "haloapi": {
    "url": "https://houstontechdev.halopsa.com/api",
    "tokenUrl": "https://houstontechdev.halopsa.com/auth/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scope": "all"
  }
}
```

## Advanced Usage

### Custom Server Name

By default, the MCP server looks for a configuration named `halopsa` in the Claude Desktop config. If you need to use a different name, use the `--server-name` option:

```bash
bin/desktop-mcp --server-name custom-name
```

Your configuration would then look like:

```json
{
  "mcpServers": {
    "custom-name": {
      "command": "node",
      "args": [...],
      "env": {...}
    }
  }
}
```

### Response Formatting

The HaloPSA MCP tools include enhanced response formatting for Claude Desktop. This ensures that responses are nicely formatted and easy to read. You can disable this with:

```
ENHANCED_FORMATTING=false
```

### Multiple Authentication Methods

The MCP server supports both OAuth 2.0 (with Client ID and Secret) and API Key authentication. You can configure both in your environment variables and the server will use the appropriate method based on which credentials are available.

## Security Considerations

### Credential Storage

The HaloPSA API credentials are sensitive information. Here are some recommendations for secure handling:

1. **Environment Variables**: Store credentials as environment variables in the Claude Desktop configuration
2. **Secure Storage**: Use a secure credential storage solution when possible
3. **Scope Limitation**: Request only the necessary API permissions (scope)
4. **API Key Security**: If using API key authentication, ensure the key has limited permissions

### Local Usage

The MCP server is designed to run locally on your machine. It communicates with Claude Desktop using a local interface, which means your API credentials aren't transmitted to external services beyond the HaloPSA API.

## Support and Feedback

If you encounter any issues or have feedback:

1. Open an issue on GitHub: [https://github.com/sulemanmanji/haloapi-mcp-tools/issues](https://github.com/sulemanmanji/haloapi-mcp-tools/issues)
2. Contact the maintainer: Suleman Manji

## License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Last updated: March 24, 2025