Servidor MCP de la puerta de enlace API de ConnectWise

Este servidor de Protocolo de Contexto de Modelo (MCP) proporciona una interfaz completa para interactuar con la API de ConnectWise Manage. Simplifica el descubrimiento, la ejecución y la gestión de la API tanto para desarrolladores como para asistentes de IA.

Capacidades principales

• Descubrimiento de API: busque y explore puntos finales de API de ConnectWise utilizando palabras clave o lenguaje natural
• Ejecución de API simplificada: ejecute llamadas API con un manejo sencillo de parámetros y gestión automática de errores.
• Sistema de memoria rápida: guarde y recupere consultas API utilizadas con frecuencia para flujos de trabajo más eficientes
• Acceso a API sin procesar: envíe solicitudes de API personalizadas con control total sobre puntos finales, métodos y parámetros

Características principales

• Descubrimiento de API respaldado por base de datos: utiliza una base de datos SQLite creada a partir del JSON de definición de API de ConnectWise para búsquedas de puntos finales rápidas y eficientes
• Búsqueda en lenguaje natural: encuentre puntos finales de API relevantes utilizando descripciones conversacionales de lo que necesita
• Navegación de API categorizada: explore los puntos finales de API organizados por categorías funcionales
• Acceso a documentación detallada: vea información completa sobre los puntos finales de la API, incluidos parámetros, esquemas y formatos de respuesta
• Aprendizaje adaptativo: el sistema aprende qué llamadas API son más valiosas para usted a través del seguimiento del uso.

Instalación y configuración

Prerrequisitos

• Python 3.10 o superior
• Acceso a las credenciales de la API de ConnectWise Manage
• Archivo de definición de API de ConnectWise ( manage.json ): incluido en el repositorio

Pasos de instalación

Opción 1: Usar el paquete NPM de GitHub (recomendado)

Puedes instalar el paquete directamente desde GitHub:

Este método maneja automáticamente todas las dependencias y proporciona una configuración más simple para Claude Desktop.

Opción 2: Instalación manual

Ventanas

1. Clonar o descargar el repositorio:
   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
2. Instalar el paquete:
   pip install -e .

macOS

Para el método de instalación NPM, simplemente ejecute:

Para la instalación manual:

1. Instale Python 3.10+ si aún no está instalado:
   # Using Homebrew brew install python@3.10 # Or using pyenv brew install pyenv pyenv install 3.10.0 pyenv global 3.10.0
2. Clonar el repositorio:
   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
3. Configurar un entorno virtual (recomendado):
   python3 -m venv venv source venv/bin/activate
4. Instalar el paquete:
   pip install -e .

Linux (Ubuntu/Debian)

Para el método de instalación NPM, simplemente ejecute:

Para la instalación manual:

1. Instale Python 3.10+ si aún no está instalado:
   # For Ubuntu 22.04+ sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip # For older versions of Ubuntu/Debian sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
2. Clonar el repositorio:
   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
3. Configurar un entorno virtual (recomendado):
   python3.10 -m venv venv source venv/bin/activate
4. Instalar el paquete:
   pip install -e .

Pasos posteriores a la instalación

Después de instalarlo en cualquier plataforma (Windows, macOS o Linux), complete los siguientes pasos:

1. (Opcional) Construir la base de datos API

Este repositorio ya incluye una base de datos predefinida, por lo que este paso es opcional. Ejecútelo solo si necesita usar un archivo de definición de la API de ConnectWise más reciente:

Este paso solo debe realizarse una vez o cada vez que cambie la definición de la API de ConnectWise.

2. Configurar las credenciales de API

Configure las siguientes variables de entorno con sus credenciales de ConnectWise:

Estas credenciales se utilizan en el proceso de autenticación de la siguiente manera:

• CONNECTWISE_API_URL : La URL base para todas las solicitudes de API a su instancia de ConnectWise
  url = f"{API_URL}{endpoint}" # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets
• CONNECTWISE_COMPANY_ID : Se incluye en el encabezado 'clientId' de cada solicitud para identificar su empresa
  headers = {'clientId': COMPANY_ID, ...}
• CONNECTWISE_PUBLIC_KEY y CONNECTWISE_PRIVATE_KEY : se utilizan junto con AUTH_PREFIX para crear las credenciales de autenticación básicas
  username = f"{AUTH_PREFIX}{PUBLIC_KEY}" # e.g., "yourprefix+your_public_key" password = PRIVATE_KEY credentials = f"{username}:{password}" # Combined into "yourprefix+your_public_key:your_private_key"
• CONNECTWISE_AUTH_PREFIX : Prefijo obligatorio que se añade antes de la clave pública en el nombre de usuario de autenticación. La API de ConnectWise requiere este prefijo para identificar el tipo de integración (p. ej., "api+", "integration+", etc.).

Los encabezados HTTP finales enviados con cada solicitud se verán así:

Configuración para Claude Desktop

Hay dos métodos para integrarse con Claude Desktop:

Método 1: Uso del paquete NPM (recomendado)

Instalar el paquete usando NPM:

Luego configure Claude Desktop ( claude_desktop_config.json ):

Método 2: Usar un script de Node.js (método alternativo)

Si ha clonado el repositorio e instalado las dependencias, puede utilizar el script Node.js incluido:

Método 3: Usar la ruta de script de Python directa

Si prefieres usar el script de Python directamente:

Para macOS y Linux, utilice el formato de ruta apropiado:

