Сервер MCP (Model Context Protocol) для виконання скриптів PowerShell, що підтримує режими роботи як через HTTP, так і через STDIO.

Опис

MCP PowerShell Server дозволяє ШІ-асистентам виконувати команди та скрипти PowerShell через стандартизований протокол MCP. Сервер підтримує два режими роботи:

• Режим STDIO: для інтеграції з gemini-cli та іншими локальними MCP-клієнтами.
• Режим HTTP: для веб-додатків та інтеграції через мережу за допомогою REST API.

Який режим вибрати: HTTP чи STDIO?

Вибір між mcp-powershell-http.ps1 та mcp-powershell-stdio.ps1 залежить від того, як і звідки клієнтський додаток буде взаємодіяти з сервером.

• mcp-powershell-http.ps1 (режим HTTP) працює як офіціант у ресторані. Він приймає замовлення (HTTP-запити) від будь-якого клієнта в мережі, передає їх на “кухню” (PowerShell) і повертає готовий результат (HTTP-відповідь).
• mcp-powershell-stdio.ps1 (режим STDIO) працює як особистий помічник на кухні. Він отримує завдання безпосередньо (через стандартний ввід stdin) від керуючого процесу (наприклад, gemini-cli), який сам його запустив, і негайно віддає результат назад (через стандартний вивід stdout).

Коли використовувати режим HTTP

Вам слід вибрати HTTP, якщо потрібна мережева взаємодія.

• Віддалене керування: Клієнтський додаток знаходиться на іншому комп’ютері.
• Веб-інтеграція: Необхідно викликати PowerShell-скрипти з веб-додатку, панелі адміністратора або через AJAX-запити.
• Мікросервісна архітектура: Інші сервіси у вашій мережі повинні взаємодіяти з PowerShell.
• Просте тестування: Ви хочете використовувати інструменти на кшталт curl, Postman або Invoke-RestMethod для надсилання команд.

Простими словами: обирайте HTTP, якщо між клієнтом та сервером є мережа.

Коли використовувати режим STDIO

Цей режим ідеально підходить для локальної та безпечної інтеграції.

• Основний сценарій — Gemini CLI: Інструмент gemini-cli сам запускає mcp-powershell-stdio.ps1 як дочірній процес і спілкується з ним напряму через стандартні потоки вводу-виводу.
• Інтеграція з іншими локальними додатками: Ваша програма на Python, Node.js або іншій мові може запустити сервер і керувати ним, не відкриваючи мережеві порти.
• Підвищена безпека: Оскільки мережеві порти не відкриваються, цей спосіб за замовчуванням є безпечнішим.

Простими словами: обирайте STDIO, якщо клієнт і сервер знаходяться на одній машині, і клієнт сам запускає сервер.

Порівняльна таблиця

Характеристика	Режим HTTP (mcp-powershell-http.ps1)	Режим STDIO (mcp-powershell-stdio.ps1)
Основний сценарій	Мережева взаємодія, веб-API	Локальна інтеграція з CLI-інструментами
Тип зв’язку	Клієнт-сервер по мережі (TCP/IP)	Міжпроцесна взаємодія (IPC)
Розташування	Клієнт та сервер можуть бути на різних машинах	Клієнт та сервер повинні бути на одній машині
Безпека	Вимагає уваги (доступ до порту, файрвол)	Більш безпечний за замовчуванням (немає відкритих портів)
Типові клієнти	curl, Postman, веб-додатки, віддалені скрипти	gemini-cli, локальні додатки-обгортки

Особливості

• ✅ Підтримка протоколу MCP версії 2024-11-05
• ✅ Два режими роботи: STDIO та HTTP
• ✅ Ізоляція виконання скриптів в окремих процесах PowerShell
• ✅ Настроювані тайм-аути виконання
• ✅ Детальне логування всіх операцій
• ✅ Обробка помилок та попереджень PowerShell
• ✅ Підтримка параметрів скриптів
• ✅ Настроювана робоча директорія
• ✅ Автоматичні launcher’и для спрощення запуску

Системні вимоги

• PowerShell 7.0 або новішої версії
• Windows 10/11 або Windows Server 2019+
• .NET 6.0 або новішої версії

Структура проєкту

mcp-powershell-server/
├── src/
│   ├── clients/           # Клієнтські додатки
│   │   ├── node/         # Node.js клієнт
│   │   ├── powershell/   # PowerShell клієнт
│   │   └── python/       # Python клієнт
│   └── servers/          # Серверні компоненти
│       ├── mcp-powershell-stdio.ps1   # STDIO версія сервера
│       ├── mcp-powershell-http.ps1    # HTTP версія сервера
│       ├── test-mcp.ps1               # Тестовий сервер
│       └── config.json                # Файл конфігурації
├── docs/                 # Документація
├── README.md            # Цей файл
└── how-to-use.md        # Детальний посібник

Швидкий старт

Режим STDIO (для gemini-cli)

1. Запуск сервера:
   powershell .\src\servers\mcp-powershell-stdio.ps1
2. Тестування:
   powershell .\src\servers\test-mcp.ps1

Режим HTTP

1. Базовий запуск:
   powershell .\src\servers\mcp-powershell-http.ps1
2. З настроюваними параметрами:
   powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
3. З файлом конфігурації:
   powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Доступні інструменти MCP

run-script

Виконує скрипт PowerShell із заданими параметрами.

Параметри:

• script (обов’язковий) – PowerShell код для виконання
• parameters (опціональний) – Хеш-таблиця параметрів
• workingDirectory (опціональний) – Робоча директорія
• timeoutSeconds (опціональний) – Тайм-аут виконання (1-3600 сек)

Приклад використання через MCP:

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

Конфігурація

Сервер підтримує конфігурацію через файл 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"
    ]
  }
}

Безпека

• Виконання скриптів відбувається в ізольованих процесах PowerShell
• Підтримка списку заборонених команд
• Обмеження за часом виконання
• Логування всіх виконуваних команд
• Можливість обмеження доступних шляхів

Логування

• Режим STDIO: Логи записуються в %TEMP%\mcp-powershell-server.log
• Режим HTTP: Логи виводяться в консоль з кольоровою індикацією

Рівні логування: DEBUG, INFO, WARNING, ERROR

Інтеграція з ШІ-асистентами

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Покажи перші 5 процесів у системі"

Інші MCP-клієнти

Сервер сумісний з усіма клієнтами, що підтримують протокол MCP 2024-11-05.

Вирішення проблем

Загальні проблеми

1. Порт зайнятий: Змініть порт у конфігурації або зупиніть процес, що використовує порт.
2. Права доступу: Запуск на привілейованих портах (<1024) вимагає прав адміністратора.
3. Кодування: Переконайтеся, що PowerShell налаштований на UTF-8.
4. Версія PowerShell: Потрібен PowerShell 7+.

Діагностика

Перевірте логи сервера для діагностики проблем:

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

Розробка та розширення

Сервер легко розширюється новими інструментами MCP. Див. how-to-use.md для детальних інструкцій з розробки.

Ліцензія

Цей проєкт розповсюджується за ліцензією MIT. Див. файл LICENSE для подробиць.

Підтримка

• Створіть Issue в GitHub репозиторії.
• Перевірте документацію в how-to-use.md.
• Ознайомтеся з прикладами використання.

Версії

• 1.0.0 – Початкова версія з підтримкою режимів STDIO та HTTP.