Windows CLI

Interactúa con interfaces de línea de comandos de Windows como PowerShell, CMD, Git Bash y WSL.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP de CLI de Windows (Mejorado)

NPM Downloads NPM Version

Servidor MCP para interacciones seguras con la línea de comandos en sistemas Windows, que permite acceso controlado a shells de PowerShell, CMD, Git Bash y Bash. Permite que clientes MCP (como Claude Desktop) realicen operaciones en su sistema, similar a Open Interpreter.

Esta versión mejorada incluye gestión avanzada de configuración, funciones de seguridad mejoradas y capacidades integrales de prueba.

[!IMPORTANTE] Este servidor MCP proporciona acceso directo a la interfaz de línea de comandos de su sistema. Cuando está habilitado, otorga acceso a sus archivos, variables de entorno y capacidades de ejecución de comandos.

  • Revise y restrinja las rutas permitidas
  • Habilite restricciones de directorio
  • Configure bloqueos de comandos
  • Considere las implicaciones de seguridad

Consulte Configuración para más detalles.

Características

  • Soporte Multi-Shell: Ejecute comandos en PowerShell, Símbolo del sistema (CMD), Git Bash, Bash y WSL
  • Arquitectura Modular: Construya solo los shells que necesite para tamaños de paquete más pequeños (reducción del 30-65%)
  • Configuración Basada en Herencia: Valores predeterminados globales con anulaciones específicas de shell
  • Validación Específica de Shell: Cada shell puede tener sus propios ajustes de seguridad y formatos de ruta
  • Gestión Flexible de Rutas: Diferentes shells admiten diferentes formatos de ruta (Windows/Unix/Mixto)
  • Exposición de Recursos: Vea la configuración y los ajustes de seguridad como recursos MCP
  • Estado Explícito del Directorio de Trabajo: El servidor mantiene un directorio de trabajo activo utilizado cuando execute_command omite workingDir. Si el directorio de inicio no está permitido, este estado comienza sin establecer y debe configurarse mediante set_current_directory.
  • Directorio Inicial Opcional: Configure initialDir para iniciar el servidor en un directorio específico.
  • Controles de Seguridad:
    • Bloqueo de comandos (rutas completas, variaciones de mayúsculas)
    • Validación del directorio de trabajo
    • Límites de longitud máxima de comandos
    • Validación inteligente de argumentos
    • Ajustes de tiempo de espera específicos de shell
  • Configurable:
    • Sistema de configuración basado en herencia
    • Anulaciones de seguridad específicas de shell
    • Descripciones dinámicas de herramientas basadas en shells habilitados

Consulte la sección API para más detalles sobre las herramientas y recursos que el servidor proporciona a los clientes MCP.

Nota: El servidor solo permitirá operaciones dentro de los directorios configurados, con los comandos permitidos.

Extensión de VS Code

Una extensión complementaria de VS Code en vscode-extension/ simplifica la configuración de este servidor. Expone cada opción de CLI como ajustes ordinarios de VS Code (con ámbito por Usuario y por Espacio de trabajo) y registra el servidor MCP con VS Code automáticamente mediante la API del Proveedor de Definición de Servidor MCP — sin necesidad de editar manualmente mcp.json. También puede generar un config.json o un .vscode/mcp.json bajo demanda. Consulte vscode-extension/README.md.

Arquitectura Modular de Shell

WCLI0 ahora admite una arquitectura modular que le permite construir versiones especializadas que contienen solo los shells que necesita. Esto resulta en tamaños de paquete significativamente más pequeños y tiempos de inicio más rápidos.

Opciones de Compilación

Elija entre varias compilaciones preconfiguradas:

# Full build (all shells) - default
npm run build

# Windows-only shells (PowerShell, CMD, Git Bash)
npm run build:windows

# Git Bash only (smallest Windows build)
npm run build:gitbash

# CMD only
npm run build:cmd

# Unix/Linux only (Bash)
npm run build:unix

# Custom combination
INCLUDED_SHELLS=gitbash,powershell npm run build:custom

Comparación de Tamaños de Paquete

CompilaciónReducción de TamañoShells Incluidos
CompletaLínea baseLos 5 shells
Windows~40% más pequeñoPowerShell, CMD, Git Bash
Solo Git Bash~60% más pequeñoGit Bash
Solo CMD~65% más pequeñoCMD
Unix~60% más pequeñoBash

Documentación

Para información detallada sobre la arquitectura modular:

Inicio Rápido con Compilaciones Especializadas

Si solo necesita Git Bash:

# Build
npm run build:gitbash

# Use in Claude Desktop config
{
  "mcpServers": {
    "windows-cli": {
      "command": "node",
      "args": ["/path/to/wcli0/dist/index.gitbash-only.js"]
    }
  }
}

Soporte para macOS y Unix/Linux

Aunque wcli0 está diseñado principalmente para Windows, también admite sistemas basados en Unix (macOS, Linux) con integración de shell Bash.

Compilación para Sistemas Unix

Para compilar wcli0 para sistemas basados en Unix (macOS, Linux):

