dsh-mcp-safe-tools

# dsh-mcp-safe-tools

一句话：给 agent 联网和发消息的"手"装上护栏 —— 只读搜索/抓取、内网地址一律拦在 DNS 之后、出站前脱敏、媒体只从白名单目录发。

从 qq-bridge 抽出的独立项目，对应成本统计里 「能力扩展（视觉 / 搜索 / 语感）」 这条线。

里面有什么

三个 stdio MCP server + 四组可单独引用的工具模块：

Related MCP server: webshot-mcp

安装

git clone https://github.com/whatxin7/dsh-mcp-safe-tools.git
cd dsh-mcp-safe-tools
npm install
npm test                  # 9 个用例，含两个真实 stdio MCP 握手
cp config.example.json config.json   # 按需改 snowluma / webSearch

装法与别的仓库不同

它不是「装完就有命令」的 CLI，而是被 MCP 客户端（DSH / Claude Desktop / Cursor / Cline）当子进程启动的 server：

# 只想验证它能起来（stdio 握手成功后 Ctrl+C 退出即可）
npx github:whatxin7/dsh-mcp-safe-tools

配置里必须写本机绝对路径（command: node，args: ["/绝对路径/src/mcp-web-search-safe.js"]），因为客户端不会去猜你在哪个目录 clone 的。

Node ≥ 20。测试里的 MCP 用例会真的 spawn 两个 server，走 initialize → tools/list，断言工具清单 —— 不是"看代码猜它能跑"。

接到 DSH / 任意 MCP 客户端

{
  "mcpServers": {
    "web-search-safe": {
      "command": "node",
      "args": ["D:/Work/dsh-mcp-safe-tools/src/mcp-web-search-safe.js"]
    },
    "snowluma-host": {
      "command": "node",
      "args": ["D:/Work/dsh-mcp-safe-tools/src/mcp-host-server.js"]
    }
  }
}

config.json 放在仓库根目录（和 src/ 同级），server 启动时读它；读不到就用默认值起步。

SSRF 防护都防了什么

web_fetch 是整条链路上最像"后门"的东西：模型能构造任意 URL。所以校验必须发生在连接之前，而且必须校验DNS 解析结果，不是字符串。

输入 URL
  ├─ 协议不是 http/https → 拒绝
  ├─ URL 里带 username/password → 拒绝（防 http://user:pass@内网/）
  ├─ DNS 解析全部 A/AAAA 记录
  │    └─ 任一条是内网/环回/链路本地/CGNAT/保留段 → 拒绝（防 DNS rebinding）
  ├─ 选一个地址建连（保留原 Host/SNI，禁止重新解析）
  ├─ 30x 重定向 → 手动跟随，每一跳重新走上面全套校验
  └─ 响应体按字节流限量读取（防超大响应拖死进程）

isPrivateIp() 覆盖：10/8、172.16/12、192.168/16、127/8、0/8、169.254/16、100.64/10、198.18/15、192.0.0/24、224+，以及 IPv6 的 ::1、fc00::/7、fe80::/10、ff00::/8、2001:db8::/32、::ffff: 映射、NAT64 64:ff9b::/96。

调用方补的请求头只能追加非 Host / Content-Length 字段 —— 否则"带 Referer 抓图"就成了改 Host 的 SSRF 跳板。

工具分组（省 context）

工具全挂着最省事，代价是每轮都付 schema 的 token。所以按组挂：

core    看消息、说话、等待、睡觉、表情、发图
memory  轻量记忆
voice / sticker / people / qzone / identity / slang / douyin / media   按需打开

resolveActiveGroups() 决定这一轮挂哪几组，auditGroups(registered) 检查"注册了但没归组"的工具 —— 这类漏网的会在切组时神秘消失。

出站脱敏与媒体白名单

• SENSITIVE_RE：本地路径（C:\...、\\host\share、/home/、/Users/、/etc/…）与 token=xxx / password: xxx 形态，用于往群聊/日志输出前拦一道。

• resolveOutMedia()：只发白名单目录（out/、assets/、audio/、exports/、state/media/）里的相对路径；..、盘符、UNC、URL 一律报错。

• checkOutMedia()：可执行/脚本类扩展名不发；图片有单独的体积上限。

作为库用

import { safeFetch } from 'dsh-mcp-safe-tools/safe-fetch';
import { mdToPlain } from 'dsh-mcp-safe-tools/md';
import { resolveActiveGroups } from 'dsh-mcp-safe-tools/tool-groups';

const { text, finalUrl } = await safeFetch('https://example.com', 50000);

已知边界

• 搜索后端依赖外部服务；DeepSeek 那条要 webSearch 凭据（配置或 DSH 的 .credentials.yaml），没有就走回退链。

• 抓取只做 GET，不提交表单、不带 cookie 会话。

• 不做 JS 渲染：SPA 页面抓到的可能只有骨架（要渲染请用浏览器自动化）。

• mcp-snowluma-safe.js 的能力取决于网关支持的动作；网关不在线时工具会返回可操作的提示，而不是静默失败。

项目家族

English

Three read-only MCP servers plus reusable guards: an SSRF-hardened web_fetch (DNS-result validation, per-hop redirect re-validation, byte-limited reads), a multi-backend web search with parsers, gateway health probing with no process control, and outbound redaction / media allow-listing. 9 tests, including a real stdio MCP handshake.

License

MIT © whatxin7