win-shell-mcp

Нативный кроссплатформенный слой абстракции команд для ИИ — предоставляет 40 детерминированных инструментов в виде MCP-сервера, заменяет вызовы голого shell, унифицирует минималистичный JSON-вывод, обрабатывает различия путей/кодировок/кавычек Windows.

Зачем

Вызов shell-команд через ИИ опасен и ненадёжен:

• Кроссплатформенная несовместимость: разделители путей Windows, кодировки (GBK), кавычки, имена команд (del vs rm) сильно отличаются от unix

• Сложность парсинга вывода: формат вывода shell-команд произволен, ИИ сложно надёжно извлечь информацию

• Риски безопасности: голый shell допускает конвейеры, перенаправления, инъекции команд

win-shell-mcp заменяет обычные shell-команды на 40 детерминированных инструментов, каждый из которых:

• Принимает структурированные JSON-параметры, возвращает единый { ok: true, ...data } или { ok: false, error: { code, message } }

• Ведёт себя одинаково на всех платформах (одна конфигурация для Windows/macOS/Linux)

• Минималистичный вывод (по умолчанию только минимальные поля, необходимые для принятия решений ИИ), флаг verbose для получения полных данных

• Стандартные коды ошибок (ENOENT/EISDIR/ENOTDIR/EACCES/EINVAL/ETIMEOUT/EEXEC/EUNKNOWN/INVALID_URL/NET_TIMEOUT/NET_FAIL/PROC_NOT_FOUND/PROC_KILL_FAIL/EXEC_FAIL/EXEC_TIMEOUT/GIT_FAIL)

Related MCP server: Pare

Установка

# 全局安装
npm install -g win-shell-mcp

# 或一次性运行
npx win-shell-mcp

Требуется Node.js ≥ 18.

Конфигурация клиента

Claude Desktop

Отредактируйте claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp"
    }
  }
}

Если не установлено глобально, используйте npx:

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "npx",
      "args": ["win-shell-mcp"]
    }
  }
}

Универсальный MCP-клиент

Любой клиент, совместимый с Model Context Protocol, может подключаться через stdio:

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp",
      "transport": "stdio"
    }
  }
}

После запуска клиент будет общаться с сервером через stdio и автоматически обнаружит все 40 инструментов.

Список инструментов (40)

Сгруппированы по доменам. Каждый инструмент возвращает единый контракт вывода: успех { ok: true, ...data }, ошибка { ok: false, error: { code, message } }.

system (4)

fs_read (3)

fs_write (6)

text (6)

search (3)

process (2)

shell_exec (1)

env (3)

net (4)

pkg (2)

git (6)

⚠️ Предупреждение безопасности

Нет песочницы, полные права.

Данный сервер выполняет все операции с полными правами запустившего его пользователя, эквивалентно голому shell. fs_rm может удалить любой доступный файл, shell_exec может выполнить любую команду, process_kill может завершить любой доступный процесс, fs_write может перезаписать любой доступный файл.

Используйте только в доверенной среде:

• Подключайтесь только к доверенному ИИ-клиенту

• Не открывайте доступ в общей/многопользовательской среде

• Перед операциями с чувствительными каталогами (системные, домашняя папка пользователя) требуйте подтверждения

• В производственной среде рекомендуется изоляция на уровне ОС (выделенная учётная запись с низкими правами, контейнер, chroot и т.д.)

Этот проект не предоставляет никакой песочницы, изоляции прав, чёрных списков команд или ограничений путей. Весь контроль доступа зависит от прав операционной системы.

Разработка

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 测试
npm test

# 测试（watch 模式）
npm run test:watch

# 覆盖率（阈值：lines/functions/statements ≥ 85%，branches ≥ 70%）
npm run coverage

# 构建
npm run build

# 开发模式（watch 构建）
npm run dev

Сборка создает dist/index.js (упаковано с помощью tsup, ESM).

Структура проекта

src/
  index.ts          # 入口：启动 stdio server
  server.ts         # MCP Server 创建与工具分发
  registry.ts       # 工具注册表（注册全部 40 个工具）
  contract/         # 输出契约与错误码
  encoding/         # 编码检测（GBK/UTF-8）
  tools/            # 40 个工具实现，按域分文件
tests/
  server.test.ts    # server 单元测试
  integration/      # 集成测试（Client + InMemoryTransport）
  tools/            # 各工具单元测试
  contract/         # 契约测试
  encoding/         # 编码测试

Лицензия

MIT