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

Opis

Serwer MCP PowerShell to serwer implementujący protokół Model Context Protocol (MCP) do wykonywania skryptów PowerShell. Serwer działa w trybie STDIO i dostarcza narzędzi do bezpiecznego wykonywania poleceń PowerShell za pomocą znormalizowanego interfejsu.

Architektura

Główne komponenty

1. Konwerter JSON – Funkcja do konwersji JSON na tablice skrótów (hashtables) PowerShell.
2. Logowanie – System do zapisywania zdarzeń w pliku.
3. Handler MCP – Główna logika przetwarzania żądań MCP.
4. Wykonawca PowerShell – Izolowane wykonywanie skryptów.
5. Interfejs STDIO – Komunikacja za pomocą standardowych strumieni.

Struktura pliku

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # Funkcja konwersji JSON
├── Write-Log                      # Funkcja logowania
├── Test-MCPRequest               # Walidacja żądań MCP
├── New-MCPResponse               # Tworzenie odpowiedzi MCP
├── Invoke-PowerShellScript       # Wykonywanie skryptów PowerShell
├── Invoke-MCPMethod              # Przetwarzanie metod MCP
├── Send-MCPResponse              # Wysyłanie odpowiedzi
├── Start-MCPServer               # Główna pętla serwera
└── Inicjalizacja i uruchomienie

Funkcje

ConvertFrom-JsonToHashtable

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

**Cel**: Ta funkcja konwertuje ciąg znaków JSON na tablice skrótów PowerShell w celu zapewnienia zgodności z PowerShell 5.x.

**Parametry**:
- `Json` (string) - Ciąg znaków JSON do konwersji.

**Zwraca**: Tablicę skrótów z przekonwertowanymi danymi.

**Cechy**:
- Rekurencyjna konwersja zagnieżdżonych obiektów.
- Obsługa tablic i kolekcji.
- Zgodność z PowerShell 5.x.

### Write-Log

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

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

}

**Cel**: Ta funkcja zapisuje logi do pliku, ponieważ `stdout` jest używany do komunikacji MCP.

**Parametry**:
- `Message` (string) - Wiadomość do zapisania w logu.
- `Level` (string) - Poziom logowania (INFO, WARNING, ERROR, DEBUG).

**Cechy**:
- Zapis do pliku `$env:TEMP\mcp-powershell-server.log`.
- Znaczniki czasu w formacie `yyyy-MM-dd HH:mm:ss`.
- Kodowanie UTF-8.

### Test-MCPRequest

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

**Cel**: Ta funkcja waliduje żądanie MCP pod kątem zgodności z protokołem.

**Parametry**:
- `Request` (hashtable) - Żądanie MCP do walidacji.

**Zwraca**: Wartość logiczną (Boolean) - wynik walidacji.

**Sprawdzenia**:
- Obecność pola `jsonrpc` o wartości "2.0".
- Obecność wymaganego pola `method`.

### New-MCPResponse

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

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

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

}

**Cel**: Ta funkcja tworzy znormalizowaną odpowiedź MCP.

**Parametry**:
- `Id` (object) - Identyfikator żądania.
- `Result` (object) - Wynik operacji.
- `Error` (hashtable) - Informacje o błędzie.

**Zwraca**: `Hashtable` z odpowiedzią MCP.

### Invoke-PowerShellScript

