Flight Control MCP

Uma API somente leitura para consultar e recuperar informações contextuais sobre dispositivos e frotas usando o servidor Flight Control MCP.

GitHubExperimente este MCPPatrocinado

Documentação

mcp-server

Servidor Model Context Protocol (MCP) para Flight Control

Visão Geral

O servidor MCP fornece uma camada de API somente leitura para consultar e recuperar informações contextuais sobre dispositivos e frotas gerenciados pelo Flight Control. Ele é projetado para integração externa segura, relatórios e automação, expondo uma API REST que suporta consultas baseadas em filtros e seletores. O servidor MCP utiliza o flightctl-python-client para comunicação com o backend e impõe autenticação compatível com o modelo de autorização do Flight Control.

Compilação Local

Para compilar a imagem do contêiner localmente usando Podman, execute:

podman build -t mcp-server:latest .

Isso criará uma imagem local chamada mcp-server:latest que você pode usar para executar o servidor.

Imagens de Contêiner Pré-Compiladas

✅ Imagens prontas para uso são publicadas automaticamente no 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

Publicação Automatizada

  • 🔄 Compilações automáticas: Cada commit mesclado em main aciona uma nova compilação
  • ✅ Qualidade garantida: Somente compilações após passar em todos os testes (linting, verificação de tipos, testes unitários)
  • 🔒 Verificação de segurança: Todas as imagens são verificadas quanto a vulnerabilidades com Trivy
  • 🏗️ Multi-plataforma: Disponível para linux/amd64 e linux/arm64
  • 🏷️ Tags inteligentes: Imagens marcadas com latest, nome do branch e SHA do commit

Para mantenedores: Consulte CONTAINER-PUBLISHING.md para instruções de configuração e detalhes do fluxo de trabalho.

Executando com Podman ou Docker

Exemplo: Usando Configuração Automática (Recomendado)

Se você executou flightctl login, você pode montar o diretório de configuração. Nota: O servidor agora usa como padrão o transporte streamable-http para melhor integração baseada na 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"
      }
    }
  }
}

Exemplo: Usando Variáveis de Ambiente

Para ambientes onde montar o arquivo de configuração não é possível:

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

Configuração de Transporte

O servidor MCP suporta três métodos de transporte com stdio como padrão para máxima compatibilidade:

STDIO (Padrão - Mais Compatível)

  • Melhor para: Ferramentas locais, scripts de linha de comando, integrações com clientes como Claude Desktop
  • Configuração: Defina MCP_TRANSPORT=stdio (padrão)
  • Por que padrão: Compatibilidade máxima com clientes MCP existentes

HTTP Transmissível (Recomendado para Implantações Web)

  • Melhor para: Implantações baseadas na web, microsserviços, exposição de MCP através de uma rede
  • Endpoint padrão: http://127.0.0.1:8000/mcp
  • Configuração: Defina MCP_TRANSPORT=streamable-http
  • Nota: Requer clientes MCP que suportem o novo transporte streamable-http

SSE (Server-Sent Events)

  • Melhor para: Implantações legadas que exigem especificamente SSE
  • Configuração: Defina MCP_TRANSPORT=sse
  • Endpoint padrão: http://127.0.0.1:8000/sse

Configuração de Autenticação

