HaloPSA Workflows MCP

A TypeScript/JavaScript MCP server for interacting with HaloPSA Workflows API, with enhanced compatibility and reliability features.

Architecture

This implementation consists of three main components:

1. Direct HaloPSA API Implementation (src/halopsa-direct.js): A clean, focused implementation that handles authentication and API calls directly to the HaloPSA API.

2. MCP Compatibility Layer (src/mcp-compatibility.js): Ensures cross-compatibility between different MCP protocol implementations, including FastMCP, Azure MCP, and Browser-use MCP server.

3. MCP Wrapper (src/halopsa-mcp.js): A thin wrapper around the direct implementation that provides the MCP interface for Claude Desktop and other AI assistants.

Key Features

• Reliable Claude Desktop integration with proper connection handling
• Cross-compatible with multiple MCP protocol implementations
• Tenant parameter for authentication
• Proper scope parameter for API access
• Case-sensitive API endpoint handling
• Clear error messaging
• Token caching for performance
• Detailed logging
• Graceful shutdown handling

Tools Provided

The MCP server provides the following tools to Claude and other compatible AI assistants:

• getWorkflows: Get a list of workflows from HaloPSA
• getWorkflowSteps: Get a list of workflow steps from HaloPSA
• getWorkflow: Get a single workflow from HaloPSA by ID
• deleteWorkflow: Delete a workflow from HaloPSA by ID
• createWorkflows: Create new workflows in HaloPSA

Installation

From Source

# Clone the repository
git clone https://github.com/ssmanji89/halopsa-workflows-mcp.git
cd halopsa-workflows-mcp

# Install dependencies
npm install

# Create a .env file (see below)
cp .env.example .env
# Edit the .env file with your credentials

# Start the server
npm start

Configuration

Create a .env file with your HaloPSA API credentials:

# HaloPSA API Configuration
HALOPSA_BASE_URL=https://your-instance.halopsa.com
HALOPSA_CLIENT_ID=your-client-id
HALOPSA_CLIENT_SECRET=your-client-secret
HALOPSA_TENANT=your-tenant-name
HALOPSA_SCOPE=all
LOG_LEVEL=info

Important Notes

1. The HALOPSA_BASE_URL should not include trailing slashes or "/api"
2. The HALOPSA_TENANT is required for authentication
3. The HALOPSA_SCOPE must be set (default is "all")
4. For debugging, set LOG_LEVEL=debug

Claude Desktop Integration

To integrate with Claude Desktop, create a claude_desktop_config.json file in the appropriate location for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Example configuration:

{
  "halopsa-workflows": {
    "command": "npx",
    "args": ["-y", "halopsa-workflows-mcp@latest"],
    "env": {
      "HALOPSA_BASE_URL": "https://your-instance.halopsa.com",
      "HALOPSA_CLIENT_ID": "your-client-id",
      "HALOPSA_CLIENT_SECRET": "your-client-secret",
      "HALOPSA_TENANT": "your-tenant-name"
    }
  }
}

For development, you can point to your local build:

{
  "halopsa-workflows": {
    "command": "node",
    "args": ["/path/to/halopsa-workflows-mcp/halopsa-mcp.js"],
    "env": {
      "HALOPSA_BASE_URL": "https://your-instance.halopsa.com",
      "HALOPSA_CLIENT_ID": "your-client-id",
      "HALOPSA_CLIENT_SECRET": "your-client-secret",
      "HALOPSA_TENANT": "your-tenant-name",
      "LOG_LEVEL": "debug"
    }
  }
}

Cross-Compatibility Features

This MCP server includes a compatibility layer that ensures seamless operation across different MCP implementations:

• Protocol Negotiation: Automatically detects and adapts to different MCP protocol versions
• Transport Compatibility: Works with both stdio and HTTP/SSE transport methods
• Error Handling: Enhanced error handling with fallback mechanisms for compatibility issues
• Client Adaptation: Adapts to different client initialization requirements

For more details on compatibility, see the COMPATIBILITY.md file.

Testing

Several test scripts are included to verify functionality and compatibility:

# Test direct API functionality
npm run test

# Test basic startup functionality
node test-startup.js

# Test MCP client compatibility
node test-fastmcp-client.js

# Test standalone FastMCP compatibility
node test-fastmcp.js

# Run comprehensive compatibility tests
node test-compatibility.js

Troubleshooting

Common Issues

1. Connection Errors: If you see messages like "Client disconnected unexpectedly", ensure you're using the latest version of the package and your claude_desktop_config.json is correct.

2. Authentication Failures: Ensure your HALOPSA_TENANT is correctly set alongside the client ID and secret.

3. API Errors: Check that your HALOPSA_BASE_URL does not include a trailing slash or "/api" suffix.

4. Compatibility Issues: If you encounter protocol compatibility issues, check the debug logs for details. Try running the compatibility test script to identify specific issues.

Debugging

To enable detailed logging, set LOG_LEVEL=debug in your .env file or in the environment variables for the claude_desktop_config.json.

Check the Claude Desktop logs for detailed error messages:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
Get-Content -Path "$env:APPDATA\Claude\Logs\mcp*.log" -Wait

# Linux
tail -f ~/.local/share/Claude/logs/mcp*.log

Development

For development with auto-reload:

npm run dev

Directory Structure

halopsa-workflows-mcp/
├── halopsa-mcp.js         # Main entry point (delegates to src/halopsa-mcp.js)
├── src/
│   ├── halopsa-direct.js  # Direct HaloPSA API implementation
│   ├── halopsa-mcp.js     # MCP server implementation
│   ├── mcp-compatibility.js # Compatibility layer for different MCP implementations
│   ├── index.js           # Exports for package use
│   └── ...                # Other source files
├── test-startup.js        # Simple startup test
├── test-fastmcp-client.js # MCP client test
├── test-compatibility.js  # Compatibility test
└── ...                    # Other files

License

MIT