Linux-Diagnose-MCP-Server - Vorlesungs-Demo

Eine Python/Linux-Adaption des ursprünglichen MCPDemo-Lehr-Repositorys. Dieses Repo erreicht nun Meilenstein-7-Parität für den öffentlichen Lehrablauf: kompakte Systeminspektion, Linux-Prozess-Detailansicht, Protokoll-Snapshots als Ressourcen, Workflow-Prompts, authentifiziertes MCP über HTTP auf /mcp, explizite Aufforderung vor Prozessbeendigung, sampling-gestützte Linux-Diagnose und erlaubte Root-Proc/Sys-Snapshots.

Was diese Demo zeigt

Diese Vorlesungs-Demo enthält nun:

• ✅ Tools: Linux-Diagnosetools für get_system_info, get_process_list, get_process_by_id, get_process_by_name und eine durch Aufforderung geschützte kill_process-Funktion

• ✅ Ressourcen: gepagte syslog://snapshot/... Protokoll-Snapshot-Ressourcen

• ✅ Prompts: MCP-Workflow-Prompts für Fehleranalyse, CPU-Untersuchung, Sicherheitsüberprüfung und Gesundheitsdiagnose

• ✅ HTTP-Transport: streamfähiges MCP über http://127.0.0.1:5000/mcp

• ✅ API-Key-Authentifizierung: X-API-Key-Header oder ?apiKey=secure-mcp-key

• ✅ KI-Chat-Client: ein Python Azure OpenAI-Client, der den lokalen HTTP-Server startet, dem Modell erlaubt, MCP-Tools, Prompts und Ressourcen aufzurufen, und lokale Formular-Aufforderungen im Terminal handhabt

• ✅ Python 3.12-Implementierung mit dem offiziellen MCP Python SDK

• ✅ Mehrere Testmethoden

• ✅ Meilenstein-5-Aufforderung für kill_process

• ✅ Meilenstein-6-sampling-gestützte Linux-Diagnose

• ✅ Meilenstein-7-Roots für schreibgeschützte /proc- und /sys-Snapshots

Related MCP server: troubleshooting-mcp-server

Schnellstart

1. Installation

Nur-Server-Installation:

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

Installation der Vorlesungs-Chat-Client-Extras:

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

2. Schneller Rauchtest (Kein LLM)

python3 scripts/smoke_test.py

Dieses Skript:

1. Startet den lokalen HTTP-MCP-Server

2. Verifiziert 401 Unauthorized ohne API-Key

3. Führt den MCP-Initialisierungs-Handshake auf /mcp durch

4. Bestätigt, dass der mcp-session-id-Ablauf über Anfragen hinweg funktioniert

5. Erkennt Tools, Prompts und Ressourcenvorlagen

6. Führt die System-, Prozess-, Protokoll-Snapshot-, Proc-Snapshot- und sampling-gestützten Diagnoseabläufe aus

7. Verifiziert, dass kill_process sicher fehlschlägt, wenn der Client keine Unterstützung für Aufforderungen ankündigt

8. Verifiziert, dass der Vorlesungs-Chat-Client sicher fehlschlägt, wenn Azure OpenAI-Einstellungen fehlen

3. Server manuell ausführen

python3 -m mcp_linux_diag_server

Der Server lauscht auf:

• Endpunkt: http://127.0.0.1:5000/mcp

• Demo-API-Key: secure-mcp-key

4. Test mit MCP Inspector oder VS Code MCP-Konfiguration

Starten Sie den Server in einem Terminal und verbinden Sie sich dann über den oben genannten HTTP-Endpunkt.

Dieses Repo enthält .vscode/mcp.json mit dem erforderlichen Header:

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

Wenn Ihr Inspector eine URL direkt akzeptiert, funktioniert auch diese Query-String-Form:

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

5. Den Vorlesungs-Chat-Client verwenden

Kopieren Sie die Beispiel-Umgebungsdatei und füllen Sie Ihre lokalen Azure OpenAI-Einstellungen aus:

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

Um den ursprünglichen .NET-Anmeldeinformationsablauf genauer abzubilden, setzen Sie:

MCP_DEMO_AZURE_OPENAI_USE_DEFAULT_CREDENTIAL=true

und lassen Sie den API-Key weg.

Interaktiven Chat ausführen:

python3 -m mcp_linux_diag_server.client

Oder einen einzelnen Prompt ausführen:

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

Die Tools

Systeminformationen

• get_system_info - Gibt einen kompakten Linux- oder WSL-System-Snapshot zurück

  • Hostname

  • Aktueller Benutzer

  • Beschreibung der Linux-Distribution

  • Kernel-Release

  • Architektur

  • Anzahl der logischen CPUs

  • Python-Laufzeit

  • Aktuelles Arbeitsverzeichnis

  • Betriebszeit (Uptime)

  • Lastdurchschnitte (Load Averages)

  • Speicherzusammenfassung

  • WSL-Erkennungs-Flag

Prozessinspektion

• get_process_list - Gibt eine leichtgewichtige Liste laufender Prozesse mit Namen und PIDs zurück

• get_process_by_id - Gibt detaillierte Linux-Prozessinformationen für eine PID zurück

• get_process_by_name - Gibt gepagte detaillierte Prozessinformationen für einen Prozessnamen zurück

  • Standardmäßig page_number=1

  • Standardmäßig page_size=5

  • Behält den Listen-zuerst, Details-danach-Lehrablauf aus der ursprünglichen Demo bei