# Unix-only build (Bash shell)
npm run build:unix

# The output will be: dist/index.unix-only.js

Inicio del Servidor en macOS

Inicie el servidor usando npx:

# Start with default settings
npx wcli0 --shell bash

# Start with a configuration file
npx wcli0 --config ./config.mac.json

# Start with specific allowed directories
npx wcli0 --shell bash \
  --allowedDir "/Users/$(whoami)" \
  --allowedDir "/tmp"

Ejemplo de Configuración para macOS

Aquí hay una configuración de muestra para macOS:

{
  "global": {
    "security": {
      "commandTimeout": 30,
      "enableInjectionProtection": true,
      "restrictWorkingDirectory": true
    },
    "restrictions": {
      "blockedCommands": ["rm -rf /", "dd", "mkfs"],
      "blockedArguments": ["--force", "-rf"],
      "blockedOperators": ["&&", "||", ";", "|"]
    },
    "paths": {
      "allowedPaths": ["/Users/$(whoami)", "/tmp"],
      "initialDir": "/Users/$(whoami)"
    }
  },
  "shells": {
    "bash_auto": {
      "type": "bash_auto",
      "enabled": true
    }
  }
}

Uso con Claude Desktop en macOS

Configure Claude Desktop para usar wcli0 en macOS:

{
  "mcpServers": {
    "macos-cli": {
      "command": "npx",
      "args": [
        "-y",
        "wcli0",
        "--config",
        "/path/to/config.mac.json"
      ]
    }
  }
}

Notas Importantes para Sistemas Unix

  • Formatos de Ruta: Los sistemas Unix usan barras diagonales (/) y no admiten letras de unidad de Windows
  • Tipo de Shell: Use tipos de shell bash o bash_auto en sistemas Unix
  • Directorio de Inicio: Use $(whoami) o su nombre de usuario real en las rutas
  • Comandos de Seguridad: Algunos comandos bloqueados en la configuración predeterminada son específicos de Windows (por ejemplo, regedit, format)

Opciones de CLI para macOS

Cuando se ejecuta en sistemas Unix, use estas opciones de CLI:

OpciónTipoDescripción
--shellcadenaShell a usar (use bash o bash_auto en Unix)
--allowedDircadenaAgregar un directorio permitido (se puede usar múltiples veces)
--configcadenaRuta al archivo de configuración
--initialDircadenaDirectorio de trabajo inicial
--allowAllDirsindicadorDeshabilitar restricciones de directorio
--unsafeindicadorDeshabilitar todas las verificaciones de seguridad (no recomendado)
--yoloindicadorDeshabilitar seguridad excepto restricciones de directorio

Gestión de Registros

wcli0 almacena automáticamente los registros de ejecución de comandos y proporciona recursos MCP para consultar la salida histórica con capacidades avanzadas de filtrado.

Truncamiento de Salida

Por defecto, las respuestas de comandos muestran solo las últimas 20 líneas para evitar abrumar con salidas largas. La salida completa siempre se almacena y es accesible mediante:

  • Almacenamiento basado en archivos: Cuando logDirectory está configurado, los registros se guardan en archivos para almacenamiento persistente
  • Almacenamiento en memoria: Comportamiento predeterminado usando recursos de registro MCP (por ejemplo, cli://logs/commands/{id})
  • La herramienta get_command_output (alternativa para hosts que no pueden leer recursos)

Configure los ajustes de truncamiento:

{
  "global": {
    "logging": {
      "maxOutputLines": 20,
      "enableTruncation": true
    }
  }
}

Almacenamiento de Registros Basado en Archivos

Para registro persistente, configure un directorio de registros:

{
  "global": {
    "logging": {
      "logDirectory": "./logs",
      "exposeFullPath": false
    }
  }
}

O mediante CLI:

npx wcli0 --shell gitbash --logDirectory ./logs

Cuando el registro basado en archivos está habilitado:

  • Los mensajes de truncamiento muestran la ruta del archivo directamente (salida más simple)
  • Los registros persisten entre reinicios del servidor
  • No se aplican límites de almacenamiento en memoria
  • Iniciar el servidor con --debug habilita automáticamente el registro basado en archivos en el directorio temporal de su sistema operativo (<temp>/wcli0-debug-logs) cuando no se establece logDirectory, por lo que cada comando y su salida se persisten durante las sesiones de depuración.

Nota de Seguridad: Los archivos de registro pueden contener salida sensible de comandos. Asegúrese de que el directorio de registros tenga permisos apropiados.

Recursos de Registro

Acceda a la salida almacenada de comandos mediante recursos MCP (modo en memoria):

  • cli://logs/list - Listar todos los registros de ejecución de comandos almacenados
  • cli://logs/recent?n=10 - Obtener los N registros más recientes
  • cli://logs/commands/{id} - Acceder a la salida completa de un comando específico
  • cli://logs/commands/{id}/range?start=1&end=100 - Consultar rangos de líneas específicos
  • cli://logs/commands/{id}/search?q=error&context=3 - Buscar registros con contexto

Consulte Documentación de API para especificaciones detalladas de recursos y parámetros de consulta.

Ejemplo de Configuración

{
  "global": {
    "logging": {
      "maxOutputLines": 20,
      "enableTruncation": true,
      "maxStoredLogs": 50,
      "maxLogSize": 1048576,
      "enableLogResources": true,
      "logRetentionMinutes": 1440,
      "logDirectory": "./logs"
    }
  }
}

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": ["-y", "wcli0"]
    }
  }
}

