win-shell-mcp

AI 原生跨平台命令抽象层 —— 以 MCP Server 形式提供 40 个确定性工具，替代裸 shell 调用，统一极简 JSON 输出，处理 Windows 路径/编码/引号差异。

为什么

让 AI 调用 shell 命令是危险且不可靠的：

• 跨平台不一致：Windows 的路径分隔符、编码（GBK）、引号、命令名（del vs rm）与 unix 差异巨大

• 输出难解析：shell 命令输出格式随意，AI 难以可靠提取信息

• 安全风险：裸 shell 允许管道、重定向、命令注入

win-shell-mcp 用 40 个确定性工具替代常见 shell 命令，每个工具：

• 接受结构化 JSON 参数，返回统一 { ok: true, ...data } 或 { ok: false, error: { code, message } }

• 跨平台行为一致（Windows/macOS/Linux 同一份配置）

• 极简输出（默认只含 AI 决策所需最小字段），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 与 server 通信，自动发现全部 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）

⚠️ 安全说明

无沙箱，全权限。

本 server 以运行用户的完整权限执行所有操作，与裸 shell 等价。fs_rm 可删除任意可访问文件，shell_exec 可执行任意命令，process_kill 可终止任意可访问进程，fs_write 可覆盖任意可访问文件。

请仅在信任环境下使用：

• 仅连接到你信任的 AI 客户端

• 不要在共享/多租户环境暴露

• 对敏感目录（系统目录、用户主目录）操作前人工确认

• 生产环境建议配合操作系统级权限隔离（专用低权限账户、容器、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/         # 编码测试

License

MIT