Dokumentation für Entwickler: MCP PowerShell HTTP Server. (mcp-powershell-server-http.py)

1. Überblick

mcp-powershell-http.ps1 ist ein eigenständiger HTTP-Server, der in PowerShell geschrieben wurde, um PowerShell-Skripte sicher aus der Ferne auszuführen. Er fungiert als „Brücke“ zwischen einem externen Client (z. B. einem KI-Assistenten) und der lokalen PowerShell-Umgebung und verwendet für die Kommunikation das JSON-RPC 2.0-Protokoll.

Hauptmerkmale:

• Sicherheit: Jedes Skript wird in einer vollständig isolierten PowerShell-Instanz (Runspace) ausgeführt, was Auswirkungen auf die Hauptumgebung des Servers verhindert.
• Flexible Konfiguration: Serverparameter (Port, Host, Timeouts) können über Befehlszeilenargumente und eine externe JSON-Datei konfiguriert werden.
• Stabilität: Eine umfassende Fehlerbehandlung auf allen Ebenen (HTTP, JSON, Skriptausführung) gewährleistet den zuverlässigen Betrieb des Servers.
• MCP-Protokoll: Implementiert das Standard-MCP-Protokoll für die Interaktion, einschließlich der Methoden initialize, tools/list und tools/call.
• Ressourcenkontrolle: Integrierte Timeouts und eine Begrenzung der Ausgabegröße verhindern den Missbrauch von Ressourcen.

2. Ausführung und Konfiguration

Voraussetzungen:

• PowerShell 7.0 oder höher.

Befehlszeilenparameter:

Parameter	Typ	Beschreibung	Standardwert
-Port	[int]	Der Port, an dem der Server auf HTTP-Anfragen lauscht.	8090
-ServerHost	[string]	Der Host (IP-Adresse oder Domainname), an den der Server gebunden wird.	localhost
-ConfigFile	[string]	Der Pfad zu einer Konfigurationsdatei im JSON-Format. Parameter aus dieser Datei überschreiben die Standardwerte und Befehlszeilenargumente.	$null

Anwendungsbeispiel:

.\mcp-powershell-http.ps1 -Port 8090 -ServerHost 0.0.0.0 -ConfigFile "C:\config\settings.json"

Konfigurationsdatei (settings.json):

Der Server kann seine Konfiguration aus einer JSON-Datei laden. Dies ist der empfohlene Ansatz für Produktionsumgebungen.

Beispiel settings.json aus dem Repository:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "LogLevel": "INFO",
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Users\\%USERNAME%\\Documents\\"
  ],
  "Security": {
    "EnableScriptValidation": false,
    "BlockDangerousCommands": false,
    "RestrictedCommands": [
      "Remove-Item -Path C:\\Windows\\*",
      "Format-Volume"
    ]
  }
}

3. Architektur und Funktionen

