Documentazione del Server MCP PowerShell. STDIO Server. (mcp-powershell-server-stdio.py)

Descrizione

Il Server MCP PowerShell è un server che implementa il Model Context Protocol (MCP) per l’esecuzione di script PowerShell. Il server opera in modalità STDIO e fornisce strumenti per l’esecuzione sicura di comandi PowerShell attraverso un’interfaccia standardizzata.

Architettura

Componenti Principali

1. Convertitore JSON – Una funzione per convertire JSON in tabelle hash di PowerShell.
2. Registrazione (Logging) – Un sistema per scrivere eventi su un file.
3. Gestore MCP – La logica principale per l’elaborazione delle richieste MCP.
4. Esecutore PowerShell – Esecuzione isolata di script.
5. Interfaccia STDIO – Comunicazione tramite flussi standard.

Struttura del File

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # Funzione di conversione JSON
├── Write-Log                      # Funzione di logging
├── Test-MCPRequest               # Validazione delle richieste MCP
├── New-MCPResponse               # Creazione delle risposte MCP
├── Invoke-PowerShellScript       # Esecuzione di script PowerShell
├── Invoke-MCPMethod              # Elaborazione dei metodi MCP
├── Send-MCPResponse              # Invio delle risposte
├── Start-MCPServer               # Ciclo principale del server
└── Inizializzazione e avvio

Funzioni

ConvertFrom-JsonToHashtable

function ConvertFrom-JsonToHashtable {
    param([string]$Json)
}

Scopo: Questa funzione converte una stringa JSON in tabelle hash di PowerShell per la compatibilità con PowerShell 5.x.

Parametri:

• Json (string) – La stringa JSON da convertire.

Restituisce: Una tabella hash con i dati convertiti.

Caratteristiche:

• Conversione ricorsiva di oggetti nidificati.
• Gestione di array e collezioni.
• Compatibilità con 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"
    )
}

Scopo: Questa funzione scrive i log in un file, poiché stdout viene utilizzato per la comunicazione MCP.

Parametri:

• Message (string) – Il messaggio da scrivere nel log.
• Level (string) – Il livello di logging (INFO, WARNING, ERROR, DEBUG).

Caratteristiche:

• Scrive nel file $env:TEMP\mcp-powershell-server.log.
• Timestamp in formato yyyy-MM-dd HH:mm:ss.
• Codifica UTF-8.

Test-MCPRequest

function Test-MCPRequest {
    param(
        [Parameter(Mandatory=$true)]
        [hashtable]$Request
    )
}

Scopo: Questa funzione valida una richiesta MCP per la conformità al protocollo.

Parametri:

• Request (hashtable) – La richiesta MCP da validare.

Restituisce: Booleano – Il risultato della validazione.

Controlli:

