תיעוד שרת MCP PowerShell. STDIO Server. (mcp-powershell-server-stdio.py)

תיאור

שרת MCP PowerShell הוא שרת המממש את פרוטוקול Model Context Protocol (MCP) להרצת סקריפטים של PowerShell. השרת פועל במצב STDIO ומספק כלים להרצה מאובטחת של פקודות PowerShell דרך ממשק סטנדרטי.

ארכיטקטורה

רכיבים עיקריים

1. ממיר JSON – פונקציה להמרת JSON לטבלאות גיבוב (hashtables) של PowerShell.
2. רישום לוגים (Logging) – מערכת לרישום אירועים בקובץ.
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 לאימות.

ערך מוחזר: בוליאני – תוצאת האימות.

בדיקות:

• נוכחות השדה 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 נפרד.
• תמיכה בפסק זמן (timeout).
• איסוף כל זרמי הפלט (output, error, warning).
• שחרור משאבים אוטומטי.

מתודות MCP

initialize

מטרה: אתחול שרת MCP והחלפת מידע על יכולות.

תגובה:

{
  "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 עם פרמטרים נתונים.

סכמת פרמטרים לכניסה:

{
  "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.

רישום לוגים (Logging)

• קובץ לוגים: $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 (Parse error)
• -32600: בקשת MCP לא תקינה (Invalid Request)
• -32601: מתודה או כלי לא נמצאו (Method not found)
• -32602: פרמטרים לא תקינים (Invalid params)
• -32603: שגיאה פנימית בשרת (Internal error)

רישום שגיאות

כל השגיאות נרשמות בקובץ עם מידע מפורט:

• חותמת זמן
• רמת השגיאה
• תיאור מפורט
• עקבת מחסנית (Stack trace) (במידת הצורך)

מגבלות

1. פסק זמן להרצה: מקסימום 3600 שניות (שעה אחת).
2. בידוד תהליכים: כל סקריפט רץ בתהליך נפרד.
3. קידוד: UTF-8 בלבד.
4. תאימות: PowerShell 5.x ומעלה.

ביצועים

• תקורה מינימלית ליצירת תהליכים.
• סריאליזציה יעילה של JSON.
• ניקוי משאבים אוטומטי.
• רישום לוגים ממוטב.

מדרגיות (Scalability)

השרת מתוכנן לטפל בבקשה אחת בכל פעם במצב סינכרוני. לעיבוד מקבילי, יש להריץ מספר מופעים של השרת.

---

גרסת התיעוד: 1.0.0
תאריך יצירה: 15 בספטמבר 2025