התקנה והגדרה

דרישות קדם

1. PowerShell 7.0+ # בדיקת גרסת PowerShell $PSVersionTable.PSVersion # התקנת PowerShell 7 (במידת הצורך) # יש להוריד מ- https://github.com/PowerShell/PowerShell
2. הרשאות גישה
   • עבור פורטים נמוכים מ-1024 נדרשות הרשאות מנהל מערכת.
   • הרשאות להרצת סקריפטים של PowerShell.
3. הגדרת מדיניות הרצה (Execution Policy) # בדיקת המדיניות הנוכחית Get-ExecutionPolicy # הגדרת מדיניות המאפשרת הרצת סקריפטים Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

הגדרה ראשונית

1. ניווט לספריית השרתים # מעבר לספריית השורש של המודול cd C:\powershell\modules\mcp-powershell-server # מעבר לספריית השרתים cd src\servers
2. בדיקת קבצים
   powershell # ודא שכל הקבצים הנדרשים קיימים Get-ChildItem *.ps1 | Select-Object Name

בחירת מצב עבודה: HTTP מול STDIO

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

• מצב HTTP (mcp-powershell-http.ps1): עובד כמו שירות רשת (web service). הוא מקבל פקודות דרך הרשת (HTTP) ויכול להיות נגיש ממחשבים אחרים או מיישומי אינטרנט. זוהי דרך גמישה לאינטגרציות רשתיות.
• מצב STDIO (mcp-powershell-stdio.ps1): עובד כמו יישום קונסולה הנשלט על ידי תהליך אחר. הוא מקבל פקודות דרך זרם הקלט הסטנדרטי (Standard Input) ומחזיר תוצאות דרך זרם הפלט הסטנדרטי (Standard Output). דרך זו אידיאלית לאינטגרציה מקומית, לדוגמה, עם gemini-cli.

מתי להשתמש במצב HTTP?

בחרו ב-HTTP אם אתם זקוקים לזמינות ברשת:

• ניהול מרחוק: אפליקציית הלקוח (למשל, סקריפט פייתון) נמצאת על מחשב אחר.
• אינטגרציית רשת: אתם רוצים להפעיל את PowerShell מפאנל ניהול אינטרנטי, על ידי שליחת בקשות באמצעות JavaScript.
• ארכיטקטורת מיקרו-שירותים: שירותים שונים ברשת שלכם צריכים להחליף ביניהם פקודות.
• בדיקות פשוטות: אתם רוצים לשלוח פקודות באמצעות כלים כמו curl או Postman.

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

מתי להשתמש במצב STDIO?

בחרו ב-STDIO עבור אינטגרציה מקומית ומאובטחת יותר:

• אינטגרציה עם Gemini CLI: זהו התרחיש העיקרי והנפוץ ביותר. gemini-cli מפעיל בעצמו את mcp-powershell-stdio.ps1 כתהליך בן ומתקשר איתו ישירות.
• סקריפטים עוטפים (wrappers) מקומיים: היישום שלכם בשפה אחרת (למשל, Node.js) מפעיל את שרת ה-PowerShell כתהליך בן ומנהל אותו.
• אבטחה מוגברת: מצב זה אינו פותח פורטים ברשת, מה שמבטל סוג שלם של איומי רשת.

תרחיש מפתח: הלקוח והשרת פועלים על אותה מכונה, והלקוח מנהל בעצמו את מחזור החיים של השרת.

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

מצב STDIO

מצב STDIO מיועד לאינטגרציה עם לקוחות MCP, כגון gemini-cli.

הפעלת שרת STDIO

# הפעלה ישירה של השרת (מתוך תיקיית src/servers)
.\mcp-powershell-stdio.ps1

# או משורש הפרויקט
.\src\servers\mcp-powershell-stdio.ps1

מאפייני מצב STDIO

• פרוטוקול: JSON-RPC דרך זרמי קלט/פלט סטנדרטיים.
• רישום (לוגים): לקובץ %TEMP%\mcp-powershell-server.log.
• קידוד: UTF-8 לעבודה תקינה עם תווים בעברית.
• תאימות: עובד עם כל לקוח MCP.

בדיקת מצב STDIO

