תיעוד למפתחים: שרת MCP PowerShell HTTP. (mcp-powershell-server-http.py)

1. סקירה כללית

mcp-powershell-http.ps1 הוא שרת HTTP עצמאי הכתוב ב-PowerShell, שנועד להרצת סקריפטים של PowerShell באופן מאובטח ומרחוק. הוא מתפקד כ"גשר" בין לקוח חיצוני (למשל, עוזר AI) לבין סביבת PowerShell מקומית, תוך שימוש בפרוטוקול JSON-RPC 2.0 לתקשורת.

תכונות עיקריות:

• אבטחה: כל סקריפט רץ בתוך מופע PowerShell מבודד לחלוטין (runspace), מה שמונע השפעה על סביבת השרת הראשית.
• תצורה גמישה: ניתן להגדיר את פרמטרי השרת (פורט, מארח, פסקי זמן) באמצעות ארגומנטים של שורת הפקודה וקובץ JSON חיצוני.
• יציבות: טיפול מקיף בשגיאות בכל הרמות (HTTP, JSON, הרצת סקריפטים) מבטיח פעולה אמינה של השרת.
• פרוטוקול MCP: מממש את פרוטוקול MCP הסטנדרטי לאינטראקציה, כולל המתודות initialize, tools/list ו-tools/call.
• בקרת משאבים: פסקי זמן (timeouts) מובנים ומגבלות על גודל הפלט מונעים שימוש לרעה במשאבים.

2. הרצה והגדרה

דרישות:

• PowerShell 7.0 ומעלה.

פרמטרים של שורת הפקודה:

פרמטר	סוג	תיאור	ברירת מחדל
-Port	[int]	הפורט שבו השרת יאזין לבקשות HTTP.	8090
-ServerHost	[string]	המארח (כתובת IP או שם דומיין) אליו השרת יקושר.	localhost
-ConfigFile	[string]	נתיב לקובץ תצורה בפורמט JSON. פרמטרים מקובץ זה ידלגו על ערכי ברירת המחדל ועל ארגומנטים משורת הפקודה.	$null

דוגמת שימוש:

.\mcp-powershell-http.ps1 -Port 8090 -ServerHost 0.0.0.0 -ConfigFile "C:\config\settings.json"

קובץ תצורה (settings.json):

השרת יכול לטעון את התצורה שלו מקובץ JSON. זוהי הגישה המומלצת לסביבות ייצור (production).

דוגמה לקובץ settings.json מתוך המאגר:

{
  "Port": 8090,
  "Host": "localhost",
  "MaxConcurrentRequests": 10,
  "TimeoutSeconds": 300,
  "LogLevel": "INFO",
  "AllowedPaths": [
    "C:\\Scripts\\",
    "C:\\Users\\%USERNAME%\\Documents\\"
  ],
  "Security": {
    "EnableScriptValidation": false,
    "BlockDangerousCommands": false,
    "RestrictedCommands": [
      "Remove-Item -Path C:\\Windows\\*",
      "Format-Volume"
    ]
  }
}

3. ארכיטקטורה ופונקציות

