HaloPSA MCP Tools

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

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

• 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

npm install -g haloapi-mcp-tools

npm install haloapi-mcp-tools

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.

# 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

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.

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

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

• 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

• 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

• 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

• 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

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

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.

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

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.

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.

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'.

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

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

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.

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

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.

# 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

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

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

• Suleman Manji (@ssmanji89)