Windows CLI

Windows CLI MCP Server (Enhanced)

Servidor MCP para interações seguras com a linha de comando em sistemas Windows, permitindo acesso controlado aos shells PowerShell, CMD, Git Bash e Bash. Ele permite que clientes MCP (como o Claude Desktop) executem operações no seu sistema, de forma semelhante ao Open Interpreter.

Esta versão aprimorada inclui gerenciamento avançado de configuração, recursos de segurança melhorados e capacidades abrangentes de teste.

[!IMPORTANT] Este servidor MCP fornece acesso direto à interface de linha de comando do seu sistema. Quando habilitado, ele concede acesso aos seus arquivos, variáveis de ambiente e capacidades de execução de comandos.

• Revise e restrinja os caminhos permitidos
• Habilite restrições de diretório
• Configure bloqueios de comandos
• Considere as implicações de segurança

Consulte Configuração para mais detalhes.

• Windows CLI MCP Server (Enhanced)
  • Recursos
  • Uso com o Claude Desktop
    • Configuração Inicial
  • Configuração
    • Estrutura de Configuração
    • Locais de Configuração
    • Configuração Padrão
    • Configurações
      • Configurações Globais
        • Configurações de Segurança
        • Configurações de Restrição
        • Configurações de Caminho
      • Configuração de Shell
        • Configuração Básica de Shell
        • Substituições Específicas de Shell
        • Configuração do WSL
    • Herança de Configuração
  • API
    • Ferramentas
    • Recursos
  • Considerações de Segurança
    • Recursos de Segurança Integrados
    • Recursos de Segurança Configuráveis (Ativos por Padrão)
    • Melhores Práticas
  • Usando o MCP Inspector para Testes
  • Desenvolvimento e Testes
    • Executando Testes
    • Testes Multiplataforma
  • Agradecimentos
  • Ambiente de Desenvolvimento usando Dev Containers
    • Pré-requisitos
    • Primeiros Passos
    • Executando Testes no Dev Container
  • Licença

Recursos

• Suporte a Múltiplos Shells: Execute comandos no PowerShell, Prompt de Comando (CMD), Git Bash, Bash e WSL
• Arquitetura Modular: Compile apenas os shells necessários para tamanhos de pacote menores (redução de 30-65%)
• Configuração Baseada em Herança: Padrões globais com substituições específicas por shell
• Validação Específica por Shell: Cada shell pode ter suas próprias configurações de segurança e formatos de caminho
• Gerenciamento Flexível de Caminhos: Diferentes shells suportam diferentes formatos de caminho (Windows/Unix/Misto)
• Exposição de Recursos: Visualize configurações e definições de segurança como recursos MCP
• Estado Explícito do Diretório de Trabalho: O servidor mantém um diretório de trabalho ativo usado quando execute_command omite workingDir. Se o diretório de inicialização não for permitido, este estado começa não definido e deve ser definido via set_current_directory.
• Diretório Inicial Opcional: Configure initialDir para iniciar o servidor em um diretório específico.
• Controles de Segurança:
  • Bloqueio de comandos (caminhos completos, variações de maiúsculas/minúsculas)
  • Validação do diretório de trabalho
  • Limites máximos de comprimento de comando
  • Validação inteligente de argumentos
  • Configurações de tempo limite específicas por shell
• Configurável:
  • Sistema de configuração baseado em herança
  • Substituições de segurança específicas por shell
  • Descrições dinâmicas de ferramentas com base nos shells habilitados

Consulte a seção API para mais detalhes sobre as ferramentas e recursos que o servidor fornece aos clientes MCP.

Nota: O servidor só permitirá operações dentro dos diretórios configurados, com comandos permitidos.

Extensão do VS Code

Uma extensão complementar do VS Code em vscode-extension/ simplifica a configuração deste servidor. Ela expõe cada opção de CLI como configurações comuns do VS Code (com escopo por Usuário e por Workspace) e registra o servidor MCP com o VS Code automaticamente via a API MCP Server Definition Provider — sem necessidade de edição manual do mcp.json. Ela também pode gerar um config.json ou um .vscode/mcp.json sob demanda. Consulte vscode-extension/README.md.

