MCP Prometheus Agentivo para Observabilidade Conversacional

Esta aplicação implementa um servidor MCP (Model Context Protocol) em Python, projetado para atuar como um executor seguro e não-declarativo de consultas PromQL sobre um Prometheus já existente, permitindo que Modelos de Linguagem (LLMs) realizem investigações dinâmicas de observabilidade de forma controlada, auditável e sem acoplamento a contratos fixos.

A solução foi concebida para habilitar observabilidade conversacional e diagnósticos orientados por hipóteses, onde o LLM decide autonomamente quais métricas consultar, em que ordem e com qual granularidade, enquanto o MCP garante segurança operacional, limitação de impacto e isolamento de infraestrutura.

🎯 Objetivos

Observabilidade Conversacional: Permitir que LLMs investiguem métricas de forma natural e interativa
Diagnósticos Orientados por Hipóteses: LLM decide dinamicamente quais queries executar baseado no contexto
Segurança Operacional: Validações e limites para prevenir queries perigosas ou com alto impacto
Isolamento de Infraestrutura: Camada de abstração que protege o Prometheus subjacente
Auditabilidade: Todas as queries são validadas e podem ser rastreadas

🏗️ Arquitetura

O projeto segue o padrão MVC (Model-View-Controller) para garantir separação de responsabilidades e facilitar manutenção:

MCP_Metrics/
├── models/                          # Camada de Modelo (Lógica de Negócio)
│   ├── __init__.py
│   ├── prometheus_validator.py      # Validações de PromQL e limites de segurança
│   └── prometheus_client.py         # Cliente HTTP para comunicação com Prometheus
│
├── views/                           # Camada de Visualização (Formatação)
│   ├── __init__.py
│   └── prometheus_view.py           # Formatação de respostas no padrão MCP
│
├── controllers/                     # Camada de Controle (Coordenação)
│   ├── __init__.py
│   └── prometheus_controller.py     # Coordena validações, requisições e formatação
│
├── main.py                          # Ponto de entrada do servidor MCP
├── requirements.txt                 # Dependências do projeto
├── Dockerfile                       # Configuração Docker (Python 3.11)
├── docker-compose.yml               # Orquestração Docker Compose
├── .dockerignore                    # Arquivos ignorados no build Docker
└── README.md                        # Este arquivo

Componentes

Models (Modelos)

PrometheusValidator: Valida queries PromQL e aplica limites de segurança
- Validação de sintaxe e comprimento
- Bloqueio de funções perigosas (count_values, label_replace, absent_over_time)
- Limites de range (máximo 24 horas)
- Step mínimo de 30 segundos
PrometheusClient: Gerencia comunicação HTTP com o Prometheus
- Queries instantâneas (/api/v1/query)
- Range queries (/api/v1/query_range)
- Tratamento de erros e timeouts (10 segundos)

Views (Visualizações)

PrometheusView: Formata respostas no padrão MCP
- Conversão de dados do Prometheus para formato JSON estruturado
- Compatibilidade com protocolo MCP

Controllers (Controladores)

PrometheusController: Coordena todo o fluxo de execução
- Orquestra validações
- Executa requisições ao Prometheus
- Formata respostas para o LLM

🚀 Instalação

Pré-requisitos

Python 3.11 (recomendado) ou Python 3.8+
Acesso a uma instância do Prometheus
Variável de ambiente PROMETHEUS_URL configurada
Docker e Docker Compose (opcional, para uso com containers)

Instalação Local

Clone o repositório ou navegue até o diretório do projeto:

git clone <url-do-repositorio>
cd MCP_Metrics

Instale as dependências:

pip install -r requirements.txt

Configure a variável de ambiente:

# Linux/Mac
export PROMETHEUS_URL=http://localhost:9090

# Windows (CMD)
set PROMETHEUS_URL=http://localhost:9090

# Windows (PowerShell)
$env:PROMETHEUS_URL="http://localhost:9090"

Execute o servidor:

python main.py

🐳 Docker

Usando Docker Compose (Recomendado)

Configure a variável de ambiente PROMETHEUS_URL:

# Linux/Mac
export PROMETHEUS_URL=http://host.docker.internal:9090

# Windows (PowerShell)
$env:PROMETHEUS_URL="http://host.docker.internal:9090"

Execute o container:

# Iniciar em background
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar o container
docker-compose down

O servidor MCP estará disponível na porta 7000.

Usando Docker diretamente

Construa a imagem:

docker build -t prometheus-mcp .

Execute o container:

docker run -d \
  --name prometheus-mcp \
  -p 7000:7000 \
  -e PROMETHEUS_URL=http://host.docker.internal:9090 \
  prometheus-mcp

Verifique os logs:

docker logs -f prometheus-mcp

Nota:

Se o Prometheus estiver em outro host, ajuste PROMETHEUS_URL adequadamente
Para acessar o Prometheus na máquina host, use host.docker.internal (Mac/Windows) ou o IP do host (Linux)
Se o Prometheus estiver em uma rede Docker, use o nome do serviço ou IP do container

💻 Uso

Executar o Servidor MCP

python main.py

O servidor MCP será iniciado na porta 7000 e estará pronto para receber requisições de LLMs compatíveis com MCP.

Verificar se o Servidor está Funcionando

Você pode verificar se o servidor está rodando verificando os logs ou testando a conexão na porta 7000.

Ferramenta MCP: `promql_execute`

