haloapi-mcp-tools/docs/TOOLS.md

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

# HaloPSA MCP Server Tools

This document describes the tools available in the HaloPSA MCP Server and how to use them.

## Overview

The HaloPSA MCP Server exposes the following tools for interacting with the HaloPSA API:

| Tool Name | Description |
|-----------|-------------|
| 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 in the system |
| update-ticket | Update an existing ticket |
| delete-ticket | Delete a ticket from the system |
| add-comment | Add a comment to an existing ticket |
| get-users | Get a list of users with optional filtering |
| get-user | Get detailed information about a specific user |
| get-assets | Get a list of assets with optional filtering |
| get-asset | Get detailed information about a specific asset |

## Ticket Tools

### get-tickets

Retrieves a list of tickets with optional filtering.

**Parameters:**

- `status` (optional): Filter by ticket status ("open", "closed", "pending", "resolved")
- `priority` (optional): Filter by priority level ("low", "medium", "high", "critical")
- `page` (optional): Page number for pagination (default: 1)
- `pageSize` (optional): Number of items per page (default: 25, max: 100)

**Example in Claude:**

```
Can you show me all open tickets with high priority?
```

### get-ticket

Retrieves detailed information about a specific ticket.

**Parameters:**

- `id` (required): The ticket ID

**Example in Claude:**

```
Can you get the details for ticket #12345?
```

### create-ticket

Creates a new ticket in the system.

**Parameters:**

- `subject` (required): The ticket subject
- `description` (optional): Detailed description of the issue
- `priority` (optional): Ticket priority level ("low", "medium", "high", "critical")
- `requesterId` (required): ID of the user who created the ticket
- `categoryId` (optional): Category ID for the ticket

**Example in Claude:**

```
Create a new ticket with the subject "Email server down" for user 101
```

### update-ticket

Updates an existing ticket.

**Parameters:**

- `id` (required): The ticket ID to update
- `subject` (optional): The ticket subject
- `description` (optional): Detailed description of the issue
- `status` (optional): Ticket status ("open", "closed", "pending", "resolved")
- `priority` (optional): Ticket priority level ("low", "medium", "high", "critical")
- `assigneeId` (optional): ID of the agent assigned to the ticket

**Example in Claude:**

```
Update ticket #12345 to change the status to resolved
```

### delete-ticket

Deletes a ticket from the system.

**Parameters:**

- `id` (required): The ticket ID to delete

**Example in Claude:**

```
Delete ticket #12345
```

### add-comment

Adds a comment to an existing ticket.

**Parameters:**

- `ticketId` (required): The ticket ID to add a comment to
- `content` (required): The comment content/text
- `authorId` (required): ID of the comment author
- `isPublic` (optional): Whether the comment is visible to the customer (default: true)

**Example in Claude:**

```
Add a comment to ticket #12345 saying "I've reset the user's password"
```

## User Tools

### get-users

Retrieves a list of users with optional filtering.

**Parameters:**

- `role` (optional): Filter by user role ("admin", "agent", "customer")
- `page` (optional): Page number for pagination (default: 1)
- `pageSize` (optional): Number of items per page (default: 25, max: 100)

**Example in Claude:**

```
Show me all support agents in the system
```

### get-user

Retrieves detailed information about a specific user.

**Parameters:**

- `id` (required): The user ID

**Example in Claude:**

```
Get details for user #101
```

## Asset Tools

### get-assets

Retrieves a list of assets with optional filtering.

**Parameters:**

- `type` (optional): Filter by asset type
- `status` (optional): Filter by asset status ("active", "inactive", "maintenance", "retired")
- `page` (optional): Page number for pagination (default: 1)
- `pageSize` (optional): Number of items per page (default: 25, max: 100)

**Example in Claude:**

```
Show me all active laptops in the system
```

### get-asset

Retrieves detailed information about a specific asset.

**Parameters:**

- `id` (required): The asset ID

**Example in Claude:**

```
Show me details for asset #5001
```

## Tool Response Format

All tools return responses with a consistent format:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Response content here"
    }
  ]
}
```

For unsuccessful operations, the response includes an `isError` flag:

```json
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error message here"
    }
  ]
}
```

## Using Tools in Scripts

If you're building your own MCP client, you can call these tools programmatically. Here's an example of how to call the `get-tickets` tool:

```javascript
// Example using the MCP client SDK
const result = await mcpClient.callTool({
  name: 'get-tickets',
  arguments: {
    status: 'open',
    priority: 'high'
  }
});

console.log(result.content[0].text);
```

## Tool Validation

All tools perform validation on their inputs. If an input doesn't meet the required format, the tool will return an error message explaining the issue.