Arquitetura Modular de Shell

O WCLI0 agora suporta uma arquitetura modular que permite criar versões especializadas contendo apenas os shells necessários. Isso resulta em tamanhos de pacote significativamente menores e tempos de inicialização mais rápidos.

Opções de Build

Escolha entre várias builds pré-configuradas:

# 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

Comparação de Tamanho do Pacote

Build	Redução de Tamanho	Shells Incluídos
Full	Linha de base	Todos os 5 shells
Windows	~40% menor	PowerShell, CMD, Git Bash
Git Bash Only	~60% menor	Git Bash
CMD Only	~65% menor	CMD
Unix	~60% menor	Bash

Documentação

Para informações detalhadas sobre a arquitetura modular:

• Visão Geral da Arquitetura - Design do sistema e estrutura de módulos
• Guia do Usuário - Como compilar e usar versões especializadas
• Documentação da API - Referência completa da API para plugins de shell
• Guia de Migração - Atualização de versões anteriores
• Guia de Testes - Estratégias de teste para shells modulares

Início Rápido com Builds Especializadas

Se você precisar apenas do 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"]
    }
  }
}

Suporte a macOS e Unix/Linux

Embora o wcli0 seja projetado principalmente para Windows, ele também suporta sistemas baseados em Unix (macOS, Linux) com integração do shell Bash.

Compilando para Sistemas Unix

Para compilar o wcli0 para sistemas baseados em Unix (macOS, Linux):

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

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

Iniciando o Servidor no macOS

Inicie o 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"

Exemplo de Configuração para macOS

Aqui está um exemplo de configuração 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
    }
  }
}

Usando com o Claude Desktop no macOS

Configure o Claude Desktop para usar o wcli0 no macOS:

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

Notas Importantes para Sistemas Unix

• Formatos de Caminho: Sistemas Unix usam barras normais (/) e não suportam letras de unidade do Windows
• Tipo de Shell: Use os tipos de shell bash ou bash_auto em sistemas Unix
• Diretório Inicial: Use $(whoami) ou seu nome de usuário real nos caminhos
• Comandos de Segurança: Alguns comandos bloqueados na configuração padrão são específicos do Windows (por exemplo, regedit, format)

Opções de CLI para macOS

Ao executar em sistemas Unix, use estas opções de CLI:

Opção	Tipo	Descrição
--shell	string	Shell a ser usado (use bash ou bash_auto no Unix)
--allowedDir	string	Adiciona um diretório permitido (pode ser usado várias vezes)
--config	string	Caminho para o arquivo de configuração
--initialDir	string	Diretório de trabalho inicial
--allowAllDirs	flag	Desativa restrições de diretório
--unsafe	flag	Desativa todas as verificações de segurança (não recomendado)
--yolo	flag	Desativa a segurança, exceto restrições de diretório

Gerenciamento de Logs

O wcli0 armazena automaticamente os logs de execução de comandos e fornece recursos MCP para consultar saídas históricas com capacidades avançadas de filtragem.

Truncamento de Saída

Por padrão, as respostas de comandos mostram apenas as últimas 20 linhas para evitar sobrecarregar com saídas longas. A saída completa é sempre armazenada e acessível via:

