Serwer MCP PowerShell. README>

Serwer MCP (Model Context Protocol) do wykonywania skryptów PowerShell, obsługujący zarówno tryb pracy HTTP, jak i STDIO.

Opis

Serwer MCP PowerShell umożliwia asystentom AI wykonywanie poleceń i skryptów PowerShell za pomocą ustandaryzowanego protokołu MCP. Serwer obsługuje dwa tryby pracy:

• Tryb STDIO: Do integracji z gemini-cli i innymi lokalnymi klientami MCP.
• Tryb HTTP: Dla aplikacji internetowych i integracji sieciowej przez REST API.

Który tryb wybrać: HTTP czy STDIO?

Wybór między mcp-powershell-http.ps1 a mcp-powershell-stdio.ps1 zależy od tego, jak i skąd aplikacja kliencka będzie komunikować się z serwerem.

• mcp-powershell-http.ps1 (tryb HTTP) działa jak kelner w restauracji. Przyjmuje zamówienia (żądania HTTP) od dowolnego klienta w sieci, przekazuje je do „kuchni” (PowerShell) i zwraca gotowy rezultat (odpowiedź HTTP).
• mcp-powershell-stdio.ps1 (tryb STDIO) działa jak osobisty asystent w kuchni. Otrzymuje zadania bezpośrednio (przez standardowe wejście stdin) od procesu zarządzającego (np. gemini-cli), który sam go uruchomił, i natychmiast oddaje wynik z powrotem (przez standardowe wyjście stdout).

Kiedy używać trybu HTTP

Powinieneś wybrać HTTP, jeśli wymagana jest komunikacja sieciowa.

• Zarządzanie zdalne: Aplikacja kliencka znajduje się na innym komputerze.
• Integracja internetowa: Konieczność wywoływania skryptów PowerShell z aplikacji internetowej, panelu administratora lub za pomocą żądań AJAX.
• Architektura mikrousług: Inne usługi w Twojej sieci muszą komunikować się z PowerShell.
• Proste testowanie: Chcesz używać narzędzi takich jak curl, Postman lub Invoke-RestMethod do wysyłania poleceń.

Mówiąc prościej: wybierz HTTP, jeśli między klientem a serwerem jest sieć.

Kiedy używać trybu STDIO

Ten tryb jest idealny do lokalnej i bezpiecznej integracji.

• Główny scenariusz — Gemini CLI: Narzędzie gemini-cli samo uruchamia mcp-powershell-stdio.ps1 jako proces potomny i komunikuje się z nim bezpośrednio przez standardowe strumienie wejścia-wyjścia.
• Integracja z innymi lokalnymi aplikacjami: Twój program w Pythonie, Node.js lub innym języku może uruchomić serwer i zarządzać nim bez otwierania portów sieciowych.
• Zwiększone bezpieczeństwo: Ponieważ porty sieciowe nie są otwierane, ten sposób jest domyślnie bezpieczniejszy.

Mówiąc prościej: wybierz STDIO, jeśli klient i serwer znajdują się na tej samej maszynie, a klient sam uruchamia serwer.

Tabela porównawcza

Cecha	Tryb HTTP (mcp-powershell-http.ps1)	Tryb STDIO (mcp-powershell-stdio.ps1)
Główny scenariusz	Komunikacja sieciowa, web API	Lokalna integracja z narzędziami CLI
Typ połączenia	Klient-serwer przez sieć (TCP/IP)	Komunikacja międzyprocesowa (IPC)
Lokalizacja	Klient i serwer mogą być na różnych maszynach	Klient i serwer muszą być na tej samej maszynie
Bezpieczeństwo	Wymaga uwagi (dostęp do portu, zapora sieciowa)	Domyślnie bezpieczniejszy (brak otwartych portów)
Typowi klienci	curl, Postman, aplikacje internetowe, zdalne skrypty	gemini-cli, lokalne aplikacje-wrapper’y

Funkcje

• ✅ Wsparcie dla protokołu MCP w wersji 2024-11-05
• ✅ Dwa tryby pracy: STDIO i HTTP
• ✅ Izolacja wykonywania skryptów w oddzielnych procesach PowerShell
• ✅ Konfigurowalne czasy oczekiwania (timeout)
• ✅ Szczegółowe logowanie wszystkich operacji
• ✅ Obsługa błędów i ostrzeżeń PowerShell
• ✅ Wsparcie dla parametrów skryptów
• ✅ Konfigurowalny katalog roboczy
• ✅ Automatyczne launchery ułatwiające uruchamianie

