dsh-mcp-tools · 一个 MCP 服务，多个「干活」工具

把深鲸已有的本地能力（合并文档、比对文档、站点体检、发版检查）用标准 MCP 工具暴露出去，让 Claude Desktop / Cursor / 任何 MCP 客户端直接调用——不用你切终端敲命令，再把输出粘回对话。

不装会怎样

这些工具本来就有 CLI，但 AI 客户端看不见它们：Claude 只能「告诉你怎么敲」，不能自己跑。你会来回切换窗口、复制粘贴路径和报错，一轮下来十分钟没了；批量活儿更是没法让它自己迭代。装上以后，一句「把 docs/ 合并成一份带目录的 docx，然后检查这个仓库能不能发版」，它自己会调工具、看结果、接着做。

Related MCP server: Claude Code MCP Bridge

它做什么

• 一个服务，四个工具，工具再多也不增加服务数：

  工具	干什么	典型参数	写文件吗
  merge_docs	多份 .docx/.md/.txt 合并成一份带目录的 .docx	inputs（文件或目录数组）、out	只写 out
  compare_docs	按段落比对两份文档，给修改/新增/删除与改动预览	a、b	只读（除非给 out）
  site_audit	上线前站点体检：死链、图片体积、SEO、robots/sitemap、混合内容	base 或 dir	不写
  release_check	按仓库规则判断「现在能不能发版」，列阻断与警告	repo、npm	不写

• 不复制业务逻辑：网关只做「校验参数 → 调插件自己的 bin/cli.mjs --json → 整理成人读摘要」。插件升级，网关自动受益；插件里修了 bug，这里立刻生效。

• 一屏能读完的结果：返回「结论 + 关键数据 + 前几条问题」，不把整份 JSON 塞进上下文。

• 错误是结构化的：缺参数、类型不对、插件没装、超时，都返回 {ok:false, error:{code, message}}，不会让服务崩。

• 长任务有超时：默认 120 秒，可传 timeout_ms（上限 600 秒），超时会终止子进程并明确报 timeout。

安装

需要 Node ≥ 20。建议装在用户目录下一个固定位置，四类插件作为同级依赖一起装（这样网关能直接找到它们）：

mkdir -p ~/dsh-mcp-tools && cd ~/dsh-mcp-tools
npm init -y >/dev/null
npm i @deepwhale-cn/dsh-mcp-tools \
      @deepwhale-cn/dsh-doc-merge \
      @deepwhale-cn/dsh-doc-compare \
      @deepwhale-cn/dsh-site-audit \
      @deepwhale-cn/dsh-release-guard

四个工具插件也可以按需只装其中几个：没装的工具被调用时返回 plugin_missing，并告诉你装哪个包，其他工具不受影响。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "dsh-tools": {
      "command": "node",
      "args": ["/Users/yourname/dsh-mcp-tools/node_modules/@deepwhale-cn/dsh-mcp-tools/bin/mcp.mjs"]
    }
  }
}

把 /Users/yourname/... 换成本机真实路径（Windows 用 C:\\Users\\...）。改完重启 Claude Desktop。

Cursor

编辑 ~/.cursor/mcp.json（全局）或项目里的 .cursor/mcp.json：

{
  "mcpServers": {
    "dsh-tools": {
      "command": "node",
      "args": ["/Users/yourname/dsh-mcp-tools/node_modules/@deepwhale-cn/dsh-mcp-tools/bin/mcp.mjs"]
    }
  }
}

不装客户端也能自测

node bin/mcp.mjs --list
node bin/mcp.mjs --call release_check '{"repo":"."}'
node bin/mcp.mjs --call site_audit '{"dir":"./dist","offline":true}'
node bin/mcp.mjs --call merge_docs '{"inputs":["docs"],"out":"./merged.docx"}'
node bin/mcp.mjs --call compare_docs '{"a":"旧版.docx","b":"新版.docx"}'

工具参数

所有工具都接受可选的 timeout_ms（整数，1000–600000，默认 120000）。未知参数会被拒绝（防止拼错参数却静默生效）。

merge_docs

compare_docs

site_audit

release_check

错误约定

工具失败时 MCP 回包里 isError: true，正文是一段 JSON：

{
  "ok": false,
  "tool": "merge_docs",
  "error": {
    "code": "invalid_params",
    "message": "缺少必填参数 inputs",
    "details": ["缺少必填参数 inputs"]
  }
}

边界

• 只在本机跑：stdio 传输，不开端口、不上传任何数据、不内置 key。

• 唯一会联网的是 site_audit——它要访问你要体检的那个站点（只 GET/HEAD，不提交表单、不登录）；默认 offline: true 连外链探测都关掉。release_check 只在 npm: true 时查一次 npm registry。

• 不拼 shell：参数逐个透传给插件 CLI，spawn(..., {shell:false})，不存在命令注入。

• 不写你没指定的地方：merge_docs 只写 out，compare_docs 只在给了 out 时写报告，其余只读。

• 子进程输出有上限（stdout 4 MB / stderr 200 KB），避免异常输出打爆内存。

• 协议：JSON-RPC 2.0 over stdio，支持 initialize / tools/list / tools/call / ping；按行分隔与 Content-Length 帧两种格式都认，回包沿用请求的格式。没有实现 resources / prompts。

已知限制

• 只实现了 tools，没有 resources、prompts、sampling。

• 客户端发 notifications/cancelled 时不会立刻杀子进程，最长等到 timeout_ms。

• 未在 Windows 上实测；路径请用绝对路径。

• 插件必须能被 Node 解析到（装在网关同级 node_modules，或设 DSH_MCP_TOOLS_PLUGIN_ROOT 指向插件目录）。

加一个新工具要多久

十分钟以内，四处改动：lib/plugins.mjs 登记插件包名与 CLI 路径 → lib/tools.mjs 加一条 schema 与 run → lib/format.mjs 加一段摘要 → tests/run.sh 加一条断言。服务数永远是 1。

开发与测试

bash tests/run.sh          # 36 条断言：清单/schema、四种工具、错误路径、JSON-RPC 往返、超时、缺插件

测试完全离线、可重复：站点体检用本地目录 fixture，发版检查用临时仓库，不访问网络。