• Armazenamento baseado em arquivos: Quando logDirectory está configurado, os logs são salvos em arquivos para armazenamento persistente
• Armazenamento em memória: Comportamento padrão usando recursos de log MCP (por exemplo, cli://logs/commands/{id})
• A ferramenta get_command_output (fallback para hosts que não conseguem ler recursos)

Configure as configurações de truncamento:

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

Armazenamento de Logs Baseado em Arquivos

Para registro persistente, configure um diretório de logs:

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

Ou via CLI:

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

Quando o registro baseado em arquivos está habilitado:

• As mensagens de truncamento mostram o caminho do arquivo diretamente (saída mais simples)
• Os logs persistem entre reinicializações do servidor
• Não há limites de armazenamento em memória
• Iniciar o servidor com --debug habilita automaticamente o registro baseado em arquivos no diretório temporário do seu SO (<temp>/wcli0-debug-logs) quando nenhum logDirectory está definido, para que cada comando e sua saída sejam persistidos durante sessões de depuração.

Nota de Segurança: Os arquivos de log podem conter saídas sensíveis de comandos. Garanta que o diretório de logs tenha permissões apropriadas.

Recursos de Log

Acesse a saída armazenada de comandos via recursos MCP (modo em memória):

• cli://logs/list - Lista todos os logs de execução de comandos armazenados
• cli://logs/recent?n=10 - Obtém os N logs mais recentes
• cli://logs/commands/{id} - Acessa a saída completa de um comando específico
• cli://logs/commands/{id}/range?start=1&end=100 - Consulta intervalos específicos de linhas
• cli://logs/commands/{id}/search?q=error&context=3 - Pesquisa logs com contexto

Consulte a Documentação da API para especificações detalhadas de recursos e parâmetros de consulta.

Exemplo de Configuração

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

Uso com o Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

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

Para usar com um arquivo de configuração específico, adicione a flag --config:

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

Configuração Inicial

Para começar com a configuração:

1. Use uma configuração de exemplo:

   • Copie config.examples/config.sample.json para configuração básica
   • Copie config.examples/config.development.json para ambientes de desenvolvimento
   • Copie config.examples/config.secure.json para ambientes de alta segurança
   • Copie config.examples/emptyRestrictions.json para remover todas as restrições padrão

2. Crie sua própria configuração:

   # 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
   

   O servidor também aceita uma flag --initialDir para substituir o diretório de trabalho inicial definido no seu arquivo de configuração:

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

   Você pode substituir os limites globais de comandos diretamente da CLI:

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

   Você pode configurar o truncamento de saída e o registro de logs via CLI:

   npx wcli0 --shell gitbash \
     --maxOutputLines 50 \
     --enableTruncation \
     --enableLogResources \
     --maxReturnLines 1000 \
     --logDirectory ./logs
   

   Opção	Tipo	Padrão	Descrição
   --maxOutputLines	number	20	Número máximo de linhas de saída antes do truncamento
   --enableTruncation	boolean	true	Habilita o truncamento de saída
   --enableLogResources	boolean	true	Habilita recursos de log para get_command_output
   --maxReturnLines	number	500	Número máximo de linhas retornadas por get_command_output
   --logDirectory	string	-	Diretório para armazenamento de logs baseado em arquivos (em vez de em memória)

   Quando --logDirectory está configurado, os logs de saída de comandos são salvos em arquivos em vez de armazenamento em memória. As mensagens de truncamento mostrarão o caminho do arquivo para facilitar o acesso à saída completa.

   Nota de Segurança: Os arquivos de log podem conter dados sensíveis da saída de comandos. Garanta que o diretório de logs tenha permissões apropriadas e considere implementar rotação de logs.

   Você pode substituir as restrições bloqueadas diretamente da CLI. Passe a opção com uma string vazia para limpar os padrões:

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

   Forneça a flag várias vezes para especificar valores:

   npx wcli0 --blockedCommand rm --blockedCommand del
   

   Você também pode iniciar o servidor com um shell específico e diretórios permitidos sem um arquivo de configuração:

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

   Para shells WSL, você pode especificar um local de montagem personalizado:

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

Para desativar completamente as restrições de diretório quando nenhum caminho permitido estiver configurado, inicie o servidor com:

npx wcli0 --allowAllDirs

Quando iniciado desta forma, restrictWorkingDirectory é forçado a ativar e enableInjectionProtection é desativado para garantir que os caminhos permitidos sejam aplicados sem verificações de injeção de shell. Se você precisar desativar as verificações de segurança que bloqueiam a execução de comandos para experimentação, você pode iniciar o servidor nos modos unsafe ou YOLO (não recomendado para produção):

# 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 os modos limpam comandos/argumentos/operadores bloqueados e desativam a proteção contra injeção. O modo YOLO mantém as restrições de diretório de trabalho ativas, enquanto o modo totalmente inseguro também desativa essas restrições. Essas duas flags são mutuamente exclusivas; usar ambas ao mesmo tempo falhará.

Você pode iniciar o servidor com um transporte baseado em HTTP em vez do transporte stdio padrão, para que clientes MCP remotos e baseados na web possam se conectar via HTTP. Dois transportes HTTP estão disponíveis:

• http -- o transporte moderno Streamable HTTP (revisão do protocolo MCP 2025-03-26), servindo um único endpoint /mcp. É o padrão dos clientes MCP atuais e é o transporte HTTP recomendado.
• sse -- o transporte legado HTTP+SSE (revisão do protocolo MCP 2024-11-05), usando dois endpoints (GET /sse, POST /messages). Ele está obsoleto na especificação MCP em favor do Streamable HTTP e é mantido apenas para compatibilidade com clientes mais antigos.

Os modos são mutuamente exclusivos (selecionados por --transport) e usam configurações de bind separadas (--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

Opção	Tipo	Padrão	Descrição
--transport	string	stdio	Protocolo de transporte: stdio, http (Streamable HTTP) ou sse (HTTP+SSE legado)
--http-host	string	127.0.0.1	Endereço do host para o transporte Streamable HTTP (modo http)
--http-port	number	9444	Porta para o transporte Streamable HTTP (modo http)
--http-allowed-origins	string	(nenhum)	Origens de navegador permitidas, separadas por vírgula, para o modo http, além de hosts de loopback e do host de bind (ex.: https://app.example.com,192.168.1.10). Apenas o componente de host é comparado. Necessário para clientes de navegador em um bind curinga (0.0.0.0).
--sse-host	string	127.0.0.1	Endereço do host para o transporte SSE legado (modo sse)
--sse-port	number	9444	Porta para o transporte SSE legado (modo sse)
--sse-allowed-origins	string	(nenhum)	Origens de navegador permitidas, separadas por vírgula, para o modo sse, além de hosts de loopback e do host de bind. Apenas o componente de host é comparado. Necessário para clientes de navegador em um bind curinga (0.0.0.0).

Quando o modo http está ativo, os clientes usam um único endpoint /mcp:

• POST /mcp transporta mensagens JSON-RPC do cliente para o servidor. Uma solicitação initialize sem id de sessão inicia uma nova sessão; o servidor retorna o id atribuído no cabeçalho de resposta Mcp-Session-Id, e o cliente deve enviar esse cabeçalho em toda solicitação subsequente.
• GET /mcp abre o fluxo SSE opcional do servidor para o cliente para uma sessão existente.
• DELETE /mcp encerra uma sessão existente.

As sessões são stateful e isoladas: cada sessão tem seu próprio diretório de trabalho ativo, portanto o set_current_directory de um cliente não pode afetar outro. Solicitações com um Mcp-Session-Id desconhecido ou encerrado são rejeitadas com 404 Not Found. O servidor registra o endereço e a porta de bind na inicialização (com --debug).

Quando o modo sse está ativo, os clientes se conectam via GET /sse para abrir um fluxo SSE e enviam mensagens via POST /messages?sessionId=<id>.

Configurando o Streamable HTTP inteiramente com parâmetros de CLI (sem arquivo de configuração). Toda configuração de transporte e operacional pode ser fornecida como parâmetro de entrada, para que o servidor possa ser executado como um servidor Streamable HTTP sem nenhum arquivo de configuração:

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

Os parâmetros de CLI também têm precedência sobre um arquivo de configuração, portanto as mesmas flags --http-* substituem os campos transport correspondentes quando um arquivo --config também é passado (veja a seção de configuração de transporte).

Ambos os transportes HTTP validam o cabeçalho Origin da solicitação para mitigar ataques de DNS-rebinding: solicitações cujo Origin não seja um host de loopback, o host de bind configurado ou uma das origens permitidas configuradas (--http-allowed-origins / --sse-allowed-origins) são rejeitadas com 403 Forbidden, enquanto clientes que não são navegadores e não enviam Origin são permitidos. Origens de navegador permitidas recebem cabeçalhos CORS, e solicitações de preflight OPTIONS são respondidas com 204.

Segurança: Nenhum dos transportes HTTP tem autenticação integrada, e ambos expõem ferramentas de execução de comandos. Mantenha o servidor vinculado a 127.0.0.1 (o padrão) para uso local. Vincular a 0.0.0.0 ou a qualquer endereço não-loopback expõe essas ferramentas a todos os hosts que possam alcançar a porta; só faça isso atrás de um proxy reverso autenticado ou controle de acesso equivalente. A validação de origem sozinha não autentica clientes que não são navegadores.

Binds curinga e origens de navegador: Ao vincular a um endereço curinga (0.0.0.0 / ::), o host de bind não é uma origem utilizável para comparação, portanto clientes de navegador que acessam o servidor pelo endereço LAN real (ou um proxy reverso cujo hostname público difere do host de bind) são rejeitados, a menos que sua origem esteja listada em --http-allowed-origins / --sse-allowed-origins (ou nos arrays de configuração transport.httpAllowedOrigins / transport.sseAllowedOrigins). Clientes que não são navegadores não são afetados, pois não enviam Origin.

1. Atualize sua configuração do Claude Desktop para usar seu arquivo de configuração:

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

Após a configuração, você pode:

• Executar comandos diretamente usando as ferramentas disponíveis
• Visualizar a configuração do servidor e as configurações de segurança na seção Recursos
• Acessar configurações e capacidades específicas do shell

Configuração

O servidor usa um sistema de configuração baseado em herança, onde os padrões globais podem ser substituídos por configurações específicas do shell.

Estrutura de Configuração

{
  "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
      }
    }
  }
}

