Server MCP PowerShell. README>

Un server MCP (Model Context Protocol) per l’esecuzione di script PowerShell, che supporta sia la modalità HTTP che STDIO.

Descrizione

Il Server MCP PowerShell consente agli assistenti AI di eseguire comandi e script PowerShell tramite il protocollo standardizzato MCP. Il server supporta due modalità operative:

• Modalità STDIO: Per l’integrazione con gemini-cli e altri client MCP locali.
• Modalità HTTP: Per applicazioni web e integrazione di rete tramite API REST.

Quale modalità scegliere: HTTP o STDIO?

La scelta tra mcp-powershell-http.ps1 e mcp-powershell-stdio.ps1 dipende da come e da dove l’applicazione client interagirà con il server.

• mcp-powershell-http.ps1 (modalità HTTP) funziona come un cameriere in un ristorante. Prende gli ordini (richieste HTTP) da qualsiasi client sulla rete, li passa alla “cucina” (PowerShell) e restituisce il risultato pronto (risposta HTTP).
• mcp-powershell-stdio.ps1 (modalità STDIO) funziona come un assistente personale in cucina. Riceve i compiti direttamente (tramite l’input standard stdin) da un processo di gestione (ad es. gemini-cli) che lo ha avviato, e restituisce immediatamente il risultato (tramite l’output standard stdout).

Quando usare la modalità HTTP

Dovresti scegliere HTTP se è richiesta un’interazione di rete.

• Gestione remota: L’applicazione client si trova su un altro computer.
• Integrazione web: È necessario chiamare script PowerShell da un’applicazione web, un pannello di amministrazione o tramite richieste AJAX.
• Architettura a microservizi: Altri servizi nella tua rete devono interagire con PowerShell.
• Test semplici: Vuoi utilizzare strumenti come curl, Postman o Invoke-RestMethod per inviare comandi.

In parole semplici: scegli HTTP se c’è una rete tra il client e il server.

Quando usare la modalità STDIO

Questa modalità è ideale per l’integrazione locale e sicura.

• Scenario principale — Gemini CLI: Lo strumento gemini-cli avvia mcp-powershell-stdio.ps1 come processo figlio e comunica con esso direttamente tramite i flussi di input/output standard.
• Integrazione con altre applicazioni locali: Il tuo programma in Python, Node.js o un altro linguaggio può avviare e gestire il server senza aprire porte di rete.
• Sicurezza migliorata: Poiché non vengono aperte porte di rete, questo metodo è più sicuro per impostazione predefinita.

In parole semplici: scegli STDIO se il client e il server si trovano sulla stessa macchina e il client avvia il server stesso.

Tabella di confronto

Caratteristica	Modalità HTTP (mcp-powershell-http.ps1)	Modalità STDIO (mcp-powershell-stdio.ps1)
Scenario principale	Interazione di rete, API web	Integrazione locale con strumenti CLI
Tipo di comunicazione	Client-server su rete (TCP/IP)	Comunicazione tra processi (IPC)
Posizione	Client e server possono trovarsi su macchine diverse	Client e server devono trovarsi sulla stessa macchina
Sicurezza	Richiede attenzione (accesso alla porta, firewall)	Più sicuro per impostazione predefinita (nessuna porta aperta)
Client tipici	curl, Postman, applicazioni web, script remoti	gemini-cli, applicazioni wrapper locali

Caratteristiche

• ✅ Supporto per il protocollo MCP versione 2024-11-05
• ✅ Due modalità operative: STDIO e HTTP
• ✅ Isolamento dell’esecuzione degli script in processi PowerShell separati
• ✅ Timeout di esecuzione configurabili
• ✅ Registrazione dettagliata di tutte le operazioni
• ✅ Gestione degli errori e degli avvisi di PowerShell
• ✅ Supporto per i parametri degli script
• ✅ Directory di lavoro configurabile
• ✅ Launcher automatici per semplificare l’avvio

