Flight Control MCP

Una API de solo lectura para consultar y recuperar información contextual sobre dispositivos y flotas utilizando el servidor Flight Control MCP.

GitHubPrueba este MCPPatrocinado

Documentación

mcp-server

Servidor del Model Context Protocol (MCP) para Flight Control

Descripción general

El servidor MCP proporciona una capa de API de solo lectura para consultar y recuperar información contextual sobre dispositivos y flotas gestionados por Flight Control. Está diseñado para integración externa segura, generación de informes y automatización, exponiendo una API REST que admite consultas basadas en filtros y selectores. El servidor MCP utiliza el flightctl-python-client para la comunicación con el backend y aplica autenticación compatible con el modelo de autorización de Flight Control.

Compilación local

Para compilar la imagen de contenedor localmente con Podman, ejecute:

podman build -t mcp-server:latest .

Esto creará una imagen local llamada mcp-server:latest que puede utilizar para ejecutar el servidor.

Imágenes de contenedor precompiladas

✅ ¡Imágenes listas para usar se publican automáticamente en quay.io!

# Pull the latest stable image
docker pull quay.io/flightctl/flightctl-mcp:latest

# Run immediately with streamable-http transport
docker run -p 8000:8000 quay.io/flightctl/flightctl-mcp:latest

Publicación automatizada

  • 🔄 Compilaciones automáticas: Cada commit fusionado en main desencadena una nueva compilación
  • ✅ Calidad garantizada: Solo se compilan después de pasar todas las pruebas (linting, verificación de tipos, pruebas unitarias)
  • 🔒 Escaneo de seguridad: Todas las imágenes se escanean en busca de vulnerabilidades con Trivy
  • 🏗️ Multiplataforma: Disponible para linux/amd64 y linux/arm64
  • 🏷️ Etiquetado inteligente: Imágenes etiquetadas con latest, nombre de rama y SHA del commit

Para mantenedores: Consulte CONTAINER-PUBLISHING.md para instrucciones de configuración y detalles del flujo de trabajo.

Ejecución con Podman o Docker

Ejemplo: Uso de configuración automática (recomendado)

Si ha ejecutado flightctl login, puede montar el directorio de configuración. Nota: El servidor ahora usa por defecto el transporte streamable-http para una mejor integración basada en web.

{
  "mcpServers": {
    "mcp-server": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", "8000:8000",
        "-v", "~/.config/flightctl:/root/.config/flightctl:ro",
        "-e", "MCP_TRANSPORT",
        "-e", "MCP_HOST",
        "-e", "MCP_PORT",
        "quay.io/flightctl/flightctl-mcp:latest"
      ],
      "env": {
        "MCP_TRANSPORT": "streamable-http",
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000"
      }
    }
  }
}

Ejemplo: Uso de variables de entorno

Para entornos donde no es posible montar el archivo de configuración:

{
  "mcpServers": {
    "mcp-server": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", "8000:8000",
        "-e", "API_BASE_URL",
        "-e", "OIDC_TOKEN_URL",
        "-e", "OIDC_CLIENT_ID",
        "-e", "REFRESH_TOKEN",
        "-e", "INSECURE_SKIP_VERIFY",
        "-e", "LOG_LEVEL",
        "-e", "MCP_TRANSPORT",
        "-e", "MCP_HOST",
        "-e", "MCP_PORT",
        "quay.io/flightctl/flightctl-mcp:latest"
      ],
      "env": {
        "API_BASE_URL": "https://api.flightctl.example.com",
        "OIDC_TOKEN_URL": "https://auth.flightctl.example.com/realms/flightctl/protocol/openid-connect/token",
        "OIDC_CLIENT_ID": "flightctl",
        "REFRESH_TOKEN": "REDACTED",
        "INSECURE_SKIP_VERIFY": "false",
        "LOG_LEVEL": "INFO",
        "MCP_TRANSPORT": "streamable-http",
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000"
      }
    }
  }
}

Configuración de transporte

El servidor MCP admite tres métodos de transporte con stdio como predeterminado para máxima compatibilidad:

STDIO (predeterminado: máxima compatibilidad)

  • Ideal para: Herramientas locales, scripts de línea de comandos, integraciones con clientes como Claude Desktop
  • Configuración: Establezca MCP_TRANSPORT=stdio (predeterminado)
  • Por qué es el predeterminado: Máxima compatibilidad con los clientes MCP existentes

HTTP transmisible (recomendado para implementaciones web)

  • Ideal para: Implementaciones basadas en web, microservicios, exposición de MCP a través de una red
  • Endpoint predeterminado: http://127.0.0.1:8000/mcp
  • Configuración: Establezca MCP_TRANSPORT=streamable-http
  • Nota: Requiere clientes MCP que admitan el nuevo transporte streamable-http

