Documentación del Servidor MCP de PowerShell. STDIO Server. (mcp-powershell-server-stdio.py)

Descripción

El Servidor MCP de PowerShell es un servidor que implementa el Protocolo de Contexto de Modelo (MCP) para ejecutar scripts de PowerShell. El servidor opera en modo STDIO y proporciona herramientas para la ejecución segura de comandos de PowerShell a través de una interfaz estandarizada.

Arquitectura

Componentes Principales

1. Convertidor JSON – Una función para convertir JSON en tablas hash de PowerShell.
2. Registro (Logging) – Un sistema para escribir eventos en un archivo.
3. Manejador MCP – La lógica principal para procesar solicitudes MCP.
4. Ejecutor de PowerShell – Ejecución aislada de scripts.
5. Interfaz STDIO – Comunicación a través de flujos estándar.

Estructura del Archivo

mcp-powershell-stdio.ps1
├── ConvertFrom-JsonToHashtable    # Función de conversión de JSON
├── Write-Log                      # Función de registro
├── Test-MCPRequest               # Validación de solicitudes MCP
├── New-MCPResponse               # Creación de respuestas MCP
├── Invoke-PowerShellScript       # Ejecución de scripts de PowerShell
├── Invoke-MCPMethod              # Procesamiento de métodos MCP
├── Send-MCPResponse              # Envío de respuestas
├── Start-MCPServer               # Bucle principal del servidor
└── Inicialización y arranque```

## Funciones

### ConvertFrom-JsonToHashtable

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

**Propósito**: Esta función convierte una cadena JSON en tablas hash de PowerShell para compatibilidad con PowerShell 5.x.

**Parámetros**:
- `Json` (string) - La cadena JSON a convertir.

**Devuelve**: Una tabla hash con los datos convertidos.

**Características**:
- Conversión recursiva de objetos anidados.
- Manejo de arreglos y colecciones.
- Compatibilidad con PowerShell 5.x.

### Write-Log

powershell
function Write-Log {
param(
[Parameter(Mandatory=$true)]
[string]$Message,

    [Parameter(Mandatory=$false)]
    [ValidateSet("INFO", "WARNING", "ERROR", "DEBUG")]
    [string]$Level = "INFO"
)

}

**Propósito**: Esta función escribe registros en un archivo, ya que `stdout` se utiliza para la comunicación MCP.

**Parámetros**:
- `Message` (string) - El mensaje a escribir en el registro.
- `Level` (string) - El nivel de registro (INFO, WARNING, ERROR, DEBUG).

**Características**:
- Escribe en el archivo `$env:TEMP\mcp-powershell-server.log`.
- Marcas de tiempo en formato `yyyy-MM-dd HH:mm:ss`.
- Codificación UTF-8.

### Test-MCPRequest

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

**Propósito**: Esta función valida una solicitud MCP para el cumplimiento del protocolo.

**Parámetros**:
- `Request` (hashtable) - La solicitud MCP a validar.

**Devuelve**: Booleano - El resultado de la validación.

**Comprobaciones**:
- Presencia del campo `jsonrpc` con el valor "2.0".
- Presencia del campo obligatorio `method`.

### New-MCPResponse

powershell
function New-MCPResponse {
param(
[Parameter(Mandatory=$false)]
[object]$Id = $null,

    [Parameter(Mandatory=$false)]
    [object]$Result = $null,

    [Parameter(Mandatory=$false)]
    [hashtable]$Error = $null
)

}

**Propósito**: Esta función crea una respuesta MCP estandarizada.

**Parámetros**:
- `Id` (object) - El identificador de la solicitud.
- `Result` (object) - El resultado de la operación.
- `Error` (hashtable) - Información sobre el error.

**Devuelve**: Una `Hashtable` con la respuesta 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
)

}

**Propósito**: Esta función ejecuta un script de PowerShell en un proceso aislado.

**Parámetros**:
- `Script` (string) - El script de PowerShell a ejecutar.
- `Parameters` (hashtable) - Parámetros para el script.
- `TimeoutSeconds` (int) - Tiempo de espera de ejecución (por defecto 300 seg).
- `WorkingDirectory` (string) - El directorio de trabajo.

**Devuelve**: Una `Hashtable` con los resultados de la ejecución:
- `success` (bool) - El estado de la ejecución.
- `output` (string) - La salida del comando.
- `errors` (array) - Un arreglo de errores.
- `warnings` (array) - Un arreglo de advertencias.

**Características**:
- Aislamiento a través de un proceso de PowerShell separado.
- Soporte de tiempo de espera (timeout).
- Recopilación de todos los flujos de salida (output, error, warning).
- Liberación automática de recursos.

## Métodos MCP

### initialize

**Propósito**: Inicializa el servidor MCP e intercambia información sobre las capacidades.

**Respuesta**:

json
{
«protocolVersion»: «2024-11-05»,
«capabilities»: {
«tools»: {
«listChanged»: true
}
},
«serverInfo»: {
«name»: «PowerShell Script Runner»,
«version»: «1.0.0»,
«description»: «Ejecuta scripts de PowerShell a través de MCP»
}
}

### tools/list

**Propósito**: Obtiene la lista de herramientas disponibles.

**Respuesta**: Un arreglo de herramientas con descripciones de sus esquemas de parámetros de entrada.

### tools/call

**Propósito**: Llama a una herramienta específica con parámetros.

**Parámetros**:
- `name` (string) - El nombre de la herramienta.
- `arguments` (object) - Argumentos para la herramienta.

## Herramientas

### run-script

**Propósito**: Ejecuta un script de PowerShell con los parámetros especificados.

**Esquema de Parámetros de Entrada**:

json
{
«type»: «object»,
«properties»: {
«script»: {
«type»: «string»,
«description»: «Script de PowerShell a ejecutar»
},
«parameters»: {
«type»: «object»,
«description»: «Parámetros para el script (opcional)»,
«additionalProperties»: true
},
«workingDirectory»: {
«type»: «string»,
«description»: «Directorio de trabajo para la ejecución (opcional)»,
«default»: «»
},
«timeoutSeconds»: {
«type»: «integer»,
«description»: «Tiempo de espera de ejecución en segundos (opcional)»,
«default»: 300,
«minimum»: 1,
«maximum»: 3600
}
},
«required»: [«script»]
}

**Respuesta**: Una estructura con los resultados de la ejecución, que incluye:
- Salida del comando en formato de texto.
- Errores (si los hay).
- Advertencias (si las hay).
- Metadatos de la ejecución.

## Configuración

### Codificación

powershell

El servidor está configurado para trabajar con codificación UTF-8 para el manejo correcto de datos JSON.

### Registro (Logging)

- **Archivo de registro**: `$env:TEMP\mcp-powershell-server.log`
- **Codificación**: UTF-8
- **Niveles**: INFO, WARNING, ERROR, DEBUG
- **Formato**: `[yyyy-MM-dd HH:mm:ss] [LEVEL] Mensaje`

### Seguridad

- Aislamiento de scripts a través de procesos de PowerShell separados.
- Tiempos de espera para prevenir bloqueos.
- Validación de todas las solicitudes entrantes.
- Registro de todas las operaciones.

## Uso

### Inicio del Servidor

powershell
.\mcp-powershell-stdio.ps1

El servidor se inicia en modo STDIO y espera comandos MCP a través de la entrada estándar.

### Ejemplos de Solicitudes MCP

#### Inicialización

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

#### Lista de Herramientas```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Ejecución 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
    }
  }
}

Manejo de Errores

Códigos de Error MCP

• -32700: Error de análisis JSON (Parse error)
• -32600: Solicitud MCP no válida (Invalid Request)
• -32601: Método o herramienta no encontrada (Method not found)
• -32602: Parámetros no válidos (Invalid params)
• -32603: Error interno del servidor (Internal error)

Registro de Errores

Todos los errores se registran en un archivo con información detallada:

• Marca de tiempo
• Nivel de error
• Descripción detallada
• Stack trace (si es necesario)

Limitaciones

1. Tiempo de espera de ejecución: Máximo 3600 segundos (1 hora).
2. Aislamiento de procesos: Cada script se ejecuta en un proceso separado.
3. Codificación: Solo UTF-8.
4. Compatibilidad: PowerShell 5.x y superior.

Rendimiento

• Sobrecarga mínima en la creación de procesos.
• Serialización eficiente de JSON.
• Limpieza automática de recursos.
• Registro optimizado.

Escalabilidad

El servidor está diseñado para manejar una solicitud a la vez en modo síncrono. Para el procesamiento en paralelo, se deben ejecutar múltiples instancias del servidor.

---

Versión de la documentación: 1.0.0
Fecha de creación: 15 de septiembre de 2025