Herramientas MCP de HaloPSA

Servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de HaloPSA.

Descripción general

Este paquete proporciona una implementación de servidor del Protocolo de Contexto de Modelo que permite a los asistentes de IA (como Claude) interactuar con la API de HaloPSA. Se puede usar en varias configuraciones:

Como servidor independiente
Integrado con Claude Desktop
Como biblioteca en aplicaciones Node.js

Características

Servidor MCP con soporte para múltiples tipos de transporte (stdio, http, tcp)
Herramientas para interactuar con tickets, usuarios, activos y más
Integración perfecta con Claude Desktop
Registro y gestión de errores configurables
Controles de seguridad robustos
Compatibilidad entre versiones con el SDK de MCP

Instalación

Instalación global de NPM

npm install -g haloapi-mcp-tools

Instalación local

npm install haloapi-mcp-tools

Configuración

Cree un archivo .env en la raíz de su proyecto con las siguientes variables de entorno:

# Required HaloPSA API Configuration
HALO_API_URL=https://yourhalo.haloservicedesk.com/api
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret

# Optional Configuration
HALO_API_VERSION=v3
HALO_SCOPE=all
HALO_TENANT=your_tenant_id
TRANSPORT=stdio
PORT=3000
DEBUG=false

Como alternativa, puede utilizar la configuración de Claude Desktop si la herramienta se ejecuta como una integración de Claude Desktop.

Uso

Uso como servidor independiente

# Start the server using stdio transport (default)
haloapi-mcp-server

# Start with HTTP transport
TRANSPORT=http PORT=3000 haloapi-mcp-server

# Start with debug mode
DEBUG=true haloapi-mcp-server

# Command-line options are also available
haloapi-mcp-server --transport http --port 3000 --debug

Uso con Claude Desktop

Para utilizar con Claude Desktop:

Instalar el paquete globalmente:

npm install -g haloapi-mcp-tools

Configure Claude Desktop para usar este servidor MCP en la configuración de Claude Desktop (Configuración > Extensiones > Agregar servidor MCP):
- Nombre: HaloPSA
- Comando: haloapi-desktop-mcp
- Variables de entorno (opcionales):
  - HALO_API_URL: Su URL de API de HaloPSA
  - HALO_CLIENT_ID: Su ID de cliente
  - HALO_CLIENT_SECRET: Su secreto de cliente
¡Comienza a utilizar las herramientas HaloPSA en tus conversaciones de Claude!

Alternativamente, si ha clonado este repositorio, puede ejecutar:

# Run the MCP server for Claude Desktop
npm run claude

# Run with debug logging
npm run claude:debug

# Or use the convenience script
./run-mcp.sh desktop

El servidor MCP detectará y utilizará automáticamente la configuración de Claude Desktop.

Uso como biblioteca

const { startServer } = require('haloapi-mcp-tools');

async function main() {
  const server = await startServer({
    transport: 'stdio', // or 'http', 'tcp'
    port: 3000,
    debug: true,
    haloBaseUrl: 'https://yourhalo.haloservicedesk.com/api',
    haloClientId: 'your_client_id',
    haloClientSecret: 'your_client_secret'
  });
  
  // Server is now running
  console.log('Server started successfully');
  
  // To shut down the server
  // await server.close();
}

main().catch(console.error);

Estructura

La base del código está organizada con la siguiente estructura:

src/core/ - Implementación del servidor MCP principal
src/tools/ - Definiciones de herramientas para las operaciones de la API de HaloPSA
src/utils/ - Funciones de utilidad para registro, validación, etc.
src/services/ - Capa de servicio para las operaciones de la API de HaloPSA
src/api/ - Clientes API para HaloPSA
bin/ - Puntos de entrada ejecutables
scripts/ - Scripts de utilidad para desarrollo y mantenimiento

Herramientas MCP

Este paquete proporciona varias herramientas para interactuar con HaloPSA e implementa los métodos de protocolo MCP estándar requeridos por Claude Desktop:

Herramientas de tickets

get-tickets : Obtenga una lista de tickets con filtrado opcional
get-ticket : Obtenga información detallada sobre un billete específico
create-ticket : Crea un nuevo ticket
update-ticket : Actualizar un ticket existente
delete-ticket : Eliminar un ticket
get-ticket-comments : Obtener comentarios para un ticket específico
add-comment : Agregar un comentario a un ticket

Herramientas de usuario

get-users : Obtener una lista de usuarios con filtrado opcional
get-user : Obtener información detallada sobre un usuario específico
create-user : Crea un nuevo usuario
update-user : Actualizar un usuario existente
delete-user : Eliminar un usuario
get-agents : Obtener una lista de agentes

Herramientas de activos