Para usar con un archivo de configuración específico, agregue el indicador --config:

{
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": [
        "-y",
        "wcli0",
        "--config",
        "path/to/your/config.json"
      ]
    }
  }
}

Configuración

Para comenzar con la configuración:

  1. Use una configuración de muestra:

    • Copie config.examples/config.sample.json para configuración básica
    • Copie config.examples/config.development.json para entornos de desarrollo
    • Copie config.examples/config.secure.json para entornos de alta seguridad
    • Copie config.examples/emptyRestrictions.json para eliminar todas las restricciones predeterminadas

  2. Cree su propia configuración:

    # Copy and customize a sample
cp config.examples/config.sample.json my-config.json

# Or generate a default config
npx wcli0 --init-config ./my-config.json

    El servidor también acepta un indicador --initialDir para anular el directorio de trabajo inicial definido en su archivo de configuración:

    npx wcli0 --config ./my-config.json --initialDir /path/to/start

    Puede anular los límites globales de comandos directamente desde la CLI:

    npx wcli0 --config ./my-config.json \
  --maxCommandLength 5000 --commandTimeout 60

    Puede configurar el truncamiento de salida y el registro mediante CLI:

    npx wcli0 --shell gitbash \
  --maxOutputLines 50 \
  --enableTruncation \
  --enableLogResources \
  --maxReturnLines 1000 \
  --logDirectory ./logs
    OpciónTipoPredeterminadoDescripción
    --maxOutputLinesnúmero20Líneas máximas de salida antes del truncamiento
    --enableTruncationbooleanotrueHabilitar truncamiento de salida
    --enableLogResourcesbooleanotrueHabilitar recursos de registro para get_command_output
    --maxReturnLinesnúmero500Líneas máximas devueltas por get_command_output
    --logDirectorycadena-Directorio para almacenamiento de registros basado en archivos (en lugar de en memoria)

    Cuando --logDirectory está configurado, los registros de salida de comandos se guardan en archivos en lugar de almacenamiento en memoria. Los mensajes de truncamiento mostrarán la ruta del archivo para facilitar el acceso a la salida completa.

    Nota de Seguridad: Los archivos de registro pueden contener datos sensibles de la salida de comandos. Asegúrese de que el directorio de registros tenga permisos apropiados y considere implementar rotación de registros.

    Puede anular las restricciones bloqueadas directamente desde la CLI. Pase la opción con una cadena vacía para borrar los valores predeterminados:

    npx wcli0 --blockedCommand "" --blockedArgument "" --blockedOperator ""

    Proporcione el indicador múltiples veces para especificar valores:

    npx wcli0 --blockedCommand rm --blockedCommand del

    También puede iniciar el servidor con un shell específico y directorios permitidos sin un archivo de configuración:

    npx wcli0 --shell powershell \
  --allowedDir C:\safe --allowedDir D:\projects

    Para shells WSL, puede especificar una ubicación de montaje personalizada:

npx wcli0 --shell wsl \
  --wslMountPoint /windows/

Para deshabilitar completamente las restricciones de directorio cuando no hay rutas permitidas configuradas, inicie el servidor con:

npx wcli0 --allowAllDirs

Cuando se inicia de esta manera, restrictWorkingDirectory se fuerza a activado y enableInjectionProtection se deshabilita para garantizar que las rutas permitidas se apliquen sin verificaciones de inyección de shell. Si necesitas desactivar las comprobaciones de seguridad que bloquean la ejecución de comandos para experimentar, puedes iniciar el servidor en modos unsafe o YOLO (no recomendados para producción):

# YOLO disables all safety checks except allowed working directories
npx wcli0 --yolo

# Fully unsafe removes all safety checks, including directory limits
npx wcli0 --unsafe

Ambos modos limpian los comandos/argumentos/operadores bloqueados y desactivan la protección contra inyección. El modo YOLO mantiene activas las restricciones del directorio de trabajo, mientras que el modo totalmente inseguro también desactiva esas restricciones. Estas dos opciones son mutuamente excluyentes; usar ambas a la vez fallará.

Puedes iniciar el servidor con un transporte basado en HTTP en lugar del transporte stdio predeterminado, para que clientes MCP remotos y basados en web puedan conectarse por HTTP. Hay dos transportes HTTP disponibles:

  • http -- el transporte moderno Streamable HTTP (revisión del protocolo MCP 2025-03-26), que sirve un único endpoint /mcp. Es el que usan por defecto los clientes MCP actuales y es el transporte HTTP recomendado.
  • sse -- el transporte heredado HTTP+SSE (revisión del protocolo MCP 2024-11-05), que usa dos endpoints (GET /sse, POST /messages). Está obsoleto según la especificación MCP en favor de Streamable HTTP y se mantiene solo por compatibilidad con clientes antiguos.