El servidor se puede ejecutar directamente desde la línea de comandos para realizar pruebas:

Herramientas disponibles

El servidor MCP de API Gateway proporciona varias herramientas para trabajar con la API de ConnectWise:

Herramientas de descubrimiento de API

Herramientas de ejecución de API

Herramientas de memoria rápida

Ejemplos de uso

Búsqueda de puntos finales relacionados con tickets

Búsqueda mediante lenguaje natural

Ejecutar una solicitud GET

Crear un nuevo ticket de servicio

Enviar una solicitud de API sin procesar

Ver contenido de Fast Memory

Guardar una consulta útil en la memoria rápida

Entendiendo la memoria rápida

La función Memoria rápida le permite guardar y recuperar consultas API utilizadas con frecuencia, optimizando su flujo de trabajo de varias maneras:

Beneficios

• Ahorro de tiempo: ejecute rápidamente llamadas API complejas sin recordar puntos finales ni parámetros exactos
• Reducción de errores: reutilice las llamadas API exitosas para minimizar posibles errores
• Aprendizaje adaptativo: el sistema aprende qué llamadas API son más valiosas para usted
• Persistencia de parámetros: los parámetros y los cuerpos de las solicitudes se almacenan para uso futuro.

Cómo funciona

1. Aprendizaje automático: cuando ejecuta una llamada API exitosa, se le solicita que la guarde en la memoria rápida
2. Recuperación inteligente: la próxima vez que utilice el mismo punto final de API, el sistema verificará primero la memoria rápida
3. Reutilización de parámetros: si no proporciona parámetros para una llamada, el sistema utiliza automáticamente los guardados en la memoria rápida
4. Seguimiento de uso: el sistema rastrea la frecuencia con la que se utiliza cada consulta y prioriza las consultas utilizadas con frecuencia.

Funcionalidad de memoria rápida

• Sugerencia automática de parámetros: el sistema sugerirá parámetros de la memoria rápida si no se proporciona ninguno
• Contador de uso: cada vez que se utiliza una consulta de Memoria rápida, su recuento de uso aumenta
• Capacidad de búsqueda: Busque en sus consultas guardadas por descripción o ruta del punto final
• Priorización: las consultas se muestran en orden de frecuencia de uso, con las consultas más utilizadas en la parte superior.

Cómo gestionar tu memoria rápida

• Ver consultas guardadas: list_fast_memory()
• Consultas específicas de búsqueda: list_fast_memory("search term")
• Eliminar una consulta: delete_from_fast_memory(query_id)
• Borrar todas las consultas: clear_fast_memory()

Detalles técnicos de la memoria rápida

El sistema Fast Memory está alimentado por una base de datos SQLite ( fast_memory_api.db ) que almacena:

• Rutas y métodos de consulta
• Parámetros y cuerpos de solicitud como JSON
• Métricas de uso y marcas de tiempo
• Descripciones fáciles de usar

La estructura de la base de datos incluye:

• id : Identificador único para cada consulta guardada
• description : Descripción proporcionada por el usuario de lo que hace la consulta
• path : ruta del punto final de la API
• method : método HTTP (GET, POST, PUT, etc.)
• params : Parámetros de consulta en formato JSON
• data : Cuerpo de la solicitud en formato JSON
• timestamp : cuándo se utilizó la consulta por última vez
• usage_count : Cuántas veces se ha utilizado la consulta

Solución de problemas

Problemas comunes

Error de base de datos no encontrada

Solución: ejecute el script build_database.py con la ruta a su archivo de definición de API de ConnectWise:

Problemas de autenticación de API

Solución: Verifique sus variables de entorno para asegurarse de que todas las credenciales de ConnectWise sean correctas:

• Verifique su CONNECTWISE_COMPANY_ID , CONNECTWISE_PUBLIC_KEY y CONNECTWISE_PRIVATE_KEY
• Asegúrese de que la clave API tenga los permisos necesarios en ConnectWise
• Compruebe que CONNECTWISE_AUTH_PREFIX esté configurado correctamente para su entorno

Tiempos de espera en las llamadas API

Solución:

• Comprueba tu conexión a Internet
• La API de ConnectWise puede estar experimentando una carga alta
• Para solicitudes de datos grandes, considere agregar filtros más específicos a su consulta

Registros y diagnósticos

Ubicaciones de registros

• Archivo de registro principal: api_gateway/api_gateway.log
• Bases de datos SQLite:
  • Base de datos API: api_gateway/connectwise_api.db
  • Base de datos de memoria rápida: api_gateway/fast_memory_api.db

Prueba de la base de datos

Verifique que la base de datos esté correctamente construida y sea accesible:

Esto mostrará estadísticas sobre la base de datos y confirmará que se puede consultar correctamente.

Uso avanzado

Optimización de consultas API

Para un mejor rendimiento con la API ConnectWise:

1. Utilice condiciones específicas: refine sus consultas con condiciones precisas
   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]" })
2. Limitar la selección de campos: solicita solo los campos que necesitas
   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "fields": "id,summary,status,priority" })
3. Paginar resultados grandes: utilizar los parámetros page y pageSize
   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "page": 1, "pageSize": 50 })

Licencia

Este software es propietario y confidencial. Queda prohibida su copia, distribución y uso no autorizados.

Expresiones de gratitud

• Construido utilizando el marco del Protocolo de Contexto de Modelo (MCP)
• Desarrollado por ConnectWise Manage API