# HaloPSA MCP Tools API Reference

This document provides a detailed reference for the HaloPSA MCP Tools API. It includes information on all available tools, their parameters, and usage examples.

## Table of Contents

- [Authentication](#authentication)
- [Ticket Tools](#ticket-tools)
- [User Tools](#user-tools)
- [Asset Tools](#asset-tools)
- [Error Handling](#error-handling)
- [Response Format](#response-format)

## Authentication

The HaloPSA MCP Tools handle authentication automatically using the provided credentials. Set the following environment variables to configure authentication:

```
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret
HALO_TOKEN_URL=https://your-instance.haloservicedesk.com/api/token
```

The client uses OAuth 2.0 Client Credentials grant flow to obtain an access token, which is automatically refreshed when needed.

## Ticket Tools

### `halo-get-tickets`

Retrieves a list of tickets with optional filtering.

**Parameters:**

```json
{
  "status": "string",     // Optional: Filter by status (open, closed, pending, resolved)
  "priority": "string",   // Optional: Filter by priority (low, medium, high, critical)
  "page": "integer",      // Optional: Page number for pagination (default: 1)
  "pageSize": "integer"   // Optional: Number of items per page (default: 25, max: 100)
}
```

**Response:**

```json
{
  "tickets": [
    {
      "id": 1001,
      "number": "TKT-1001",
      "subject": "Test Ticket",
      "description": "This is a test ticket",
      "status": "Open",
      "priority": "Medium",
      "assignedTo": "John Doe",
      "requester": "Jane Smith",
      "createdAt": "2023-01-01T09:00:00Z",
      "updatedAt": "2023-01-02T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-tickets', { 
  status: 'open',
  page: 1,
  pageSize: 10
});
```

### `halo-get-ticket`

Retrieves detailed information about a specific ticket.

**Parameters:**

```json
{
  "id": "integer"   // Required: The ticket ID
}
```

**Response:**

```json
{
  "id": 1001,
  "number": "TKT-1001",
  "subject": "Test Ticket",
  "description": "This is a test ticket with full details",
  "status": "Open",
  "priority": "Medium",
  "assignedTo": "John Doe",
  "requester": "Jane Smith",
  "createdAt": "2023-01-01T09:00:00Z",
  "updatedAt": "2023-01-02T10:00:00Z",
  "category": "Support",
  "team": "IT Support"
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-ticket', { 
  id: 1001
});
```

### `halo-create-ticket`

Creates a new ticket in the system.

**Parameters:**

```json
{
  "subject": "string",      // Required: The ticket subject
  "description": "string",  // Optional: Detailed description of the issue
  "priority": "string",     // Optional: Ticket priority level (low, medium, high, critical)
  "requesterId": "integer", // Required: ID of the user who created the ticket
  "categoryId": "integer"   // Optional: Category ID for the ticket
}
```

**Response:**

Success message with the ID of the created ticket.

**Example:**

```javascript
const result = await client.invokeTool('halo-create-ticket', { 
  subject: 'New Test Ticket',
  description: 'This is a test ticket created via MCP',
  priority: 'medium',
  requesterId: 101
});
```

### `halo-update-ticket`

Updates an existing ticket.

**Parameters:**

```json
{
  "id": "integer",         // Required: The ticket ID to update
  "subject": "string",     // Optional: The ticket subject
  "description": "string", // Optional: Detailed description of the issue
  "status": "string",      // Optional: Ticket status (open, closed, pending, resolved)
  "priority": "string",    // Optional: Ticket priority level (low, medium, high, critical)
  "assigneeId": "integer"  // Optional: ID of the agent assigned to the ticket
}
```

**Response:**

Success message with the ID of the updated ticket.

**Example:**

```javascript
const result = await client.invokeTool('halo-update-ticket', { 
  id: 1001,
  subject: 'Updated Test Ticket',
  status: 'resolved'
});
```

### `halo-delete-ticket`

Deletes a ticket from the system.

**Parameters:**

```json
{
  "id": "integer"  // Required: The ticket ID to delete
}
```

**Response:**

Success message with the ID of the deleted ticket.

**Example:**

```javascript
const result = await client.invokeTool('halo-delete-ticket', { 
  id: 1001
});
```

### `halo-get-ticket-comments`

Gets comments for a specific ticket.

**Parameters:**

```json
{
  "ticketId": "integer",  // Required: The ticket ID to get comments for
  "page": "integer",      // Optional: Page number for pagination (default: 1)
  "pageSize": "integer"   // Optional: Number of items per page (default: 25, max: 100)
}
```

**Response:**

```json
[
  {
    "id": 2001,
    "content": "This is a comment",
    "author": "John Doe",
    "createdAt": "2023-01-02T10:00:00Z",
    "isPublic": true
  }
]
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-ticket-comments', { 
  ticketId: 1001
});
```

### `halo-add-comment`

Adds a comment to an existing ticket.

**Parameters:**

```json
{
  "ticketId": "integer",  // Required: The ticket ID to add a comment to
  "content": "string",    // Required: The comment content/text
  "authorId": "integer",  // Optional: ID of the comment author
  "isPublic": "boolean"   // Optional: Whether the comment is visible to the customer (default: true)
}
```

**Response:**

Success message indicating the comment was added.

**Example:**

```javascript
const result = await client.invokeTool('halo-add-comment', { 
  ticketId: 1001,
  content: 'This is a new comment added via MCP',
  isPublic: true
});
```

## User Tools

### `halo-get-users`

Retrieves a list of users with optional filtering.

**Parameters:**

```json
{
  "role": "string",      // Optional: Filter by user role (agent, customer, admin)
  "active": "boolean",   // Optional: Filter by active status
  "page": "integer",     // Optional: Page number for pagination (default: 1)
  "pageSize": "integer"  // Optional: Number of items per page (default: 25, max: 100)
}
```

**Response:**

```json
{
  "users": [
    {
      "id": 101,
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "role": "agent",
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-users', { 
  role: 'agent',
  active: true
});
```

### `halo-get-user`

Retrieves detailed information about a specific user.

**Parameters:**

```json
{
  "id": "integer"  // Required: The user ID
}
```

**Response:**

```json
{
  "id": 101,
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "role": "agent",
  "active": true,
  "phone": "+1234567890",
  "department": "IT Support"
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-user', { 
  id: 101
});
```

### `halo-create-user`

Creates a new user in the system.

**Parameters:**

```json
{
  "firstName": "string",  // Required: User's first name
  "lastName": "string",   // Required: User's last name
  "email": "string",      // Required: User's email address
  "role": "string",       // Required: User role (agent, customer, admin)
  "phone": "string",      // Optional: User's phone number
  "department": "string"  // Optional: User's department
}
```

**Response:**

Success message with the ID of the created user.

**Example:**

```javascript
const result = await client.invokeTool('halo-create-user', { 
  firstName: 'Jane',
  lastName: 'Smith',
  email: 'jane.smith@example.com',
  role: 'customer'
});
```

### `halo-update-user`

Updates an existing user.

**Parameters:**

```json
{
  "id": "integer",       // Required: The user ID to update
  "firstName": "string", // Optional: User's first name
  "lastName": "string",  // Optional: User's last name
  "email": "string",     // Optional: User's email address
  "role": "string",      // Optional: User role (agent, customer, admin)
  "phone": "string",     // Optional: User's phone number
  "department": "string", // Optional: User's department
  "active": "boolean"    // Optional: User active status
}
```

**Response:**

Success message with the ID of the updated user.

**Example:**

```javascript
const result = await client.invokeTool('halo-update-user', { 
  id: 101,
  department: 'IT Management',
  role: 'admin'
});
```

### `halo-delete-user`

Deletes a user from the system.

**Parameters:**

```json
{
  "id": "integer"  // Required: The user ID to delete
}
```

**Response:**

Success message with the ID of the deleted user.

**Example:**

```javascript
const result = await client.invokeTool('halo-delete-user', { 
  id: 101
});
```

### `halo-get-agents`

Gets a list of agents (users with agent role).

**Parameters:**

```json
{
  "active": "boolean",   // Optional: Filter by active status
  "page": "integer",     // Optional: Page number for pagination (default: 1)
  "pageSize": "integer"  // Optional: Number of items per page (default: 25, max: 100)
}
```

**Response:**

```json
{
  "agents": [
    {
      "id": 101,
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "role": "agent",
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-agents', { 
  active: true
});
```

## Asset Tools

### `halo-get-assets`

Retrieves a list of assets with optional filtering.

**Parameters:**

```json
{
  "status": "string",    // Optional: Filter by asset status
  "typeId": "integer",   // Optional: Filter by asset type ID
  "name": "string",      // Optional: Filter by asset name (partial match)
  "page": "integer",     // Optional: Page number for pagination (default: 1)
  "pageSize": "integer"  // Optional: Number of items per page (default: 25, max: 100)
}
```

**Response:**

```json
{
  "assets": [
    {
      "id": 501,
      "name": "Laptop-001",
      "type": "Laptop",
      "status": "In Use",
      "serialNumber": "LT12345",
      "assetTag": "ASSET-001"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-assets', { 
  status: 'In Use',
  typeId: 1
});
```

### `halo-get-asset`

Retrieves detailed information about a specific asset.

**Parameters:**

```json
{
  "id": "integer"  // Required: The asset ID
}
```

**Response:**

```json
{
  "id": 501,
  "name": "Laptop-001",
  "type": "Laptop",
  "status": "In Use",
  "serialNumber": "LT12345",
  "assetTag": "ASSET-001",
  "purchaseDate": "2022-06-01",
  "warrantyExpiryDate": "2025-06-01"
}
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-asset', { 
  id: 501
});
```

### `halo-create-asset`

Creates a new asset in the system.

**Parameters:**

```json
{
  "name": "string",               // Required: Asset name
  "typeId": "integer",            // Required: Asset type ID
  "status": "string",             // Optional: Asset status
  "assetTag": "string",           // Optional: Asset tag for tracking
  "serialNumber": "string",       // Optional: Serial number of the asset
  "notes": "string",              // Optional: Additional notes about the asset
  "purchaseDate": "string",       // Optional: Date the asset was purchased (YYYY-MM-DD)
  "warrantyExpiryDate": "string"  // Optional: Date the warranty expires (YYYY-MM-DD)
}
```

**Response:**

Success message with the ID of the created asset.

**Example:**

```javascript
const result = await client.invokeTool('halo-create-asset', { 
  name: 'New Laptop',
  typeId: 1,
  status: 'In Stock',
  serialNumber: 'LT67890',
  assetTag: 'ASSET-003'
});
```

### `halo-update-asset`

Updates an existing asset.

**Parameters:**

```json
{
  "id": "integer",                // Required: The asset ID to update
  "name": "string",               // Optional: Asset name
  "typeId": "integer",            // Optional: Asset type ID
  "status": "string",             // Optional: Asset status
  "assetTag": "string",           // Optional: Asset tag for tracking
  "serialNumber": "string",       // Optional: Serial number of the asset
  "notes": "string",              // Optional: Additional notes about the asset
  "purchaseDate": "string",       // Optional: Date the asset was purchased (YYYY-MM-DD)
  "warrantyExpiryDate": "string"  // Optional: Date the warranty expires (YYYY-MM-DD)
}
```

**Response:**

Success message with the ID of the updated asset.

**Example:**

```javascript
const result = await client.invokeTool('halo-update-asset', { 
  id: 501,
  name: 'Updated Laptop',
  status: 'In Repair'
});
```

### `halo-delete-asset`

Deletes an asset from the system.

**Parameters:**

```json
{
  "id": "integer"  // Required: The asset ID to delete
}
```

**Response:**

Success message with the ID of the deleted asset.

**Example:**

```javascript
const result = await client.invokeTool('halo-delete-asset', { 
  id: 501
});
```

### `halo-get-asset-types`

Gets a list of all asset types available in the system.

**Parameters:**

This tool does not require any parameters.

**Response:**

```json
[
  {
    "id": 1,
    "name": "Laptop",
    "description": "Portable computers"
  },
  {
    "id": 2,
    "name": "Desktop",
    "description": "Stationary computers"
  }
]
```

**Example:**

```javascript
const result = await client.invokeTool('halo-get-asset-types');
```

## Error Handling

All tools follow a consistent error handling pattern. When an error occurs, the tool returns a response with `isError: true` and a descriptive error message:

```json
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error retrieving ticket 1001: Ticket not found"
    }
  ]
}
```

Common error scenarios include:

- Authentication failures
- Invalid parameters
- Resource not found
- Permission denied
- API rate limits
- Network errors

## Response Format

All tool responses follow the MCP protocol format:

```json
{
  "content": [
    {
      "type": "text",
      "text": "..."  // Response content, often JSON-formatted data
    }
  ]
}
```

For error responses, the format includes an `isError` flag:

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