Locais de Configuração

O servidor procura arquivos de configuração na seguinte ordem:

1. Caminho especificado via argumento de linha de comando --config
2. win-cli-mcp.config.json no diretório de trabalho atual
3. ~/.win-cli-mcp/config.json no diretório home do usuário

Se nenhum arquivo de configuração for encontrado, o servidor usará uma configuração padrão (restrita).

Configuração Padrão

Nota: A configuração padrão foi projetada para ser restritiva e segura. Encontre mais detalhes sobre cada configuração na seção Configurações.

Para uma referência completa de todos os valores padrão, veja 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"]
      }
    }
  }
}

Configurações

O arquivo de configuração usa um sistema de herança com duas seções principais: global e shells.

Configurações Globais

As configurações globais fornecem padrões que se aplicam a todos os shells, a menos que sejam substituídos.

Configurações de Segurança

{
  "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
    }
  }
}

Configurações de Restrição

{
  "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": ["&", "|", ";", "`"]
    }
  }
}

Configurações de Caminho

{
  "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
    }
  }
}

Se o array allowedPaths for omitido do seu arquivo de configuração, nenhum diretório padrão será permitido automaticamente. Quando restrictWorkingDirectory está habilitado, apenas o initialDir (se especificado) será adicionado à lista de caminhos permitidos. Use a flag --allowAllDirs ao iniciar o servidor para desativar automaticamente o restrictWorkingDirectory se nenhum caminho permitido ou initialDir estiver definido.