Das Skript ist logisch in mehrere Regionen (#region) unterteilt, um die Navigation zu vereinfachen.

Region: Utility Functions (Hilfsfunktionen)

1. Write-Log
   • Zweck: Gibt formatierte und farbige Nachrichten mit einem Zeitstempel in der Konsole aus. Dies ist die Hauptfunktion für die Protokollierung.
   • Parameter:
     • $Message [string] (obligatorisch): Der Nachrichtentext.
     • $Level [string] (optional): Die Protokollierungsstufe (DEBUG, INFO, WARNING, ERROR). Beeinflusst die Farbe der Ausgabe.
2. Test-MCPRequest
   • Zweck: Überprüft, ob die eingehende Anfrage die grundlegenden Anforderungen des JSON-RPC 2.0-Protokolls erfüllt (Vorhandensein der Felder jsonrpc: "2.0" und method).
   • Parameter:
     • $Request [hashtable] (obligatorisch): Die aus JSON deserialisierte Anfrage.
   • Rückgabewert: $true, wenn die Anfrage gültig ist, andernfalls $false.
3. New-MCPResponse
   • Zweck: Eine Factory-Funktion zur Erstellung standardisierter JSON-RPC-Antwortobjekte.
   • Parameter:
     • $Id [object]: Der Bezeichner der Anfrage.
     • $Result [object]: Das Objekt, das ein erfolgreiches Ergebnis enthält.
     • $Error [hashtable]: Das Objekt, das Fehlerinformationen enthält.
   • Rückgabewert: Eine [hashtable] mit der vollständigen Antwortstruktur.
4. Test-ScriptSafety
   • Zweck: Überprüft das Skript auf potenziell gefährliche Befehle, die in der globalen Variablen $script:RestrictedCommands aufgeführt sind.
   • Hinweis: In der bereitgestellten Version ist diese Funktion standardmäßig deaktiviert (return $true). Für den Produktionseinsatz sollte sie aktiviert und konfiguriert werden.
   • Parameter:
     • $Script [string] (obligatorisch): Der zu überprüfende PowerShell-Skripttext.
   • Rückgabewert: $true, wenn das Skript sicher ist, andernfalls $false.

Region: Core Logic (Kernlogik)

1. Invoke-PowerShellScript
   • Zweck: Die Kernfunktion, die für die sichere Ausführung eines PowerShell-Skripts verantwortlich ist.
   • Ablauf:
     1. Erstellt eine neue, vollständig isolierte PowerShell-Instanz ([powershell]::Create()).
     2. (Optional) Legt das Arbeitsverzeichnis innerhalb dieser Instanz fest.
     3. Fügt den Skripttext und seine Parameter zur Instanz hinzu.
     4. Führt das Skript asynchron mit einem Timeout aus.
     5. Sammelt die Ausgabe (Output)-, Fehler (Error)- und Warnungs (Warning)-Streams.
     6. Begrenzt die Ausgabegröße (Standard 10.000 Zeichen), um große Datenübertragungen zu verhindern.
     7. Gibt die Ressourcen nach Abschluss wieder frei (Dispose()).
   • Parameter:
     • $Script [string] (obligatorisch): Der auszuführende Code.
     • $Parameters [hashtable]: Parameter, die an das Skript übergeben werden.
     • $TimeoutSeconds [int]: Maximale Ausführungszeit in Sekunden.
     • $WorkingDirectory [string]: Das Arbeitsverzeichnis für das Skript.
   • Rückgabewert: Eine [hashtable] mit den Ergebnissen: success (bool), output (string), errors (array), warnings (array), executionTime (double).

Region: MCP Protocol Methods (MCP-Protokollmethoden)

1. Invoke-MCPMethod
   • Zweck: Ein Dispatcher, der die Aufrufe von MCP-Protokollmethoden verarbeitet.
   • Ablauf: Verwendet eine switch-Anweisung auf den Methodennamen ($Method), um die entsprechende Logik aufzurufen.
   • Unterstützte Methoden:
     • "initialize": Gibt Informationen über den Server zurück.
     • "tools/list": Gibt eine Liste der verfügbaren Tools zurück (in diesem Fall nur "run-script").
     • "tools/call": Verarbeitet einen Tool-Aufruf. Extrahiert die Parameter und ruft Invoke-PowerShellScript zur Ausführung auf.
   • Parameter:
     • $Method [string]: Der Name der aufzurufenden Methode.
     • $Params [hashtable]: Die Parameter der Methode.
     • $Id [object]: Der Bezeichner der Anfrage.
   • Rückgabewert: Eine [hashtable], die die vollständige, sendebereite MCP-Antwort darstellt.

Region: HTTP Server

1. Invoke-RequestHandler
   • Zweck: Verarbeitet den gesamten Lebenszyklus einer einzelnen HTTP-Anfrage.
   • Ablauf:
     1. Richtet CORS-Header ein.
     2. Behandelt OPTIONS-Anfragen (CORS-Preflight).
     3. Überprüft, ob die Anfragemethode POST ist.
     4. Liest und validiert den Anfragetext (Body).
     5. Parst das JSON und konvertiert es in eine Hashtabelle.
     6. Ruft Test-MCPRequest zur Validierung auf.
     7. Übergibt die Anfrage zur Verarbeitung an Invoke-MCPMethod.
     8. Serialisiert die Antwort zurück in JSON und sendet sie an den Client.
     9. Behandelt alle möglichen Fehler auf diesem Weg.
   • Parameter:
     • $Context [System.Net.HttpListenerContext]: Der HTTP-Anfragekontext vom .NET-Listener.
2. Start-MCPServer
   • Zweck: Die Hauptfunktion, die den HTTP-Listener initialisiert und startet.
   • Ablauf:
     1. Erstellt und konfiguriert ein System.Net.HttpListener-Objekt.
     2. Startet den Listener mit listener.Start().
     3. Tritt in eine Endlosschleife while ($listener.IsListening) ein, um auf eingehende Verbindungen zu warten.
     4. Ruft für jede Verbindung Invoke-RequestHandler auf.
     5. Stoppt den Server ordnungsgemäß, wenn der Prozess beendet wird.

4. Ablauf einer Anforderungsausführung

1. Ein Client sendet eine POST-Anfrage mit Content-Type: application/json an die URL des Servers.
2. Start-MCPServer nimmt die Anfrage entgegen und übergibt sie an Invoke-RequestHandler.
3. Invoke-RequestHandler validiert die HTTP-Header, die Methode und parst den JSON-Body.
4. Die gültige MCP-Anfrage wird an Invoke-MCPMethod übergeben.
5. Invoke-MCPMethod stellt fest, dass die Methode tools/call mit dem Tool run-script aufgerufen wurde.
6. Die Parameter (Skript, Timeout usw.) werden an Invoke-PowerShellScript übergeben.
7. Invoke-PowerShellScript führt das Skript in einer isolierten Umgebung aus.
8. Das Ausführungsergebnis wird die Aufrufkette zurückgegeben, in eine Standard-JSON-RPC-Antwort formatiert und von Invoke-RequestHandler an den Client zurückgesendet.

5. Erweiterung der Funktionalität

Um ein neues „Tool“ (neben run-script) hinzuzufügen, muss ein Entwickler:

1. Eine Beschreibung des neuen Tools zum Block "tools/list" in der Funktion Invoke-MCPMethod hinzufügen.
2. Einen neuen case-Zweig für dieses Tool in der switch ($toolName)-Anweisung innerhalb des "tools/call"-Blocks von Invoke-MCPMethod hinzufügen.
3. Die Logik für das neue Tool implementieren.