Requisiti di sistema

• PowerShell 7.0 o successivo
• Windows 10/11 o Windows Server 2019+
• .NET 6.0 o successivo

Struttura del progetto

mcp-powershell-server/
├── src/
│   ├── clients/           # Applicazioni client
│   │   ├── node/         # Client Node.js
│   │   ├── powershell/   # Client PowerShell
│   │   └── python/       # Client Python
│   └── servers/          # Componenti del server
│       ├── mcp-powershell-stdio.ps1   # Versione STDIO del server
│       ├── mcp-powershell-http.ps1    # Versione HTTP del server
│       ├── test-mcp.ps1               # Server di test
│       └── config.json                # File di configurazione
├── docs/                 # Documentazione
├── README.md            # Questo file
└── how-to-use.md        # Guida dettagliata all'uso

Avvio rapido

Modalità STDIO (per gemini-cli)

1. Avviare il server:
   powershell .\src\servers\mcp-powershell-stdio.ps1
2. Testare:
   powershell .\src\servers\test-mcp.ps1

Modalità HTTP

1. Avvio base:
   powershell .\src\servers\mcp-powershell-http.ps1
2. Con parametri personalizzati:
   powershell .\src\servers\mcp-powershell-http.ps1 -Port 9090 -ServerHost "0.0.0.0"
3. Con un file di configurazione:
   powershell .\src\servers\mcp-powershell-http.ps1 -ConfigFile ".\src\servers\config.json"

Strumenti MCP disponibili

run-script

Esegue uno script PowerShell con i parametri specificati.

Parametri:

• script (obbligatorio) – Codice PowerShell da eseguire
• parameters (opzionale) – Tabella hash dei parametri
• workingDirectory (opzionale) – Directory di lavoro
• timeoutSeconds (opzionale) – Timeout di esecuzione (1-3600 sec)

Esempio di utilizzo tramite MCP:

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

Configurazione

Il server supporta la configurazione tramite il file 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"
    ]
  }
}

Sicurezza

• L’esecuzione degli script avviene in processi PowerShell isolati
• Supporto per un elenco di comandi vietati
• Limite del tempo di esecuzione
• Registrazione di tutti i comandi eseguiti
• Possibilità di limitare i percorsi accessibili

Registrazione (Logging)

• Modalità STDIO: I log vengono scritti in %TEMP%\mcp-powershell-server.log
• Modalità HTTP: I log vengono visualizzati nella console con evidenziazione a colori

Livelli di log: DEBUG, INFO, WARNING, ERROR

Integrazione con assistenti AI

Gemini CLI

gemini --mcp-config "path/to/mcp_servers.json" -m gemini-2.5-pro -p "Mostra i primi 5 processi nel sistema"

Altri client MCP

Il server è compatibile con tutti i client che supportano il protocollo MCP 2024-11-05.

Risoluzione dei problemi

Problemi comuni

1. Porta occupata: Cambia la porta nella configurazione o arresta il processo che utilizza la porta.
2. Diritti di accesso: L’esecuzione su porte privilegiate (<1024) richiede i diritti di amministratore.
3. Codifica: Assicurati che PowerShell sia configurato su UTF-8.
4. Versione di PowerShell: È richiesto PowerShell 7+.

Diagnostica

Controlla i log del server per diagnosticare i problemi:

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

Sviluppo ed estensione

Il server è facilmente estendibile con nuovi strumenti MCP. Consulta how-to-use.md per istruzioni dettagliate sullo sviluppo.

Licenza

Questo progetto è distribuito sotto la licenza MIT. Vedi il file LICENSE per i dettagli.

Supporto

• Crea una “Issue” nel repository GitHub.
• Controlla la documentazione in how-to-use.md.
• Consulta gli esempi di utilizzo.

Versioni

• 1.0.0 – Versione iniziale con supporto per le modalità STDIO e HTTP.