win-shell-mcp

AI 原生跨平台命令抽象层 —— 以 MCP Server 形式提供 58 个确定性工具，替代裸 shell 调用，统一极简 JSON 输出，处理 Windows 路径/编码/引号差异。同时以原生 Cordis 插件（. / ./core / ./plugin 多入口）进入 DSH，按 MCP 标准注解做并发分类。

为什么

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

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

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

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

win-shell-mcp 用 58 个确定性工具替代常见 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）

安装

# 全局安装
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 通信，自动发现全部 58 个工具。

DSH / Cordis 插件入口

除 MCP Server 外，本包还以原生 Cordis 插件形式进入 DeepSeek Harness (dsh)。多入口：

• . → dist/index.js：MCP stdio server（shebang）

• ./core → dist/core.js：通用核心（服务/注册表，无 dsh 依赖）

• ./plugin → dist/plugin.js：Cordis 插件（name + apply(ctx, config)），把 58 工具全量投影到 ctx.tools.defineTool，支持 config.exclude 按名裁剪

并发分类以 MCP 标准 ToolAnnotations.readOnlyHint 为单一事实源（ADR-0014）：只读工具投影为 isConcurrencySafe；参数级例外（当前仅 git_stash action:'list'）走插件层小覆盖表放行并发，其余变更工具默认独占（fail-closed）。@deepseek-ai/dsh-tools / @deepseek-ai/cordis 为 optional peer dep，约定最小宿主契约类型，不硬依赖。

环境变量

部署面共用小节，现有四个变量：工具白名单 WIN_SHELL_TOOLS、懒加载开关 WIN_SHELL_LAZY、输出截断阈值 WIN_SHELL_TRUNCATE、相对路径基准 WIN_SHELL_CWD。均只在 MCP stdio 入口读取；DSH 插件面对应 config.exclude / config.cwd，不读本节变量。

WIN_SHELL_TOOLS —— 工具白名单（MCP stdio 入口）

逗号分隔的工具正名，仅暴露列出的工具，其余不注册：

# 仅暴露 git 流水线所需工具（ListTools 固定开销随子集规模下降）
WIN_SHELL_TOOLS=git_status,git_add,git_commit,git_push win-shell-mcp

• 默认行为不变：未设置或空串 = 全量暴露全部工具；

• 解析规则：逐项 trim、忽略空段、重复项去重；

• 别名随正名共进退：写 fs_list 则其别名 ls/list_directory 一起进退；别名本身不可写入白名单（误写别名按未知条目处理）;

• fail-fast：含未知条目时启动即失败，错误信息列出全部非法条目原文；不做「忽略未知项」的宽容模式；

• 调用被裁工具返回「未在当前部署暴露（WIN_SHELL_TOOLS）」，与拼错工具名的 Unknown tool: X 明确区分；batch_run 步骤引用被裁工具同样该步失败并短路；

• 作用范围：MCP stdio 入口。dsh 插件面不读取本变量（沿用既有 config.exclude）。

WIN_SHELL_LAZY —— 懒加载开关（MCP stdio 入口）

# 首次 ListTools 只返回 3 个导航/编排 meta，按需取域明细后再照常调用
WIN_SHELL_LAZY=1 win-shell-mcp

• 语义无歧义：仅精确等于 1 启用；缺省、空串及一切其他值（0、true、带空白等）均为全量模式，不做宽容变体；

• 懒模式列出面：ListTools 恰返回 tool_groups / list_domain_tools / batch_run 三个 meta——先看域概览，再按需取目标域明细；

• 调用不设门禁：未在列出面的工具照常可调用（加载只是信息获取、不是授权），不会因裁剪列出而得到 Unknown tool；

• 运行期稳定：注册集不变，不发 listChanged 通知，模式切换无需调整提示词；

