Servidor MCP de Diagnóstico de Linux - Demostración de Clase

Una adaptación para Python/Linux del repositorio de enseñanza original MCPDemo. Este repositorio alcanza ahora la paridad con el Hito 7 para el flujo de enseñanza público: inspección compacta del sistema, análisis detallado de procesos de Linux, instantáneas de registros como recursos, flujos de trabajo, MCP autenticado sobre HTTP en /mcp, solicitud explícita antes de la terminación de procesos, diagnóstico de Linux asistido por muestreo e instantáneas de /proc y /sys con raíces permitidas.

Qué muestra esta demostración

Esta demostración de clase incluye ahora:

• ✅ Herramientas: herramientas de diagnóstico de Linux para get_system_info, get_process_list, get_process_by_id, get_process_by_name y kill_process con solicitud de confirmación

• ✅ Recursos: recursos de instantáneas de registros paginados syslog://snapshot/...

• ✅ Prompts: flujos de trabajo MCP para análisis de errores, investigación de CPU, revisión de seguridad y diagnóstico de salud

• ✅ Transporte HTTP: MCP transmitible sobre http://127.0.0.1:5000/mcp

• ✅ Autenticación con clave API: cabecera X-API-Key o ?apiKey=secure-mcp-key

• ✅ Cliente de chat de IA: un cliente de Azure OpenAI en Python que inicia el servidor HTTP local, permite al modelo llamar a herramientas, prompts y recursos de MCP, y maneja la solicitud de formularios locales en la terminal

• ✅ Implementación en Python 3.12 con el SDK oficial de MCP para Python

• ✅ Múltiples métodos de prueba

• ✅ Solicitud del Hito 5 para kill_process

• ✅ Diagnóstico de Linux asistido por muestreo del Hito 6

• ✅ Raíces del Hito 7 para instantáneas de solo lectura de /proc y /sys

Related MCP server: troubleshooting-mcp-server

Inicio rápido

1. Instalación

Instalación solo del servidor:

python3 -m pip install --user --break-system-packages -e .

Instalar los extras del cliente de chat de la clase:

python3 -m pip install --user --break-system-packages -e '.[llm]'

2. Prueba rápida (sin LLM)

python3 scripts/smoke_test.py

Este script:

1. Inicia el servidor HTTP MCP local

2. Verifica 401 Unauthorized sin una clave API

3. Realiza el saludo de inicialización de MCP en /mcp

4. Confirma que el flujo mcp-session-id funciona entre solicitudes

5. Descubre herramientas, prompts y plantillas de recursos

6. Ejercita los flujos de sistema, procesos, instantáneas de registros, instantáneas de proc y diagnósticos asistidos por muestreo

7. Verifica que kill_process falla de forma segura cuando el cliente no anuncia soporte para solicitudes

8. Verifica que el cliente de chat de la clase falla de forma segura cuando faltan los ajustes de Azure OpenAI

3. Ejecutar el servidor manualmente

python3 -m mcp_linux_diag_server

El servidor escucha en:

• endpoint: http://127.0.0.1:5000/mcp

• clave API de demostración: secure-mcp-key

4. Probar con MCP Inspector o la configuración de MCP de VS Code

Inicie el servidor en una terminal y luego conéctese usando el endpoint HTTP anterior.

Este repositorio incluye .vscode/mcp.json con la cabecera requerida:

{
  "servers": {
    "linux-diag-demo": {
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "X-API-Key": "secure-mcp-key"
      }
    }
  }
}

Si su inspector acepta una URL directamente, esta forma de cadena de consulta también funciona:

http://127.0.0.1:5000/mcp?apiKey=secure-mcp-key

5. Usar el cliente de chat de la clase

Copie el archivo de entorno de muestra y rellene sus ajustes locales de Azure OpenAI:

cp .env.example .env.local
$EDITOR .env.local
python3 -m mcp_linux_diag_server.client --prompt "Summarize this machine."

Para reflejar más fielmente el flujo de credenciales original de .NET, establezca:

MCP_DEMO_AZURE_OPENAI_USE_DEFAULT_CREDENTIAL=true

y omita la clave API.

Ejecute el chat interactivo:

python3 -m mcp_linux_diag_server.client

O ejecute un solo prompt:

python3 -m mcp_linux_diag_server.client --prompt "What is the system information?"

Las herramientas

Información del sistema

• get_system_info - Devuelve una instantánea compacta del sistema Linux o WSL

  • Nombre del host

  • Usuario actual

  • Descripción de la distribución de Linux

  • Versión del kernel

  • Arquitectura

  • Número de CPUs lógicas

  • Entorno de ejecución de Python

  • Directorio de trabajo actual

  • Tiempo de actividad (uptime)

  • Promedios de carga

  • Resumen de memoria

  • Indicador de detección de WSL

Inspección de procesos

• get_process_list - Devuelve una lista ligera de procesos en ejecución con nombres y PIDs

• get_process_by_id - Devuelve información detallada del proceso de Linux para un PID

• get_process_by_name - Devuelve información detallada paginada del proceso para un nombre de proceso

  • Por defecto page_number=1

  • Por defecto page_size=5

  • Mantiene el flujo de enseñanza de listar primero, detallar después de la demo original

• kill_process - Termina un proceso de Linux solo después de una solicitud explícita

  • Si se omite process_id, el servidor muestrea los principales consumidores de CPU y pide al cliente que elija uno

  • El servidor siempre requiere la frase de confirmación escrita CONFIRM PID {pid}

  • El cliente de la clase maneja estas solicitudes localmente en la terminal cuando stdin/stdout son interactivos

