Documentazione per Sviluppatori: MCP PowerShell HTTP Server. (mcp-powershell-server-http.py)

1. Panoramica

mcp-powershell-http.ps1 è un server HTTP autonomo scritto in PowerShell, progettato per eseguire script PowerShell in modo remoto e sicuro. Funziona come un “ponte” tra un client esterno (ad esempio, un assistente IA) e l’ambiente PowerShell locale, utilizzando il protocollo JSON-RPC 2.0 per la comunicazione.

Caratteristiche Principali:

• Sicurezza: Ogni script viene eseguito in un’istanza PowerShell (runspace) completamente isolata, impedendo qualsiasi impatto sull’ambiente principale del server.
• Configurazione Flessibile: I parametri del server (porta, host, timeout) possono essere configurati tramite argomenti da riga di comando e un file JSON esterno.
• Stabilità: Una gestione completa degli errori a tutti i livelli (HTTP, JSON, esecuzione dello script) garantisce il funzionamento affidabile del server.
• Protocollo MCP: Implementa il protocollo standard MCP per l’interazione, inclusi i metodi initialize, tools/list e tools/call.
• Controllo delle Risorse: Timeout integrati e limiti sulla dimensione dell’output prevengono l’abuso di risorse.

2. Esecuzione e Configurazione

Requisiti:

• PowerShell 7.0 o superiore.

Parametri della Riga di Comando:

Parametro	Tipo	Descrizione	Predefinito
-Port	[int]	La porta su cui il server si metterà in ascolto per le richieste HTTP.	8090
-ServerHost	[string]	L’host (indirizzo IP o nome di dominio) a cui associare il server.	localhost
-ConfigFile	[string]	Il percorso di un file di configurazione in formato JSON. I parametri di questo file sovrascrivono i valori predefiniti e gli argomenti della riga di comando.	$null

Esempio di Utilizzo:

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

File di Configurazione (settings.json):

Il server può caricare la sua configurazione da un file JSON. Questo è l’approccio consigliato per gli ambienti di produzione.

Esempio di settings.json dal repository:

