Documentación para Desarrolladores: MCP PowerShell HTTP Server. (mcp-powershell-server-http.py)

1. Descripción General

mcp-powershell-http.ps1 es un servidor HTTP autónomo escrito en PowerShell, diseñado para ejecutar scripts de PowerShell de forma remota y segura. Funciona como un «puente» entre un cliente externo (por ejemplo, un asistente de IA) y el entorno local de PowerShell, utilizando el protocolo JSON-RPC 2.0 para la comunicación.

Características Principales:

• Seguridad: Cada script se ejecuta en una instancia de PowerShell (runspace) completamente aislada, lo que previene cualquier impacto en el entorno principal del servidor.
• Configuración Flexible: Los parámetros del servidor (puerto, host, tiempos de espera) se pueden configurar mediante argumentos de línea de comandos y un archivo JSON externo.
• Estabilidad: Un manejo de errores completo en todos los niveles (HTTP, JSON, ejecución de scripts) asegura el funcionamiento fiable del servidor.
• Protocolo MCP: Implementa el protocolo estándar MCP para la interacción, incluyendo los métodos initialize, tools/list y tools/call.
• Control de Recursos: Tiempos de espera integrados y límites en el tamaño de la salida evitan el abuso de recursos.

2. Ejecución y Configuración

Requisitos:

• PowerShell 7.0 o superior.

Parámetros de Línea de Comandos:

Parámetro	Tipo	Descripción	Por defecto
-Port	[int]	El puerto en el que el servidor escuchará las peticiones HTTP.	8090
-ServerHost	[string]	El host (dirección IP o nombre de dominio) al que se vinculará el servidor.	localhost
-ConfigFile	[string]	La ruta a un archivo de configuración en formato JSON. Los parámetros de este archivo sobrescriben los valores por defecto y los argumentos de la línea de comandos.	$null

Ejemplo de Uso:

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

Archivo de Configuración (settings.json):

El servidor puede cargar su configuración desde un archivo JSON. Este es el enfoque recomendado para entornos de producción.

Ejemplo de settings.json del repositorio:

