ConnectWise API Gateway

Una interfaz completa para interactuar con la API de ConnectWise Manage.

Documentación

Servidor MCP de ConnectWise API Gateway

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

Capacidades Principales

Descubrimiento de API: Busque y explore endpoints de la API de ConnectWise usando palabras clave o lenguaje natural
Ejecución Simplificada de API: Ejecute llamadas a la API con manejo amigable de parámetros y gestión automática de errores
Sistema de Memoria Rápida: Guarde y recupere consultas de API utilizadas con frecuencia para flujos de trabajo más eficientes
Acceso Directo a la API: Envíe solicitudes personalizadas a la API con control total sobre endpoints, métodos y parámetros

Características Clave

Descubrimiento de API Basado en Base de Datos: Utiliza una base de datos SQLite creada a partir del archivo de definición JSON de la API de ConnectWise para búsquedas rápidas y eficientes de endpoints
Búsqueda en Lenguaje Natural: Encuentre endpoints de API relevantes usando descripciones conversacionales de lo que necesita
Navegación de API por Categorías: Explore endpoints de API organizados por categorías funcionales
Acceso a Documentación Detallada: Vea información completa sobre endpoints de API, incluyendo parámetros, esquemas y formatos de respuesta
Aprendizaje Adaptativo: El sistema aprende qué llamadas a la API son más valiosas para usted mediante el seguimiento de uso

Instalación y Configuración

Requisitos Previos

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

Pasos de Instalación

Opción 1: Usando el Paquete NPM de GitHub (Recomendado)

Puede instalar el paquete directamente desde GitHub:

npm install -g jasondsmith72/CWM-API-Gateway-MCP

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

Windows

Clone o descargue el repositorio:

git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP

Instale el paquete:
```
pip install -e .
```

macOS

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

npm install -g jasondsmith72/CWM-API-Gateway-MCP

Para instalación manual:

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

Clone el repositorio:

git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP

Configure un entorno virtual (recomendado):

python3 -m venv venv
source venv/bin/activate

Instale el paquete:
```
pip install -e .
```

Linux (Ubuntu/Debian)

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

sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

Para instalación manual:

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

Clone el repositorio:

git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
cd CWM-API-Gateway-MCP

Configure un entorno virtual (recomendado):

python3.10 -m venv venv
source venv/bin/activate

Instale el paquete:
```
pip install -e .
```

Pasos Posteriores a la Instalación

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

1. (Opcional) Construir la Base de Datos de la API

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

# On Windows
python build_database.py path/to/manage.json

# On macOS/Linux
python3 build_database.py path/to/manage.json

Este paso solo necesita hacerse una vez, o cada vez que cambie la definición de la API de ConnectWise.

2. Configurar Credenciales de la API

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

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CONNECTWISE_COMPANY_ID=your_company_id
CONNECTWISE_PUBLIC_KEY=your_public_key
CONNECTWISE_PRIVATE_KEY=your_private_key
CONNECTWISE_AUTH_PREFIX=yourprefix+  # Prefix required by ConnectWise for API authentication

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

CONNECTWISE_API_URL: La URL base para todas las solicitudes a la API de 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ásica

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 requerido que se agrega antes de su 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 (por ejemplo, "api+", "integration+", etc.)

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

'Authorization': 'Basic [base64 encoded credentials]'
'clientId': 'your_company_id'
'Content-Type': 'application/json'

Configuración para Claude Desktop

Hay dos métodos para integrarse con Claude Desktop:

Método 1: Usando el Paquete NPM (Recomendado)

Instale el paquete usando NPM:

npm install -g jasondsmith72/CWM-API-Gateway-MCP

Luego configure Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@jasondsmith72/CWM-API-Gateway-MCP"
      ],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

Método 2: Usando el Script de Node.js (Método Alternativo)

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "node",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

Método 3: Usando la Ruta Directa del Script de Python

Si prefiere usar el script de Python directamente:

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python3",
      "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

# If installed via NPM
cwm-api-gateway-mcp

# If using the Node.js script (after cloning the repository)
node bin/server.js

# Or using the Python script directly
# On Windows
python api_gateway_server.py

# On macOS/Linux
python3 api_gateway_server.py

Herramientas Disponibles

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

Herramientas de Descubrimiento de API

Herramienta	Descripción
`search_api_endpoints`	Buscar endpoints de API por cadena de consulta
`natural_language_api_search`	Encontrar endpoints usando descripciones en lenguaje natural
`list_api_categories`	Listar todas las categorías de API disponibles
`get_category_endpoints`	Listar todos los endpoints en una categoría específica
`get_api_endpoint_details`	Obtener información detallada sobre un endpoint específico