• kill_process - Beendet einen Linux-Prozess erst nach expliziter Aufforderung

  • Wenn process_id weggelassen wird, sampelt der Server die Prozesse mit der höchsten CPU-Auslastung und bittet den Client, einen auszuwählen

  • Der Server erfordert immer den getippten Bestätigungssatz CONFIRM PID {pid}

  • Der Vorlesungs-Client handhabt diese Aufforderungen lokal im Terminal, wenn stdin/stdout interaktiv sind

• troubleshoot_linux_diagnostics - Verwendet Sampling, um eine natürlichsprachliche Linux-Diagnosefrage in einen validierten /proc- oder /sys-Lesezugriff umzuwandeln

  • Der Server validiert den gesampelten Pfad und das Feld gegen eine Erlaubnisliste, bevor er irgendetwas liest

  • Exakte Python-Adaption: die gesampelte Abfrage ist eine einzelne sichere PATH- oder PATH | grep FIELD-Zeile anstelle von WQL

  • Der Server sampelt dann erneut, um die Beobachtung für den Benutzer zusammenzufassen

• create_proc_snapshot - Erstellt einen unveränderlichen, schreibgeschützten Snapshot von einem erlaubten /proc- oder /sys-Pfad und gibt Ressourcen-URIs zurück

  • Datei-Snapshots paginieren den Inhalt Zeile für Zeile

  • Verzeichnis-Snapshots paginieren deterministische Kind-Metadaten, ohne symbolischen Links zu folgen

  • Erzwingt explizite erlaubte Roots, bevor irgendetwas gelesen wird

• request_proc_access - Verwendet Aufforderungen, um schreibgeschützten Zugriff auf eine zusätzliche /proc- oder /sys-Root anzufordern

  • Fügt die genehmigte Root zur In-Memory-Erlaubnisliste des Servers hinzu

  • Ermöglicht es dem Modell, proaktiv Zugriff anzufordern, bevor ein blockierter Snapshot-Versuch unternommen wird

Protokoll-Snapshots

• create_log_snapshot - Erstellt einen unveränderlichen Snapshot von einer gängigen Linux-Protokolldatei und gibt Ressourcen-URIs zurück

  • Unterstützt die Protokollgruppen system, security, kernel und package

  • Optionales filter_text schränkt den Snapshot auf übereinstimmende Zeilen ein

  • Gibt eine Basis-Ressourcen-URI plus eine paginierte Ressourcenvorlage zurück

Ressourcen

• syslog://snapshot/{snapshot_id} - Liest einen gespeicherten Linux-Protokoll-Snapshot mit Standard-Paginierung

• syslog://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Liest eine bestimmte Seite aus einem gespeicherten Snapshot

• proc://snapshot/{snapshot_id} - Liest einen gespeicherten Proc/Sys-Snapshot mit Standard-Paginierung

• proc://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Liest eine bestimmte Seite aus einem gespeicherten Proc/Sys-Snapshot

Jeder Ressourcen-Lesezugriff gibt zurück:

• Snapshot-Metadaten

• erfasste Einträge

• Paginierungs-Metadaten (total_count, returned_count, limit, offset, has_more, next_offset)

Prompts

• AnalyzeRecentApplicationErrors - Fehlerfokussierter Protokollanalyse-Workflow

• ExplainHighCpu - Korreliert CPU-intensive Prozesse mit Linux-Protokollen

• DetectSecurityAnomalies - Überprüft verdächtige Prozesse sowie Beweise aus Auth-/Sicherheitsprotokollen

• DiagnoseSystemHealth - End-to-End-Systemgesundheits-Workflow

• TroubleshootLinuxComponent - Fokussierter Deep-Dive-Workflow, der den Agenten in Richtung troubleshoot_linux_diagnostics lenkt

Projekte

src/mcp_linux_diag_server/server.py

Der authentifizierte HTTP-MCP-Server, der die Diagnose-Tools, Ressourcen und Workflow-Prompts der Meilensteine 1-7 bereitstellt.

src/mcp_linux_diag_server/client.py

Der Vorlesungs-Chat-Client, der:

• den lokalen HTTP-Server startet

• sich über streamfähiges HTTP mit dem Demo-API-Key verbindet

• MCP-Prompt-/Ressourcen-APIs als Hilfswerkzeuge für das Modell bereitstellt

• MCP-Formular-Aufforderungen im lokalen Terminal erfüllt, wenn das Modell kill_process auslöst

• MCP-Sampling-Anfragen erfüllt, damit der Server sichere Linux-Diagnoseabfragen und Zusammenfassungen synthetisieren kann

• dem Modell beibringt, Proc/Sys-Zugriff anzufordern, bevor blockierte Pfade gesnapshotet werden

• Tool-Aufruf-Turns ausführt

Testmethoden

Für die M1-Validierungs-Checkliste, die dem Basis-Lehrablauf immer noch zugrunde liegt, siehe M1_VALIDATION_GUIDE.md.

Projektstruktur

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

Anforderungen

• Python 3.12+

• mcp[cli]

• Azure OpenAI nur, wenn Sie den Vorlesungs-Chat-Client ausführen möchten

Meilensteine

✅ Meilenstein 1 - Minimales Diagnose-Tool über stdio plus Vorlesungs-Chat-Client ✅ Meilenstein 2 - Prozessinspektion ✅ Meilenstein 3 - Protokoll-Snapshot-Ressourcen und Prompts ✅ Meilenstein 4 - HTTP-Transport und Sicherheit ✅ Meilenstein 5 - Aufforderungs-gestütztes kill_process ✅ Meilenstein 6 - Sampling-gestützte Linux-Diagnose ✅ Meilenstein 7 - Roots und Proc/Sys-Snapshots

Lizenz

MIT. Siehe LICENSE.txt.

Ressourcen

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• Ursprüngliche C# MCPDemo