# הפעלת שרת בדיקה לצורך אימות (מתוך תיקיית src/servers)
.\test-mcp.ps1

# או משורש הפרויקט
.\src\servers\test-mcp.ps1

דוגמה לבדיקה ידנית:"`json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run-script","arguments":{"script":"Get-Date"}}}

## מצב HTTP

מצב HTTP מיועד לאינטגרציות רשת ו-REST API.

### הפעלת שרת HTTP

powershell

הפעלה בסיסית (localhost:8090) מתוך תיקיית src/servers

.\mcp-powershell-http.ps1

הפעלה על פורט אחר

.\mcp-powershell-http.ps1 -Port 9090

הפעלה על כל הממשקים

.\mcp-powershell-http.ps1 -ServerHost "0.0.0.0" -Port 8080

הפעלה עם קובץ תצורה

.\mcp-powershell-http.ps1 -ConfigFile "config.json"

או משורש הפרויקט

.\src\servers\mcp-powershell-http.ps1 -Port 8090

### נקודות קצה (Endpoints) של API HTTP

כל הבקשות נשלחות כ-`POST` לכתובת ה-URL הראשית של השרת.

**URL**: `http://localhost:8090/`
**Method**: `POST`
**Content-Type**: `application/json`

### בדיקת מצב HTTP

powershell

בדיקה באמצעות Invoke-RestMethod

$body = @{
jsonrpc = "2.0"
id = 1
method = "tools/list"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8090/" -Method POST -Body $body -ContentType "application/json"

bash

בדיקה באמצעות curl

curl -X POST http://localhost:8090/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

## אינטגרציה עם Gemini CLI

### הגדרה אוטומטית

powershell

הפעלה עם הגדרה אוטומטית של Gemini CLI

.\start-mcp-with-gemini.ps1 -ApiKey "your-gemini-api-key"

עם פרמטרים נוספים

.\start-mcp-with-gemini.ps1 -ApiKey "your-key" -ServerPort 9090 -Wait 15

### הגדרה ידנית

1.  **יצירת תצורת MCP**
    ```powershell
    # יצירת ספריית התצורה
    $configDir = "$env:USERPROFILE\.config\gemini"
    New-Item -Path $configDir -ItemType Directory -Force

    # יצירת קובץ תצורת MCP
    $config = @{
        mcpServers = @{
            powershell = @{
                command = "pwsh"
                args = @("-File", "C:\path\to\mcp-powershell-stdio.ps1")
                env = @{}
            }
        }
    } | ConvertTo-Json -Depth 5

    $config | Set-Content "$configDir\mcp_servers.json" -Encoding UTF8
    ```
2.  **שימוש עם gemini-cli**
    ```bash
    # מצב אינטראקטיבי
    gemini --mcp-config "path/to/mcp_servers.json" -i

    # בקשה בודדת
    gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "בצע את הפקודה Get-Process | Select-Object -First 5"
    ```

## דוגמאות שימוש

### פקודות PowerShell בסיסיות

json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "run-script",
"arguments": {
"script": "Get-ComputerInfo | Select-Object WindowsProductName, TotalPhysicalMemory"
}
}
}

### עבודה עם קבצים

json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "run-script",
"arguments": {
"script": "Get-ChildItem C:\ -Directory | Select-Object Name, CreationTime | Format-Table",
"workingDirectory": "C:\",
"timeoutSeconds": 30
}
}
}

### סקריפטים עם פרמטרים

json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "run-script",
"arguments": {
"script": "param($ProcessName) Get-Process -Name $ProcessName -ErrorAction SilentlyContinue",
"parameters": {
"ProcessName": "notepad"
}
}
}
}

### ניטור מערכת

json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "run-script",
"arguments": {
"script": "$cpu = Get-Counter '\Processor(_Total)\% Processor Time' | Select-Object -ExpandProperty CounterSamples | Select-Object -ExpandProperty CookedValue; $memory = Get-Counter '\Memory\Available MBytes' | Select-Object -ExpandProperty CounterSamples | Select-Object -ExpandProperty CookedValue; Write-Output \"CPU: $([math]::Round($cpu, 2))%, Available Memory: $memory MB\""
}
}
}

## תצורה

### קובץ config.json