• troubleshoot_linux_diagnostics - Utiliza muestreo para convertir una pregunta de diagnóstico de Linux en lenguaje natural en una lectura validada de /proc o /sys

  • El servidor valida la ruta y el campo muestreados contra una lista de permitidos antes de leer nada

  • Adaptación exacta de Python: la consulta muestreada es una línea segura de PATH o PATH | grep FIELD en lugar de WQL

  • El servidor luego muestrea de nuevo para resumir la observación al usuario

• create_proc_snapshot - Crea una instantánea inmutable de solo lectura desde una ruta permitida de /proc o /sys y devuelve URIs de recursos

  • Las instantáneas de archivos paginan el contenido línea por línea

  • Las instantáneas de directorios paginan metadatos secundarios deterministas sin seguir enlaces simbólicos

  • Aplica raíces permitidas explícitas antes de leer nada

• request_proc_access - Utiliza la solicitud para pedir acceso de solo lectura a una raíz adicional de /proc o /sys

  • Añade la raíz aprobada a la lista de permitidos en memoria del servidor

  • Permite al modelo pedir acceso de forma proactiva antes de un intento de instantánea bloqueado

Instantáneas de registros

• create_log_snapshot - Crea una instantánea inmutable desde un archivo de registro común de Linux y devuelve URIs de recursos

  • Soporta grupos de registros system, security, kernel y package

  • filter_text opcional reduce la instantánea a las líneas coincidentes

  • Devuelve un URI de recurso base más una plantilla de recurso paginada

Recursos

• syslog://snapshot/{snapshot_id} - Lee una instantánea de registro de Linux almacenada con paginación por defecto

• syslog://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Lee una página específica de una instantánea almacenada

• proc://snapshot/{snapshot_id} - Lee una instantánea de proc/sys almacenada con paginación por defecto

• proc://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Lee una página específica de una instantánea de proc/sys almacenada

Cada lectura de recurso devuelve:

• metadatos de la instantánea

• entradas capturadas

• metadatos de paginación (total_count, returned_count, limit, offset, has_more, next_offset)

Prompts

• AnalyzeRecentApplicationErrors - Flujo de trabajo de análisis de registros centrado en errores

• ExplainHighCpu - Correlaciona procesos con alto uso de CPU con registros de Linux

• DetectSecurityAnomalies - Revisa procesos sospechosos más evidencia de registros de autenticación/seguridad

• DiagnoseSystemHealth - Flujo de trabajo de salud del sistema de extremo a extremo

• TroubleshootLinuxComponent - Flujo de trabajo de inmersión profunda enfocado que dirige al agente hacia troubleshoot_linux_diagnostics

Proyectos

src/mcp_linux_diag_server/server.py

El servidor HTTP MCP autenticado que expone las herramientas de diagnóstico, recursos y flujos de trabajo de los hitos 1-7.

src/mcp_linux_diag_server/client.py

El cliente de chat de la clase que:

• inicia el servidor HTTP local

• se conecta a través de HTTP transmitible con la clave API de demostración

• expone APIs de prompt/recurso de MCP como herramientas auxiliares para el modelo

• cumple con la solicitud de formularios MCP en la terminal local cuando el modelo activa kill_process

• cumple con las solicitudes de muestreo de MCP para que el servidor pueda sintetizar consultas y resúmenes de diagnóstico de Linux seguros

• enseña al modelo a solicitar acceso a proc/sys antes de tomar instantáneas de rutas bloqueadas

• ejecuta turnos de llamada a herramientas

Métodos de prueba

Para la lista de verificación de validación del Hito 1 que aún sustenta el flujo base de la clase, consulte M1_VALIDATION_GUIDE.md.

Estructura del proyecto

MCPPythonDemo/
├── README.md
├── LICENSE.txt
├── pyproject.toml
├── .env.example
├── .vscode/
│   └── mcp.json
├── scripts/
│   └── smoke_test.py
├── src/
│   └── mcp_linux_diag_server/
│       ├── __main__.py
│       ├── client.py
│       ├── http_config.py
│       ├── server.py
│       └── tools/
│           ├── log_snapshots.py
│           ├── proc_snapshots.py
│           ├── processes.py
│           └── system_info.py
├── tests/
│   ├── http_harness.py
│   ├── test_client.py
│   ├── test_m1_smoke.py
│   ├── test_m2_smoke.py
│   ├── test_m3_smoke.py
│   ├── test_m4_http.py
│   ├── test_log_snapshots.py
│   ├── test_processes.py
│   └── test_system_info.py

Requisitos

• Python 3.12+

• mcp[cli]

• Azure OpenAI solo si desea ejecutar el cliente de chat de la clase

Hitos

✅ Hito 1 - Herramienta de diagnóstico mínima sobre stdio más cliente de chat de clase ✅ Hito 2 - Inspección de procesos ✅ Hito 3 - Recursos de instantáneas de registros y prompts ✅ Hito 4 - Transporte HTTP y seguridad ✅ Hito 5 - kill_process respaldado por solicitud ✅ Hito 6 - Diagnóstico de Linux asistido por muestreo ✅ Hito 7 - Raíces e instantáneas de proc/sys

Licencia

MIT. Consulte LICENSE.txt.

Recursos

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• MCPDemo original en C#