Herramientas de Ejecución de API

Herramienta	Descripción
`execute_api_call`	Ejecutar una llamada a la API con ruta, método, parámetros y datos
`send_raw_api_request`	Enviar una solicitud de API sin procesar en el formato "METHOD /path [JSON body]"

Herramientas de Memoria Rápida

Herramienta	Descripción
`save_to_fast_memory`	Guardar manualmente una consulta de API en Memoria Rápida
`list_fast_memory`	Listar todas las consultas guardadas en Memoria Rápida
`delete_from_fast_memory`	Eliminar una consulta específica de Memoria Rápida
`clear_fast_memory`	Borrar todas las consultas de Memoria Rápida

Ejemplos de Uso

Buscar Endpoints Relacionados con Tickets

search_api_endpoints("tickets")

Buscar Usando Lenguaje Natural

natural_language_api_search("find all open service tickets that are high priority")

Ejecutar una Solicitud GET

execute_api_call(
    "/service/tickets", 
    "GET", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

Crear un Nuevo Ticket de Servicio

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # No query parameters 
    {
        "summary": "Server is down",
        "board": {"id": 1},
        "company": {"id": 2},
        "status": {"id": 1},
        "priority": {"id": 3}
    }
)

Enviar una Solicitud de API Sin Procesar

send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")

Ver el Contenido de Memoria Rápida

list_fast_memory()

Guardar una Consulta Útil en Memoria Rápida

save_to_fast_memory(
    "/service/tickets", 
    "GET", 
    "Get all high priority open tickets", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

Entendiendo la Memoria Rápida

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

Beneficios

Ahorro de Tiempo: Ejecute rápidamente llamadas complejas a la API sin recordar endpoints o parámetros exactos
Reducción de Errores: Reutilice llamadas exitosas a la API para minimizar errores potenciales
Aprendizaje Adaptativo: El sistema aprende qué llamadas a la API son más valiosas para usted
Persistencia de Parámetros: Los parámetros y cuerpos de solicitud se almacenan para uso futuro

Cómo Funciona

Aprendizaje Automático: Cuando ejecuta una llamada exitosa a la API, se le solicita guardarla en Memoria Rápida
Recuperación Inteligente: La próxima vez que use el mismo endpoint de API, el sistema verifica Memoria Rápida primero
Reutilización de Parámetros: Si no proporciona parámetros para una llamada, el sistema usa automáticamente los guardados en Memoria Rápida
Seguimiento de Uso: El sistema rastrea la frecuencia de uso de 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 Memoria Rápida si no se proporcionan
Contador de Uso: Cada vez que se usa una consulta de Memoria Rápida, su contador de uso aumenta
Capacidad de Búsqueda: Busque entre sus consultas guardadas por descripción o ruta de endpoint
Priorización: Las consultas se muestran en orden de frecuencia de uso, con las consultas más utilizadas al principio

Gestión de su Memoria Rápida

Ver Consultas Guardadas: list_fast_memory()
Buscar Consultas Específicas: 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 Memoria Rápida

El sistema de Memoria Rápida está impulsado 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 amigables para el usuario

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 endpoint de la API
method: Método HTTP (GET, POST, PUT, etc.)
params: Parámetros de consulta en formato JSON
data: Cuerpo de solicitud en formato JSON
timestamp: Cuándo se usó 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

Error: Database file not found at [path]
Please run build_database.py script first to generate the database

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

python build_database.py path/to/manage.json

Problemas de Autenticación de la API

HTTP error 401: Unauthorized

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 de API tenga los permisos necesarios en ConnectWise
Compruebe que CONNECTWISE_AUTH_PREFIX esté configurado correctamente para su entorno

Tiempos de Espera en Llamadas a la API

Request timed out. ConnectWise API may be slow to respond.

Solución:

Verifique su conexión a internet
La API de ConnectWise puede estar experimentando alta carga
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 de 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:

python test_database.py

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

Uso Avanzado

Optimización de Consultas a la API

Para un mejor rendimiento con la API de ConnectWise:

Use Condiciones Específicas: Limite sus consultas con condiciones precisas

execute_api_call("/service/tickets", "GET", {
    "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]"
})

Limite la Selección de Campos: Solicite solo los campos que necesita

execute_api_call("/service/tickets", "GET", {
    "conditions": "status/name='Open'",
    "fields": "id,summary,status,priority"
})

Paginar Resultados Grandes: Use 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. Se prohíbe la copia, distribución o uso no autorizado.

Agradecimientos

Construido usando el marco del Protocolo de Contexto de Modelos (MCP)
Impulsado por la API de ConnectWise Manage