• 与白名单正交可组合：两者同设时白名单先过滤工具集，域概览/明细只反映过滤后集合（被裁空的域不出现）；懒模式下 meta 三件套豁免白名单恒列入恒可调，纯白名单模式（不设本变量）下 meta 照常受约束；

• 作用范围：MCP stdio 入口。dsh 插件面不读取本变量。

WIN_SHELL_TRUNCATE —— 输出截断阈值（MCP stdio 入口）

WIN_SHELL_TRUNCATE=800 win-shell-mcp

• 长内容截断的字符上限，正整数；未设置或空串 = 默认 2000；

• fail-fast：0、负数、非整数、非数字一律启动失败并点名变量与非法值原文， 不静默降级。

WIN_SHELL_CWD —— 相对路径基准（MCP stdio 入口）

WIN_SHELL_CWD=/d/work/space/my-repo win-shell-mcp

• 决定各工具 path / cwd 参数缺省时的解析起点：给了非空值就用该值，否则回落到 本基准；pwd 报出的也是这个目录；

• 未设置 = 行为不变：基准实时取进程 process.cwd()（不快照，chdir 照常生效）；

• 值是纯字符串，不校验目录是否存在（基准目录可能稍后才创建）；

• 同一进程内重复设置为不同值直接抛错：基准是进程级唯一值，静默取其一会让另一路 调用把文件写到意料外的目录；

• DSH 插件面对应 config.cwd（不读本变量）：WShell 三模式的 preset 写成 cwd: !!js process.env.DSH_CWD ?? process.cwd()，与提示词里的 {{cwd}} 同源—— 模型据此不必再花一轮调 pwd 探路。

工具清单（59 个）

AI 建立工具概览优先读 docs/ai-tool-cheatsheet.md（按 15 命令域分节的四列表格：正名｜一句话用途｜关键参数｜别名）。

按域分组。每个工具返回统一输出契约：成功 { ok: true, ...data }，失败 { ok: false, error: { code, message } }。

system（4）

fs 只读（4）

fs 变更（6）

find（1）

text（7）

search（3）

process（2）

shell_exec（1）

run_command（1）

env（3）

net（7）

pkg（2）

git（11）

core（2）

hash（1）

json（1）

archive（2）

meta（1）

⚠️ 安全说明

无沙箱，全权限。

本 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 ≥ 84%）
npm run coverage

# 构建
npm run build

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

构建产物为多入口 ESM（tsup）：dist/index.js（MCP stdio，带 shebang）、dist/core.js、dist/plugin.js。

CHANGELOG 维护约定

发版时 CHANGELOG.md 条目从 git log 的 commit message 汇总提炼，不要求回顾全量 diff：

1. 基线：自上个版本标签起（仓库尚无标签时，以最近一次版本提交为基线）；

2. 按 Keep a Changelog 的 Added / Changed / Fixed 分类，并为相关条目补 ADR / 工单交叉引用；

3. 配套要求：commit message 须自带完整主题与 ADR/工单引用（本仓库现有 commit 风格已满足，本约定只是固化现状），使提炼有据可依。

项目结构

src/
  index.ts          # 入口①：启动 MCP stdio server
  server.ts         # MCP Server 创建与工具分发
  core.ts           # 入口②：通用核心（服务/注册表，无 dsh 依赖）
  plugin.ts         # 入口③：Cordis 插件（apply → ctx.tools），并发分类 + config.exclude
  registry.ts       # 工具注册表（注册全部 58 个工具 + annotations）
  contract/         # 输出契约与错误码
  encoding/         # 编码检测（GBK/UTF-8）
  tools/            # 58 个工具实现，按域分文件
tests/
  server.test.ts    # server 单元测试
  plugin.test.ts    # 插件投影测试
  plugin-integration.test.ts  # 插件 + DSH 环境冒烟
  tools/            # 各工具单元测试 + 并发分类/guard 防漂移护栏
  contract/         # 契约测试
  encoding/         # 编码测试

License

MIT