homelab-evidence-mcp

homelab-evidence-mcp

Recopila evidencia de incidentes de solo lectura de seis fuentes de homelab a través de MCP. Un binario Go utiliza stdio y une identidades de fuentes mediante un service_id configurado.

El servidor ordena la evidencia por tiempo de observación. Cada elemento incluye su fuente, marcas de tiempo, frescura, recuento de redacción y estado de truncamiento. La correlación presenta hechos; no establece una causa raíz. Los destinos permanecen fijos después del inicio, y cada solicitud ascendente utiliza HTTP GET.

Instalación

Requisito previo: Go 1.26.9 es la versión mínima.

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

Para compilar desde el repositorio:

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

Inicio rápido

1. Copie config.example.yaml a un directorio que no esté en el repositorio.
2. Restrinja el acceso al propietario con chmod 600 /path/config.yaml. En Windows, use una ACL de solo usuario.
3. Configure las URL de las fuentes y los enlaces de servicio.
4. Establezca cada token requerido mediante token_env o un token_file privado.
5. Valide la configuración antes de agregarla al cliente MCP.

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

La validación resuelve referencias de tokens y verifica la configuración de destinos. No envía solicitudes HTTP. Las claves YAML desconocidas causan un error. Un base_url no puede contener cadenas de consulta, fragmentos o userinfo. Para Healthchecks, use una clave API de solo lectura.

Registro con un cliente MCP:

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

Este ejemplo utiliza archivos de tokens o variables de entorno heredadas. El servidor reserva stdout para JSON-RPC y escribe registros y eventos de auditoría en stderr. También puede escribir un archivo de auditoría rotativo configurado. Consulte Configuración del cliente MCP y el ejemplo de integración.

Adaptadores de fuentes

El servidor tiene estos adaptadores de fuentes:

• Gatus: El adaptador utiliza GET /api/v1/endpoints/statuses. Selecciona el resultado con la marca de tiempo más grande.
• Docker Engine: El adaptador utiliza GET /containers/json?all=true. Filtra campos y no incluye Config.Env.
• Loki: El adaptador utiliza GET /loki/api/v1/query_range. La configuración proporciona el selector.
• Healthchecks: El adaptador utiliza GET /api/v3/checks/. Utiliza una clave de solo lectura y no incluye URL de ping en su salida.
• Beszel: El adaptador utiliza GET /api/systems y rutas compatibles. Puede proporcionar una instantánea del host.
• ntfy: El adaptador utiliza GET /{topic}/json?poll=1&since=<unix>. La configuración proporciona el tema.

Los destinos utilizan solo http y https. Para Docker, use un proxy de socket con límite de lectura. El socket Unix de Docker no es compatible con el servidor. El servidor ignora HTTP_PROXY y HTTPS_PROXY.

Puede usar un prefijo de ruta en base_url. Por ejemplo, use https://proxy.example/gatus para Gatus. El servidor mantiene /gatus antes de cada ruta API de Gatus.

Establezca el TTL de caché de fuentes con limits.source_cache_ttl. El valor predeterminado es 15s; 0 lo desactiva. Las claves de caché utilizan un HMAC local al proceso en lugar de valores de autenticación en texto claro. Los aciertos de caché conservan observed_at; retrieved_at registra la nueva hora de lectura. Por lo tanto, la frescura refleja la antigüedad de la instantánea.

Herramientas MCP

• evidence_capabilities proporciona la versión, fuentes activas, límites y estadísticas.
• list_services proporciona servicios en el registro de servicios canónico.
• service_status proporciona una instantánea de Gatus, Docker, Healthchecks y Beszel.
• incident_context proporciona una línea de tiempo de múltiples fuentes con límites de configuración.
• search_logs examina Loki con el selector en la configuración.
• failed_crons proporciona verificaciones en el estado down, grace o paused.
• get_evidence lee evidencia temporal nuevamente mediante su identificador opaco.

Todas las anotaciones de herramientas las identifican como de solo lectura. Los límites globales controlan ventanas, tamaños de cuerpo HTTP, recuentos de evidencia y concurrencia.

Modelo de evidencia

Cada elemento de evidencia contiene su fuente y sus marcas de tiempo de observación y recopilación. También contiene severidad, estado de frescura, truncamiento y el recuento de redacción. Las respuestas proporcionan el estado ok, absent, skipped, error y timeout de cada fuente.

Consulte el modelo de evidencia y contratos de API probados.

Seguridad

Lea SECURITY.md para garantías y riesgos restantes. Los controles de seguridad principales son:

• Los destinos no pueden cambiar después del inicio.
• El servidor no acepta redirecciones HTTP.
• Las llamadas MCP no pueden proporcionar una URL o selector de flujo.
• El contenido de los registros es datos hostiles.
• El servidor utiliza redacción integrada y reglas locales opcionales.
• En Unix, otorgue solo al propietario acceso a los archivos de configuración y tokens. Use el modo 0600.
• En Windows, use una ACL de solo usuario. El binario no examina las ACL de Windows.

Demostración local

go run ./demo

La demostración utiliza fixtures HTTP locales y una sesión MCP en memoria. Verifica errores de fuentes, redacción, marcadores de instrucciones y solicitudes solo GET. No inicia el ejecutable stdio ni contacta un homelab.

Desarrollo

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

CI compila binarios para Linux, macOS y Windows. Los objetivos principales son sistemas Linux y macOS sin interfaz gráfica.

Documentación

• Ejemplo de configuración y plantilla YAML
• Clientes MCP
• Manual de incidentes
• Modelo de evidencia y compatibilidad de API
• Contribución y Registro de cambios

Licencia

MIT. Consulte LICENSE.