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

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
2. Configure Claude Desktop to use this MCP server

haloapi-desktop-mcp

Claude Desktop will automatically find and use the configuration set in 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:

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

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

License

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

Contributors

• Suleman Manji (@ssmanji89)