Linux-Diagnose-MCP-Server - Vorlesungs-Demo

Eine Python/Linux-Adaption des ursprünglichen MCPDemo-Lehr-Repositorys. Dieses Repo erreicht nun Meilenstein 4-Parität für den öffentlichen Lehrablauf: kompakte Systeminspektion, Linux-Prozess-Detailansicht, Protokoll-Snapshots als Ressourcen, Workflow-Prompts und authentifiziertes MCP über HTTP auf /mcp.

Was diese Demo zeigt

Diese Vorlesungs-Demo enthält nun:

• ✅ Tools: schreibgeschützte Linux-Diagnosetools für get_system_info, get_process_list, get_process_by_id und get_process_by_name

• ✅ Ressourcen: paginierte 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 und es dem Modell ermöglicht, MCP-Tools, Prompts und Ressourcen aufzurufen

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

• ✅ Mehrere Testmethoden

• ⏳ Ermittlung, Sampling und Roots sind für später geplant

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. Überprüft 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- und Protokoll-Snapshot-Abläufe aus

7. Überprüft, ob 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 paginierte detaillierte Prozessinformationen für einen Prozessnamen zurück

  • Standardmäßig page_number=1

  • Standardmäßig page_size=5

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

Protokoll-Snapshots

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

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

  • Optionaler 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

Jeder Ressourcen-Lesezugriff gibt Folgendes zurück:

• Snapshot-Metadaten

• Erfasste Zeilen

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

Prompts

• AnalyzeRecentApplicationErrors - Fehlerfokussierter Protokollanalyse-Workflow

• ExplainHighCpu - Korrelation von CPU-intensiven Prozessen mit Linux-Protokollen

• DetectSecurityAnomalies - Überprüfung verdächtiger Prozesse sowie Beweise aus Authentifizierungs-/Sicherheitsprotokollen

• DiagnoseSystemHealth - End-to-End-Systemzustands-Workflow

Projekte

src/mcp_linux_diag_server/server.py

Der authentifizierte HTTP-MCP-Server, der die Diagnose-Tools, Protokollressourcen und Workflow-Prompts der Meilensteine 1-4 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

• Tool-Aufruf-Turns ausführt

Testmethoden

Für die Meilenstein 1-Validierungs-Checkliste, die weiterhin die Grundlage des Basis-Lehrablaufs bildet, 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
│           ├── 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 Diagnosetool über stdio plus Vorlesungs-Chat-Client ✅ Meilenstein 2 - Prozessinspektion ✅ Meilenstein 3 - Protokoll-Snapshot-Ressourcen und Prompts ✅ Meilenstein 4 - HTTP-Transport und Sicherheit ⏳ Meilenstein 5+ - Ermittlung, Sampling und Roots

Lizenz

MIT. Siehe LICENSE.txt.

Ressourcen

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• Ursprüngliche C# MCPDemo