haloapi-mcp-tools/docs/usage-guide.md

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

# HaloPSA MCP Tools Usage Guide

This guide provides detailed instructions on how to use the HaloPSA MCP Tools package in various scenarios. It includes setup, configuration, and usage examples.

## Table of Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Integrating with Claude](#integrating-with-claude)
- [Troubleshooting](#troubleshooting)

## Installation

### npm Installation

Install the package from npm:

```bash
npm install haloapi-mcp-tools
```

### Manual Installation

Alternatively, you can clone the repository and install it locally:

```bash
git clone https://github.com/yourusername/haloapi-mcp-tools.git
cd haloapi-mcp-tools
npm install
npm run build
```

## Configuration

### Environment Variables

The HaloPSA MCP Tools package uses environment variables for configuration. Create a `.env` file in your project root with the following variables:

```
# HaloPSA API Authentication
HALO_CLIENT_ID=your_client_id_here
HALO_CLIENT_SECRET=your_client_secret_here
HALO_TOKEN_URL=https://your-instance.haloservicedesk.com/api/token

# HaloPSA API Configuration
HALO_API_URL=https://your-instance.haloservicedesk.com/api
HALO_API_VERSION=v3
HALO_API_TIMEOUT=30000

# MCP Server Configuration
DEBUG=false
LOG_LEVEL=info
MCP_VERSION=1.0.0
TOOL_PREFIX=halo

# Features
AUTO_RETRY=true
MAX_RETRY_ATTEMPTS=3
```

### Configuration in Code

You can also configure the package programmatically:

```javascript
// Set environment variables before requiring the package
process.env.HALO_CLIENT_ID = 'your_client_id';
process.env.HALO_CLIENT_SECRET = 'your_client_secret';
process.env.HALO_API_URL = 'https://your-instance.haloservicedesk.com/api';

// Then require the package
const haloMcpTools = require('haloapi-mcp-tools');
```

## Basic Usage

### Starting the MCP Server

The easiest way to start the MCP server is to use the provided CLI:

```bash
# If installed globally
haloapi-mcp-tools

# If installed locally
npx haloapi-mcp-tools
```

### Using as a Library

You can also use the package as a library in your code:

```javascript
const { Server } = require('@modelcontextprotocol/sdk/server');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio');
const { registerTools } = require('haloapi-mcp-tools');

async function main() {
  // Create MCP server
  const server = new Server({
    name: 'halopsa-mcp-server',
    version: '1.0.0'
  }, {
    capabilities: {
      tools: {}
    }
  });
  
  // Register HaloPSA tools
  registerTools(server);
  
  // Create transport
  const transport = new StdioServerTransport();
  
  // Connect server to transport
  await server.connect(transport);
  
  console.log('HaloPSA MCP Server running');
}

main().catch(console.error);
```

## Advanced Usage

### Creating a Client

To use the MCP server from a client application, use the MCP client SDK:

```javascript
const { Client } = require('@modelcontextprotocol/sdk/client');
const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio');
const { spawn } = require('child_process');

async function main() {
  // Start the server as a child process
  const serverProcess = spawn('npx', ['haloapi-mcp-tools']);
  
  // Create a transport to the server
  const transport = new StdioClientTransport(
    serverProcess.stdin,
    serverProcess.stdout
  );
  
  // Create a client
  const client = new Client();
  
  // Connect to the server
  await client.connect(transport);
  
  // Get server info
  const info = await client.getInfo();
  console.log('Server info:', info);
  
  // Get available tools
  const tools = await client.getTools();
  console.log('Available tools:', tools.map(tool => tool.name).join(', '));
  
  // Use a tool
  const result = await client.invokeTool('halo-get-tickets', { 
    status: 'open',
    page: 1,
    pageSize: 10
  });
  console.log('Tickets:', result);
  
  // Clean up
  await client.close();
  serverProcess.kill();
}

main().catch(console.error);
```

### Custom Error Handling

You can add custom error handling to handle different scenarios:

```javascript
try {
  const result = await client.invokeTool('halo-get-ticket', { id: 1001 });
  console.log('Ticket:', result);
} catch (error) {
  if (error.message.includes('Authentication failed')) {
    console.error('Authentication failed. Check your credentials.');
  } else if (error.message.includes('not found')) {
    console.error('Ticket not found. Check the ID and try again.');
  } else {
    console.error('An error occurred:', error.message);
  }
}
```

## Integrating with Claude

The primary use case for the HaloPSA MCP Tools is integration with Claude or other AI assistants that support the MCP protocol.

### Claude Integration Example

Here's how to use the HaloPSA MCP Tools with Claude:

```javascript
const { spawn } = require('child_process');
const Claude = require('claude-sdk'); // This is a hypothetical SDK

async function main() {
  // Start the HaloPSA MCP server
  const serverProcess = spawn('npx', ['haloapi-mcp-tools']);
  
  // Initialize Claude
  const claude = new Claude({
    apiKey: 'your-claude-api-key',
    mcpServers: [
      {
        name: 'HaloPSA',
        command: 'npx haloapi-mcp-tools',
        description: 'HaloPSA service desk management tools'
      }
    ]
  });
  
  // Use Claude with the MCP server
  const response = await claude.complete({
    prompt: `
      I need help managing HaloPSA tickets. Can you help me get a list of open tickets?
      Use the halo-get-tickets tool to show me all open tickets.
    `,
    tools: ['HaloPSA']
  });
  
  console.log('Claude response:', response);
  
  // Clean up
  serverProcess.kill();
}

main().catch(console.error);
```

## Troubleshooting

### Common Issues

#### Authentication Errors

If you encounter authentication errors:

1. Verify your `HALO_CLIENT_ID` and `HALO_CLIENT_SECRET` are correct
2. Check that your `HALO_TOKEN_URL` points to the correct endpoint
3. Make sure your HaloPSA instance is accessible

#### Connection Issues

If the client cannot connect to the server:

1. Check that the server is running
2. Verify that the transport is correctly configured
3. Look for error messages in the server logs

#### Tool Invocation Errors

If tool invocation fails:

1. Verify that the tool name is correct (including the prefix)
2. Check that all required parameters are provided
3. Make sure the parameters have the correct types

### Logging

Enable debug logging for more detailed information:

```
DEBUG=true
LOG_LEVEL=debug
```

This will output detailed logs that can help identify the source of issues.

### Getting Help

If you encounter issues that are not covered in this guide:

1. Check the [API Reference](api.md) for detailed information on tools and parameters
2. Look for similar issues in the [GitHub repository](https://github.com/yourusername/haloapi-mcp-tools/issues)
3. Open a new issue with detailed information about your problem