Skip to main content
Glama
Sign In
enesjakozh

HaloPSA MCP Tools

by ssmanji89
npmGitHub
JavaScript
MIT License
74
  • Apple
  • Linux
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Uses .env files for configuration management, allowing easy setup of API credentials and server options.

  • Supports platform-specific logging locations for Claude Desktop integration on Linux.

  • Supports platform-specific logging locations for Claude Desktop integration on macOS.

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
  • Seamless integration with Claude Desktop
  • Configurable logging and error handling
  • Robust security checks
  • Cross-version compatibility with MCP SDK

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 # Command-line options are also available haloapi-mcp-server --transport http --port 3000 --debug

Using with Claude Desktop

To use with Claude Desktop:

  1. Install the package globally:
npm install -g haloapi-mcp-tools
  1. 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
  2. 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 # Or use the convenience script ./run-mcp.sh desktop

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

Structure

The codebase is organized with the following structure:

  • src/core/ - Core MCP server implementation
  • src/tools/ - Tool definitions for HaloPSA API operations
  • src/utils/ - Utility functions for logging, validation, etc.
  • src/services/ - Service layer for HaloPSA API operations
  • src/api/ - API clients for HaloPSA
  • bin/ - Executable entry points
  • scripts/ - Utility scripts for development and maintenance

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

Claude Desktop Integration

The package includes a unified implementation for Claude Desktop integration that works across different MCP SDK versions.

Key features of the unified implementation:

  • Cross-version compatibility through the SDK compatibility layer
  • Automatic configuration detection from Claude Desktop settings
  • Robust error handling and fallback mechanisms
  • Comprehensive logging and debugging support

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 the latest version of this package which includes the unified MCP implementation with robust support for the MCP protocol.

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: The latest version 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

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

Testing

You can test the MCP server using the included test script:

# Run the test script against a running server npm run test:mcp # Run the automated tests npm test

The interactive test script allows you to test individual tools and inspect their responses, which is useful for debugging and development.

Development and Extension

The codebase follows several design patterns and practices that should be followed when adding new features or making changes:

Design Patterns

  1. Compatibility Layer Pattern: Used in src/sdk-compat.js to provide a consistent interface across different SDK versions.
  2. Dependency Injection: Used throughout the codebase to provide dependencies to modules, making them easier to test and more modular.
  3. Module Pattern: Each component is organized into modules with clear responsibilities and interfaces.
  4. Facade Pattern: The main entry points (desktop-mcp-unified.js, standalone-mcp.js) provide simplified interfaces to the underlying functionality.

Adding New Features

When adding new features to the codebase, follow these steps:

  1. Add new tool definitions to the appropriate module in src/tools/
  2. Register the new tools in src/tools/index.js
  3. Add any new utility functions to the appropriate module in src/utils/
  4. Write tests for the new functionality in the tests/ directory
  5. Update the documentation to reflect the new features

License

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

Contributors

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

Model Context Protocol server for interacting with the HaloPSA API, enabling AI assistants like Claude to manage tickets, users, and assets in HaloPSA through natural language.

  1. Overview
    1. Features
      1. Installation
        1. NPM Global Installation
        2. Local Installation
      2. Configuration
        1. Usage
          1. Using as a Standalone Server
          2. Using with Claude Desktop
          3. Using as a Library
        2. Structure
          1. MCP Tools
            1. Ticket Tools
            2. User Tools
            3. Asset Tools
            4. Standard MCP Methods
          2. Claude Desktop Integration
            1. Troubleshooting
              1. Common Issues
              2. Debugging
              3. Testing
            2. Development and Extension
              1. Design Patterns
              2. Adding New Features
            3. License
              1. Contributors
                ID: fum88zvdnm