json
{
"Port": 8090,
"Host": "localhost",
"MaxConcurrentRequests": 10,
"TimeoutSeconds": 300,
"LogLevel": "INFO",
"AllowedPaths": [
"C:\Scripts\",
"C:\Tools\",
"C:\Temp\"
],
"Security": {
"EnableScriptValidation": true,
"BlockDangerousCommands": true,
"RestrictedCommands": [
"Remove-Item",
"Format-Volume",
"Stop-Computer",
"Restart-Computer",
"New-ItemProperty -Path 'HKLM:'", "Remove-ItemProperty -Path 'HKLM:'"
],
"AllowedModules": [
"Microsoft.PowerShell.*",
"PackageManagement",
"PowerShellGet"
]
},
"Logging": {
"LogFile": "%TEMP%\mcp-powershell-server.log",
"MaxLogSize": "10MB",
"LogRotation": true
}
}

### משתני סביבה

powershell

הגדרה באמצעות משתני סביבה

$env:MCP_PS_PORT = "8090"
$env:MCP_PS_HOST = "localhost"
$env:MCP_PS_TIMEOUT = "300"
$env:MCP_PS_LOG_LEVEL = "INFO"

## אבטחה

### המלצות אבטחה

1.  **הגבלת פקודות**
    ```json
    "RestrictedCommands": [
      "Remove-Item",
      "Format-Volume",
      "Stop-Computer",
      "Restart-Computer",
      "Invoke-Expression",
      "iex",
      "& *"
    ]
    ```
2.  **הגבלת נתיבים**
    ```json
    "AllowedPaths": [
      "C:\\Scripts\\",
      "C:\\Tools\\",
      "C:\\Temp\\"
    ]
    ```
3.  **הגבלות רשת**
    ```powershell
    # הגבלת גישה למארח המקומי בלבד
    .\start-mcp-server.ps1 -ServerHost "127.0.0.1"
    ```
4.  **זמני קצוב (Timeouts)**
    ```json
    "TimeoutSeconds": 60  // הגבלת זמן ריצה
    ```

### ביקורת וניטור

powershell

ניטור לוגים בזמן אמת

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

ניתוח פקודות שבוצעו

Select-String -Path "$env:TEMP\mcp-powershell-server.log" -Pattern "מריץ סקריפט PowerShell"

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

### הוספת כלי MCP חדשים

1.  **מבנה הכלי**
    ```powershell
    # בפונקציה Invoke-MCPMethod, הוסף case חדש
    "my-custom-tool" {
        # אימות פרמטרים
        if (-not $arguments.ContainsKey("required_param")) {
            return New-MCPResponse -Id $Id -Error @{
                code = -32602
                message = "חסר פרמטר חובה 'required_param'"
            }
        }

        # לוגיקת ביצוע
        $result = Invoke-MyCustomFunction -Param $arguments.required_param

        # החזרת תוצאה
        return New-MCPResponse -Id $Id -Result @{
            content = @(
                @{
                    type = "text"
                    text = "תוצאה: $result"
                }
            )
        }
    }
    ```
2.  **רישום ב-tools/list**
    ```powershell
    # הוסף את תיאור הכלי למתודה tools/list
    @{
        name = "my-custom-tool"
        description = "תיאור הכלי המותאם אישית שלי"
        inputSchema = @{
            type = "object"
            properties = @{
                required_param = @{
                    type = "string"
                    description = "פרמטר חובה"
                }
            }
            required = @("required_param")
        }
    }
    ```

### דוגמה לכלי מותאם אישית

powershell

הוספת כלי לעבודה עם הרישום (Registry)

"registry-query" {
if (-not $arguments.ContainsKey("path")) {
return New-MCPResponse -Id $Id -Error @{
code = -32602
message = "חסר פרמטר חובה 'path'"
}
}

try {
    $regPath = $arguments.path
    $regKey = Get-ItemProperty -Path $regPath -ErrorAction Stop
    $result = $regKey | Format-List | Out-String

    return New-MCPResponse -Id $Id -Result @{
        content = @(
            @{
                type = "text"
                text = "ערכי רישום בנתיב ${regPath}:`n$result"
            }
        )
    }
}
catch {
    return New-MCPResponse -Id $Id -Error @{
        code = -32603
        message = "שאילתת הרישום נכשלה: $($_.Exception.Message)"
    }
}

}"`