Los modos son mutuamente excluyentes (se seleccionan mediante --transport) y usan ajustes de enlace separados (--http-* para http, --sse-* para sse).

# Streamable HTTP on the default host/port (127.0.0.1:9444), serving /mcp
npx wcli0 --transport http

# Custom port, still bound to localhost
npx wcli0 --transport http --http-host 127.0.0.1 --http-port 3000

# Legacy HTTP+SSE transport
npx wcli0 --transport sse --sse-host 127.0.0.1 --sse-port 3000
OpciónTipoPredeterminadoDescripción
--transportstringstdioProtocolo de transporte: stdio, http (Streamable HTTP) o sse (HTTP+SSE heredado)
--http-hoststring127.0.0.1Dirección del host para el transporte Streamable HTTP (modo http)
--http-portnumber9444Puerto para el transporte Streamable HTTP (modo http)
--http-allowed-originsstring(ninguno)Orígenes de navegador permitidos para el modo http, separados por comas, además de los hosts de bucle local y el host de enlace (p. ej. https://app.example.com,192.168.1.10). Solo se compara el componente del host. Requerido para clientes de navegador en un enlace comodín (0.0.0.0).
--sse-hoststring127.0.0.1Dirección del host para el transporte SSE heredado (modo sse)
--sse-portnumber9444Puerto para el transporte SSE heredado (modo sse)
--sse-allowed-originsstring(ninguno)Orígenes de navegador permitidos para el modo sse, separados por comas, además de los hosts de bucle local y el host de enlace. Solo se compara el componente del host. Requerido para clientes de navegador en un enlace comodín (0.0.0.0).

Cuando el modo http está activo, los clientes usan un único endpoint /mcp:

  • POST /mcp transporta mensajes JSON-RPC de cliente a servidor. Una solicitud initialize sin id de sesión inicia una nueva sesión; el servidor devuelve el id asignado en el encabezado de respuesta Mcp-Session-Id, y el cliente debe enviar ese encabezado en cada solicitud posterior.
  • GET /mcp abre el flujo SSE opcional de servidor a cliente para una sesión existente.
  • DELETE /mcp termina una sesión existente.

Las sesiones tienen estado y están aisladas: cada sesión tiene su propio directorio de trabajo activo, por lo que el set_current_directory de un cliente no puede afectar a otro. Las solicitudes que llevan un Mcp-Session-Id desconocido o terminado se rechazan con 404 Not Found. El servidor registra la dirección y el puerto de enlace al iniciar (con --debug).

Cuando el modo sse está activo, los clientes se conectan mediante GET /sse para abrir un flujo SSE y envían mensajes a través de POST /messages?sessionId=<id>.

Configurar Streamable HTTP completamente con parámetros de CLI (sin archivo de configuración). Cada ajuste de transporte y operativo se puede proporcionar como parámetro de entrada, de modo que el servidor pueda ejecutarse como servidor Streamable HTTP sin ningún archivo de configuración:

npx wcli0 \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 9444 \
  --http-allowed-origins "https://app.example.com,192.168.1.10" \
  --shell gitbash \
  --allowedDir "D:/work/project" \
  --commandTimeout 60 \
  --debug

Los parámetros de CLI también tienen prioridad sobre un archivo de configuración, por lo que las mismas opciones --http-* anulan los campos transport correspondientes cuando también se pasa un archivo --config (consulta la sección de configuración de transporte).

Ambos transportes HTTP validan el encabezado de solicitud Origin para mitigar ataques de rebinding de DNS: las solicitudes cuyo Origin no es un host de bucle local, el host de enlace configurado o uno de los orígenes permitidos configurados (--http-allowed-origins / --sse-allowed-origins) se rechazan con 403 Forbidden, mientras que los clientes que no son de navegador y no envían Origin se permiten. Los orígenes de navegador permitidos reciben encabezados CORS, y las solicitudes de verificación previa OPTIONS se responden con 204.

Seguridad: Ninguno de los transportes HTTP tiene autenticación integrada, y ambos exponen herramientas de ejecución de comandos. Mantén el servidor enlazado a 127.0.0.1 (el valor predeterminado) para uso local. Enlazar a 0.0.0.0 o a cualquier dirección que no sea de bucle local expone esas herramientas a cada host que pueda alcanzar el puerto; hazlo solo detrás de un proxy inverso autenticado o un control de acceso equivalente. La validación de origen por sí sola no autentica a los clientes que no son de navegador.

Enlaces comodín y orígenes de navegador: Al enlazar a una dirección comodín (0.0.0.0 / ::), el host de enlace no es un origen utilizable para comparar, por lo que los clientes de navegador que llegan al servidor a través de su dirección LAN real (o un proxy inverso cuyo nombre de host público difiere del host de enlace) se rechazan a menos que su origen esté listado en --http-allowed-origins / --sse-allowed-origins (o en los arreglos de configuración transport.httpAllowedOrigins / transport.sseAllowedOrigins). Los clientes que no son de navegador no se ven afectados, ya que no envían Origin.

  1. Actualiza tu configuración de Claude Desktop para usar tu archivo de configuración:

    {
  "mcpServers": {
    "windows-cli": {
      "command": "npx",
      "args": [
        "-y",
        "wcli0",
        "--config",
        "./my-config.json"
      ]
    }
  }
}

Después de configurar, puedes:

  • Ejecutar comandos directamente usando las herramientas disponibles
  • Ver la configuración del servidor y los ajustes de seguridad en la sección Recursos
  • Acceder a configuraciones y capacidades específicas del shell

Configuración

El servidor usa un sistema de configuración basado en herencia donde los valores predeterminados globales pueden ser anulados por ajustes específicos del shell.

Estructura de Configuración

{
  "global": {
    "security": {
      "maxCommandLength": 2000,
      "commandTimeout": 30,
      "enableInjectionProtection": true,
      "restrictWorkingDirectory": true
    },
    "restrictions": {
      "blockedCommands": ["format", "shutdown"],
      "blockedArguments": ["--exec", "-e"],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "paths": {
      "allowedPaths": ["/home/user", "/tmp"],
      "initialDir": "/home/user"
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      },
      "overrides": {
        "security": {
          "commandTimeout": 45
        },
        "restrictions": {
          "blockedCommands": ["Remove-Item", "Format-Volume"]
        }
      }
    },
    "wsl": {
      "type": "wsl",
      "enabled": true,
      "executable": {
        "command": "wsl.exe",
        "args": ["-e"]
      },
      "wslConfig": {
        "mountPoint": "/mnt/",
        "inheritGlobalPaths": true
      }
    }
  }
}

Ubicaciones de Configuración

El servidor busca archivos de configuración en el siguiente orden:

  1. Ruta especificada mediante el argumento de línea de comandos --config
  2. win-cli-mcp.config.json en el directorio de trabajo actual
  3. ~/.win-cli-mcp/config.json en el directorio personal del usuario

Si no se encuentra ningún archivo de configuración, el servidor usará una configuración predeterminada (restringida).

Configuración Predeterminada

Nota: La configuración predeterminada está diseñada para ser restrictiva y segura. Encuentra más detalles sobre cada ajuste en la sección Ajustes de Configuración.

Para una referencia completa de todos los valores predeterminados, consulta docs/defaults.md.

{
  "global": {
    "security": {
      "maxCommandLength": 2000,
      "commandTimeout": 30,
      "enableInjectionProtection": true,
      "restrictWorkingDirectory": true
    },
    "restrictions": {
      "blockedCommands": [
        "rm", "del", "rmdir", "format", "shutdown", "restart",
        "reg", "regedit", "net", "netsh", "takeown", "icacls"
      ],
      "blockedArguments": [
        "--exec", "-e", "/c", "-enc", "-encodedcommand",
        "-command", "--interactive", "-i", "--login", "--system"
      ],
      "blockedOperators": ["&", "|", ";", "`"]
    },
    "paths": {
      "initialDir": null
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      }
    },
    "cmd": {
      "type": "cmd",
      "enabled": true,
      "executable": {
        "command": "cmd.exe",
        "args": ["/c"]
      }
    },
    "gitbash": {
      "type": "gitbash",
      "enabled": true,
      "executable": {
        "command": "C:\\Program Files\\Git\\bin\\bash.exe",
        "args": ["-c"]
      }
    }
  }
}

