Документація сервера MCP PowerShell. STDIO Server. (mcp-powershell-server-stdio.py)

Опис

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

Архітектура

Основні компоненти

1. JSON Конвертер – функція для перетворення JSON у хеш-таблиці PowerShell.
2. Логування – система запису подій у файл.
3. MCP Оброробник – основна логіка обробки MCP запитів.
4. PowerShell Виконавець – ізольоване виконання скриптів.
5. STDIO Інтерфейс – комунікація через стандартні потоки.

Структура файлу

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # Функція конвертації JSON
├── Write-Log                      # Функція логування
├── Test-MCPRequest               # Валідація MCP запитів
├── New-MCPResponse               # Створення MCP відповідей
├── Invoke-PowerShellScript       # Виконання PowerShell скриптів
├── Invoke-MCPMethod              # Обробка MCP методів
├── Send-MCPResponse              # Надсилання відповідей
├── Start-MCPServer               # Основний цикл сервера
└── Ініціалізація та запуск

Функції

ConvertFrom-JsonToHashtable

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

Призначення: Функція перетворює рядок JSON у хеш-таблиці PowerShell для сумісності з PowerShell 5.x.

Параметри:

• Json (string) – Рядок JSON для перетворення.

Повертає: Хеш-таблицю з перетвореними даними.

Особливості:

• Рекурсивне перетворення вкладених об’єктів.
• Обробка масивів та колекцій.
• Сумісність із 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"
    )
}

Призначення: Функція записує логи у файл, оскільки stdout використовується для MCP комунікації.

Параметри:

• Message (string) – Повідомлення для запису в лог.
• Level (string) – Рівень логування (INFO, WARNING, ERROR, DEBUG).

Особливості:

• Запис у файл $env:TEMP\mcp-powershell-server.log.
• Часові мітки у форматі yyyy-MM-dd HH:mm:ss.
• Кодування UTF-8.

Test-MCPRequest

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

Призначення: Функція валідує MCP запит на відповідність протоколу.

Параметри:

• Request (hashtable) – MCP запит для валідації.

Повертає: Boolean – результат валідації.

Перевірки:

• Наявність поля jsonrpc зі значенням “2.0”.
• Наявність обов’язкового поля 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
    )
}

Призначення: Функція створює стандартизовану MCP відповідь.

Параметри:

• Id (object) – Ідентифікатор запиту.
• Result (object) – Результат виконання операції.
• Error (hashtable) – Інформація про помилку.

Повертає: Hashtable з MCP відповіддю.

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

Призначення: Функція виконує скрипт PowerShell в ізольованому процесі.

Параметри:

• Script (string) – PowerShell скрипт для виконання.
• Parameters (hashtable) – Параметри для скрипта.
• TimeoutSeconds (int) – Таймаут виконання (за замовчуванням 300 сек).
• WorkingDirectory (string) – Робоча директорія.

Повертає: Hashtable з результатами виконання:

• success (bool) – Статус виконання.
• output (string) – Вивід команди.
• errors (array) – Масив помилок.
• warnings (array) – Масив попереджень.

Особливості:

• Ізоляція через окремий процес PowerShell.
• Підтримка таймауту.
• Збір усіх потоків виводу (output, error, warning).
• Автоматичне звільнення ресурсів.

Методи MCP

initialize

Призначення: Ініціалізація MCP сервера та обмін інформацією про можливості.

Відповідь:“`json
{
“protocolVersion”: “2024-11-05”,
“capabilities”: {
“tools”: {
“listChanged”: true
}
},
“serverInfo”: {
“name”: “PowerShell Script Runner”,
“version”: “1.0.0”,
“description”: “Виконує скрипти PowerShell через MCP”
}
}

### tools/list

**Призначення**: Отримання списку доступних інструментів.

**Відповідь**: Масив інструментів з описом схем вхідних параметрів.

### tools/call

**Призначення**: Виклик конкретного інструмента з параметрами.

**Параметри**:
- `name` (string) - Ім'я інструмента.
- `arguments` (object) - Аргументи для інструмента.

## Інструменти

### run-script

**Призначення**: Виконує скрипт PowerShell із заданими параметрами.

**Схема вхідних параметрів**:

json
{
“type”: “object”,
“properties”: {
“script”: {
“type”: “string”,
“description”: “PowerShell скрипт для виконання”
},
“parameters”: {
“type”: “object”,
“description”: “Параметри для скрипта (опціонально)”,
“additionalProperties”: true
},
“workingDirectory”: {
“type”: “string”,
“description”: “Робоча директорія для виконання (опціонально)”,
“default”: “<поточна директорія>”
},
“timeoutSeconds”: {
“type”: “integer”,
“description”: “Таймаут виконання в секундах (опціонально)”,
“default”: 300,
“minimum”: 1,
“maximum”: 3600
}
},
“required”: [“script”]
}“`

Відповідь: Структура з результатами виконання, що включає:

• Вивід команди у відформатованому вигляді.
• Помилки (якщо є).
• Попередження (якщо є).
• Метадані виконання.

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

Кодування

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

Сервер налаштований на роботу з кодуванням UTF-8 для коректної обробки даних JSON.

Логування

• Файл логів: $env:TEMP\mcp-powershell-server.log
• Кодування: UTF-8
• Рівні: INFO, WARNING, ERROR, DEBUG
• Формат: [yyyy-MM-dd HH:mm:ss] [LEVEL] Message

Безпека

• Ізоляція скриптів через окремі процеси PowerShell.
• Таймаути для запобігання зависанню.
• Валідація всіх вхідних запитів.
• Логування всіх операцій.

Використання

Запуск сервера

.\mcp-powershell-stdio.ps1

Сервер запускається в режимі STDIO і очікує на команди MCP через стандартний ввід.

Приклади MCP запитів

Ініціалізація

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

Список інструментів

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

Виконання скрипта

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

Обробка помилок

Коди помилок MCP

• -32700: Помилка парсингу JSON
• -32600: Невалідний MCP запит
• -32601: Невідомий метод або інструмент
• -32602: Невірні параметри
• -32603: Внутрішня помилка сервера

Логування помилок

Усі помилки логуються у файл з детальною інформацією:

• Часова мітка
• Рівень помилки
• Детальний опис
• Stack trace (за необхідності)

Обмеження

1. Таймаут виконання: Максимум 3600 секунд (1 година).
2. Ізоляція процесів: Кожен скрипт виконується в окремому процесі.
3. Кодування: Тільки UTF-8.
4. Сумісність: PowerShell 5.x і вище.

Продуктивність

• Мінімальні накладні витрати на створення процесів.
• Ефективна серіалізація JSON.
• Автоматичне очищення ресурсів.
• Оптимізоване логування.

Масштабованість

Сервер розроблений для обробки одного запиту за раз у синхронному режимі. Для паралельної обробки потрібно запускати кілька екземплярів сервера.

---

Версія документації: 1.0.0
Дата створення: 15 вересня 2025