MCP PowerShell Server Dokumentation. STDIO Server. (mcp-powershell-server-stdio.py)

Beschreibung

Der MCP PowerShell Server ist ein Server, der das Model Context Protocol (MCP) zur Ausführung von PowerShell-Skripten implementiert. Der Server arbeitet im STDIO-Modus und stellt Werkzeuge zur sicheren Ausführung von PowerShell-Befehlen über eine standardisierte Schnittstelle bereit.

Architektur

Hauptkomponenten

1. JSON-Konverter – Eine Funktion zum Konvertieren von JSON in PowerShell-Hashtabellen.
2. Protokollierung (Logging) – Ein System zum Schreiben von Ereignissen in eine Datei.
3. MCP-Handler – Die Kernlogik zur Verarbeitung von MCP-Anfragen.
4. PowerShell-Executor – Isolierte Ausführung von Skripten.
5. STDIO-Schnittstelle – Kommunikation über Standardströme.

Dateistruktur

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # JSON-Konvertierungsfunktion
├── Write-Log                      # Protokollierungsfunktion
├── Test-MCPRequest               # MCP-Anforderungsvalidierung
├── New-MCPResponse               # Erstellung von MCP-Antworten
├── Invoke-PowerShellScript       # Ausführung von PowerShell-Skripten
├── Invoke-MCPMethod              # Verarbeitung von MCP-Methoden
├── Send-MCPResponse              # Senden von Antworten
├── Start-MCPServer               # Hauptschleife des Servers
└── Initialisierung und Start

Funktionen

ConvertFrom-JsonToHashtable

function ConvertFrom-JsonToHashtable {
    param([string]$Json)
}

Zweck: Diese Funktion konvertiert eine JSON-Zeichenkette in PowerShell-Hashtabellen zur Kompatibilität mit PowerShell 5.x.

Parameter:

• Json (string) – Die zu konvertierende JSON-Zeichenkette.

Rückgabewert: Eine Hashtabelle mit den konvertierten Daten.

Merkmale:

• Rekursive Konvertierung von verschachtelten Objekten.
• Verarbeitung von Arrays und Sammlungen.
• Kompatibilität mit PowerShell 5.x.

Write-Log

function Write-Log {
    param(
        [Parameter(Mandatory=$true)]
        [string]$Message,

        [Parameter(Mandatory=$false)]
        [ValidateSet("INFO", "WARNING", "ERROR", "DEBUG")]
        [string]$Level = "INFO"
    )
}

Zweck: Diese Funktion schreibt Protokolle in eine Datei, da stdout für die MCP-Kommunikation verwendet wird.

Parameter:

• Message (string) – Die Nachricht, die in das Protokoll geschrieben werden soll.
• Level (string) – Die Protokollierungsstufe (INFO, WARNING, ERROR, DEBUG).

Merkmale:

• Schreibt in die Datei $env:TEMP\mcp-powershell-server.log.
• Zeitstempel im Format yyyy-MM-dd HH:mm:ss.
• UTF-8-Kodierung.

Test-MCPRequest

function Test-MCPRequest {
    param(
        [Parameter(Mandatory=$true)]
        [hashtable]$Request
    )
}

Zweck: Diese Funktion validiert eine MCP-Anfrage auf Einhaltung des Protokolls.

Parameter:

• Request (hashtable) – Die zu validierende MCP-Anfrage.

Rückgabewert: Boolean – Das Ergebnis der Validierung.

Prüfungen:

• Vorhandensein des Feldes jsonrpc mit dem Wert „2.0“.
• Vorhandensein des obligatorischen Feldes method.

New-MCPResponse

function New-MCPResponse {
    param(
        [Parameter(Mandatory=$false)]
        [object]$Id = $null,

        [Parameter(Mandatory=$false)]
        [object]$Result = $null,

        [Parameter(Mandatory=$false)]
        [hashtable]$Error = $null
    )
}

Zweck: Diese Funktion erstellt eine standardisierte MCP-Antwort.

Parameter:

• Id (object) – Der Bezeichner der Anfrage.
• Result (object) – Das Ergebnis der Operation.
• Error (hashtable) – Informationen über den Fehler.

Rückgabewert: Eine Hashtable mit der MCP-Antwort.

Invoke-PowerShellScript

function Invoke-PowerShellScript {
    param(
        [Parameter(Mandatory=$true)]
        [string]$Script,

        [Parameter(Mandatory=$false)]
        [hashtable]$Parameters = @{},

        [Parameter(Mandatory=$false)]
        [int]$TimeoutSeconds = 300,

        [Parameter(Mandatory=$false)]
        [string]$WorkingDirectory = $PWD
    )
}

Zweck: Diese Funktion führt ein PowerShell-Skript in einem isolierten Prozess aus.

Parameter:

• Script (string) – Das auszuführende PowerShell-Skript.
• Parameters (hashtable) – Parameter für das Skript.
• TimeoutSeconds (int) – Ausführungs-Timeout (Standard 300 Sek.).
• WorkingDirectory (string) – Das Arbeitsverzeichnis.