Configuração do Shell

Cada shell pode ser configurado individualmente e pode substituir as configurações globais. Cada entrada de shell deve incluir um campo type indicando o shell. Os valores válidos são powershell, cmd, gitbash, bash e wsl.

Configuração Básica do Shell

{
  "shells": {
    "powershell": {
      "type": "powershell",
      "enabled": true,
      "executable": {
        "command": "powershell.exe",
        "args": ["-NoProfile", "-NonInteractive", "-Command"]
      }
    }
  }
}

Substituições Específicas do 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": ["|", "&"]
        }
      }
    }
  }
}

Configuração WSL

Os shells WSL têm opções de configuração adicionais para mapeamento de caminhos:

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

Você pode substituir o ponto de montagem na inicialização usando a flag de CLI --wslMountPoint.

Herança de Configuração

A seção de transporte também pode ser definida no arquivo de configuração. Para o 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 o transporte legado HTTP+SSE (modo sse):

{
  "transport": {
    "mode": "sse",
    "sseHost": "127.0.0.1",
    "ssePort": 9444,
    "sseAllowedOrigins": ["https://app.example.com", "192.168.1.10"]
  }
}

Campo	Tipo	Padrão	Aplica-se a	Descrição
mode	string	stdio	todos	stdio, http ou sse
httpHost	string	127.0.0.1	http	Host de bind para o transporte Streamable HTTP
httpPort	number	9444	http	Porta de bind para o transporte Streamable HTTP (inteiro 1..65535)
httpAllowedOrigins	string[]	[]	http	Origens de navegador permitidas além de hosts de loopback e httpHost
sseHost	string	127.0.0.1	sse	Host de bind para o transporte SSE legado
ssePort	number	9444	sse	Porta de bind para o transporte SSE legado (inteiro 1..65535)
sseAllowedOrigins	string[]	[]	sse	Origens de navegador permitidas além de hosts de loopback e sseHost

