内容
# agent-web-fetch
** | [简体中文](./README.zh-CN.md)
一款**免费、无限制的网页读取器**，适用于支持MCP协议的代理客户端（Claude Code、ZCode，以及任何支持模型上下文协议的客户端）。它接受代理客户端已经持有的URL，并以干净、适合模型的Markdown格式返回页面的主要内容 — 这是许多代理客户端中内置的付费、限速的抓取工具的直接替代品。
- **免费无限制** — 在您的机器上通过普通的HTTP运行。无需API密钥，无需配额，无需每月限制，无需429错误。
- **可靠启动** — 作为单个静态链接的二进制文件发布。无需`npx`，无需安装运行时，无需启动时联网。它每次连接都成功。
- **几乎零维护** — 静态HTTP抓取 + Readability提取算法（与Firefox Reader View使用的相同引擎）。无需无头浏览器累赘，无需与反检测技术进行对抗。
## 功能
给它一个URL，获取页面的主要文章，以Markdown格式返回：
```
fetch({ "url": "https://example.com" })
→ "# 示例域名\n\n此域名用于文档示例..."
```
它运行类似Readability的提取，以隔离主要文章并剥去模板（导航、页脚、脚本）。当页面没有明确的主要文章（列表页面、仪表盘）时，它会退回到完整的文档，以确保您永远不会得到空输出。图像URL在Markdown中被保留。
### 工具参数
| 参数 | 必需 | 默认值 | 描述 |
| --------------- | -------- | --------- | ---------------------------------------------------------------- |
| `url` | 是 | — | 要抓取的URL。必须是绝对的`http`/`https` URL。 |
| `timeout` | 否 | `30s` | 每个请求的超时时间，以Go的持续时间字符串表示（例如`45s`）。 |
| `return_format` | 否 | `markdown`| `markdown` 或 `text`。 |
| `no_cache` | 否 | `false` | 绕过内存缓存，强制重新抓取。 |
### 功能限制
- **无网页搜索/发现** — 它抓取您给它的URL；它不查找页面。
- **无JavaScript渲染** — 需要JavaScript才能生成内容的页面会返回稀疏的结果。（这是v1版本的有意权衡，以实现几乎零维护。）
- **无摘要/翻译/图像描述** — 它返回内容，不处理内容。无需付费模型调用。
- **无身份验证内容** — 它匿名抓取；登录墙页面超出了其范围。
## 安装
### 1. 下载适用于您平台的二进制文件
从最新版本中获取正确的文件：
| 平台 | 文件 |
| ----------------- | ------------------------------------- |
| Windows | `agent-web-fetch-windows-amd64.exe` |
| macOS (Apple Silicon) | `agent-web-fetch-darwin-arm64` |
| macOS (Intel) | `agent-web-fetch-darwin-amd64` |
| Linux | `agent-web-fetch-linux-amd64` |
无需安装程序，无需安装运行时（无需Node、Python或Go）。
**文件放置位置：** 每个平台都有推荐的按用户位置 — 无需管理员权限，是用户安装程序的惯例位置：
| 平台 | 推荐位置 |
| -------- | -------------------- |
| Windows | `%LOCALAPPDATA%\Programs\agent-web-fetch\agent-web-fetch.exe` |
| macOS / Linux | `~/.local/bin/agent-web-fetch` |
也就是说，MCP实际上并不关心文件位于哪里 — 它通过配置文件中的绝对路径启动二进制文件，因此您可以将其放在具有读取/执行权限的任何位置（无需添加到`PATH`）。只需不要将其放入其他用户的目录或需要管理员权限的系统文件夹中。以下示例使用推荐的位置；如果您将其放在其他位置，请替换路径。
### 2. 在您的MCP客户端中注册它
这是一个标准的**stdio MCP服务器**：它没有参数，也没有环境要求。在每个MCP客户端中，配置条目都是相同的想法 — 将`command`指向二进制文件的绝对路径，将`args`留空：
```json
"chhsich-web-fetch": {
"type": "stdio",
"command": "/绝对路径/to/agent-web-fetch",
"args": []
}
```
不同客户端的区别在于**位置**和确切的键名。常见客户端的具体示例：
**ZCode** — 将条目添加到其MCP服务器配置（一个以服务器名称为键的扁平对象，无外部包装）：
```json
{
"chhsich-web-fetch": {
"type": "stdio",
"command": "C:/Users/<用户名>/AppData/Local/Programs/agent-web-fetch/agent-web-fetch.exe",
"args": []
}
}
```
**Claude Code** — `~/.claude.json`（或Windows上的`%USERPROFILE%\.claude.json`），其中服务器位于`mcpServers`键下：
```json
{
"mcpServers": {
"chhsich-web-fetch": {
"type": "stdio",
"command": "C:/Users/<用户名>/AppData/Local/Programs/agent-web-fetch/agent-web-fetch.exe",
"args": []
}
}
}
```
或通过CLI（执行相同的操作）：`claude mcp add chhsich-web-fetch "C:/Users/<用户名>/AppData/Local/Programs/agent-web-fetch/agent-web-fetch.exe"`
**任何其他stdio MCP客户端** — 查找它保存MCP服务器列表的位置（JSON/ YAML配置文件、设置UI等），并添加一个条目：类型`stdio`，`command` = 二进制文件的绝对路径，`args` = `[]`。这就是整个合同 — 没有其他参数需要设置。
> **替换路径：** 上面的示例使用推荐的安装位置，以`<用户名>`作为占位符 — 替换为您实际的用户名（或使用`%LOCALAPPDATA%`如果您的客户端扩展环境变量）。如果您将二进制文件放在其他位置，请调整路径。
> **命名：** 键（上面的`chhsich-web-fetch`）是您客户端的服务器标签 — 您可以随意命名它。工具暴露的名称为`fetch`，因此模型调用`fetch(...)`。两个服务器暴露的工具都命名为`fetch`，只要服务器键不同（服务器名称是命名空间），它们就不会冲突。
> **路径提示（Windows）：** 使用包含`.exe`的完整绝对路径。在JSON中，正斜杠有效，避免反斜杠转义。
> **Windows SmartScreen注意：** 发布二进制文件未签名，因此Windows可能会在第一次运行它时显示“Windows保护了您的PC”的提示。单击**更多信息 → 仍然运行**。这是未签名二进制文件的预期行为，仅发生一次。
在编辑配置后重启您的客户端。`fetch`工具现在与内置工具一起出现，模型可以像调用其他工具一样调用它。
### 3. 验证它是否有效
在重启您的客户端后，要求模型获取任何公共页面，例如：
> 使用获取工具读取https://example.com
您应该会收到页面的内容，以Markdown格式返回。如果没有返回任何内容或工具丢失，请设置`WEB_FETCH_LOG`（如下），并检查日志文件。
### 4. （可选）启用文件日志记录
默认情况下，服务器是静默的（stdout是MCP传输，必须保持干净）。要将诊断信息写入文件进行故障排除：
将`WEB_FETCH_LOG`环境变量设置为文件路径。日志将追加到那里，永远不会触及stdout。
## 从源代码构建
需要Go 1.22+。
```bash
# 构建所有四个平台的二进制文件到dist/
./build.sh # 任何bash（Git Bash，WSL，Linux，macOS）
# 或者，在unix上使用make：
make release
```
每个二进制文件都是静态链接的（`CGO_ENABLED=0`），没有外部运行时依赖。使用`go test ./...`运行测试套件。
## 工作原理
```
URL → 验证（http/https，绝对）→ HTTP GET（现实的浏览器头部）
→ Readability提取 → markdown → 内存缓存（1小时TTL）
↘ 完整文档备用（永不为空）
```
抓取管道是一个单一的深度模块（`internal/fetch`），通过stdio作为一个MCP工具公开（`internal/mcpserver`）。每个失败（超时，非2xx，错误内容类型，甚至是恢复的恐慌）都会以模型可以读取的结构化错误返回 — 服务器进程永远不会崩溃。
参见`CONTEXT.md`了解项目词汇表，参见`docs/adr/`了解架构决策（MCP + 二进制文件分发，匿名抓取，静态提取，Go，启动可靠性）。