Rückgabewert: Eine Hashtable mit den Ausführungsergebnissen:

• success (bool) – Der Ausführungsstatus.
• output (string) – die Ausgabe des Befehls.
• errors (array) – Ein Array von Fehlern.
• warnings (array) – Ein Array von Warnungen.

Merkmale:

• Isolation durch einen separaten PowerShell-Prozess.
• Timeout-Unterstützung.
• Sammlung aller Ausgabeströme (Output, Error, Warning).
• Automatische Ressourcenbereinigung.

MCP-Methoden

initialize

Zweck: Initialisiert den MCP-Server und tauscht Informationen über Fähigkeiten aus.

Antwort:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "serverInfo": {
    "name": "PowerShell Script Runner",
    "version": "1.0.0",
    "description": "Führt PowerShell-Skripte über MCP aus"
  }
}

tools/list

Zweck: Ruft die Liste der verfügbaren Werkzeuge ab.

Antwort: Ein Array von Werkzeugen mit Beschreibungen ihrer Eingabeparameterschemata.

tools/call

Zweck: Ruft ein bestimmtes Werkzeug mit Parametern auf.

Parameter:

• name (string) – Der Name des Werkzeugs.
• arguments (object) – Argumente für das Werkzeug.

Werkzeuge

run-script

Zweck: Führt ein PowerShell-Skript mit angegebenen Parametern aus.

Eingabeparameterschema:

{
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "Auszuführendes PowerShell-Skript"
    },
    "parameters": {
      "type": "object",
      "description": "Parameter für das Skript (optional)",
      "additionalProperties": true
    },
    "workingDirectory": {
      "type": "string",
      "description": "Arbeitsverzeichnis für die Ausführung (optional)",
      "default": "<aktuelles Verzeichnis>"
    },
    "timeoutSeconds": {
      "type": "integer",
      "description": "Ausführungs-Timeout in Sekunden (optional)",
      "default": 300,
      "minimum": 1,
      "maximum": 3600
    }
  },
  "required": ["script"]
}

Antwort: Eine Struktur mit den Ausführungsergebnissen, einschließlich:

• Formatierte Befehlsausgabe.
• Fehler (falls vorhanden).
• Warnungen (falls vorhanden).
• Ausführungsmetadaten.

Konfiguration

Kodierung

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

Der Server ist für die Arbeit mit UTF-8-Kodierung zur korrekten Verarbeitung von JSON-Daten konfiguriert.

Protokollierung (Logging)

• Protokolldatei: $env:TEMP\mcp-powershell-server.log
• Kodierung: UTF-8
• Stufen: INFO, WARNING, ERROR, DEBUG
• Format: [yyyy-MM-dd HH:mm:ss] [LEVEL] Nachricht

Sicherheit

• Skriptisolierung durch separate PowerShell-Prozesse.
• Timeouts zur Verhinderung von Hängenbleiben.
• Validierung aller eingehenden Anfragen.
• Protokollierung aller Operationen.

Verwendung

Starten des Servers

.\mcp-powershell-stdio.ps1

Der Server startet im STDIO-Modus und wartet auf MCP-Befehle über die Standardeingabe.

Beispiel-MCP-Anfragen

Initialisierung

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    }
  }
}

Liste der Werkzeuge„`json

{
„jsonrpc“: „2.0“,
„id“: 2,
„method“: „tools/list“
}

#### Skriptausführung

json
{
„jsonrpc“: „2.0“,
„id“: 3,
„method“: „tools/call“,
„params“: {
„name“: „run-script“,
„arguments“: {
„script“: „Get-Process | Select-Object -First 5 Name, CPU“,
„timeoutSeconds“: 60
}
}
}
„`

Fehlerbehandlung

MCP-Fehlercodes

• -32700: JSON-Parse-Fehler
• -32600: Ungültige MCP-Anfrage
• -32601: Methode oder Werkzeug nicht gefunden
• -32602: Ungültige Parameter
• -32603: Interner Serverfehler

Fehlerprotokollierung

Alle Fehler werden in einer Datei mit detaillierten Informationen protokolliert:

• Zeitstempel
• Fehlerstufe
• Detaillierte Beschreibung
• Stack-Trace (falls erforderlich)

Einschränkungen

1. Ausführungs-Timeout: Maximal 3600 Sekunden (1 Stunde).
2. Prozessisolierung: Jedes Skript wird in einem separaten Prozess ausgeführt.
3. Kodierung: Nur UTF-8.
4. Kompatibilität: PowerShell 5.x und höher.

Leistung

• Minimaler Overhead bei der Prozesserstellung.
• Effiziente JSON-Serialisierung.
• Automatische Ressourcenbereinigung.
• Optimierte Protokollierung.

Skalierbarkeit

Der Server ist dafür ausgelegt, eine Anfrage nach der anderen im synchronen Modus zu verarbeiten. Für die parallele Verarbeitung müssen mehrere Instanzen des Servers ausgeführt werden.

---

Dokumentationsversion: 1.0.0
Erstellungsdatum: 15. September 2025