Ajustes de Configuración

El archivo de configuración usa un sistema de herencia con dos secciones principales: global y shells.

Ajustes Globales

Los ajustes globales proporcionan valores predeterminados que se aplican a todos los shells a menos que se anulen.

Ajustes de Seguridad
{
  "global": {
    "security": {
      // Maximum allowed length for any command
      "maxCommandLength": 2000,

      // Command execution timeout in seconds
      "commandTimeout": 30,

      // Enable protection against command injection
      "enableInjectionProtection": true,

      // Restrict commands to allowed working directories
      "restrictWorkingDirectory": true
    }
  }
}
Ajustes de Restricción
{
  "global": {
    "restrictions": {
      // Commands to block - blocks both direct use and full paths
      "blockedCommands": ["rm", "format", "shutdown"],

      // Arguments to block across all commands
      "blockedArguments": ["--exec", "-e", "/c"],

      // Operators to block in commands
      "blockedOperators": ["&", "|", ";", "`"]
    }
  }
}
Ajustes de Ruta
{
  "global": {
    "paths": {
      // Directories where commands can be executed
      "allowedPaths": ["/home/user", "/tmp", "C:\\Users\\username"],

      // Initial working directory (null = use launch directory)
      "initialDir": "/home/user",

      // Whether to restrict working directories
      "restrictWorkingDirectory": true
    }
  }
}

Si el arreglo allowedPaths se omite en tu archivo de configuración, no se permiten automáticamente directorios predeterminados. Cuando restrictWorkingDirectory está habilitado, solo el initialDir (si se especifica) se agregará a la lista de rutas permitidas. Usa la opción --allowAllDirs al iniciar el servidor para desactivar automáticamente restrictWorkingDirectory si no se establecen rutas permitidas o initialDir.