{
  "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. Arquitectura y Funciones

El script está dividido lógicamente en varias regiones (#region) para simplificar la navegación.

Región: Utility Functions (Funciones de Utilidad)

1. Write-Log
   • Propósito: Muestra mensajes formateados y coloreados en la consola con una marca de tiempo. Es la función principal para el registro de eventos (logging).
   • Parámetros:
     • $Message [string] (obligatorio): El texto del mensaje.
     • $Level [string] (opcional): El nivel de registro (DEBUG, INFO, WARNING, ERROR). Afecta al color de la salida.
2. Test-MCPRequest
   • Propósito: Valida si la solicitud entrante cumple con los requisitos básicos del protocolo JSON-RPC 2.0 (presencia de los campos jsonrpc: "2.0" y method).
   • Parámetros:
     • $Request [hashtable] (obligatorio): La solicitud, deserializada desde JSON.
   • Devuelve: $true si la solicitud es válida, de lo contrario $false.
3. New-MCPResponse
   • Propósito: Una función de fábrica para crear objetos de respuesta JSON-RPC estandarizados.
   • Parámetros:
     • $Id [object]: El identificador de la solicitud.
     • $Result [object]: El objeto que contiene un resultado exitoso.
     • $Error [hashtable]: El objeto que contiene información del error.
   • Devuelve: Una [hashtable] con la estructura completa de la respuesta.
4. Test-ScriptSafety
   • Propósito: Comprueba si el script contiene comandos potencialmente peligrosos listados en la variable global $script:RestrictedCommands.
   • Nota: En la versión proporcionada, esta función está deshabilitada por defecto (return $true). Para uso en producción, debería ser habilitada y configurada.
   • Parámetros:
     • $Script [string] (obligatorio): El texto del script de PowerShell que se va a comprobar.
   • Devuelve: $true si el script es seguro, de lo contrario $false.

Región: Core Logic (Lógica Principal)

1. Invoke-PowerShellScript
   • Propósito: La función central responsable de ejecutar de forma segura un script de PowerShell.
   • Proceso:
     1. Crea una instancia de PowerShell nueva y completamente aislada ([powershell]::Create()).
     2. (Opcional) Establece el directorio de trabajo dentro de esta instancia.
     3. Añade el texto del script y sus parámetros a la instancia.
     4. Ejecuta el script de forma asíncrona con un tiempo de espera.
     5. Recopila los flujos de salida (Output), error (Error) y advertencia (Warning).
     6. Limita el tamaño de la salida (por defecto, 10,000 caracteres) para prevenir grandes transferencias de datos.
     7. Libera los recursos (Dispose()) al finalizar.
   • Parámetros:
     • $Script [string] (obligatorio): El código a ejecutar.
     • $Parameters [hashtable]: Parámetros para pasar al script.
     • $TimeoutSeconds [int]: Tiempo máximo de ejecución en segundos.
     • $WorkingDirectory [string]: El directorio de trabajo para el script.
   • Devuelve: Una [hashtable] con los resultados: success (bool), output (string), errors (array), warnings (array), executionTime (double).

Región: MCP Protocol Methods (Métodos del Protocolo MCP)

1. Invoke-MCPMethod
   • Propósito: Un despachador que maneja las llamadas a los métodos del protocolo MCP.
   • Proceso: Utiliza una estructura switch sobre el nombre del método ($Method) para invocar la lógica apropiada.
   • Métodos Soportados:
     • "initialize": Devuelve información sobre el servidor.
     • "tools/list": Devuelve una lista de las herramientas disponibles (en este caso, solo "run-script").
     • "tools/call": Maneja la invocación de una herramienta. Extrae los parámetros y llama a Invoke-PowerShellScript para la ejecución.
   • Parámetros:
     • $Method [string]: El nombre del método a llamar.
     • $Params [hashtable]: Los parámetros del método.
     • $Id [object]: El identificador de la solicitud.
   • Devuelve: Una [hashtable] que representa la respuesta MCP completa, lista para ser enviada.

Región: HTTP Server (Servidor HTTP)

1. Invoke-RequestHandler
   • Propósito: Maneja el ciclo de vida completo de una única petición HTTP.
   • Proceso:
     1. Configura las cabeceras CORS.
     2. Maneja las peticiones OPTIONS (CORS preflight).
     3. Verifica que el método de la petición sea POST.
     4. Lee y valida el cuerpo de la petición.
     5. Analiza (parsea) el JSON y lo convierte en una tabla hash.
     6. Llama a Test-MCPRequest para la validación.
     7. Pasa la solicitud a Invoke-MCPMethod para su procesamiento.
     8. Serializa la respuesta de nuevo a JSON y la envía al cliente.
     9. Maneja todos los posibles errores durante el proceso.
   • Parámetros:
     • $Context [System.Net.HttpListenerContext]: El contexto de la petición HTTP del listener de .NET.
2. Start-MCPServer
   • Propósito: La función principal que inicializa e inicia el listener HTTP.
   • Proceso:
     1. Crea y configura un objeto System.Net.HttpListener.
     2. Inicia el listener con listener.Start().
     3. Entra en un bucle infinito while ($listener.IsListening) para esperar conexiones entrantes.
     4. Para cada conexión, llama a Invoke-RequestHandler.
     5. Detiene correctamente el servidor cuando el proceso termina.

4. Flujo de Ejecución de una Solicitud

1. Un cliente envía una petición POST con Content-Type: application/json a la URL del servidor.
2. Start-MCPServer acepta la petición y la pasa a Invoke-RequestHandler.
3. Invoke-RequestHandler valida las cabeceras HTTP, el método y analiza el cuerpo JSON.
4. La solicitud MCP válida se pasa a Invoke-MCPMethod.
5. Invoke-MCPMethod determina que se invocó el método tools/call con la herramienta run-script.
6. Los parámetros (script, tiempo de espera, etc.) se pasan a Invoke-PowerShellScript.
7. Invoke-PowerShellScript ejecuta el script en un entorno aislado.
8. El resultado de la ejecución se devuelve a través de la cadena de llamadas, se formatea en una respuesta JSON-RPC estándar y es enviado de vuelta al cliente por Invoke-RequestHandler.

5. Ampliación de Funcionalidad

Para añadir una nueva «herramienta» (además de run-script), un desarrollador necesita:

1. Añadir una descripción de la nueva herramienta en el bloque "tools/list" de la función Invoke-MCPMethod.
2. Añadir una nueva rama case para esta herramienta en la estructura switch ($toolName) dentro del bloque "tools/call" de Invoke-MCPMethod.
3. Implementar la lógica para la nueva herramienta.