Wymagania systemowe

• PowerShell 7.0 lub nowszy
• Windows 10/11 lub Windows Server 2019+
• .NET 6.0 lub nowszy

Struktura projektu

mcp-powershell-server/
├── src/
│   ├── clients/           # Aplikacje klienckie
│   │   ├── node/         # Klient Node.js
│   │   ├── powershell/   # Klient PowerShell
│   │   └── python/       # Klient Python
│   └── servers/          # Komponenty serwera
│       ├── mcp-powershell-stdio.ps1   # Wersja STDIO serwera
│       ├── mcp-powershell-http.ps1    # Wersja HTTP serwera
│       ├── test-mcp.ps1               # Serwer testowy
│       └── config.json                # Plik konfiguracyjny
├── docs/                 # Dokumentacja
├── README.md            # Ten plik
└── how-to-use.md        # Szczegółowy poradnik

Szybki start

Tryb STDIO (dla gemini-cli)

1. Uruchomienie serwera:
   powershell .\src\servers\mcp-powershell-stdio.ps1
2. Testowanie:
   powershell .\src\servers\test-mcp.ps1

Tryb HTTP

1. Podstawowe uruchomienie:
   powershell .\src\servers\mcp-powershell-http.ps1
2. Z niestandardowymi parametrami:
   powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0" 3. Z plikiem konfiguracyjnym:
   powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Dostępne narzędzia MCP

run-script

Wykonuje skrypt PowerShell z zadanymi parametrami.

Parametry:

• script (wymagany) – Kod PowerShell do wykonania
• parameters (opcjonalny) – Tablica mieszająca (hashtable) parametrów
• workingDirectory (opcjonalny) – Katalog roboczy
• timeoutSeconds (opcjonalny) – Czas oczekiwania na wykonanie (1-3600 sek)

Przykład użycia przez MCP:

{
  "name": "run-script",
  "arguments": {
    "script": "Get-Process | Select-Object -First 5 | Format-Table",
    "workingDirectory": "C:\\",
    "timeoutSeconds": 30
  }
}

Konfiguracja

Serwer obsługuje konfigurację za pomocą pliku config.json:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Tools\\"
  ],
  "Security": {
    "EnableScriptValidation": true,
    "BlockDangerousCommands": true,
    "RestrictedCommands": [
      "Remove-Item",
      "Format-Volume",
      "Stop-Computer",
      "Restart-Computer"
    ]
  }
}

Bezpieczeństwo

• Wykonywanie skryptów odbywa się w izolowanych procesach PowerShell
• Wsparcie dla listy zabronionych poleceń
• Ograniczenie czasu wykonywania
• Logowanie wszystkich wykonywanych poleceń
• Możliwość ograniczenia dostępnych ścieżek

Logowanie

• Tryb STDIO: Logi są zapisywane w %TEMP%\mcp-powershell-server.log
• Tryb HTTP: Logi są wyświetlane w konsoli z kolorowym podświetleniem

Poziomy logowania: DEBUG, INFO, WARNING, ERROR

Integracja z asystentami AI

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Pokaż pierwsze 5 procesów w systemie"

Inni klienci MCP

Serwer jest kompatybilny ze wszystkimi klientami obsługującymi protokół MCP 2024-11-05.

Rozwiązywanie problemów

Typowe problemy

1. Port zajęty: Zmień port w konfiguracji lub zatrzymaj proces, który go używa.
2. Prawa dostępu: Uruchomienie na uprzywilejowanych portach (<1024) wymaga uprawnień administratora.
3. Kodowanie: Upewnij się, że PowerShell jest skonfigurowany na UTF-8.
4. Wersja PowerShell: Wymagany jest PowerShell 7+.

Diagnostyka

Sprawdź logi serwera, aby zdiagnozować problemy:

Get-Content "$env:TEMP\mcp-powershell-server.log" -Tail 20

Rozwój i rozszerzanie

Serwer można łatwo rozszerzać o nowe narzędzia MCP. Zobacz how-to-use.md po szczegółowe instrukcje dotyczące rozwoju.

Licencja

Ten projekt jest dystrybuowany na licencji MIT. Zobacz plik LICENSE, aby uzyskać szczegółowe informacje.

Wsparcie

• Utwórz „Issue” w repozytorium GitHub.
• Sprawdź dokumentację w how-to-use.md.
• Zapoznaj się z przykładami użycia.

Wersje

• 1.0.0 – Wersja początkowa z obsługą trybów STDIO i HTTP.