Configuración del Shell

Cada shell se puede configurar individualmente y puede anular los ajustes globales. Cada entrada de shell debe incluir un campo type que indique el shell. Los valores válidos son powershell, cmd, gitbash, bash y wsl.

Configuración Básica del Shell
{
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      }
    }
  }
}
Anulaciones Específicas del Shell
{
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      },
      "overrides": {
        "security": {
          "commandTimeout": 45,
          "maxCommandLength": 3000
        },
        "restrictions": {
          "blockedCommands": ["Remove-Item", "Format-Volume"],
          "blockedOperators": ["|", "&"]
        }
      }
    }
  }
}
Configuración de WSL

Los shells WSL tienen opciones de configuración adicionales para el mapeo de rutas:

{
  "shells": {
    "wsl": {
      "type": "wsl",
      "enabled": true,
      "executable": {
        "command": "wsl.exe",
        "args": ["-e"]
      },
      "wslConfig": {
        "mountPoint": "/mnt/",
        "inheritGlobalPaths": true
      }
    }
  }
}

Puedes anular el punto de montaje al iniciar usando la opción de CLI --wslMountPoint.

Herencia de Configuración

La sección de transporte también se puede establecer en el archivo de configuración. Para el transporte Streamable HTTP (modo http):

{
  "transport": {
    "mode": "http",
    "httpHost": "127.0.0.1",
    "httpPort": 9444,
    "httpAllowedOrigins": ["https://app.example.com", "192.168.1.10"]
  }
}

Para el transporte HTTP+SSE heredado (modo sse):

{
  "transport": {
    "mode": "sse",
    "sseHost": "127.0.0.1",
    "ssePort": 9444,
    "sseAllowedOrigins": ["https://app.example.com", "192.168.1.10"]
  }
}
CampoTipoPredeterminadoAplica aDescripción
modestringstdiotodosstdio, http o sse
httpHoststring127.0.0.1httpHost de enlace para el transporte Streamable HTTP
httpPortnumber9444httpPuerto de enlace para el transporte Streamable HTTP (entero 1..65535)
httpAllowedOriginsstring[][]httpOrígenes de navegador permitidos además de los hosts de bucle local y httpHost
sseHoststring127.0.0.1sseHost de enlace para el transporte SSE heredado
ssePortnumber9444ssePuerto de enlace para el transporte SSE heredado (entero 1..65535)
sseAllowedOriginsstring[][]sseOrígenes de navegador permitidos además de los hosts de bucle local y sseHost

Las listas *AllowedOrigins son opcionales y su valor predeterminado es una lista vacía. Cada entrada es una URL de origen o un host simple; solo se compara el componente del host (sin distinguir mayúsculas de minúsculas).

Las opciones de CLI anulan los valores del archivo de configuración: --transport, --http-host, --http-port, --http-allowed-origins, --sse-host, --sse-port y --sse-allowed-origins.

El sistema de herencia funciona de la siguiente manera:

  1. Los valores predeterminados globales se aplican a todos los shells
  2. Las anulaciones específicas del shell reemplazan o extienden los ajustes globales
  3. Los ajustes de arreglo (como blockedCommands) anulan los valores predeterminados cuando se proporcionan. Especificar un arreglo vacío elimina todas las entradas predeterminadas para ese ajuste.
  4. Los ajustes de objeto se fusionan en profundidad
  5. Los ajustes primitivos se reemplazan

Ejemplo de herencia en acción:

{
  "global": {
    "security": { "commandTimeout": 30 },
    "restrictions": { "blockedCommands": ["rm", "format"] }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "overrides": {
        "security": { "commandTimeout": 45 },
        "restrictions": { "blockedCommands": ["Remove-Item"] }
      }
    }
  }
}

Resulta en que PowerShell tenga:

  • commandTimeout: 45 (anulado)
  • blockedCommands: ["Remove-Item"] (anula los valores predeterminados)

Para eliminar por completo los valores predeterminados de una restricción determinada, proporciona un arreglo vacío:

{
  "global": {
    "restrictions": {
      "blockedCommands": [],
      "blockedArguments": [],
      "blockedOperators": []
    }
  },
  "shells": {
    "powershell": {
      "type": "powershell",
      "overrides": {
        "restrictions": { "blockedCommands": [] }
      }
    }
  }
}

Perfiles de Entorno

Los perfiles de entorno con nombre permiten que una única instancia del servidor ejecute la misma herramienta CLI bajo diferentes conjuntos de variables de entorno, seleccionados por llamada mediante el parámetro opcional profile en execute_command. Un caso de uso común es probar el mismo SQL contra diferentes versiones de sqlplus, donde cada versión necesita su propio ORACLE_HOME, TNS_ADMIN y un PATH que apunte al bin de esa versión.

Los perfiles se definen bajo un mapa opcional de nivel superior profiles. Cada entrada acepta:

