Servidor MCP de Observabilidade Docker

Um servidor Model Context Protocol (MCP) que fornece ferramentas de observabilidade para containers Docker e métricas do sistema host, utilizando FastMCP e Server-Sent Events (SSE).

📋 Visão Geral

Este projeto implementa um servidor MCP que permite monitorar e inspecionar:

• Containers Docker: Status, logs, estatísticas de uso, health checks e informações detalhadas
• Métricas do Host: CPU, memória, disco e load average via Node Exporter
• Integração com IA: Protocolo MCP permite que assistentes de IA acessem essas informações

🔧 Funcionalidades

Ferramentas Docker

• DockerPsFrom{CLIENT_NAME} - Lista containers (rodando ou todos)
• DockerStatsFrom{CLIENT_NAME} - Estatísticas de uso de recursos
• HealthcheckFrom{CLIENT_NAME} - Status de health checks
• DockerLogsFrom{CLIENT_NAME} - Logs dos containers
• DockerInspectFrom{CLIENT_NAME} - Informações detalhadas do container

Métricas do Sistema

• HostMetricsFrom{CLIENT_NAME} - Métricas completas do host:
  • CPU: Percentual de uso
  • Memória: Total, usado, disponível
  • Disco: Espaço total, livre, usado
  • Load Average: 1min, 5min, 15min

Utilitários

• GetClientNameFrom{CLIENT_NAME} - Retorna o nome do cliente configurado

🏗️ Arquitetura

mcp_sse.py              # Servidor principal FastMCP
├── tools/              # Módulos de funcionalidades
│   ├── __init__.py     # Cliente Docker base
│   ├── container_stats.py
│   ├── container_health.py
│   ├── container_logs.py
│   ├── container_inspect.py
│   ├── list_containers.py
│   └── host_metrics.py # Cliente Node Exporter
├── docker-compose.n8n.yaml
├── Dockerfile
└── requirements.txt

🚀 Como Executar

Opção 1: Docker Compose (Recomendado)

# Clone o repositório
git clone <seu-repositorio>
cd <diretorio-do-projeto>

# Execute com Docker Compose
docker-compose -f docker-compose.n8n.yaml up -d

Isso irá inicializar:

• n8n (automação) na porta 5678
• Redis para cache/sessões
• Node Exporter para métricas do sistema
• MCP Server conectado via SSE

Opção 2: Execução Local

# Instale as dependências
pip install -r requirements.txt

# Configure as variáveis de ambiente
export MCP_CLIENT_NAME="Meu-Cliente"
export NODE_EXPORTER_URL="http://localhost:9100/metrics"

# Execute o servidor
python mcp_sse.py

⚙️ Configuração

Variáveis de Ambiente

Docker Compose

O arquivo docker-compose.n8n.yaml inclui:

• N8N: Plataforma de automação com autenticação básica

  • Usuário: marcola
  • Senha: 12345678987456321
  • Porta: 5678

• Node Exporter: Coletor de métricas do sistema

  • Acesso aos diretórios /proc, /sys e / do host

• Redis: Cache e armazenamento de sessões

🔌 Integrações

Model Context Protocol (MCP)

O servidor implementa o protocolo MCP via SSE, permitindo que assistentes de IA:

1. Descubram automaticamente as ferramentas disponíveis
2. Executem comandos de observabilidade
3. Recebam dados estruturados em tempo real

Node Exporter

Integração com Prometheus Node Exporter para coleta de métricas:

from tools.host_metrics import NodeExporterClient

client = NodeExporterClient("http://node-exporter:9100/metrics")
metrics = client.get_all_metrics()

Docker API

Acesso completo à API Docker via socket Unix:

from tools import get_client

client = get_client()  # docker.from_env()
containers = client.containers.list()

📊 Exemplos de Uso

Listando Containers

# Via MCP tool
{
  "tool": "DockerPsFromMeu-Cliente",
  "arguments": {
    "all_containers": true
  }
}

Obtendo Métricas do Host

# Retorna algo como:
{
  "cpu": {"usage_percent": 23.45},
  "memory": {
    "total_bytes": 8589934592,
    "used_bytes": 4294967296,
    "used_percent": 50.0
  },
  "disk": {
    "total_bytes": 107374182400,
    "used_percent": 45.2
  },
  "load": {
    "load_1min": 1.2,
    "load_5min": 1.0,
    "load_15min": 0.8
  }
}

🔒 Segurança

• Docker Socket: Montado com acesso somente leitura quando possível
• Autenticação N8N: Configurada com usuário/senha básicos
• Isolamento: Containers executam em rede isolada
• Logs: Configurados com níveis apropriados

📝 Desenvolvimento

Estrutura de Código

• FastMCP: Framework para servidores MCP simples
• Pydantic: Validação de dados de entrada
• Docker SDK: Integração com Docker API
• Requests: Cliente HTTP para Node Exporter

Adicionando Novas Ferramentas

1. Crie um novo módulo em tools/
2. Implemente a função de negócio
3. Registre como @mcp_server.tool() em mcp_sse.py
4. Defina modelos Pydantic se necessário

Exemplo:

@mcp_server.tool(name=f"MinhaNovaFerramentaFrom{CLIENT_NAME}")
def minha_ferramenta(parametro: str):
    """Descrição da minha ferramenta"""
    return {"resultado": f"Processado: {parametro}"}

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🆘 Suporte

Para dúvidas ou problemas:

1. Verifique os logs: docker-compose logs mcp_sse
2. Teste a conectividade: curl http://localhost:9100/metrics
3. Valide o Docker socket: docker ps

Desenvolvido com ❤️ para observabilidade inteligente via MCP