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

npm install -g haloapi-mcp-tools

Local Installation

npm install haloapi-mcp-tools

Configuration

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

# 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

# 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:

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:

# 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

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:

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:

DEBUG=true haloapi-mcp-server

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

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

# 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

npm run build:haloapi

2. Use the integration script to configure Claude Desktop:

   # 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)