CampoTipoRequeridoDescripción
envobjectSíMapa de nombres de variables de entorno a valores de cadena. Los valores admiten interpolación ${VAR} resuelta contra el entorno del servidor.
descriptionstringNoResumen legible por humanos que se muestra en la descripción de la herramienta execute_command.
allowedShellsstring[]NoShells con los que se puede usar este perfil (cmd, powershell, gitbash, wsl, bash). Cuando se omite, el perfil se permite para todos los shells.
{
  "profiles": {
    "ora19": {
      "description": "Oracle 19c sqlplus client",
      "allowedShells": ["cmd", "powershell"],
      "env": {
        "ORACLE_HOME": "C:\\oracle\\product\\19.0.0\\client",
        "TNS_ADMIN": "C:\\oracle\\product\\19.0.0\\client\\network\\admin",
        "PATH": "C:\\oracle\\product\\19.0.0\\client\\bin;${PATH}"
      }
    }
  }
}

Comportamiento:

  • Cuando se selecciona un perfil, su mapa env se fusiona sobre el entorno del servidor ({ ...process.env, ...profileEnv }) antes de que se ejecute el comando.
  • ${VAR} se reemplaza con el valor del entorno del servidor de VAR; una referencia indefinida se resuelve a una cadena vacía. Así es como se antepone PATH ("C:\\oracle\\product\\19.0.0\\client\\bin;${PATH}").
  • Los perfiles se validan en el momento de la carga: env debe ser un mapa no vacío de cadena a cadena y cada entrada de allowedShells debe ser un shell conocido. Los perfiles no válidos abortan el inicio con un error descriptivo.
  • Seleccionar un perfil desconocido, o un perfil cuyo allowedShells excluye el shell solicitado, devuelve un error InvalidParams.
  • Cuando no se configuran profiles, el comportamiento no cambia y el parámetro profile no se expone.

Se proporciona un ejemplo completo en config.examples/profiles.json. Consulte Ejemplos de configuración para más información.

API

Herramientas

  • execute_command

    • Ejecuta un comando en el shell especificado
    • Entradas:
      • shell (cadena): Shell a utilizar ("powershell", "cmd", "gitbash", "bash" o "wsl")
      • command (cadena): Comando a ejecutar
      • workingDir (cadena opcional): Directorio de trabajo
      • maxOutputLines (número opcional): Número máximo de líneas de salida a devolver (1-10,000). Anula la configuración global.
      • timeout (número opcional): Tiempo de espera del comando en segundos (1-3,600). Anula la configuración global.
      • profile (cadena opcional): Perfil de entorno con nombre a aplicar para este comando. Debe nombrar un perfil configurado (consulte Perfiles de entorno). Solo está presente en el esquema cuando hay perfiles configurados; omítalo para ejecutar con el entorno predeterminado del servidor.
    • Devuelve la salida del comando como texto, o un mensaje de error si la ejecución falla
    • Si se omite workingDir, el comando se ejecuta en el directorio de trabajo activo del servidor. Si este no se ha establecido, la herramienta devuelve un error.

  • get_current_directory

    • Obtiene el directorio de trabajo activo del servidor
    • Si el directorio no está establecido, devuelve un mensaje que explica cómo configurarlo

  • set_current_directory

    • Establece el directorio de trabajo activo del servidor
    • Entradas:
      • path (cadena): Ruta a establecer como directorio de trabajo actual
    • Devuelve un mensaje de confirmación con la nueva ruta del directorio, o un mensaje de error si el cambio falla

  • get_config

    • Obtiene la configuración del servidor de CLI de Windows
    • Devuelve la configuración del servidor como una cadena JSON (excluyendo datos sensibles)

  • validate_directories

    • Comprueba si los directorios especificados están dentro de las rutas permitidas
    • Solo está disponible cuando restrictWorkingDirectory está habilitado en la configuración
    • Entradas:
      • directories (matriz de cadenas): Lista de rutas de directorio a validar
    • Devuelve un mensaje de éxito si todos los directorios son válidos, o un mensaje de error que detalla qué directorios están fuera de las rutas permitidas

Recursos

  • cli://config

    • Devuelve la configuración principal del servidor CLI (excluyendo datos sensibles como detalles de comandos bloqueados si la seguridad lo requiere).

  • cli://logs/list

    • Lista todos los registros de ejecución de comandos almacenados con metadatos

  • cli://logs/recent?n={count}

    • Obtiene los N registros de comandos más recientes (predeterminado: 5)

  • cli://logs/commands/{id}

    • Accede a la salida completa de una ejecución de comando específica

  • cli://logs/commands/{id}/range?start={n}&end={m}

    • Consulta rangos de líneas específicos de un registro (admite índices negativos)

  • cli://logs/commands/{id}/search?q={pattern}&context={n}&occurrence={n}

    • Busca en los registros con patrones de expresiones regulares y líneas de contexto

Consideraciones de Seguridad

Este servidor permite que herramientas externas ejecuten comandos en su sistema. Tenga extrema precaución al configurarlo y usarlo.

