ConnectWise API Gateway

Uma interface abrangente para interagir com a API do ConnectWise Manage.

Documentação

Servidor MCP ConnectWise API Gateway

Este servidor Model Context Protocol (MCP) fornece uma interface abrangente para interagir com a API ConnectWise Manage. Ele simplifica a descoberta, execução e gerenciamento de APIs tanto para desenvolvedores quanto para assistentes de IA.

Capacidades Principais

Descoberta de API: Pesquise e explore endpoints da API ConnectWise usando palavras-chave ou linguagem natural
Execução Simplificada de API: Execute chamadas de API com tratamento amigável de parâmetros e gerenciamento automático de erros
Sistema de Memória Rápida: Salve e recupere consultas de API usadas com frequência para fluxos de trabalho mais eficientes
Acesso Bruto à API: Envie solicitações de API personalizadas com controle total sobre endpoints, métodos e parâmetros

Principais Recursos

Descoberta de API com Banco de Dados: Usa um banco de dados SQLite criado a partir do JSON de definição da API ConnectWise para buscas rápidas e eficientes de endpoints
Pesquisa em Linguagem Natural: Encontre endpoints de API relevantes usando descrições conversacionais do que você precisa
Navegação Categorizada de API: Navegue pelos endpoints de API organizados por categorias funcionais
Acesso a Documentação Detalhada: Visualize informações abrangentes sobre endpoints de API, incluindo parâmetros, esquemas e formatos de resposta
Aprendizado Adaptativo: O sistema aprende quais chamadas de API são mais valiosas para você por meio do rastreamento de uso

Instalação e Configuração

Pré-requisitos

Python 3.10 ou superior
Acesso às credenciais da API ConnectWise Manage
Arquivo de definição da API ConnectWise (manage.json) - incluído no repositório

Etapas de Instalação

Opção 1: Usando o Pacote NPM do GitHub (Recomendado)

Você pode instalar o pacote diretamente do GitHub:

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

Este método lida automaticamente com todas as dependências e fornece uma configuração mais simples para o Claude Desktop.

Opção 2: Instalação Manual

Windows

Clone ou baixe o repositório:

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

Instale o pacote:
```
pip install -e .
```

macOS

Para o método de instalação via NPM, basta executar:

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

Para instalação manual:

Instale o Python 3.10+ se ainda não estiver 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 o repositório:

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

Configure um ambiente virtual (recomendado):

python3 -m venv venv
source venv/bin/activate

Instale o pacote:
```
pip install -e .
```

Linux (Ubuntu/Debian)

Para o método de instalação via NPM, basta executar:

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

Para instalação manual:

Instale o Python 3.10+ se ainda não estiver 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 o repositório:

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

Configure um ambiente virtual (recomendado):

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

Instale o pacote:
```
pip install -e .
```

Etapas Pós-Instalação

Após instalar em qualquer plataforma (Windows, macOS ou Linux), conclua as seguintes etapas:

1. (Opcional) Construir o Banco de Dados da API

Este repositório já inclui um banco de dados pré-construído, portanto esta etapa é opcional. Execute apenas se precisar usar um arquivo de definição da API ConnectWise mais recente:

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

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

Esta etapa só precisa ser feita uma vez, ou sempre que a definição da API ConnectWise mudar.

2. Configurar Credenciais da API

Defina as seguintes variáveis de ambiente com suas credenciais 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

Essas credenciais são usadas no processo de autenticação da seguinte forma:

CONNECTWISE_API_URL: A URL base para todas as solicitações de API para sua instância ConnectWise

url = f"{API_URL}{endpoint}"  # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets

CONNECTWISE_COMPANY_ID: Incluída no cabeçalho 'clientId' de cada solicitação para identificar sua empresa
```
headers = {'clientId': COMPANY_ID, ...}
```

CONNECTWISE_PUBLIC_KEY e CONNECTWISE_PRIVATE_KEY: Usadas juntamente com AUTH_PREFIX para criar as credenciais de autenticação 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: Prefixo obrigatório adicionado antes da sua chave pública no nome de usuário de autenticação. A API ConnectWise exige esse prefixo para identificar o tipo de integração (por exemplo, "api+", "integration+", etc.)

Os cabeçalhos HTTP finais enviados com cada solicitação serão assim:

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

Configuração para o Claude Desktop

Existem dois métodos para integrar com o Claude Desktop:

Método 1: Usando o Pacote NPM (Recomendado)

Instale o pacote usando NPM:

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

Em seguida, configure o 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 o Script Node.js (Método Alternativo)

Se você clonou o repositório e instalou as dependências, pode usar o script Node.js incluído:

{
  "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 o Caminho Direto do Script Python

Se preferir usar o script Python diretamente:

{
  "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 e Linux, use o formato de caminho apropriado:

{
  "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+"
      }
    }
  }
}

O servidor pode ser executado diretamente pela linha de comando para testes:

# 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

Ferramentas Disponíveis

O servidor API Gateway MCP fornece várias ferramentas para trabalhar com a API ConnectWise:

Ferramentas de Descoberta de API

Ferramenta	Descrição
`search_api_endpoints`	Pesquisar endpoints de API por string de consulta
`natural_language_api_search`	Encontrar endpoints usando descrições em linguagem natural
`list_api_categories`	Listar todas as categorias de API disponíveis
`get_category_endpoints`	Listar todos os endpoints em uma categoria específica
`get_api_endpoint_details`	Obter informações detalhadas sobre um endpoint específico

Ferramentas de Execução de API

Ferramenta	Descrição
`execute_api_call`	Executar uma chamada de API com caminho, método, parâmetros e dados
`send_raw_api_request`	Enviar uma solicitação de API bruta no formato "METHOD /path [JSON body]"