As listas *AllowedOrigins são opcionais e o padrão é uma lista vazia. Cada entrada é uma URL de origem ou um host simples; apenas o componente de host é comparado (sem diferenciar maiúsculas de minúsculas).

As flags de CLI substituem os valores do arquivo de configuração: --transport, --http-host, --http-port, --http-allowed-origins, --sse-host, --sse-port e --sse-allowed-origins.

O sistema de herança funciona da seguinte forma:

1. Padrões globais são aplicados a todos os shells
2. Substituições específicas do shell substituem ou estendem as configurações globais
3. Configurações de array (como blockedCommands) substituem os padrões quando fornecidas. Especificar um array vazio remove todas as entradas padrão para essa configuração.
4. Configurações de objeto são mescladas em profundidade
5. Configurações primitivas são substituídas

Exemplo de herança em ação:

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

Resulta no PowerShell tendo:

• commandTimeout: 45 (substituído)
• blockedCommands: ["Remove-Item"] (substitui os padrões)

Para remover completamente os padrões de uma determinada restrição, forneça um array vazio:

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

Perfis de Ambiente

Perfis de ambiente nomeados permitem que uma única instância do servidor execute a mesma ferramenta CLI sob diferentes conjuntos de variáveis de ambiente, selecionados por chamada através do parâmetro opcional profile em execute_command. Um caso de uso comum é testar o mesmo SQL em diferentes versões de sqlplus, onde cada versão precisa de seu próprio ORACLE_HOME, TNS_ADMIN e um PATH que aponte para o bin dessa versão.

Os perfis são definidos em um mapa opcional de nível superior profiles. Cada entrada aceita:

Campo	Tipo	Obrigatório	Descrição
env	object	Sim	Mapa de nomes de variáveis de ambiente para valores de string. Os valores suportam interpolação ${VAR} resolvida em relação ao ambiente do servidor.
description	string	Não	Resumo legível por humanos exibido na descrição da ferramenta execute_command.
allowedShells	string[]	Não	Shells com os quais este perfil pode ser usado (cmd, powershell, gitbash, wsl, bash). Quando omitido, o perfil é permitido para todos os 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}"
      }
    }
  }
}

Comportamento:

• Quando um perfil é selecionado, seu mapa env é mesclado sobre o ambiente do servidor ({ ...process.env, ...profileEnv }) antes da execução do comando.
• ${VAR} é substituído pelo valor do ambiente do servidor de VAR; uma referência indefinida resolve para uma string vazia. É assim que PATH é prefixado ("C:\\oracle\\product\\19.0.0\\client\\bin;${PATH}").
• Os perfis são validados no momento do carregamento: env deve ser um mapa não vazio de string para string e cada entrada de allowedShells deve ser um shell conhecido. Perfis inválidos abortam a inicialização com um erro descritivo.
• Selecionar um perfil desconhecido, ou um perfil cujo allowedShells exclui o shell solicitado, retorna um erro InvalidParams.
• Quando nenhum profiles está configurado, o comportamento permanece inalterado e o parâmetro profile não é exposto.

Um exemplo completo é fornecido em config.examples/profiles.json. Consulte Exemplos de Configuração para mais informações.

API

Ferramentas

• execute_command

  • Executa um comando no shell especificado
  • Entradas:
    • shell (string): Shell a ser usado ("powershell", "cmd", "gitbash", "bash" ou "wsl")
    • command (string): Comando a ser executado
    • workingDir (string opcional): Diretório de trabalho
    • maxOutputLines (número opcional): Número máximo de linhas de saída a retornar (1-10.000). Substitui a configuração global.
    • timeout (número opcional): Tempo limite do comando em segundos (1-3.600). Substitui a configuração global.
    • profile (string opcional): Perfil de ambiente nomeado a ser aplicado para este comando. Deve nomear um perfil configurado (consulte Perfis de Ambiente). Presente apenas no esquema quando perfis estão configurados; omita para executar com o ambiente padrão do servidor.
  • Retorna a saída do comando como texto, ou mensagem de erro se a execução falhar
  • Se workingDir for omitido, o comando é executado no diretório de trabalho ativo do servidor. Se este não tiver sido definido, a ferramenta retorna um erro.

• get_current_directory

  • Obtém o diretório de trabalho ativo do servidor
  • Se o diretório não estiver definido, retorna uma mensagem explicando como defini-lo

• set_current_directory

  • Define o diretório de trabalho ativo do servidor
  • Entradas:
    • path (string): Caminho a ser definido como diretório de trabalho atual
  • Retorna mensagem de confirmação com o novo caminho do diretório, ou mensagem de erro se a alteração falhar

• get_config

  • Obtém a configuração do servidor Windows CLI
  • Retorna a configuração do servidor como uma string JSON (excluindo dados sensíveis)

• validate_directories

  • Verifica se os diretórios especificados estão dentro dos caminhos permitidos
  • Disponível apenas quando restrictWorkingDirectory está habilitado na configuração
  • Entradas:
    • directories (array de strings): Lista de caminhos de diretórios a validar
  • Retorna mensagem de sucesso se todos os diretórios forem válidos, ou mensagem de erro detalhando quais diretórios estão fora dos caminhos permitidos

Recursos

• cli://config

  • Retorna a configuração principal do servidor CLI (excluindo dados sensíveis, como detalhes de comandos bloqueados, se a segurança exigir).

• cli://logs/list

  • Lista todos os logs de execução de comandos armazenados com metadados

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

  • Obtém os N logs de comandos mais recentes (padrão: 5)

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

  • Acessa a saída completa de uma execução de comando específica

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

  • Consulta intervalos específicos de linhas de um log (suporta índices negativos)

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

  • Pesquisa logs com padrões regex e linhas de contexto

Considerações de Segurança

Este servidor permite que ferramentas externas executem comandos no seu sistema. Tenha extrema cautela ao configurá-lo e usá-lo.

Recursos de Segurança Integrados