O servidor MCP usa tokens de atualização OIDC/OAuth2 para autenticação. Para obter as credenciais necessárias:

  1. OIDC_TOKEN_URL: Geralmente no formato https://your-auth-server/realms/your-realm/protocol/openid-connect/token

    • Se você tiver apenas a URL base do realm (por exemplo, https://auth.example.com/realms/flightctl), o servidor anexará automaticamente /protocol/openid-connect/token

  2. REFRESH_TOKEN: Obtenha do seu sistema de autenticação do Flight Control

    • Este token deve ter permissões apropriadas para ler recursos do Flight Control

  3. OIDC_CLIENT_ID: Geralmente flightctl (este é o padrão se não for especificado)

Configuração

O servidor MCP suporta dois métodos de configuração:

1. Configuração Automática (Recomendado)

Se você executou flightctl login, o servidor lerá automaticamente a configuração de ~/.config/flightctl/client.yaml. Isso inclui:

  • URL do servidor da API
  • Configurações de autenticação OIDC
  • Configuração de certificado SSL
  • Tokens de atualização

2. Configuração por Variáveis de Ambiente

As seguintes variáveis de ambiente podem substituir ou complementar a configuração automática:

  • API_BASE_URL: URL base para a API do Flight Control (por exemplo, https://api.flightctl.example.com) - Opcional (lido do arquivo de configuração)
  • OIDC_TOKEN_URL: URL completa para o endpoint de token OIDC (por exemplo, https://auth.flightctl.example.com/realms/flightctl/protocol/openid-connect/token) - Opcional (lido do arquivo de configuração)
  • OIDC_CLIENT_ID: Identificador do cliente OIDC (padrão: flightctl) - Opcional
  • REFRESH_TOKEN: Token de atualização OAuth2 para autenticação - Opcional (lido do arquivo de configuração)
  • INSECURE_SKIP_VERIFY: Ignorar verificação de certificado SSL (true/false) - Opcional (lido do arquivo de configuração)
  • CA_CERT_PATH: Caminho para arquivo de certificado CA personalizado para verificação SSL - Opcional
  • LOG_LEVEL: Nível de registro (DEBUG, INFO, WARNING, ERROR) - Opcional (padrão: INFO)

3. Configuração de Transporte MCP

As seguintes variáveis de ambiente controlam o transporte e as configurações de rede do servidor MCP:

  • MCP_TRANSPORT: Mecanismo de transporte (stdio, sse, streamable-http) - Opcional (padrão: stdio)
  • MCP_HOST: Host para vincular em transportes HTTP - Opcional (padrão: 127.0.0.1)
  • MCP_PORT: Porta para escutar em transportes HTTP - Opcional (padrão: 8000)
  • MCP_PATH: Caminho para o endpoint MCP - Opcional (padrão: /mcp para streamable-http)
  • MCP_LOG_LEVEL: Nível de registro do servidor (debug, info, warning, error) - Opcional (padrão: info)

Tratamento de Certificado SSL

O servidor trata corretamente certificados SSL na seguinte prioridade:

  1. Certificado CA Personalizado: Se CA_CERT_PATH estiver definido, usa o arquivo de certificado especificado
  2. Ignorar Verificação SSL: Se INSECURE_SKIP_VERIFY=true, desativa a verificação de certificado (útil para desenvolvimento)
  3. Pacote CA do Sistema: Usa o pacote de autoridade de certificação padrão do sistema (padrão de produção)

Registro (Logging)

O servidor usa registro baseado em arquivo para evitar conflitos com o protocolo MCP no stdio:

  • Local do Registro: ~/.local/share/flightctl-mcp/flightctl-mcp.log
  • Rotação de Registro: Rotação automática em 10MB com 5 arquivos de backup
  • Níveis de Registro: Configuráveis via variável de ambiente LOG_LEVEL
  • Registro Estruturado: Inclui carimbos de data/hora, nomes de componentes e contexto detalhado de erros

Tratamento de Erros

O servidor fornece tratamento robusto de erros:

  • Exceções Específicas: Usa exceções tipadas (AuthenticationError, APIError, FlightControlError)
  • Registro Detalhado: Todos os erros são registrados com contexto completo

Executando o Servidor

Desenvolvimento 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

Acessando o Endpoint HTTP

Ao executar com transporte HTTP, o endpoint MCP estará disponível em:

  • HTTP Transmissível: http://127.0.0.1:8000/mcp (padrão)
  • SSE: http://127.0.0.1:8000/sse

Exemplos de Conexão de Cliente

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 da API

O servidor MCP expõe os seguintes endpoints de ferramentas:

Gerenciamento de Dispositivos

  • query_devices: Consultar e filtrar dispositivos usando seletores de rótulo e campo
  • run_command_on_device: Executar comandos Linux em dispositivos específicos

Gerenciamento de Frotas

  • query_fleets: Consultar e filtrar configurações de frotas

Eventos e Monitoramento

  • query_events: Consultar eventos do sistema e logs de auditoria

Inscrição (Enrollment)

  • query_enrollment_requests: Consultar solicitações de inscrição de dispositivos

Gerenciamento de Configuração

  • query_repositories: Consultar repositórios de configuração
  • query_resource_syncs: Consultar status de sincronização de recursos

Testes

Teste com Instância ao Vivo

Para testar contra sua instância real do Flight Control:

# Ensure you have logged in first
flightctl login

# Run the live integration test
python test_live_instance.py

Testes Unitários

# 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

Testes com 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())
"

Solução de Problemas

Problemas Comuns

  1. Servidor não inicia: Verifique se a porta já está em uso

    lsof -i :8000

  2. Falhas de autenticação: Verifique suas credenciais do Flight Control

    flightctl login

  3. Conexão recusada: Certifique-se de que o servidor está em execução e acessível

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

  4. Problemas de transporte: Verifique se a configuração de transporte corresponde ao seu cliente

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

Modo de Depuração

Ative o registro de depuração para informações mais detalhadas:

MCP_LOG_LEVEL=debug LOG_LEVEL=DEBUG python main.py

Migração do STDIO

Se você está migrando da versão anterior somente stdio:

  1. Atualize a configuração do seu cliente para usar endpoints HTTP em vez de stdio
  2. Defina variáveis de ambiente para configuração de host/porta, se necessário
  3. Atualize regras de firewall se estiver executando em um servidor remoto
  4. Teste a conexão usando os exemplos de cliente fornecidos

O servidor ainda suportará transporte stdio se você definir MCP_TRANSPORT=stdio, mantendo compatibilidade retroativa.

Recursos

  • Consulta somente leitura de dispositivos, frotas, eventos, solicitações de inscrição, repositórios e sincronizações de recursos do Flight Control
  • Suporte para filtragem por rótulos e campos usando seletores no estilo Kubernetes
  • Respostas JSON ricas em contexto, incluindo metadados e links para recursos relacionados
  • Autenticação segura baseada em token de atualização OIDC/OAuth2
  • Acesso remoto ao console de dispositivos para executar comandos em dispositivos gerenciados
  • Tratamento automático de paginação para grandes conjuntos de resultados

Documentação

Endpoints da API, opções de filtragem e exemplos de solicitações serão descritos no diretório docs/ ou na especificação OpenAPI.

Licença

Este projeto é open source. Consulte LICENSE para detalhes.

Contribuição

Issues e pull requests são bem-vindos! Consulte CONTRIBUTING.md para diretrizes.