Ferramentas de Memória Rápida

Ferramenta	Descrição
`save_to_fast_memory`	Salvar manualmente uma consulta de API na Memória Rápida
`list_fast_memory`	Listar todas as consultas salvas na Memória Rápida
`delete_from_fast_memory`	Excluir uma consulta específica da Memória Rápida
`clear_fast_memory`	Limpar todas as consultas da Memória Rápida

Exemplos de Uso

Pesquisar Endpoints Relacionados a Tickets

search_api_endpoints("tickets")

Pesquisar Usando Linguagem Natural

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

Executar uma Solicitação GET

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

Criar um Novo Ticket de Serviço

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 uma Solicitação de API Bruta

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

Visualizar o Conteúdo da Memória Rápida

list_fast_memory()

Salvar uma Consulta Útil na Memória Rápida

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

Entendendo a Memória Rápida

O recurso de Memória Rápida permite salvar e recuperar consultas de API usadas com frequência, otimizando seu fluxo de trabalho de várias maneiras:

Benefícios

Economia de Tempo: Execute chamadas de API complexas rapidamente sem lembrar endpoints ou parâmetros exatos
Redução de Erros: Reutilize chamadas de API bem-sucedidas para minimizar erros potenciais
Aprendizado Adaptativo: O sistema aprende quais chamadas de API são mais valiosas para você
Persistência de Parâmetros: Parâmetros e corpos de solicitação são armazenados para uso futuro

Como Funciona

Aprendizado Automático: Quando você executa uma chamada de API bem-sucedida, é solicitado a salvá-la na Memória Rápida
Recuperação Inteligente: Na próxima vez que usar o mesmo endpoint de API, o sistema verifica a Memória Rápida primeiro
Reutilização de Parâmetros: Se você não fornecer parâmetros para uma chamada, o sistema usa automaticamente os salvos na Memória Rápida
Rastreamento de Uso: O sistema rastreia com que frequência cada consulta é usada e prioriza as consultas usadas com frequência

Funcionalidades da Memória Rápida

Sugestão Automática de Parâmetros: O sistema sugerirá parâmetros da Memória Rápida se nenhum for fornecido
Contador de Uso: Cada vez que uma consulta da Memória Rápida é usada, seu contador de uso aumenta
Capacidade de Pesquisa: Pesquise suas consultas salvas por descrição ou caminho de endpoint
Priorização: As consultas são exibidas em ordem de frequência de uso, com as consultas mais usadas no topo

Gerenciando Sua Memória Rápida

Visualizar Consultas Salvas: list_fast_memory()
Pesquisar Consultas Específicas: list_fast_memory("search term")
Excluir uma Consulta: delete_from_fast_memory(query_id)
Limpar Todas as Consultas: clear_fast_memory()

Detalhes Técnicos da Memória Rápida

O sistema de Memória Rápida é alimentado por um banco de dados SQLite (fast_memory_api.db) que armazena:

Caminhos e métodos de consulta
Parâmetros e corpos de solicitação como JSON
Métricas de uso e carimbos de data/hora
Descrições amigáveis ao usuário

A estrutura do banco de dados inclui:

id: Identificador único para cada consulta salva
description: Descrição fornecida pelo usuário do que a consulta faz
path: Caminho do endpoint da API
method: Método HTTP (GET, POST, PUT, etc.)
params: Parâmetros de consulta em formato JSON
data: Corpo da solicitação em formato JSON
timestamp: Quando a consulta foi usada pela última vez
usage_count: Quantas vezes a consulta foi usada

Solução de Problemas

Problemas Comuns

Erro de Banco de Dados Não Encontrado

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

Solução: Execute o script build_database.py com o caminho para o seu arquivo de definição da API ConnectWise:

python build_database.py path/to/manage.json

Problemas de Autenticação na API

HTTP error 401: Unauthorized

Solução: Verifique suas variáveis de ambiente para garantir que todas as credenciais ConnectWise estejam corretas:

Verifique seu CONNECTWISE_COMPANY_ID, CONNECTWISE_PUBLIC_KEY e CONNECTWISE_PRIVATE_KEY
Garanta que a chave de API tenha as permissões necessárias no ConnectWise
Verifique se CONNECTWISE_AUTH_PREFIX está definido corretamente para seu ambiente

Timeouts em Chamadas de API

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

Solução:

Verifique sua conexão com a internet
A API ConnectWise pode estar enfrentando alta carga
Para solicitações de grandes volumes de dados, considere adicionar filtros mais específicos à sua consulta

Logs e Diagnóstico

Locais dos Logs

Arquivo de log principal: api_gateway/api_gateway.log
Bancos de dados SQLite:
- Banco de Dados da API: api_gateway/connectwise_api.db
- Banco de Dados da Memória Rápida: api_gateway/fast_memory_api.db

Testando o Banco de Dados

Verifique se o banco de dados está corretamente construído e acessível:

python test_database.py

Isso exibirá estatísticas sobre o banco de dados e confirmará que ele pode ser consultado corretamente.

Uso Avançado

Otimizando Consultas de API

Para melhor desempenho com a API ConnectWise:

Use Condições Específicas: Restrinja suas consultas com condições precisas

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

Limite a Seleção de Campos: Solicite apenas os campos que você precisa

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

Paginação de Resultados Grandes: Use os parâmetros page e pageSize

execute_api_call("/service/tickets", "GET", {
    "conditions": "status/name='Open'",
    "page": 1,
    "pageSize": 50
})

Licença

Este software é proprietário e confidencial. Cópia, distribuição ou uso não autorizado é proibido.

Agradecimentos

Construído usando o framework Model Context Protocol (MCP)
Alimentado pela API ConnectWise Manage