• Restrições de Caminho: Comandos só podem ser executados em diretórios especificados (allowedPaths) se restrictWorkingDirectory for verdadeiro.
• Bloqueio de Comandos: Comandos e argumentos definidos são bloqueados para prevenir operações potencialmente perigosas (blockedCommands, blockedArguments).
• Proteção contra Injeção: Caracteres comuns de injeção de shell (;, &, |, `) are blocked in command strings if enableInjectionProtection é verdadeiro.
• Tempo Limite: Comandos são encerrados se excederem o tempo limite configurado (commandTimeout).
• Validação de entrada: Todas as entradas do usuário são validadas antes da execução
• Gerenciamento de processos do shell: Processos são devidamente encerrados após a execução ou tempo limite

Recursos de Segurança Configuráveis (Ativos por Padrão)

• Restrição de Diretório de Trabalho (restrictWorkingDirectory): ALTAMENTE RECOMENDADO. Limita a execução de comandos a diretórios seguros.
• Proteção contra Injeção (enableInjectionProtection): Recomendado para prevenir a violação de regras de segurança.

Melhores Práticas

• Caminhos Permitidos Mínimos: Permita execução apenas em diretórios necessários.
• Listas de Bloqueio Restritivas: Bloqueie quaisquer comandos ou argumentos potencialmente prejudiciais.
• Revise Logs Regularmente: Verifique o histórico de comandos para atividades suspeitas.
• Mantenha o Software Atualizado: Garanta que Node.js, npm e o próprio servidor estejam atualizados.

Usando o MCP Inspector para Testes

Use o Inspector para testar interativamente este servidor com um arquivo de configuração personalizado. Passe quaisquer flags do servidor após --:

# 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

Desenvolvimento e Testes

Este projeto requer Node.js 18 ou posterior.

Executando Testes

# 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

Testes entre Plataformas

O projeto usa um emulador WSL baseado em Node.js (scripts/wsl-emulator.js) para permitir o teste da funcionalidade WSL em todas as plataformas. Isso permite que a suíte de testes seja executada com sucesso em ambientes Windows e Linux.

Agradecimentos

Este projeto é baseado no excelente trabalho de SimonB97 no repositório win-cli-mcp-server. Devido a diferenças significativas de configuração e mudanças arquiteturais que tornaram o merge de volta ao repositório de origem desafiador, este foi mantido como um fork separado com recursos aprimorados e modificações extensas.

Principais aprimoramentos nesta versão:

• Sistema de configuração aprimorado baseado em herança
• Suporte WSL melhorado com testes entre plataformas
• Recursos avançados de segurança e validação de caminhos
• Cobertura abrangente de testes com emulação WSL baseada em Node.js
• Documentação estendida e exemplos de configuração

Agradecemos sinceramente o trabalho fundamental de SimonB97 que tornou este projeto possível.

Ambiente de Desenvolvimento usando Dev Containers

Este projeto inclui uma configuração de Dev Container, que permite usar um contêiner Docker como ambiente de desenvolvimento completo. Isso garante consistência e facilita o início do desenvolvimento e testes.

Pré-requisitos

• Docker Desktop instalado e em execução.
• Visual Studio Code instalado.
• A extensão Dev Containers instalada no VS Code.

Começando

1. Clone este repositório para sua máquina local.
2. Abra o repositório no Visual Studio Code.
3. Quando solicitado "Reabrir no Contêiner", clique no botão. (Se você não vir o prompt, pode abrir a Paleta de Comandos (Ctrl+Shift+P ou Cmd+Shift+P) e selecionar "Dev Containers: Reopen in Container".)
4. O VS Code construirá a imagem do contêiner de desenvolvimento (conforme definido em .devcontainer/devcontainer.json e Dockerfile) e iniciará o contêiner. Isso pode levar alguns minutos na primeira vez.
5. Uma vez que o contêiner esteja construído e iniciado, seu VS Code estará conectado a este ambiente. O postCreateCommand (npm install) garantirá que todas as dependências estejam instaladas.

Executando Testes no Dev Container

Após abrir o projeto no contêiner de desenvolvimento:

1. Abra um novo terminal no VS Code (será um terminal dentro do contêiner).

2. Execute os testes usando o comando:

   npm test
   

Esta configuração espelha o ambiente usado nas GitHub Actions para testes, garantindo consistência entre o desenvolvimento local e a CI.

Licença

Este projeto está licenciado sob a Licença MIT. Consulte o arquivo LICENSE para detalhes.