SSE (Server-Sent Events)

  • Ideal para: Implementaciones heredadas que requieren específicamente SSE
  • Configuración: Establezca MCP_TRANSPORT=sse
  • Endpoint predeterminado: http://127.0.0.1:8000/sse

Configuración de autenticación

El servidor MCP utiliza tokens de actualización OIDC/OAuth2 para la autenticación. Para obtener las credenciales necesarias:

  1. OIDC_TOKEN_URL: Normalmente tiene el formato https://your-auth-server/realms/your-realm/protocol/openid-connect/token

    • Si solo tiene la URL base del realm (p. ej., https://auth.example.com/realms/flightctl), el servidor agregará automáticamente /protocol/openid-connect/token

  2. REFRESH_TOKEN: Obténgalo de su sistema de autenticación de Flight Control

    • Este token debe tener permisos adecuados para leer los recursos de Flight Control

  3. OIDC_CLIENT_ID: Generalmente flightctl (este es el valor predeterminado si no se especifica)

Configuración

El servidor MCP admite dos métodos de configuración:

1. Configuración automática (recomendada)

Si ha ejecutado flightctl login, el servidor leerá automáticamente la configuración de ~/.config/flightctl/client.yaml. Esto incluye:

  • URL del servidor de API
  • Configuración de autenticación OIDC
  • Configuración de certificados SSL
  • Tokens de actualización

2. Configuración mediante variables de entorno

Las siguientes variables de entorno pueden anular o complementar la configuración automática:

  • API_BASE_URL: URL base para la API de Flight Control (p. ej., https://api.flightctl.example.com) - Opcional (se lee del archivo de configuración)
  • OIDC_TOKEN_URL: URL completa del endpoint de token OIDC (p. ej., https://auth.flightctl.example.com/realms/flightctl/protocol/openid-connect/token) - Opcional (se lee del archivo de configuración)
  • OIDC_CLIENT_ID: Identificador del cliente OIDC (el valor predeterminado es flightctl) - Opcional
  • REFRESH_TOKEN: Token de actualización OAuth2 para autenticación - Opcional (se lee del archivo de configuración)
  • INSECURE_SKIP_VERIFY: Omitir la verificación de certificados SSL (true/false) - Opcional (se lee del archivo de configuración)
  • CA_CERT_PATH: Ruta al archivo de certificado CA personalizado para la verificación SSL - Opcional
  • LOG_LEVEL: Nivel de registro (DEBUG, INFO, WARNING, ERROR) - Opcional (el valor predeterminado es INFO)

3. Configuración de transporte MCP

Las siguientes variables de entorno controlan el transporte del servidor MCP y la configuración de red:

  • MCP_TRANSPORT: Mecanismo de transporte (stdio, sse, streamable-http) - Opcional (el valor predeterminado es stdio)
  • MCP_HOST: Host al que vincularse para transportes HTTP - Opcional (el valor predeterminado es 127.0.0.1)
  • MCP_PORT: Puerto para escuchar en transportes HTTP - Opcional (el valor predeterminado es 8000)
  • MCP_PATH: Ruta para el endpoint MCP - Opcional (el valor predeterminado es /mcp para streamable-http)
  • MCP_LOG_LEVEL: Nivel de registro del servidor (debug, info, warning, error) - Opcional (el valor predeterminado es info)

Manejo de certificados SSL

El servidor maneja correctamente los certificados SSL con la siguiente prioridad:

  1. Certificado CA personalizado: Si se establece CA_CERT_PATH, se utiliza el archivo de certificado especificado
  2. Omitir verificación SSL: Si INSECURE_SKIP_VERIFY=true, se desactiva la verificación de certificados (útil para desarrollo)
  3. Paquete de CA del sistema: Se utiliza el paquete de autoridades de certificación predeterminado del sistema (predeterminado en producción)

Registro (logging)

El servidor utiliza registro basado en archivos para evitar conflictos con el protocolo MCP en stdio:

  • Ubicación del registro: ~/.local/share/flightctl-mcp/flightctl-mcp.log
  • Rotación del registro: Rotación automática a 10 MB con 5 archivos de respaldo
  • Niveles de registro: Configurables mediante la variable de entorno LOG_LEVEL
  • Registro estructurado: Incluye marcas de tiempo, nombres de componentes y contexto de error detallado

Manejo de errores

El servidor proporciona un manejo robusto de errores:

  • Excepciones específicas: Utiliza excepciones tipadas (AuthenticationError, APIError, FlightControlError)
  • Registro detallado: Todos los errores se registran con contexto completo

Ejecución del servidor

Desarrollo local

# Run with default stdio transport
python main.py

# Run with streamable-http transport (for web deployments)
MCP_TRANSPORT=streamable-http python main.py

# Run with custom HTTP configuration
MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8080 python main.py

Acceso al endpoint HTTP

Cuando se ejecuta con transporte HTTP, el endpoint MCP estará disponible en:

  • HTTP transmisible: http://127.0.0.1:8000/mcp (predeterminado)
  • SSE: http://127.0.0.1:8000/sse

Ejemplos de conexión de clientes

Para clientes HTTP (streamable-http):

from fastmcp import Client

# Connect to streamable-http server
client = Client("http://127.0.0.1:8000/mcp")

Para Claude Desktop (stdio):

{
  "mcpServers": {
    "flightctl": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Endpoints de la API

El servidor MCP expone los siguientes endpoints de herramientas:

Gestión de dispositivos

  • query_devices: Consultar y filtrar dispositivos mediante selectores de etiquetas y campos
  • run_command_on_device: Ejecutar comandos de Linux en dispositivos específicos

Gestión de flotas

  • query_fleets: Consultar y filtrar configuraciones de flotas

Eventos y monitoreo

  • query_events: Consultar eventos del sistema y registros de auditoría

Inscripción

  • query_enrollment_requests: Consultar solicitudes de inscripción de dispositivos

Gestión de configuración

  • query_repositories: Consultar repositorios de configuración
  • query_resource_syncs: Consultar el estado de sincronización de recursos

Pruebas

Pruebas con instancia en vivo

Para probar contra su instancia real de Flight Control:

# Ensure you have logged in first
flightctl login

# Run the live integration test
python test_live_instance.py

Pruebas unitarias

# Run unit tests
python -m pytest test_flightctl_mcp.py -v

# Run with coverage
python -m pytest test_flightctl_mcp.py --cov=resource_queries --cov=main --cov=cli --cov-report=html

Pruebas de cliente MCP

# Test the MCP server with a simple client
python -c "
from fastmcp import Client
import asyncio

async def test():
    client = Client('http://127.0.0.1:8000/mcp')
    async with client:
        tools = await client.list_tools()
        print(f'Available tools: {[t.name for t in tools]}')

asyncio.run(test())
"

Solución de problemas

Problemas comunes

  1. El servidor no se inicia: Verifique si el puerto ya está en uso

    lsof -i :8000

  2. Fallos de autenticación: Verifique sus credenciales de Flight Control

    flightctl login

  3. Conexión rechazada: Asegúrese de que el servidor esté en ejecución y sea accesible

    curl -v http://127.0.0.1:8000/mcp

  4. Problemas de transporte: Verifique que la configuración de transporte coincida con su cliente

    # Check server logs
tail -f ~/.local/share/flightctl-mcp/flightctl-mcp.log

Modo de depuración

Habilite el registro de depuración para obtener información más detallada:

MCP_LOG_LEVEL=debug LOG_LEVEL=DEBUG python main.py

Migración desde STDIO

Si está migrando desde la versión anterior solo con stdio:

  1. Actualice la configuración de su cliente para usar endpoints HTTP en lugar de stdio
  2. Establezca variables de entorno para la configuración de host/puerto si es necesario
  3. Actualice las reglas del firewall si se ejecuta en un servidor remoto
  4. Pruebe la conexión utilizando los ejemplos de clientes proporcionados

El servidor seguirá admitiendo el transporte stdio si establece MCP_TRANSPORT=stdio, manteniendo la compatibilidad con versiones anteriores.

Características

  • Consulta de solo lectura de dispositivos, flotas, eventos, solicitudes de inscripción, repositorios y sincronizaciones de recursos de Flight Control
  • Soporte para filtrar por etiquetas y campos mediante selectores de estilo Kubernetes
  • Respuestas JSON ricas en contexto, incluidos metadatos y enlaces a recursos relacionados
  • Autenticación segura basada en tokens de actualización OIDC/OAuth2
  • Acceso remoto a la consola de dispositivos para ejecutar comandos en dispositivos gestionados
  • Manejo automático de paginación para conjuntos de resultados grandes

Documentación

Los endpoints de la API, las opciones de filtrado y las solicitudes de ejemplo se describirán en el directorio docs/ o en la especificación OpenAPI.

Licencia

Este proyecto es de código abierto. Consulte LICENSE para obtener más detalles.

Contribuciones

¡Las incidencias y las solicitudes de extracción (pull requests) son bienvenidas! Consulte CONTRIBUTING.md para conocer las pautas.