mcp-infra-lens

Explica incidentes en Linux a través de SSH con herramientas MCP que conocen las líneas base.

Demo

Respuesta de ejemplo de analyze_server cuando Claude pregunta: "¿Qué le pasa a prod-01?":

{
  "host": "prod-01.internal",
  "health_score": 42,
  "summary": "Found 2 anomalies on prod-01.internal. Most urgent signal: CPU is at 91% (3.4σ above baseline 28.2%). Load is 7.2/6.8/5.1. Top CPU consumer: java (87%).",
  "anomalies": [
    {
      "metric": "cpu",
      "severity": "high",
      "value": 91,
      "z_score": 3.4,
      "explanation": "CPU is at 91% (3.4σ above baseline 28.2%). Load is 7.2/6.8/5.1. Top CPU consumer: java (87%).",
      "recommendation": "Investigate java (PID 18432) and review application logs or scale-out options."
    },
    {
      "metric": "disk:/",
      "severity": "high",
      "value": 91,
      "explanation": "Disk / is 91% full (182GB/200GB).",
      "recommendation": "Run du -sh //* | sort -rh | head -20 and clean logs or temporary files."
    }
  ]
}

Qué hace

mcp-infra-lens se conecta a hosts Linux mediante SSH, captura una instantánea de la infraestructura en tiempo real, la compara con líneas base registradas recientemente y explica las anomalías en lenguaje sencillo.

• Recopila datos de CPU, memoria, disco, red, procesos y SO sin modificar el host de destino

• Registra el historial de métricas local en SQLite para líneas base, comparaciones y consultas de tendencias

• Utiliza análisis de puntuación z (z-score) para la detección de anomalías de CPU una vez que existen suficientes muestras de línea base

• Explica la causa probable de la presión, no solo el valor bruto de la métrica

• Soporta MCP a través de stdio y HTTP transmitible

Cómo funciona

flowchart TD
    A["Claude / Cursor / VS Code / Windsurf"] --> B["mcp-infra-lens"]
    B --> C["server-core.ts"]
    C --> D["collector.ts"]
    C --> E["analyzer.ts"]
    C --> F["baseline.ts + db.ts"]
    D --> G["ssh.ts"]
    G --> H["Linux host over SSH"]
    F --> I["SQLite history + baselines"]

analyze_server ahora realiza una recopilación muestreada real durante el duration_minutes solicitado, promedia la presión de CPU y memoria a través de la ventana de recopilación, persiste la instantánea resultante y luego ejecuta la detección de anomalías contra la línea base seleccionada.

Herramientas

Inicio rápido

1. Ejecutar mediante npx

npx -y mcp-infra-lens

Si estás fijado en la versión 1.0.1, actualiza a 1.0.2 o superior para evitar fallos de instalación nativa en Node 24:

npx -y mcp-infra-lens@latest

2. Claude Desktop

Paquete publicado:

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "mcp-infra-lens"],
      "env": {
        "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db"
      }
    }
  }
}

Desarrollo local:

{
  "mcpServers": {
    "infra-lens": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-infra-lens/dist/mcp.js"],
      "env": {
        "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db"
      }
    }
  }
}

3. Docker

docker build -t mcp-infra-lens .
docker run --rm -it \
  -v "$HOME/.mcp-infra-lens:/home/appuser/.mcp-infra-lens" \
  mcp-infra-lens

Configuración

Puntuación de salud

• 90-100: saludable, no se detectaron anomalías significativas

• 70-89: presión leve o aislada

• 40-69: múltiples advertencias o un problema importante en curso

• 0-39: condición crítica con necesidad de remediación urgente

Flujo de trabajo recomendado

1. Registra muestras con record_baseline durante ventanas de operación saludable.

2. Usa analyze_server durante incidentes o picos de carga.

3. Usa compare_to_baseline para una vista diferencial más ajustada contra una línea base nombrada.

4. Usa get_history para inspeccionar tendencias y separar instantáneas predeterminadas de sesiones de línea base etiquetadas.

Autenticación

El esquema de entrada SSH soporta:

• Autenticación por contraseña

• Autenticación por clave privada en línea

• Soporte opcional de frase de contraseña para claves cifradas

Los campos de credenciales se eliminan de los registros estructurados antes de escribirse en stderr.

Notas de seguridad

• La recopilación SSH es de solo lectura en el host de destino

• Las credenciales SSH nunca se almacenan en SQLite

• La verificación de la clave del host es permisiva en la v1 por compatibilidad; los despliegues en producción deben restringir el acceso a la red saliente y planificar la aplicación de una verificación estricta del host en una versión posterior

• El transporte HTTP no tiene autenticación integrada; enlaza a loopback y colócalo detrás de un proxy inverso autenticado en cualquier despliegue no local

Consulta SECURITY.md para conocer la política de informes y el alcance de los datos almacenados.

Integraciones

Claude Desktop

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "mcp-infra-lens"],
      "env": {
        "INFRA_LENS_DB": "/Users/you/.mcp-infra-lens/metrics.db"
      }
    }
  }
}

Cursor IDE

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "mcp-infra-lens"]
    }
  }
}

VS Code (extensión MCP)

{
  "inputs": [],
  "servers": {
    "infra-lens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-infra-lens"]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "infra-lens": {
      "command": "npx",
      "args": ["-y", "mcp-infra-lens"]
    }
  }
}

Docker (transporte HTTP)

docker run -d \
  -p 3000:3000 \
  -v $HOME/.mcp-infra-lens:/home/appuser/.mcp-infra-lens \
  ghcr.io/oaslananka/mcp-infra-lens:latest

Luego configura tu cliente MCP para usar http://localhost:3000.

Docker

La imagen de Docker incluida:

• Construye el proyecto TypeScript en una etapa separada

• Reconstruye better-sqlite3 para la arquitectura del contenedor en ambas etapas

• Se ejecuta como un appuser sin privilegios de root

• Almacena datos de SQLite en /home/appuser/.mcp-infra-lens/metrics.db

Contribución

Las contribuciones son bienvenidas. Comienza con CONTRIBUTING.md, luego usa:

• docs/usage.md para ejemplos de herramientas

• docs/architecture.md para el mapa de componentes

• docs/testing.md para validación local y comprobaciones de publicación

• RELEASE_POLICY.md para las reglas de versionado de npm y el Registro MCP

• AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md y .agent/rules/repository.md para orientación de codificación con IA específica del repositorio

Notas operativas / CI

• azure-pipelines.yml es la canalización de CI canónica y ahora ejecuta una etapa de Quality en Node 20 y Node 22, publica artefactos JUnit y Cobertura, y ejecuta cobertura e2e de SSH respaldada por Docker en Node 20

• .azure/pipelines/publish.yml sigue siendo la canalización de lanzamiento manual de npm

• .azure/pipelines/mirror.yml sigue disponible para flujos de trabajo de duplicación de repositorios

• Publica solo después de que la lista de verificación previa a la publicación local y la CI pasen limpiamente en Node 20

• Sigue RELEASE_POLICY.md al decidir si un cambio necesita publicación de pre-lanzamiento en npm, Registro MCP o solo en el registro

Licencia

MIT