homelab-evidence-mcp

homelab-evidence-mcp

Coleta evidências de incidentes somente leitura de seis fontes do homelab por meio do MCP. Um binário Go usa stdio e une identidades de fontes por meio de um service_id configurado.

O servidor ordena as evidências pelo horário de observação. Cada item inclui sua fonte, carimbos de data/hora, frescor, contagem de redação e estado de truncamento. A correlação apresenta fatos; ela não estabelece uma causa raiz. Os destinos permanecem fixos após a inicialização, e cada requisição upstream usa HTTP GET.

Instalação

Pré-requisito: Go 1.26.9 é a versão mínima.

go install github.com/ThomasCrouzet/homelab-evidence-mcp/cmd/homelab-evidence-mcp@latest

Para compilar a partir do repositório:

make build
./bin/homelab-evidence-mcp --version

Início rápido

1. Copie config.example.yaml para um diretório que não esteja no repositório.
2. Restrinja o acesso ao proprietário com chmod 600 /path/config.yaml. No Windows, use uma ACL somente para o usuário.
3. Configure as URLs das fontes e os vínculos de serviço.
4. Defina cada token obrigatório por meio de token_env ou de um token_file privado.
5. Valide a configuração antes de adicioná-la ao cliente MCP.

homelab-evidence-mcp --config /path/config.yaml --validate

A validação resolve referências de token e verifica as configurações de destino. Ela não envia requisições HTTP. Chaves YAML desconhecidas causam erro. Um base_url não pode conter strings de consulta, fragmentos ou userinfo. Para Healthchecks, use uma chave de API somente leitura.

Registro com um cliente MCP:

{
  "mcpServers": {
    "homelab-evidence": {
      "command": "/path/homelab-evidence-mcp",
      "args": ["--config", "/path/config.yaml"]
    }
  }
}

Este exemplo usa arquivos de token ou variáveis de ambiente herdadas. O servidor reserva o stdout para JSON-RPC e grava logs e eventos de auditoria no stderr. Ele também pode gravar um arquivo de auditoria rotativo configurado. Consulte configuração do cliente MCP e o exemplo de integração.

Adaptadores de fonte

O servidor possui estes adaptadores de fonte:

• Gatus: O adaptador usa GET /api/v1/endpoints/statuses. Ele seleciona o resultado com o maior carimbo de data/hora.
• Docker Engine: O adaptador usa GET /containers/json?all=true. Ele filtra campos e não inclui Config.Env.
• Loki: O adaptador usa GET /loki/api/v1/query_range. A configuração fornece o seletor.
• Healthchecks: O adaptador usa GET /api/v3/checks/. Ele usa uma chave somente leitura e não inclui URLs de ping em sua saída.
• Beszel: O adaptador usa GET /api/systems e rotas compatíveis. Ele pode fornecer um snapshot do host.
• ntfy: O adaptador usa GET /{topic}/json?poll=1&since=<unix>. A configuração fornece o tópico.

Os destinos usam apenas http e https. Para Docker, use um proxy de socket com leitura limitada. O socket Unix do Docker não é compatível com o servidor. O servidor ignora HTTP_PROXY e HTTPS_PROXY.

Você pode usar um prefixo de caminho em base_url. Por exemplo, use https://proxy.example/gatus para Gatus. O servidor mantém /gatus antes de cada rota da API do Gatus.

Defina o TTL do cache da fonte com limits.source_cache_ttl. O padrão é 15s; 0 o desativa. As chaves de cache usam um HMAC local ao processo em vez de valores de autenticação em texto claro. Os acertos de cache retêm observed_at; retrieved_at registra o novo horário de leitura. Assim, o frescor reflete a idade do snapshot.

Ferramentas MCP

• evidence_capabilities fornece a versão, fontes ativas, limites e estatísticas.
• list_services fornece serviços no registro canônico de serviços.
• service_status fornece um snapshot de Gatus, Docker, Healthchecks e Beszel.
• incident_context fornece uma linha do tempo de múltiplas fontes com limites de configuração.
• search_logs examina Loki com o seletor na configuração.
• failed_crons fornece verificações no estado down, grace ou paused.
• get_evidence lê evidências temporárias novamente por seu identificador opaco.

Todas as anotações de ferramentas identificam as ferramentas como somente leitura. Limites globais controlam janelas, tamanhos de corpo HTTP, contagens de evidências e concorrência.

Modelo de evidência

Cada item de evidência contém sua fonte e seus carimbos de data/hora de observação e coleta. Ele também contém severidade, estado de frescor, truncamento e a contagem de redação. As respostas fornecem o estado ok, absent, skipped, error e timeout de cada fonte.

Consulte o modelo de evidência e os contratos de API testados.

Segurança

Leia SECURITY.md para garantias e riscos restantes. Os principais controles de segurança são:

• Os destinos não podem mudar após a inicialização.
• O servidor não aceita redirecionamentos HTTP.
• Chamadas MCP não podem fornecer uma URL ou seletor de stream.
• O conteúdo de log é dado hostil.
• O servidor usa redação integrada e regras locais opcionais.
• No Unix, conceda apenas ao proprietário acesso aos arquivos de configuração e token. Use o modo 0600.
• No Windows, use uma ACL somente para o usuário. O binário não examina ACLs do Windows.

Demonstração local

go run ./demo

A demonstração usa fixtures HTTP locais e uma sessão MCP em memória. Ela verifica erros de fonte, redação, marcadores de instrução e requisições somente GET. Ela não inicia o executável stdio nem contata um homelab.

Desenvolvimento

make test          # tests with race detection
make test-quick    # fast tests
make lint-docs     # Markdown checks
make lint          # formatting, go vet, and golangci-lint
make coverage
make build

O CI compila binários para Linux, macOS e Windows. Os alvos principais são sistemas Linux e macOS sem cabeça.

Documentação

• Exemplo de configuração e modelo YAML
• Clientes MCP
• Playbook de incidentes
• Modelo de evidência e compatibilidade de API
• Contribuição e Changelog

Licença

MIT. Consulte LICENSE.