SuzieQ

Interaja com a plataforma de observabilidade de rede SuzieQ via sua API REST.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Servidor MCP para SuzieQ

smithery badge

Este projeto fornece um servidor Model Context Protocol (MCP) que permite que modelos de linguagem e outros clientes MCP interajam com uma instância de observabilidade de rede SuzieQ por meio de sua API REST.

Visão Geral

O servidor expõe os comandos do SuzieQ como ferramentas MCP:

  • run_suzieq_show: Acesse o comando 'show' para consultar tabelas detalhadas de estado da rede
  • run_suzieq_summarize: Acesse o comando 'summarize' para obter estatísticas agregadas e resumos

Essas ferramentas permitem que clientes (como o Claude Desktop) consultem várias tabelas de estado da rede (por exemplo, interfaces, BGP, rotas) e apliquem filtros, recuperando os resultados diretamente da sua instância SuzieQ.

Pré-requisitos

  • Python: Versão 3.8 ou superior é recomendada.
  • uv: Um instalador e resolvedor de pacotes Python rápido. (Guia de instalação)
  • Instância SuzieQ: Uma instância SuzieQ em execução com sua API REST habilitada e acessível.
  • Endpoint e Chave da API SuzieQ: Você precisa da URL da API SuzieQ (por exemplo, http://your-suzieq-host:8000/api/v2) e de uma chave de API válida (access_token).

Instalação e Configuração

Instalando via Smithery

Para instalar o suzieq-mcp para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

Instalando Manualmente

  1. Obtenha o Código: Clone este repositório ou baixe os arquivos main.py e server.py para um diretório de projeto dedicado.

  2. Crie o Ambiente Virtual: Navegue até o diretório do seu projeto no terminal e crie um ambiente virtual usando uv:

    uv venv

  3. Ative o Ambiente:

    • No macOS/Linux: 
      source .venv/bin/activate
    • No Windows: 
      .venv\Scripts\activate

    (Você deve ver (.venv) antes do seu prompt)

  4. Instale as Dependências: Instale os pacotes Python necessários usando uv:

    uv pip install mcp httpx python-dotenv
    • mcp: O SDK do Model Context Protocol.
    • httpx: Um cliente HTTP assíncrono usado para se comunicar com a API SuzieQ.
    • python-dotenv: Usado para carregar variáveis de ambiente de um arquivo .env para configuração.

Configuração

O servidor precisa do seu endpoint da API SuzieQ e da chave da API. Use um arquivo .env para configuração segura e fácil:

  1. Crie o arquivo .env: Na raiz do diretório do seu projeto (no mesmo local que main.py), crie um arquivo chamado .env.

  2. Adicione as Credenciais: Adicione seu endpoint e chave SuzieQ ao arquivo .env. Certifique-se de que não haja aspas ao redor dos valores, a menos que façam parte da chave/endpoint em si.

    # .env
SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
SUZIEQ_API_KEY=your_actual_api_key

    Substitua os valores de exemplo pelo seu endpoint e chave reais.

  3. Proteja o arquivo .env: Adicione .env ao seu arquivo .gitignore para evitar o commit acidental de segredos.

    echo ".env" >> .gitignore

  4. Integração de Código: O server.py fornecido usa automaticamente python-dotenv para carregar essas variáveis quando o servidor inicia.

Executando o Servidor

Certifique-se de que seu ambiente virtual esteja ativado. O servidor carregará a configuração do arquivo .env no diretório atual.

1. Diretamente

Execute o servidor diretamente do seu terminal:

uv run python main.py

O servidor iniciará, exibirá Starting SuzieQ MCP Server... e escutará conexões MCP na entrada/saída padrão (stdio). Você deve ver logs [INFO] se ele consultar a API com sucesso por meio da ferramenta. Pressione Ctrl+C para interrompê-lo.

2. Com o MCP Inspector (para Depuração)

O MCP Inspector é útil para testar a ferramenta diretamente. Se você tiver as ferramentas CLI mcp instaladas (via uv pip install "mcp[cli]"), execute:

uv run mcp dev main.py

Isso inicia um depurador interativo. Vá para a aba "Ferramentas", selecione run_suzieq_show, insira parâmetros (por exemplo, table: "device") e clique em "Chamar Ferramenta" para testar.

Usando com o Claude Desktop

Integre o servidor com o Claude Desktop para uso contínuo:

  1. Encontre a Configuração do Claude Desktop: Localize o arquivo claude_desktop_config.json.

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Crie o arquivo e o diretório Claude se eles não existirem.

  2. Edite o Arquivo de Configuração: Adicione uma entrada para este servidor. Use o caminho absoluto para main.py. O servidor carrega segredos de .env, então eles não precisam estar nesta configuração.

{
  "mcpServers": {
    "suzieq-server": {
      // Use 'uv' if it's in the system PATH Claude uses,
      // otherwise provide the full path to the uv executable.
      "command": "uv",
      "args": [
        "run",
        "python",
        // --- VERY IMPORTANT: Use the ABSOLUTE path below ---
        "/full/path/to/your/project/mcp-suzieq-server/main.py"
      ],
      // 'env' block is not needed here if .env is in the project directory above
      "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" // Optional, but recommended
    }
    // Add other servers here if needed
  }
}
  • Substitua /full/path/to/your/project/mcp-suzieq-server/main.py pelo caminho absoluto correto no seu sistema.
  • Substitua /full/path/to/your/project/mcp-suzieq-server/ pelo caminho absoluto do diretório que contém main.py e .env. Definir workingDirectory ajuda a garantir que o arquivo .env seja encontrado.
  • Se uv não for encontrado pelo Claude, substitua "uv" pelo seu caminho absoluto (encontre via which uv ou where uv).
  • No Windows, você pode precisar de "env": { "PYTHONUTF8": "1" } se encontrar problemas de codificação de texto.

  1. Reinicie o Claude Desktop: Feche e reabra completamente o Claude Desktop.

  2. Verifique: Procure o indicador de ferramenta MCP (ícone de martelo 🔨) no Claude Desktop. Clicar nele deve mostrar as ferramentas run_suzieq_show e run_suzieq_summarize.

Uso da Ferramenta (run_suzieq_show)

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (String, Obrigatório) O nome da tabela SuzieQ (por exemplo, "device", "interface", "bgp").
  • filters: (Dicionário, Opcional) Pares chave-valor para filtragem (por exemplo, "hostname": "leaf01"). Omita ou use {} para nenhum filtro.
  • Retorna: Uma string JSON com os resultados ou um erro.

Exemplos de Invocação (Conceitual):

Mostrar todos os dispositivos:

{ "table": "device" }

Mostrar vizinhos BGP para o hostname 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Mostrar interfaces 'up' na VRF 'default':

{ "table": "interface", "filters": { "vrf": "default", "state": "up" } }

Uso da Ferramenta (run_suzieq_summarize)

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (String, Obrigatório) O nome da tabela SuzieQ para resumir (por exemplo, "device", "interface", "bgp").
  • filters: (Dicionário, Opcional) Pares chave-valor para filtragem (por exemplo, "hostname": "leaf01"). Omita ou use {} para nenhum filtro.
  • Retorna: Uma string JSON com os resultados resumidos ou um erro.

Exemplos de Invocação (Conceitual):

Resumir todos os dispositivos:

{ "table": "device" }

Resumir sessões BGP por hostname 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Resumir estados de interface na VRF 'default':

{ "table": "interface", "filters": { "vrf": "default" } }

Solução de Problemas

Erro: "Endpoint ou chave da API SuzieQ não configurados...":

  • Certifique-se de que o arquivo .env esteja no mesmo diretório que main.py.
  • Verifique se SUZIEQ_API_ENDPOINT e SUZIEQ_API_KEY estão escritos corretamente e têm valores válidos em .env.
  • Se estiver usando o Claude Desktop, certifique-se de que o workingDirectory em claude_desktop_config.json aponte para o diretório que contém .env.

Erros HTTP (4xx, 5xx):

  • Verifique se a chave da API SuzieQ (SUZIEQ_API_KEY) está correta (erros 401/403).
  • Verifique se o SUZIEQ_API_ENDPOINT está correto e se o servidor da API está em execução.