Documentation du Serveur MCP PowerShell. STDIO Server. (mcp-powershell-server-stdio.py)

Description

Le Serveur MCP PowerShell est un serveur qui implémente le Protocole de Contexte de Modèle (Model Context Protocol – MCP) pour exécuter des scripts PowerShell. Le serveur fonctionne en mode STDIO et fournit des outils pour l’exécution sécurisée de commandes PowerShell via une interface standardisée.

Architecture

Composants principaux

1. Convertisseur JSON – Une fonction pour convertir le JSON en tables de hachage PowerShell.
2. Journalisation (Logging) – Un système pour enregistrer les événements dans un fichier.
3. Gestionnaire MCP – La logique principale pour traiter les requêtes MCP.
4. Exécuteur PowerShell – Exécution isolée des scripts.
5. Interface STDIO – Communication via les flux standards.

Structure du fichier

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # Fonction de conversion JSON
├── Write-Log                      # Fonction de journalisation
├── Test-MCPRequest               # Validation des requêtes MCP
├── New-MCPResponse               # Création des réponses MCP
├── Invoke-PowerShellScript       # Exécution des scripts PowerShell
├── Invoke-MCPMethod              # Traitement des méthodes MCP
├── Send-MCPResponse              # Envoi des réponses
├── Start-MCPServer               # Boucle principale du serveur
└── Initialisation et démarrage

Fonctions

ConvertFrom-JsonToHashtable

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

Objectif : Cette fonction convertit une chaîne JSON en tables de hachage PowerShell pour la compatibilité avec PowerShell 5.x.

Paramètres :

• Json (string) – La chaîne JSON à convertir.

Retourne : Une table de hachage avec les données converties.

Caractéristiques :

• Conversion récursive des objets imbriqués.
• Gestion des tableaux et des collections.
• Compatibilité avec 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"
    )
}

Objectif : Cette fonction écrit les journaux (logs) dans un fichier, car stdout est utilisé pour la communication MCP.

Paramètres :

• Message (string) – Le message à écrire dans le journal.
• Level (string) – Le niveau de journalisation (INFO, WARNING, ERROR, DEBUG).

Caractéristiques :

• Écriture dans le fichier $env:TEMP\mcp-powershell-server.log.
• Horodatage au format yyyy-MM-dd HH:mm:ss.
• Encodage UTF-8.

Test-MCPRequest

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

Objectif : Cette fonction valide une requête MCP pour s’assurer de sa conformité avec le protocole.

Paramètres :

• Request (hashtable) – La requête MCP à valider.

Retourne : Booléen – le résultat de la validation.

Vérifications :

• Présence du champ jsonrpc avec la valeur « 2.0 ».
• Présence du champ obligatoire 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
    )
}

Objectif : Cette fonction crée une réponse MCP standardisée.

Paramètres :

• Id (object) – L’identifiant de la requête.
• Result (object) – Le résultat de l’opération.
• Error (hashtable) – Les informations sur l’erreur.

Retourne : Une Hashtable avec la réponse MCP.

Invoke-PowerShellScript

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

Objectif : Cette fonction exécute un script PowerShell dans un processus isolé.

Paramètres :

• Script (string) – Le script PowerShell à exécuter.
• Parameters (hashtable) – Les paramètres pour le script.
• TimeoutSeconds (int) – Délai d’attente pour l’exécution (par défaut 300 sec).
• WorkingDirectory (string) – Le répertoire de travail.

Retourne : Une Hashtable avec les résultats de l’exécution :

• success (bool) – Le statut de l’exécution.
• output (string) – La sortie de la commande.
• errors (array) – Un tableau d’erreurs.
• warnings (array) – Un tableau d’avertissements.

Caractéristiques :

• Isolation via un processus PowerShell séparé.
• Prise en charge du délai d’attente (timeout).
• Collecte de tous les flux de sortie (output, error, warning).
• Libération automatique des ressources.

Méthodes MCP

initialize

Objectif : Initialise le serveur MCP et échange des informations sur les capacités.

Réponse :

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "serverInfo": {
    "name": "PowerShell Script Runner",
    "version": "1.0.0",
    "description": "Exécute des scripts PowerShell via MCP"
  }
}

tools/list

Objectif : Obtient la liste des outils disponibles.

Réponse : Un tableau d’outils avec la description de leurs schémas de paramètres d’entrée.

tools/call

Objectif : Appelle un outil spécifique avec des paramètres.

Paramètres :

• name (string) – Le nom de l’outil.
• arguments (object) – Les arguments pour l’outil.

Outils

run-script

Objectif : Exécute un script PowerShell avec les paramètres spécifiés.

Schéma des paramètres d’entrée :

{
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "Script PowerShell à exécuter"
    },
    "parameters": {
      "type": "object",
      "description": "Paramètres pour le script (optionnel)",
      "additionalProperties": true
    },
    "workingDirectory": {
      "type": "string",
      "description": "Répertoire de travail pour l'exécution (optionnel)",
      "default": "<répertoire actuel>"
    },
    "timeoutSeconds": {
      "type": "integer",
      "description": "Délai d'attente d'exécution en secondes (optionnel)",
      "default": 300,
      "minimum": 1,
      "maximum": 3600
    }
  },
  "required": ["script"]
}

Réponse : Une structure avec les résultats de l’exécution, incluant :

• La sortie de la commande formatée.
• Les erreurs (s’il y en a).
• Les avertissements (s’il y en a).
• Les métadonnées de l’exécution.

Configuration

Encodage

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

Le serveur est configuré pour fonctionner avec l’encodage UTF-8 pour une gestion correcte des données JSON.

Journalisation (Logging)

• Fichier de log : $env:TEMP\mcp-powershell-server.log
• Encodage : UTF-8
• Niveaux : INFO, WARNING, ERROR, DEBUG
• Format : [yyyy-MM-dd HH:mm:ss] [LEVEL] Message

Sécurité

• Isolation des scripts via des processus PowerShell séparés.
• Délais d’attente pour éviter les blocages.
• Validation de toutes les requêtes entrantes.
• Journalisation de toutes les opérations.

Utilisation

Démarrage du serveur

.\mcp-powershell-stdio.ps1

Le serveur démarre en mode STDIO et attend les commandes MCP via l’entrée standard.

Exemples de requêtes MCP

Initialisation

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

Liste des outils

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

Exécution de script

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

Gestion des erreurs

Codes d’erreur MCP

• -32700 : Erreur d’analyse JSON (Parse error)
• -32600 : Requête MCP invalide (Invalid Request)
• -32601 : Méthode ou outil non trouvé (Method not found)
• -32602 : Paramètres invalides (Invalid params)
• -32603 : Erreur interne du serveur (Internal error)

Journalisation des erreurs

Toutes les erreurs sont journalisées dans un fichier avec des informations détaillées :

• Horodatage
• Niveau de l’erreur
• Description détaillée
• Trace de la pile (si nécessaire)

Limitations

1. Délai d’attente d’exécution : Maximum 3600 secondes (1 heure).
2. Isolation des processus : Chaque script s’exécute dans un processus séparé.
3. Encodage : UTF-8 uniquement.
4. Compatibilité : PowerShell 5.x et supérieur.

Performance

• Surcharge minimale pour la création de processus.
• Sérialisation JSON efficace.
• Nettoyage automatique des ressources.
• Journalisation optimisée.

Scalabilité

Le serveur est conçu pour traiter une requête à la fois en mode synchrone. Pour un traitement parallèle, il est nécessaire de lancer plusieurs instances du serveur.

---

Version de la documentation : 1.0.0
Date de création : 15 septembre 2025