O servidor expõe uma ferramenta chamada promql_execute que permite executar queries PromQL de forma segura.

Parâmetros

promql (obrigatório): Query PromQL a ser executada
range (opcional, padrão: false): Se true, executa uma range query
start (opcional): Data/hora de início em formato ISO (obrigatório se range=true)
end (opcional): Data/hora de fim em formato ISO (obrigatório se range=true)
step (opcional): Intervalo em segundos (obrigatório se range=true, mínimo: 30s)

Exemplo de Query Instantânea

{
  "promql": "up{job=\"prometheus\"}"
}

Exemplo de Range Query

{
  "promql": "rate(http_requests_total[5m])",
  "range": true,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-01T01:00:00Z",
  "step": "30s"
}

🔒 Segurança e Limitações

Validações Implementadas

Validação de PromQL:
- Query não pode ser vazia ou nula
- Comprimento máximo de 500 caracteres
- Bloqueio de funções perigosas
Limites de Range:
- Range máximo de 24 horas
- Step mínimo de 30 segundos
- Validação de formato de datas (ISO 8601)
Funções Bloqueadas:
- count_values
- label_replace
- absent_over_time
Timeouts:
- Timeout de 10 segundos para requisições HTTP

Por que essas limitações?

Prevenção de sobrecarga: Limites de range e step previnem queries que consomem muitos recursos
Segurança de dados: Funções bloqueadas podem expor informações sensíveis ou causar problemas de performance
Isolamento: A camada de validação protege o Prometheus de queries maliciosas ou acidentais
Estabilidade: Timeouts previnem que queries lentas bloqueiem o servidor

🧪 Casos de Uso

Observabilidade Conversacional

Um LLM pode investigar problemas de forma natural:

Usuário: "Por que a latência está alta?"
LLM: [Executa query para verificar latência]
     [Identifica pico em determinado serviço]
     [Executa query para investigar métricas relacionadas]
     [Fornece diagnóstico baseado nos dados]

Diagnósticos Orientados por Hipóteses

O LLM formula hipóteses e as testa dinamicamente:

Hipótese 1: "O problema pode ser relacionado a CPU"
→ Executa: cpu_usage{service="api"}

Hipótese 2: "Pode ser um problema de memória"
→ Executa: memory_usage{service="api"}

[Continua investigando baseado nos resultados]

🐛 Troubleshooting

Problemas Comuns

Erro: "PROMETHEUS_URL não configurada"

Solução: Certifique-se de que a variável de ambiente PROMETHEUS_URL está configurada corretamente:

# Verificar se está configurada
echo $PROMETHEUS_URL  # Linux/Mac
echo %PROMETHEUS_URL% # Windows CMD
echo $env:PROMETHEUS_URL # Windows PowerShell

Erro: "Connection refused" ou timeout

Soluções:

Verifique se o Prometheus está rodando e acessível
Teste a conexão: curl http://localhost:9090/api/v1/query?query=up
Se estiver usando Docker, verifique se PROMETHEUS_URL aponta para o host correto
Em Linux, use o IP do host em vez de host.docker.internal

Erro: "PromQL inválida" ou "Função PromQL bloqueada"

Solução: Verifique se a query não contém funções bloqueadas e está dentro do limite de 500 caracteres.

Porta 7000 já em uso

Solução:

Pare outros processos usando a porta 7000
Ou modifique a porta no main.py e no docker-compose.yml

Logs e Debugging

Docker Compose

# Ver logs em tempo real
docker-compose logs -f

# Ver últimas 100 linhas
docker-compose logs --tail=100

Docker

# Ver logs do container
docker logs -f prometheus-mcp

# Ver últimas 100 linhas
docker logs --tail=100 prometheus-mcp

📝 Desenvolvimento

Estrutura de Código

O código segue princípios de:

Separação de responsabilidades: Cada classe tem uma função específica
Testabilidade: Componentes isolados facilitam testes unitários
Manutenibilidade: Código organizado e documentado
Extensibilidade: Fácil adicionar novas validações ou funcionalidades

Adicionar Novas Validações

Para adicionar novas validações, edite models/prometheus_validator.py:

def validate_promql(promql: str):
    # Adicione suas validações aqui
    pass

Adicionar Novas Funções Bloqueadas

Edite a lista FORBIDDEN_FUNCTIONS em models/prometheus_validator.py:

FORBIDDEN_FUNCTIONS = [
    "count_values",
    "label_replace",
    "absent_over_time",
    "sua_funcao_aqui"  # Adicione novas funções
]

Modificar Limites

Edite as constantes em models/prometheus_validator.py:

MAX_PROMQL_LENGTH = 500  # Ajuste o limite de caracteres
MIN_STEP_SECONDS = 30     # Ajuste o step mínimo
MAX_RANGE_HOURS = 24      # Ajuste o range máximo

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

Mantenha o padrão MVC
Adicione validações apropriadas
Documente mudanças significativas
Teste suas alterações
Siga as convenções de código existentes

📄 Licença

Este projeto é fornecido como está, para uso em ambientes de observabilidade e diagnóstico.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
controllers		controllers
models		models
tests		tests
views		views
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
docker-compose.yml		docker-compose.yml
main.py		main.py
readme.md		readme.md
requirements.txt		requirements.txt

License

GabrielFernandesDEV/MCP_Metrics

Folders and files

Latest commit

History

Repository files navigation