• Presenza del campo jsonrpc con il valore “2.0”.
• Presenza del campo obbligatorio 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
    )
}```

**Scopo**: Questa funzione crea una risposta MCP standardizzata.

**Parametri**:
- `Id` (object) - L'identificatore della richiesta.
- `Result` (object) - Il risultato dell'operazione.
- `Error` (hashtable) - Informazioni sull'errore.

**Restituisce**: Una `Hashtable` con la risposta MCP.

### Invoke-PowerShellScript

powershell
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
)

}

**Scopo**: Questa funzione esegue uno script PowerShell in un processo isolato.

**Parametri**:
- `Script` (string) - Lo script PowerShell da eseguire.
- `Parameters` (hashtable) - Parametri per lo script.
- `TimeoutSeconds` (int) - Timeout di esecuzione (predefinito 300 sec).
- `WorkingDirectory` (string) - La directory di lavoro.

**Restituisce**: Una `Hashtable` con i risultati dell'esecuzione:
- `success` (bool) - Lo stato dell'esecuzione.
- `output` (string) - L'output del comando.
- `errors` (array) - Un array di errori.
- `warnings` (array) - Un array di avvisi.

**Caratteristiche**:
- Isolamento tramite un processo PowerShell separato.
- Supporto per il timeout.
- Raccolta di tutti i flussi di output (output, error, warning).
- Pulizia automatica delle risorse.

## Metodi MCP

### initialize

**Scopo**: Inizializza il server MCP e scambia informazioni sulle capacità.

**Risposta**:

json
{
“protocolVersion”: “2024-11-05”,
“capabilities”: {
“tools”: {
“listChanged”: true
}
},
“serverInfo”: {
“name”: “PowerShell Script Runner”,
“version”: “1.0.0”,
“description”: “Esegue script PowerShell tramite MCP”
}
}

### tools/list

**Scopo**: Ottiene l'elenco degli strumenti disponibili.

**Risposta**: Un array di strumenti con la descrizione dei loro schemi di parametri di input.

### tools/call

**Scopo**: Chiama uno strumento specifico con parametri.

**Parametri**:
- `name` (string) - Il nome dello strumento.
- `arguments` (object) - Argomenti per lo strumento.

## Strumenti

### run-script

**Scopo**: Esegue uno script PowerShell con i parametri specificati.

**Schema dei Parametri di Input**:

json
{
“type”: “object”,
“properties”: {
“script”: {
“type”: “string”,
“description”: “Script PowerShell da eseguire”
},
“parameters”: {
“type”: “object”,
“description”: “Parametri per lo script (opzionale)”,
“additionalProperties”: true
},
“workingDirectory”: {
“type”: “string”,
“description”: “Directory di lavoro per l’esecuzione (opzionale)”,
“default”: “”
},
“timeoutSeconds”: {
“type”: “integer”,
“description”: “Timeout di esecuzione in secondi (opzionale)”,
“default”: 300,
“minimum”: 1,
“maximum”: 3600
}
},
“required”: [“script”]
}

**Risposta**: Una struttura con i risultati dell'esecuzione, che include:
- Output del comando formattato.
- Errori (se presenti).
- Avvisi (se presenti).
- Metadati dell'esecuzione.

## Configurazione

### Codifica

powershell

Il server è configurato per funzionare con la codifica UTF-8 per la corretta gestione dei dati JSON.

### Logging

- **File di log**: `$env:TEMP\mcp-powershell-server.log`
- **Codifica**: UTF-8
- **Livelli**: INFO, WARNING, ERROR, DEBUG
- **Formato**: `[yyyy-MM-dd HH:mm:ss] [LEVEL] Messaggio`

### Sicurezza

- Isolamento degli script tramite processi PowerShell separati.
- Timeout per prevenire blocchi.
- Validazione di tutte le richieste in arrivo.
- Registrazione di tutte le operazioni.

## Utilizzo

### Avvio del Server

powershell
.\mcp-powershell-stdio.ps1

Il server si avvia in modalità STDIO e attende i comandi MCP tramite l'input standard.

### Esempi di Richieste MCP

#### Inizializzazione

json
{
“jsonrpc”: “2.0”,
“id”: 1,
“method”: “initialize”,
“params”: {
“protocolVersion”: “2024-11-05”,
“capabilities”: {},
“clientInfo”: {
“name”: “test-client”,
“version”: “1.0.0”
}
}
}

#### Elenco Strumenti

json
{
“jsonrpc”: “2.0”,
“id”: 2,
“method”: “tools/list”
}

#### Esecuzione Script

json
{
“jsonrpc”: “2.0”,
“id”: 3,
“method”: “tools/call”,
“params”: {
“name”: “run-script”,
“arguments”: {
“script”: “Get-Process | Select-Object -First 5 Name, CPU”,
“timeoutSeconds”: 60
}
}
}
“`

Gestione degli Errori

Codici di Errore MCP

• -32700: Errore di parsing JSON (Parse error)
• -32600: Richiesta MCP non valida (Invalid Request)
• -32601: Metodo o strumento non trovato (Method not found)
• -32602: Parametri non validi (Invalid params)
• -32603: Errore interno del server (Internal error)

Registrazione degli Errori

Tutti gli errori vengono registrati in un file con informazioni dettagliate:

• Timestamp
• Livello di errore
• Descrizione dettagliata
• Stack trace (se necessario)

Limitazioni

1. Timeout di esecuzione: Massimo 3600 secondi (1 ora).
2. Isolamento dei processi: Ogni script viene eseguito in un processo separato.
3. Codifica: Solo UTF-8.
4. Compatibilità: PowerShell 5.x e versioni successive.

Prestazioni

• Overhead minimo per la creazione di processi.
• Serializzazione JSON efficiente.
• Pulizia automatica delle risorse.
• Logging ottimizzato.

Scalabilità

Il server è progettato per gestire una richiesta alla volta in modalità sincrona. Per l’elaborazione parallela, è necessario eseguire più istanze del server.

---

Versione della documentazione: 1.0.0
Data di creazione: 15 settembre 2025