get-assets : Obtenga una lista de activos con filtrado opcional
get-asset : Obtenga información detallada sobre un activo específico
create-asset : Crea un nuevo activo
update-asset : Actualizar un activo existente
delete-asset : Eliminar un activo
get-asset-types : obtener una lista de todos los tipos de activos

Métodos MCP estándar

resources/list : enumera todos los recursos disponibles en el servidor MCP
prompts/list : enumera todas las indicaciones disponibles para la integración de Claude Desktop
tools/list : enumera todas las herramientas disponibles en el servidor MCP

Integración de escritorio de Claude

El paquete incluye una implementación unificada para la integración de Claude Desktop que funciona en diferentes versiones del SDK de MCP.

Características principales de la implementación unificada:

Compatibilidad entre versiones a través de la capa de compatibilidad del SDK
Detección automática de la configuración desde la configuración de Claude Desktop
Manejo robusto de errores y mecanismos de respaldo
Soporte integral de registro y depuración

Solución de problemas

Problemas comunes

Importaciones de módulos

Si encuentra errores relacionados con las importaciones o los sistemas de módulos:

SyntaxError: Cannot use import statement outside a module

Solución: Comprueba que estés usando la sintaxis de importación correcta para la configuración de tu proyecto. Este paquete usa principalmente CommonJS, así que usa instrucciones require() .

Errores de autenticación

Si ve errores relacionados con la autenticación de HaloPSA:

Error: Invalid client credentials

Solución: Verifique su ID de cliente y su secreto de cliente en las variables de entorno o la configuración.

Problemas de transporte

Si el servidor no puede iniciarse con un tipo de transporte específico:

Error: Unsupported transport

Solución: asegúrese de estar utilizando uno de los tipos de transporte admitidos: 'stdio', 'http' o 'tcp'.

Problemas de integración de Claude Desktop

Si Claude Desktop no puede conectarse a su servidor MCP o muestra errores sobre métodos no compatibles:

Error: Method not supported: tools/list

Solución: asegúrese de estar utilizando la última versión de este paquete, que incluye la implementación unificada de MCP con soporte sólido para el protocolo MCP.

Errores de análisis de JSON

Si ve errores de análisis de JSON en los registros del servidor MCP como:

Error parsing JSON message: Unexpected non-whitespace character after JSON at position X

Solución: La última versión incluye un manejo mejorado de JSON que corrige automáticamente problemas comunes con mensajes malformados. Si el problema persiste, active el modo de depuración para obtener más información.

DEBUG=true haloapi-mcp-server

Depuración

Para habilitar información de depuración detallada, configure la variable de entorno DEBUG:

DEBUG=true haloapi-mcp-server

También puede aumentar el nivel de registro para obtener información aún más detallada:

LOG_LEVEL=trace haloapi-mcp-server

Para la integración de Claude Desktop, puede encontrar registros en las siguientes ubicaciones:

macOS: ~/Library/Logs/Claude/mcp-server-halopsa.log
Windows: %APPDATA%\Claude\Logs\mcp-server-halopsa.log
Linux: ~/.local/share/claude/logs/mcp-server-halopsa.log

Pruebas

Puede probar el servidor MCP utilizando el script de prueba incluido:

# Run the test script against a running server
npm run test:mcp

# Run the automated tests
npm test

El script de prueba interactivo le permite probar herramientas individuales e inspeccionar sus respuestas, lo que resulta útil para la depuración y el desarrollo.

Desarrollo y extensión

El código base sigue varios patrones de diseño y prácticas que se deben seguir al agregar nuevas funciones o realizar cambios:

Patrones de diseño

Patrón de capa de compatibilidad : se utiliza en src/sdk-compat.js para proporcionar una interfaz consistente en las diferentes versiones del SDK.
Inyección de dependencia : se utiliza en todo el código base para proporcionar dependencias a los módulos, lo que los hace más fáciles de probar y más modulares.
Patrón de módulo : cada componente está organizado en módulos con responsabilidades e interfaces claras.
Patrón de fachada : los puntos de entrada principales ( desktop-mcp-unified.js , standalone-mcp.js ) proporcionan interfaces simplificadas a la funcionalidad subyacente.

Añadiendo nuevas funciones

Al agregar nuevas funciones al código base, siga estos pasos:

Agregue nuevas definiciones de herramientas al módulo apropiado en src/tools/
Registra las nuevas herramientas en src/tools/index.js
Agregue cualquier nueva función de utilidad al módulo apropiado en src/utils/
Escriba pruebas para la nueva funcionalidad en el directorio tests/
Actualice la documentación para reflejar las nuevas características

Licencia

Colaboradores

Suleman Manji ( @ssmanji89 )

HaloPSA MCP Tools

Integrations