haloapi-mcp-tools
Version:
Model Context Protocol (MCP) server for interacting with the HaloPSA API
753 lines (580 loc) • 14.8 kB
Markdown
# 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"
}
]
}
```