网页抓取 withlovehub/dsh-webfetch

dsh-webfetch

test

一个零依赖的 webfetch MCP 服务器：获取任意 http(s) URL 并返回干净的内容——文本、简化 Markdown、原始 HTML 或格式化 JSON。专为 DeepSeek Harness（dsh）打造，可与任何支持 stdio 服务器的 MCP 客户端配合使用。

- 零依赖：单个 server.js，手写的 stdio JSON-RPC 2.0——无需 npm install，无 SDK 版本冲突。
- 对模型友好的输出：正文提取（/）、实体解码、绝对链接、图片 alt 文本、分块读取。
- 礼貌且安全：遵守 robots.txt、Cloudflare 挑战重试、SSRF 防护、限制为 5 MiB 的读取。

设计参考

对比了三个现有实现（2026-08），并以零依赖的等效方案采纳了其中有用的部分：

| 来源 | 采纳的设计 |
| 官方 mcp-server-fetch | startIndex 分块读取、遵守 robots.txt、原始模式 |
| OpenCode tool/webfetch.ts | 感知格式的 Accept 请求头、Cloudflare 挑战 → 纯 UA 重试、5 MiB 限制读取 |
| pi-web-access | 正文优先（轻量级 Readability 启发式）、SSRF 防护、相对链接绝对化、图片 alt |

刻意未采纳：@mozilla/readability、turndown、undici、unpdf——无依赖的等效方案已覆盖常见场景。

快速开始

需要 Node.js ≥ 20（使用全局 fetch）。

git clone https://github.com/withlovehub/dsh-webfetch.git
cd dsh-webfetch

Optional but convenient: puts the dsh-webfetch command on your PATH
npm link # or: npm install -g .

node test.js # 32 in-process test cases — all green means your Node is ready

该服务器在 stdio 上使用以换行符分隔的 JSON-RPC 2.0。一旦发布到 npm，一行命令即可运行：npx -y dsh-webfetch。

手动对服务器进行冒烟测试（预期在 stdout 上收到一个 initialize 响应和一个 tools/list 响应）：

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node server.js

PowerShell 等效命令：

@(
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}',
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
) | node server.js

客户端设置

该服务器是一个普通的 stdio MCP 服务器——任何 MCP 客户端都可以使用。在下面选择你的客户端；每个示例都使用 node + server.js 的路径。两个快捷方式能让事情更轻松：
- 路径风格：即使在 Windows 上也使用正斜杠（C:/dev/dsh-webfetch/server.js）——Node 接受它们，而且你能避免 JSON 反斜杠转义。
- 执行 npm link 之后：将 command 设置为 dsh-webfetch，并完全去掉 args。

大多数客户端要求绝对路径；${workspaceFolder} 风格的变量仅在文档说明的地方有效（VS Code）。

DeepSeek Harness

文件：~/.dsh/cordis.patch.yml

- insert:
- id: mcp-webfetch
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: web
transport: stdio
command: node
args:
- '/path/to/dsh-webfetch/server.js'

重启 dsh web；模型将获得 mcp__web__fetch 工具。

Claude Desktop

文件：claude_desktop_config.json（Windows：%APPDATA%\Claude\，macOS：~/Library/Application Support/Claude/，Linux：~/.config/Claude/）。之后重启 Claude。

{
"mcpServers": {
"webfetch": {
"command": "node",
"args": ["C:/path/to/dsh-webfetch/server.js"]
}
}
}

Claude Code

文件：项目根目录下的 .mcp.json，或从 CLI 添加：

claude mcp add webfetch -- node /path/to/dsh-webfetch/server.js

{
"mcpServers": {
"webfetch": {
"type": "stdio",
"command": "node",
"args": ["/path/to/dsh-webfetch/server.js"]
}
}
}

使用 claude mcp list 验证。

Cursor

文件：项目中的 .cursor/mcp.json（或 Cursor Settings → MCP → Add new MCP server）。

{
"mcpServers": {
"webfetch": {
"command": "node",
"args": ["C:/path/to/dsh-webfetch/server.js"]
}
}
}

在 Cursor Settings → MCP 中验证（绿色状态点）。

VS Code Copilot

文件：.vscode/mcp.json —— 支持 ${workspaceFolder} 变量，因此克隆的仓库可以自行配置：

{
"servers": {
"webfetch": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/server.js"]
}
}
}

验证：命令面板 → MCP: List Servers。

OpenCode

文件：opencode.json（项目）或全局配置。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"webfetch": {
"type": "local",
"command": ["node", "/path/to/dsh-webfetch/server.js"]
}
}
}
}

使用 opencode2 mcp list 验证（v1：opencode mcp list）。

其他任何客户端

任何支持 stdio 的 MCP 客户端都可以使用相同的 command + args 形式——该协议是通用的。

工具参数

| 参数 | 类型 | 默认值 | 描述 |
| url | string（必填） | — | 完整 URL，仅限 http/https（拒绝 file://） |
| format | text / markdown / html / json | text | text = 清理后的内容；markdown = 保留链接/标题/图片；html = 原始 HTML；json = 格式化打印的 JSON |
| maxChars | 1000–200000 | 60000 | 本次调用返回的最大字符数 |
| startIndex | 0–10000000 | 0 | 从此字符索引开始获取内容——与 maxChars 搭配使用，可分块读取长页面 |
| timeoutMs | 3000–120000 | 20000 | 请求超时 |

行为

- 主内容优先：如果 / 块的文本占页面的 ≥ 30%，则只返回该块——导航/页脚噪声会被过滤掉（轻量级 Readability）。
- HTML 清理：丢弃 script/style/svg，块级标签转换为换行符，解码实体，提取 。
- Markdown 模式：相对 href/src 会基于最终 URL 转为绝对地址（javascript:/mailto: 降级为纯文本），图片变为 alt，h1–h6 变为 ATX 标题；包裹图片的链接保留 alt 文本。
- JSON API：自动 JSON.parse + 缩进；无效 JSON 返回 isError 并附带预览，而不是静默传递原始文本。
- 二进制：仅返回元数据（status/content-type/bytes）——字节永远不会被送入模型上下文。
- robots.txt：默认遵守（先查 dsh-webfetch 组，再查 组，最长前缀匹配）；被阻止的 URL 返回 isError；结果缓存 30 分钟；设置 DSH_WEBFETCH_IGNORE_ROBOTS=1 可禁用。根据 RFC 9309，空的 Disallow: 表示全部允许。
- Cloudflare 质询：在 403 + cf-mitigated: challenge 时，使用透明 UA 重试一次。
- SSRF 防护：拒绝 metadata.google.internal、169.254.、0.0.0.0。
- 有界读取：每个响应最大 5 MiB（声明限制 → 报错；未声明 → 流式截断）。
- 错误：失败返回 MCP isError: true；诊断信息仅输出到 stderr（stdout 是协议通道）。

已知限制

- 不执行 JavaScript——SPA 返回原始外壳，而不是渲染后的应用。
- 不支持 PDF 提取 / 真正的 Readability / 代理支持（零依赖路线；在实际需要时再添加）。
- href 内含引号的畸形 HTML 会降级为纯文本，而不是崩溃。

许可证

MIT