Funciones de Seguridad Integradas

  • Restricciones de Ruta: Los comandos solo se pueden ejecutar en directorios especificados (allowedPaths) si restrictWorkingDirectory es verdadero.
  • Bloqueo de Comandos: Los comandos y argumentos definidos están bloqueados para prevenir operaciones potencialmente peligrosas (blockedCommands, blockedArguments).
  • Protección contra Inyección: Los caracteres comunes de inyección de shell (;, &, |, `) are blocked in command strings if enableInjectionProtection es verdadero.
  • Tiempo de Espera: Los comandos se terminan si exceden el tiempo de espera configurado (commandTimeout).
  • Validación de Entradas: Todas las entradas de usuario se validan antes de la ejecución
  • Gestión de Procesos de Shell: Los procesos se terminan correctamente después de la ejecución o el tiempo de espera

Funciones de Seguridad Configurables (Activas por Defecto)

  • Restricción del Directorio de Trabajo (restrictWorkingDirectory): ALTAMENTE RECOMENDADO. Limita la ejecución de comandos a directorios seguros.
  • Protección contra Inyección (enableInjectionProtection): Recomendado para prevenir la omisión de reglas de seguridad.

Mejores Prácticas

  • Rutas Permitidas Mínimas: Solo permita la ejecución en directorios necesarios.
  • Listas de Bloqueo Restrictivas: Bloquee cualquier comando o argumento potencialmente dañino.
  • Revise los Registros Regularmente: Verifique el historial de comandos para detectar actividad sospechosa.
  • Mantenga el Software Actualizado: Asegúrese de que Node.js, npm y el propio servidor estén actualizados.

Uso del Inspector MCP para Pruebas

Use el Inspector para probar interactivamente este servidor con un archivo de configuración personalizado. Pase cualquier bandera del servidor después de --:

# Inspect with built server and test config
npx @modelcontextprotocol/inspector -- node dist/index.js --config tests/config.json

# Or test the published package
npx @modelcontextprotocol/inspector wcli0 -- --config tests/config.json

Desarrollo y Pruebas

Este proyecto requiere Node.js 18 o posterior.

Ejecución de Pruebas

# Install dependencies
npm install

# Run all tests
npm test

# Run specific test suites
npm run test:validation    # Path validation tests
npm run test:wsl          # WSL emulation tests
npm run test:integration  # Integration tests
npm run test:async        # Async operation tests

# Run tests with coverage
npm run test:coverage

# Debug open handles
npm run test:debug

Pruebas Multiplataforma

El proyecto utiliza un emulador WSL basado en Node.js (scripts/wsl-emulator.js) para permitir probar la funcionalidad WSL en todas las plataformas. Esto permite que el conjunto de pruebas se ejecute correctamente tanto en entornos Windows como Linux.

Agradecimientos

Este proyecto se basa en el excelente trabajo de SimonB97 en el repositorio win-cli-mcp-server. Debido a diferencias significativas de configuración y cambios arquitectónicos que dificultaron la fusión de vuelta al repositorio fuente, este se ha mantenido como un fork separado con funciones mejoradas y modificaciones extensas.

Mejoras clave en esta versión:

  • Sistema de configuración mejorado basado en herencia
  • Soporte WSL mejorado con pruebas multiplataforma
  • Funciones de seguridad avanzadas y validación de rutas
  • Cobertura de pruebas integral con emulación WSL basada en Node.js
  • Documentación extendida y ejemplos de configuración

Agradecemos sinceramente el trabajo fundacional de SimonB97 que hizo posible este proyecto.

Entorno de Desarrollo usando Contenedores de Desarrollo

Este proyecto incluye una configuración de Contenedor de Desarrollo, que le permite usar un contenedor Docker como entorno de desarrollo completamente funcional. Esto garantiza consistencia y facilita comenzar con el desarrollo y las pruebas.

Requisitos Previos

Cómo Empezar

  1. Clone este repositorio en su máquina local.
  2. Abra el repositorio en Visual Studio Code.
  3. Cuando se le solicite "Reabrir en Contenedor", haga clic en el botón. (Si no ve una solicitud, puede abrir la Paleta de Comandos (Ctrl+Shift+P o Cmd+Shift+P) y seleccionar "Dev Containers: Reopen in Container").
  4. VS Code construirá la imagen del contenedor de desarrollo (como se define en .devcontainer/devcontainer.json y Dockerfile) e iniciará el contenedor. Esto puede tomar unos minutos la primera vez.
  5. Una vez que el contenedor esté construido e iniciado, su VS Code se conectará a este entorno. El postCreateCommand (npm install) garantizará que todas las dependencias estén instaladas.

Ejecución de Pruebas en el Contenedor de Desarrollo

Después de abrir el proyecto en el contenedor de desarrollo:

  1. Abra una nueva terminal en VS Code (será una terminal dentro del contenedor).

  2. Ejecute las pruebas usando el comando:

    npm test

Esta configuración refleja el entorno utilizado en GitHub Actions para las pruebas, garantizando consistencia entre el desarrollo local y la CI.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo LICENSE para más detalles.