powershell
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
)

}„`

Cel: Ta funkcja wykonuje skrypt PowerShell w izolowanym procesie.

Parametry:

• Script (string) – Skrypt PowerShell do wykonania.
• Parameters (hashtable) – Parametry dla skryptu.
• TimeoutSeconds (int) – Limit czasu wykonania (domyślnie 300 s).
• WorkingDirectory (string) – Katalog roboczy.

Zwraca: Hashtable z wynikami wykonania:

• success (bool) – Status wykonania.
• output (string) – Wyjście polecenia.
• errors (array) – Tablica błędów.
• warnings (array) – Tablica ostrzeżeń.

Cechy:

• Izolacja poprzez osobny proces PowerShell.
• Obsługa limitu czasu (timeout).
• Zbieranie wszystkich strumieni wyjściowych (output, error, warning).
• Automatyczne zwalnianie zasobów.

Metody MCP

initialize

Cel: Inicjalizuje serwer MCP i wymienia informacje o możliwościach.

Odpowiedź:

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "serverInfo": {
    "name": "PowerShell Script Runner",
    "version": "1.0.0",
    "description": "Wykonuje skrypty PowerShell przez MCP"
  }
}

tools/list

Cel: Pobiera listę dostępnych narzędzi.

Odpowiedź: Tablica narzędzi z opisem ich schematów parametrów wejściowych.

tools/call

Cel: Wywołuje określone narzędzie z parametrami.

Parametry:

• name (string) – Nazwa narzędzia.
• arguments (object) – Argumenty dla narzędzia.

Narzędzia

run-script

Cel: Wykonuje skrypt PowerShell z podanymi parametrami.

Schemat parametrów wejściowych:

{
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "Skrypt PowerShell do wykonania"
    },
    "parameters": {
      "type": "object",
      "description": "Parametry dla skryptu (opcjonalnie)",
      "additionalProperties": true
    },
    "workingDirectory": {
      "type": "string",
      "description": "Katalog roboczy do wykonania (opcjonalnie)",
      "default": "<bieżący katalog>"
    },
    "timeoutSeconds": {
      "type": "integer",
      "description": "Limit czasu wykonania w sekundach (opcjonalnie)",
      "default": 300,
      "minimum": 1,
      "maximum": 3600
    }
  },
  "required": ["script"]
}

Odpowiedź: Struktura z wynikami wykonania, zawierająca:

• Sformatowane wyjście polecenia.
• Błędy (jeśli wystąpiły).
• Ostrzeżenia (jeśli wystąpiły).
• Metadane wykonania.

Konfiguracja

Kodowanie

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

Serwer jest skonfigurowany do pracy z kodowaniem UTF-8 w celu poprawnej obsługi danych JSON.

Logowanie

• Plik logów: $env:TEMP\mcp-powershell-server.log
• Kodowanie: UTF-8
• Poziomy: INFO, WARNING, ERROR, DEBUG
• Format: [yyyy-MM-dd HH:mm:ss] [LEVEL] Wiadomość

Bezpieczeństwo

• Izolacja skryptów poprzez osobne procesy PowerShell.
• Limity czasowe (timeouty) zapobiegające zawieszeniu.
• Walidacja wszystkich przychodzących żądań.
• Logowanie wszystkich operacji.

Użycie

Uruchamianie serwera

.\mcp-powershell-stdio.ps1

Serwer uruchamia się w trybie STDIO i oczekuje na polecenia MCP przez standardowe wejście.

Przykładowe żądania MCP

Inicjalizacja

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

Lista narzędzi

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

Wykonanie skryptu

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

Obsługa błędów

Kody błędów MCP

• -32700: Błąd parsowania JSON (Parse error)
• -32600: Nieprawidłowe żądanie MCP (Invalid Request)
• -32601: Nie znaleziono metody lub narzędzia (Method not found)
• -32602: Nieprawidłowe parametry (Invalid params)
• -32603: Wewnętrzny błąd serwera (Internal error)

Logowanie błędów

Wszystkie błędy są logowane do pliku ze szczegółowymi informacjami:

• Znacznik czasu
• Poziom błędu
• Szczegółowy opis
• Ślad stosu (jeśli konieczne)

Ograniczenia

1. Limit czasu wykonania: Maksymalnie 3600 sekund (1 godzina).
2. Izolacja procesów: Każdy skrypt jest wykonywany w osobnym procesie.
3. Kodowanie: Tylko UTF-8.
4. Zgodność: PowerShell 5.x i nowsze.

Wydajność

• Minimalny narzut na tworzenie procesów.
• Wydajna serializacja JSON.
• Automatyczne czyszczenie zasobów.
• Zoptymalizowane logowanie.

Skalowalność

Serwer jest zaprojektowany do obsługi jednego żądania na raz w trybie synchronicznym. Do przetwarzania równoległego wymagane jest uruchomienie wielu instancji serwera.

---

Wersja dokumentacji: 1.0.0
Data utworzenia: 15 września 2025