פתרון בעיות

פקודות אבחון

# בדיקת גרסת PowerShell
$PSVersionTable.PSVersion

# בדיקת זמינות פורט
Test-NetConnection -ComputerName localhost -Port 8090

# בדיקת לוגים
Get-Content "$env:TEMP\mcp-powershell-server.log" -Tail 50

# בדיקת תהליכי PowerShell
Get-Process -Name pwsh*

בעיות נפוצות

1. "הפורט כבר בשימוש" # מצא את התהליך המשתמש בפורט Get-NetTCPConnection -LocalPort 8090 | Get-Process # או השתמש בפורט אחר .\start-mcp-server.ps1 -Port 9090
2. "הגישה נדחתה"
   powershell # הפעל עם הרשאות מנהל עבור פורטים < 1024 Start-Process pwsh -Verb RunAs -ArgumentList "-File", "start-mcp-server.ps1"
3. "בעיות קידוד" # בדיקת קידוד הקונסולה [Console]::OutputEncoding [Console]::InputEncoding # כפיית קידוד UTF-8 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 [Console]::InputEncoding = [System.Text.Encoding]::UTF8
4. "הסקריפט אינו רץ" # בדיקת מדיניות ההרצה Get-ExecutionPolicy -List # הרשאה זמנית powershell.exe -ExecutionPolicy Bypass -File "script.ps1"

ניפוי שגיאות (Debugging)

# הפעלת רישום מפורט
$DebugPreference = "Continue"

# מעקב אחר הרצת סקריפטים
Set-PSDebug -Trace 1

# כיבוי מעקב
Set-PSDebug -Off

תיעוד API

מתודות MCP

initialize

מאתחל את שרת ה-MCP.

בקשה (Request):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05"
  }
}

תשובה (Response):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "PowerShell Script Runner",
      "version": "1.0.0",
      "description": "מריץ סקריפטים של PowerShell דרך MCP"
    }
  }
}

tools/list

מחזיר את רשימת הכלים הזמינים.

בקשה (Request):

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

תשובה (Response):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "run-script",
        "description": "מריץ סקריפט PowerShell עם פרמטרים נתונים",
        "inputSchema": {
          "type": "object",
          "properties": {
            "script": {
              "type": "string",
              "description": "קוד PowerShell להרצה"
            },
            "parameters": {
              "type": "object",
              "description": "פרמטרים לסקריפט (אופציונלי)"
            },
            "workingDirectory": {
              "type": "string",
              "description": "ספריית עבודה להרצה"
            },
            "timeoutSeconds": {
              "type": "integer",
              "description": "זמן קצוב להרצה בשניות",
              "default": 300,
              "minimum": 1,
              "maximum": 3600
            }
          },
          "required": ["script"]
        }
      }
    ]
  }
}

tools/call

מפעיל כלי.

בקשה (Request):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "run-script",
    "arguments": {
      "script": "Get-Date",
      "timeoutSeconds": 30
    }
  }
}

תשובה (Response):json { "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "פלט הפקודה:\n\nיום שלישי, 25 בספטמבר 2025 14:30:45\n" } ], "isError": false, "_meta": { "executionTime": "2025-09-25 14:30:45", "success": true, "errorCount": 0, "warningCount": 0 } } }

קודי שגיאה

קוד	תיאור
-32700	Parse error – שגיאת פיענוח JSON
-32600	Invalid Request – בקשה לא חוקית
-32601	Method not found – המתודה לא נמצאה
-32602	Invalid params – פרמטרים לא חוקיים
-32603	Internal error – שגיאה פנימית בשרת

רמות רישום (לוגים)

רמה	תיאור
DEBUG	מידע מפורט לניפוי שגיאות
INFO	מידע כללי על פעולת השרת
WARNING	אזהרות על בעיות פוטנציאליות
ERROR	שגיאות הדורשות טיפול

סיכום

שרת MCP PowerShell מספק דרך חזקה ומאובטחת לשלב את PowerShell עם עוזרי AI ויישומים אחרים באמצעות פרוטוקול MCP המתוקנן. עקבו אחר המלצות האבטחה והשתמשו ברישום לניטור פעולת השרת.