SuzieQ

Interactúa con la plataforma de observabilidad de red SuzieQ a través de su API REST.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP para SuzieQ

smithery badge

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los modelos de lenguaje y otros clientes MCP interactuar con una instancia de observabilidad de red SuzieQ a través de su API REST.

Descripción General

El servidor expone los comandos de SuzieQ como herramientas MCP:

  • run_suzieq_show: Accede al comando 'show' para consultar tablas detalladas de estado de la red
  • run_suzieq_summarize: Accede al comando 'summarize' para obtener estadísticas agregadas y resúmenes

Estas herramientas permiten a los clientes (como Claude Desktop) consultar varias tablas de estado de la red (por ejemplo, interfaces, BGP, rutas) y aplicar filtros, recuperando los resultados directamente de su instancia de SuzieQ.

Requisitos Previos

  • Python: Se recomienda la versión 3.8 o superior.
  • uv: Un instalador y resolutor de paquetes de Python rápido. (Guía de instalación)
  • Instancia de SuzieQ: Una instancia de SuzieQ en ejecución con su API REST habilitada y accesible.
  • Endpoint y Clave de la API de SuzieQ: Necesita la URL para la API de SuzieQ (por ejemplo, http://your-suzieq-host:8000/api/v2) y una clave de API válida (access_token).

Instalación y Configuración

Instalación mediante Smithery

Para instalar suzieq-mcp para Claude Desktop automáticamente a través de Smithery:

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

Instalación Manual

  1. Obtener el Código: Clone este repositorio o descargue los archivos main.py y server.py en un directorio de proyecto dedicado.

  2. Crear Entorno Virtual: Navegue a su directorio de proyecto en la terminal y cree un entorno virtual usando uv:

    uv venv

  3. Activar el Entorno:

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

    (Debería ver (.venv) precediendo a su prompt)

  4. Instalar Dependencias: Instale los paquetes de Python requeridos usando uv:

    uv pip install mcp httpx python-dotenv
    • mcp: El SDK del Protocolo de Contexto de Modelo.
    • httpx: Un cliente HTTP asíncrono utilizado para comunicarse con la API de SuzieQ.
    • python-dotenv: Se utiliza para cargar variables de entorno desde un archivo .env para la configuración.

Configuración

El servidor necesita su endpoint de la API de SuzieQ y su clave de API. Use un archivo .env para una configuración segura y fácil:

  1. Crear archivo .env: En la raíz de su directorio de proyecto (el mismo lugar que main.py), cree un archivo llamado .env.

  2. Agregar Credenciales: Agregue su endpoint y clave de SuzieQ al archivo .env. Asegúrese de que no haya comillas alrededor de los valores a menos que sean parte de la clave/endpoint en sí.

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

    Reemplace los valores de marcador de posición con su endpoint y clave reales.

  3. Asegurar el archivo .env: Agregue .env a su archivo .gitignore para evitar comprometer secretos accidentalmente.

    echo ".env" >> .gitignore

  4. Integración de Código: El server.py proporcionado usa automáticamente python-dotenv para cargar estas variables cuando el servidor se inicia.

Ejecución del Servidor

Asegúrese de que su entorno virtual esté activado. El servidor cargará la configuración del archivo .env en el directorio actual.

1. Directamente

Ejecute el servidor directamente desde su terminal:

uv run python main.py

El servidor se iniciará, imprimirá Starting SuzieQ MCP Server... y escuchará conexiones MCP en la entrada/salida estándar (stdio). Debería ver registros de [INFO] si consulta exitosamente la API a través de la herramienta. Presione Ctrl+C para detenerlo.

2. Con MCP Inspector (para Depuración)

El MCP Inspector es útil para probar la herramienta directamente. Si tiene las herramientas CLI de mcp instaladas (a través de uv pip install "mcp[cli]"), ejecute:

uv run mcp dev main.py

Esto lanza un depurador interactivo. Vaya a la pestaña "Tools", seleccione run_suzieq_show, ingrese parámetros (por ejemplo, tabla: "device") y haga clic en "Call Tool" para probar.

Uso con Claude Desktop

Integre el servidor con Claude Desktop para un uso sin interrupciones:

  1. Encontrar la Configuración de Claude Desktop: Localice el archivo claude_desktop_config.json.

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Cree el archivo y el directorio de Claude si no existen.

  2. Editar el Archivo de Configuración: Agregue una entrada para este servidor. Use la ruta absoluta a main.py. El servidor carga los secretos desde .env, por lo que no necesitan estar en esta configuración.

{
  "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
  }
}
  • Reemplace /full/path/to/your/project/mcp-suzieq-server/main.py con la ruta absoluta correcta en su sistema.
  • Reemplace /full/path/to/your/project/mcp-suzieq-server/ con la ruta absoluta al directorio que contiene main.py y .env. Establecer workingDirectory ayuda a asegurar que se encuentre el archivo .env.
  • Si uv no es encontrado por Claude, reemplace "uv" con su ruta absoluta (encuéntrelo a través de which uv o where uv).
  • En Windows, podría necesitar "env": { "PYTHONUTF8": "1" } si encuentra problemas de codificación de texto.

  1. Reiniciar Claude Desktop: Cierre y vuelva a abrir completamente Claude Desktop.

  2. Verificar: Busque el indicador de herramienta MCP (icono de martillo 🔨) en Claude Desktop. Al hacer clic, debería mostrar tanto las herramientas run_suzieq_show como run_suzieq_summarize.

Uso de la Herramienta (run_suzieq_show)

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (Cadena, Obligatorio) El nombre de la tabla de SuzieQ (por ejemplo, "device", "interface", "bgp").
  • filters: (Diccionario, Opcional) Pares clave-valor para filtrar (por ejemplo, "hostname": "leaf01"). Omita o use {} para no aplicar filtros.
  • Devuelve: Una cadena JSON con los resultados o un error.

Ejemplos de Invocaciones (Conceptuales):

Mostrar todos los dispositivos:

{ "table": "device" }

Mostrar vecinos BGP para el hostname 'spine01':

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

Mostrar interfaces 'up' en la VRF 'default':

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

Uso de la Herramienta (run_suzieq_summarize)

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (Cadena, Obligatorio) El nombre de la tabla de SuzieQ a resumir (por ejemplo, "device", "interface", "bgp").
  • filters: (Diccionario, Opcional) Pares clave-valor para filtrar (por ejemplo, "hostname": "leaf01"). Omita o use {} para no aplicar filtros.
  • Devuelve: Una cadena JSON con los resultados resumidos o un error.

Ejemplos de Invocaciones (Conceptuales):

Resumir todos los dispositivos:

{ "table": "device" }

Resumir sesiones BGP por hostname 'spine01':

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

Resumir estados de interfaz en la VRF 'default':

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

Solución de Problemas

Error: "SuzieQ API endpoint or key not configured...":

  • Asegúrese de que el archivo .env esté en el mismo directorio que main.py.
  • Verifique que SUZIEQ_API_ENDPOINT y SUZIEQ_API_KEY estén escritos correctamente y tengan valores válidos en .env.
  • Si usa Claude Desktop, asegúrese de que workingDirectory en claude_desktop_config.json apunte al directorio que contiene .env.

Errores HTTP (4xx, 5xx):

  • Verifique que la clave de la API de SuzieQ (SUZIEQ_API_KEY) sea correcta (errores 401/403).
  • Verifique que SUZIEQ_API_ENDPOINT sea correcto y que el servidor de la API esté en ejecución.