{
  "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. Architettura e Funzioni

Lo script è logicamente suddiviso in diverse regioni (#region) per semplificare la navigazione.

Regione: Utility Functions (Funzioni di Utilità)

1. Write-Log
   • Scopo: Stampa messaggi formattati e colorati nella console con un timestamp. È la funzione principale per il logging.
   • Parametri:
     • $Message [string] (obbligatorio): Il testo del messaggio.
     • $Level [string] (opzionale): Il livello di log (DEBUG, INFO, WARNING, ERROR). Influisce sul colore dell’output.
2. Test-MCPRequest
   • Scopo: Verifica se la richiesta in arrivo soddisfa i requisiti di base del protocollo JSON-RPC 2.0 (presenza dei campi jsonrpc: "2.0" e method).
   • Parametri:
     • $Request [hashtable] (obbligatorio): La richiesta, deserializzata da JSON.
   • Restituisce: $true se la richiesta è valida, altrimenti $false.
3. New-MCPResponse
   • Scopo: Una funzione “factory” per creare oggetti di risposta JSON-RPC standardizzati.
   • Parametri:
     • $Id [object]: L’identificatore della richiesta.
     • $Result [object]: L’oggetto contenente un risultato di successo.
     • $Error [hashtable]: L’oggetto contenente le informazioni sull’errore.
   • Restituisce: Una [hashtable] con la struttura completa della risposta.
4. Test-ScriptSafety
   • Scopo: Controlla se lo script contiene comandi potenzialmente pericolosi elencati nella variabile globale $script:RestrictedCommands.
   • Nota: Nella versione fornita, questa funzione è disabilitata per impostazione predefinita (return $true). Per l’uso in produzione, dovrebbe essere abilitata e configurata.
   • Parametri:
     • $Script [string] (obbligatorio): Il testo dello script PowerShell da controllare.
   • Restituisce: $true se lo script è sicuro, altrimenti $false.

Regione: Core Logic (Logica Principale)

1. Invoke-PowerShellScript
   • Scopo: La funzione principale responsabile dell’esecuzione sicura di uno script PowerShell.
   • Processo:
     1. Crea una nuova istanza PowerShell completamente isolata ([powershell]::Create()).
     2. (Opzionale) Imposta la directory di lavoro all’interno di questa istanza.
     3. Aggiunge il testo dello script e i suoi parametri all’istanza.
     4. Esegue lo script in modo asincrono con un timeout.
     5. Raccoglie i flussi di output (Output), errore (Error) e avviso (Warning).
     6. Limita la dimensione dell’output (predefinito 10.000 caratteri) per prevenire trasferimenti di dati di grandi dimensioni.
     7. Rilascia le risorse (Dispose()) al termine.
   • Parametri:
     • $Script [string] (obbligatorio): Il codice da eseguire.
     • $Parameters [hashtable]: Parametri da passare allo script.
     • $TimeoutSeconds [int]: Tempo massimo di esecuzione in secondi.
     • $WorkingDirectory [string]: La directory di lavoro per lo script.
   • Restituisce: Una [hashtable] con i risultati: success (bool), output (string), errors (array), warnings (array), executionTime (double).

Regione: MCP Protocol Methods (Metodi del Protocollo MCP)

1. Invoke-MCPMethod
   • Scopo: Un dispatcher che gestisce le chiamate ai metodi del protocollo MCP.
   • Processo: Utilizza un’istruzione switch sul nome del metodo ($Method) per invocare la logica appropriata.
   • Metodi Supportati:
     • "initialize": Restituisce informazioni sul server.
     • "tools/list": Restituisce un elenco degli strumenti disponibili (in questo caso, solo "run-script").
     • "tools/call": Gestisce l’invocazione di uno strumento. Estrae i parametri e chiama Invoke-PowerShellScript per l’esecuzione.
   • Parametri:
     • $Method [string]: Il nome del metodo da chiamare.
     • $Params [hashtable]: I parametri del metodo.
     • $Id [object]: L’identificatore della richiesta.
   • Restituisce: Una [hashtable] che rappresenta la risposta MCP completa, pronta per essere inviata.

Regione: HTTP Server

1. Invoke-RequestHandler
   • Scopo: Gestisce l’intero ciclo di vita di una singola richiesta HTTP.
   • Processo:
     1. Imposta gli header CORS.
     2. Gestisce le richieste OPTIONS (CORS preflight).
     3. Verifica che il metodo della richiesta sia POST.
     4. Legge e convalida il corpo della richiesta.
     5. Esegue il parsing del JSON e lo converte in una hashtable.
     6. Chiama Test-MCPRequest per la validazione.
     7. Passa la richiesta a Invoke-MCPMethod per l’elaborazione.
     8. Serializza la risposta in JSON e la invia al client.
     9. Gestisce tutti i possibili errori lungo questo percorso.
   • Parametri:
     • $Context [System.Net.HttpListenerContext]: Il contesto della richiesta HTTP dal listener .NET.
2. Start-MCPServer
   • Scopo: La funzione principale che inizializza e avvia il listener HTTP.
   • Processo:
     1. Crea e configura un oggetto System.Net.HttpListener.
     2. Avvia il listener con listener.Start().
     3. Entra in un ciclo infinito while ($listener.IsListening) per attendere le connessioni in arrivo.
     4. Per ogni connessione, chiama Invoke-RequestHandler.
     5. Arresta correttamente il server quando il processo viene terminato.

4. Flusso di Esecuzione di una Richiesta

1. Un client invia una richiesta POST con Content-Type: application/json all’URL del server.
2. Start-MCPServer accetta la richiesta e la passa a Invoke-RequestHandler.
3. Invoke-RequestHandler convalida gli header HTTP, il metodo ed esegue il parsing del corpo JSON.
4. La richiesta MCP valida viene passata a Invoke-MCPMethod.
5. Invoke-MCPMethod determina che è stato invocato il metodo tools/call con lo strumento run-script.
6. I parametri (script, timeout, ecc.) vengono passati a Invoke-PowerShellScript.
7. Invoke-PowerShellScript esegue lo script in un ambiente isolato.
8. Il risultato dell’esecuzione viene restituito lungo la catena di chiamate, formattato in una risposta JSON-RPC standard e inviato al client da Invoke-RequestHandler.

5. Estendere le Funzionalità

Per aggiungere un nuovo “strumento” (oltre a run-script), uno sviluppatore deve:

1. Aggiungere una descrizione del nuovo strumento nel blocco "tools/list" della funzione Invoke-MCPMethod.
2. Aggiungere un nuovo ramo case per questo strumento nell’istruzione switch ($toolName) all’interno del blocco "tools/call" di Invoke-MCPMethod.
3. Implementare la logica per il nuovo strumento.