Skip to main content
Glama
dsh-mcp-safe-tools

dsh-mcp-safe-tools

by whatxin7

# dsh-mcp-safe-tools

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

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


里面有什么

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

入口

暴露的工具

干什么

src/mcp-web-search-safe.js

web_search、web_fetch

只读联网:搜索优先走与 DSH 同一条 DeepSeek 联网搜索,失败回退百度 → 360 → Bing;抓取只允许 http/https

src/mcp-host-server.js

snowluma_status

只读探活:网关在不在线、登录的是哪个号。故意没有启停进程的能力

src/mcp-snowluma-safe.js

QQ 相关工具(按工具组开关)

消息/表情/语音/空间等,默认只挂 core + memory 两组

src/safe-fetch.js

—

SSRF 防护核心:DNS 全解析检查、逐跳重定向校验、限量读取

src/web-search.js

—

四个后端 + 缓存 + 请求间隔,纯函数解析可直接测

src/tool-groups.js

—

工具分组与开关状态(省 context 的手段)

src/md-to-plain.js / sensitive.js / media-out.js

—

Markdown 降级、出站脱敏正则、媒体白名单

Related MCP server: FastMCP Gateway

安装

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 的能力取决于网关支持的动作;网关不在线时工具会返回可操作的提示,而不是静默失败。

项目家族

项目

对应成本条目

dsh-mcp-safe-tools(本仓库)

能力扩展(视觉 / 搜索 / 语感)

dsh-token-meter

用量与成本核算

dsh-qq-access

好友 / 白名单 / 权限

dsh-qq-voice

语音 / 唱歌 / 音色

dsh-qq-stickers

表情包 / 斗图

dsh-session-link

联通会话 / 行为调优

dsh-persona-kit

人格 / 角色卡

qq-bridge

桥接内核(旗舰仓库)

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to run Google-first web searches with Bing and Google News fallbacks, and to fetch web pages as markdown, text, or raw HTML through an enterprise proxy with corporate TLS validation. Provides proxy, TLS, browser, and connectivity diagnostics without requiring search-provider API keys.
      3
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients and agents to run structured web searches and fetch web pages as Markdown through a search/fetch API, with rate limiting, retry/backoff, request deadlines, and private-address blocking for safer agent use.
      2
      81 npm
      MIT