הסקריפט מחולק לוגית למספר אזורים (#region) כדי לפשט את הניווט.

אזור: Utility Functions (פונקציות עזר)

1. Write-Log
   • מטרה: מדפיסה הודעות מעוצבות וצבעוניות לקונסולה עם חותמת זמן. זוהי הפונקציה הראשית לרישום לוגים.
   • פרמטרים:
     • $Message [string] (חובה): טקסט ההודעה.
     • $Level [string] (אופציונלי): רמת הרישום (DEBUG, INFO, WARNING, ERROR). משפיעה על צבע הפלט.
2. Test-MCPRequest
   • מטרה: בודקת אם בקשה נכנסת עומדת בדרישות הבסיסיות של פרוטוקול JSON-RPC 2.0 (נוכחות השדות jsonrpc: "2.0" ו-method).
   • פרמטרים:
     • $Request [hashtable] (חובה): הבקשה, לאחר שהומרה מ-JSON.
   • ערך מוחזר: $true אם הבקשה תקינה, אחרת $false.
3. New-MCPResponse
   • מטרה: פונקציית ייצור (factory function) ליצירת אובייקטי תגובה סטנדרטיים של JSON-RPC.
   • פרמטרים:
     • $Id [object]: מזהה הבקשה.
     • $Result [object]: האובייקט המכיל תוצאה מוצלחת.
     • $Error [hashtable]: האובייקט המכיל מידע על שגיאה.
   • ערך מוחזר: [hashtable] עם מבנה התגובה המלא.
4. Test-ScriptSafety
   • מטרה: בודקת את הסקריפט לנוכחות פקודות שעלולות להיות מסוכנות, המפורטות במשתנה הגלובלי $script:RestrictedCommands.
   • הערה: בגרסה שסופקה, פונקציה זו מושבתת כברירת מחדל (return $true). לשימוש בסביבת ייצור, יש להפעיל ולהגדיר אותה.
   • פרמטרים:
     • $Script [string] (חובה): טקסט סקריפט ה-PowerShell לבדיקה.
   • ערך מוחזר: $true אם הסקריפט בטוח, אחרת $false.

אזור: Core Logic (לוגיקת הליבה)

1. Invoke-PowerShellScript
   • מטרה: פונקציית הליבה האחראית להרצה בטוחה של סקריפט PowerShell.
   • תהליך:
     1. יוצרת מופע PowerShell חדש ומבודד לחלוטין ([powershell]::Create()).
     2. (אופציונלי) מגדירה את ספריית העבודה בתוך מופע זה.
     3. מוסיפה למופע את טקסט הסקריפט והפרמטרים שלו.
     4. מריצה את הסקריפט באופן אסינכרוני עם פסק זמן (timeout).
     5. אוספת את זרמי הפלט (Output), השגיאות (Error) והאזהרות (Warning).
     6. מגבילה את גודל הפלט (ברירת מחדל: 10,000 תווים) כדי למנוע העברת נתונים גדולה.
     7. מנקה את המשאבים (Dispose()) בסיום.
   • פרמטרים:
     • $Script [string] (חובה): הקוד להרצה.
     • $Parameters [hashtable]: פרמטרים להעברה לסקריפט.
     • $TimeoutSeconds [int]: זמן ריצה מקסימלי בשניות.
     • $WorkingDirectory [string]: ספריית העבודה עבור הסקריפט.
   • ערך מוחזר: [hashtable] עם התוצאות: success (bool), output (string), errors (array), warnings (array), executionTime (double).

אזור: MCP Protocol Methods (מתודות פרוטוקול MCP)

1. Invoke-MCPMethod
   • מטרה: דיספצ'ר (dispatcher) המטפל בקריאות למתודות של פרוטוקול MCP.
   • תהליך: משתמש במבנה switch על שם המתודה ($Method) כדי להפעיל את הלוגיקה המתאימה.
   • מתודות נתמכות:
     • "initialize": מחזירה מידע על השרת.
     • "tools/list": מחזירה רשימה של כלים זמינים (במקרה זה, רק "run-script").
     • "tools/call": מטפלת בקריאה לכלי. שולפת את הפרמטרים וקוראת ל-Invoke-PowerShellScript לביצוע.
   • פרמטרים:
     • $Method [string]: שם המתודה שיש להפעיל.
     • $Params [hashtable]: הפרמטרים של המתודה.
     • $Id [object]: מזהה הבקשה.
   • ערך מוחזר: [hashtable] המייצג תגובת MCP מלאה ומוכנה לשליחה.

אזור: HTTP Server (שרת HTTP)

1. Invoke-RequestHandler
   • מטרה: מטפלת במחזור החיים המלא של בקשת HTTP בודדת.
   • תהליך:
     1. מגדירה כותרות CORS.
     2. מטפלת בבקשות OPTIONS (CORS preflight).
     3. מוודאת שמתודת הבקשה היא POST.
     4. קוראת ומאמתת את גוף הבקשה.
     5. מנתחת (parse) את ה-JSON וממירה אותו לטבלת גיבוב.
     6. קוראת ל-Test-MCPRequest לאימות.
     7. מעבירה את הבקשה ל-Invoke-MCPMethod לעיבוד.
     8. ממירה את התגובה בחזרה ל-JSON ושולחת אותה ללקוח.
     9. מטפלת בכל השגיאות האפשריות לאורך הדרך.
   • פרמטרים:
     • $Context [System.Net.HttpListenerContext]: הקשר בקשת ה-HTTP ממאזין ה-.NET.
2. Start-MCPServer
   • מטרה: הפונקציה הראשית המאתחלת ומפעילה את מאזין ה-HTTP.
   • תהליך:
     1. יוצרת ומגדירה אובייקט System.Net.HttpListener.
     2. מפעילה את המאזין עם listener.Start().
     3. נכנסת ללולאה אינסופית while ($listener.IsListening) כדי להמתין לחיבורים נכנסים.
     4. עבור כל חיבור, קוראת ל-Invoke-RequestHandler.
     5. עוצרת את השרת בצורה תקינה בסיום התהליך.

4. זרימת ביצוע הבקשה

1. לקוח שולח בקשת POST עם Content-Type: application/json לכתובת ה-URL של השרת.
2. Start-MCPServer מקבל את הבקשה ומעביר אותה ל-Invoke-RequestHandler.
3. Invoke-RequestHandler מאמת את כותרות ה-HTTP, המתודה, ומנתח את גוף ה-JSON.
4. בקשת ה-MCP התקינה מועברת ל-Invoke-MCPMethod.
5. Invoke-MCPMethod מזהה שהופעלה המתודה tools/call עם הכלי run-script.
6. הפרמטרים (סקריפט, פסק זמן וכו') מועברים ל-Invoke-PowerShellScript.
7. Invoke-PowerShellScript מריץ את הסקריפט בסביבה מבודדת.
8. תוצאת הביצוע מוחזרת במעלה שרשרת הקריאות, מעוצבת לתגובת JSON-RPC סטנדרטית, ונשלחת חזרה ללקוח על ידי Invoke-RequestHandler.

5. הרחבת פונקציונליות

כדי להוסיף "כלי" חדש (בנוסף ל-run-script), מפתח צריך:

1. להוסיף תיאור של הכלי החדש לבלוק "tools/list" בפונקציה Invoke-MCPMethod.
2. להוסיף ענף case חדש עבור כלי זה במבנה ה-switch ($toolName) בתוך בלוק ה-"tools/call" ב-Invoke-MCPMethod.
3. לממש את הלוגיקה עבור הכלי החדש.