内容
# 获取MCP服务器
用于LLMs的高效网络层。通过在上下文窗口中清理网页和API数据，**降低73–87%**的令牌消耗。
无需API密钥 — 搜索由DuckDuckGo提供支持。
## 为什么
当LLM获取URL或调用API时，大部分响应是噪音 — 导航栏、脚本、跟踪像素、模板化API URL、空字段、重复子对象。您为所有这些支付令牌、延迟和减少推理空间。
Fetch MCP位于代理和网络之间。它剥去噪音，只返回重要的内容，并让代理按需深入具体细节。
## 工作原理
```
代理调用 smart_fetch(url)
│
▼
┌─────────┐
│ 获取 │
└────┬─────┘
│
HTML ▼ JSON ▼
┌──────────────┐ ┌──────────────────────┐
│ → Markdown │ │ 剥去URL模板 │
│ 剥去噪音 │ │ 删除空值/空值 │
│ 73%节省 │ │ 消除子对象重复 │
└──────────────┘ │ 基于模式的模式 │
│ 87%节省 │
└──────────────────────┘
```
对于JSON，默认行为是**基于模式**：大型数组返回结构 + 2个样本项，而不是所有数据。然后，代理使用`jsonpath`获取所需的内容。
```
1. smart_fetch("https://api.github.com/orgs/python/repos")
→ { _schema: {id: int, name: string, ...}, _count: 30, _sample: [...2 items] }
2. smart_fetch("https://api.github.com/orgs/python/repos", jsonpath="$[*].name")
→ ["cpython", "mypy", "typeshed", ...]
```
## 令牌节省
运行 `uv run python scripts/benchmark.py` 以重现。来自真实端点的结果：
### HTML → Markdown
| 网页 | 原始令牌 | 优化后 | 节省 |
|------|-----------|-----------|-------|
| GitHub 博客 | 92,352 | 26,459 | 71% |
| Hacker News | 11,790 | 4,237 | 64% |
| MDN — JavaScript | 51,417 | 8,855 | 83% |
| BBC 新闻 | 116,111 | 27,207 | 77% |
| Rust 语言 | 5,107 | 1,163 | 77% |
| Go 包 — net/http | 121,427 | 55,383 | 54% |
| Python 文档 — asyncio | 6,692 | 1,473 | 78% |
| Socket.dev — Axios 泄露 | 138,981 | 23,788 | 83% |
| **总计** | **543,877** | **148,565** | **73%** |
### JSON → 基于模式
| 端点 | 原始令牌 | 精简后 | 基于模式 | 最佳 |
|----------|-----------|--------|-------------|------|
| GitHub API — 仓库 | 16,518 | 7,055 | 2,474 | **85%** |
| GitHub API — 问题 | 20,790 | 16,690 | 3,785 | **82%** |
| JSONPlaceholder — 文章 | 8,761 | 8,761 | 315 | **96%** |
| JSONPlaceholder — 待办事项 | 8,240 | 8,240 | 202 | **98%** |
| JSONPlaceholder — 用户 | 1,839 | 1,839 | 529 | **71%** |
| JSONPlaceholder — 评论 | 492 | 479 | 330 | **33%** |
| npm — typescript | 1,750 | 1,745 | n/a | **0%** |
| OpenLibrary — 搜索 | 1,646 | 1,640 | n/a | **0%** |
| **总计** | **60,036** | — | **11,020** | **82%** |
在Sonnet定价（$3/M）下，每批次节省 **$1.33**。在Opus定价（$15/M）下，每批次节省 **$6.66**。
## 工具
| 工具 | 功能 |
|------|-------------|
| [`smart_fetch`](#smart_fetch) | 获取任何URL — 自动优化HTML（→ markdown）和JSON（→ 基于模式） |
| [`browser_fetch`](#browser_fetch) | 使用Playwright/Chrome获取JavaScript渲染的页面 |
| [`web_search`](#web_search) | 通过DuckDuckGo搜索网页，无需API密钥 |
| [`css_query`](#css_query) | 获取页面，返回仅匹配CSS选择器的元素 |
| [`pdf_fetch`](#pdf_fetch) | 获取PDF URL并返回其文本内容（需要`pdfminer.six`） |
| [`optimize_json`](#optimize_json) | 优化任何JSON数据块 — 在其他MCP服务器的输出上使用 |
### `smart_fetch`
获取URL并自动检测内容类型：
- **HTML** — 剥去导航、广告、脚本和跟踪。转换为干净的markdown。
- **JSON数组（5+项）** — 返回模式 + 2个样本项。使用`jsonpath`深入获取。
- **JSON对象/小数组** — 精简空值，剥去URL模板，消除重复。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串 | *必填* | 要获取的URL |
| `jsonpath` | 字符串 | `None` | 用于提取特定字段的JSONPath（例如 `$[*].name`，`$[?@.id==42]`） |
| `max_depth` | 整数 | `5` | JSON嵌套深度限制，超过后转换为点表示法 |
| `extract_metadata` | 布尔值 | `False` | 包含YAML前置信息，附带页面元数据（仅限HTML） |
| `max_chars` | 整数 | `20000` | 输出的最大字符数（1,000–100,000） |
| `headers` | 字典 | `None` | 可选的HTTP头部（例如 `{"Authorization": "Bearer token"}`） |
| `use_cache` | 布尔值 | `True` | 如果可用，返回缓存的响应（按URL + 参数的TTL范围） |
| `ttl` | 整数 | `1800` | 缓存TTL（秒），范围60–86400 |
### `browser_fetch`
使用Playwright/Chrome获取URL，等待渲染的页面，将最终HTML转换为markdown。
用于阻止简单HTTP客户端或需要JavaScript渲染的页面。它 **不**绕过CAPTCHA；使用有头模式时，需要人类完成挑战或登录后提取。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串 | *必填* | 要获取的URL |
| `selector` | 字符串 | `None` | 可选的CSS选择器，从渲染的页面中提取 |
| `wait_ms` | 整数 | `3000` | `DOMContentLoaded`后等待的毫秒数 |
| `timeout_ms` | 整数 | `30000` | 导航超时毫秒数 |
| `headed` | 布尔值 | `False` | 打开可见的浏览器窗口，进行手动CAPTCHA/登录 |
| `extract_metadata` | 布尔值 | `False` | 包含YAML前置信息，附带页面元数据 |
| `max_chars` | 整数 | `20000` | 输出的最大字符数（1,000–100,000） |
| `headers` | 字典 | `None` | 注入浏览器上下文的可选HTTP头部 |
### `web_search`
通过DuckDuckGo搜索网页。返回结果为markdown列表。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `query` | 字符串 | *必填* | 搜索查询 |
| `max_results` | 整数 | `10` | 结果数量（1–20） |
| `region` | 字符串 | `"wt-wt"` | 地区代码（`"us-en"`，`"wt-wt"`表示全局） |
### `css_query`
获取页面，返回仅匹配CSS选择器的内容。使用时，您确切知道需要页面哪一部分（价格表、文章正文、特定`div`）。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串 | *必填* | 要获取的URL |
| `selector` | 字符串 | *必填* | CSS选择器（例如 `#pricing-table`，`.product-card`，`article`） |
| `max_chars` | 整数 | `20000` | 输出的最大字符数（1,000–100,000） |
| `use_cache` | 布尔值 | `True` | 如果可用，返回缓存的响应 |
| `ttl` | 整数 | `1800` | 缓存TTL（秒），范围60–86400 |
### `pdf_fetch`
获取提供PDF的URL，返回其文本为纯markdown。如果URL不返回PDF，则回退到HTML→markdown。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串 | *必填* | PDF文档的URL |
| `pages` | 字符串 | `None` | 要提取的页面范围，例如 `"1-5"` 或 `"3"`。默认：所有页面。 |
| `headers` | 字典 | `None` | 可选的HTTP头部（例如 `{"Authorization": "Bearer token"}`） |
| `max_chars` | 整数 | `20000` | 输出的最大字符数（1,000–100,000） |
### `optimize_json`
优化任何JSON数据块 — 来自其他MCP服务器、API响应或文件。在整个MCP堆栈中用于减少令牌使用。
接受原始JSON字符串 **或文件路径**。当MCP工具响应太大，Claude保存到文件时，直接传递文件路径。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `data` | 字符串 | *必填* | 原始JSON字符串，或JSON文件的路径 |
| `jsonpath` | 字符串 | `None` | 用于提取特定字段的JSONPath |
| `max_depth` | 整数 | `5` | 扁平化前的最大嵌套深度 |
| `max_chars` | 整数 | `20000` | 输出的最大字符数（1,000–100,000） |
**与其他MCP服务器的典型工作流程：**
```
1. 调用 mcp__github__list_pull_requests → 代理获取大型JSON响应
2. 调用 optimize_json(data=<response>) → 模式 + 2个样本，令牌减少85%
3. 调用 optimize_json(data=<response>, jsonpath="$[?@.state=='open'].title") → 正好需要的内容
```
### JSON优化管道
由`smart_fetch`（在JSON URL上）和`optimize_json`（在任何JSON数据块上）应用：
| 步骤 | 功能 | 影响 |
|------|-------------|--------|
| 基于模式的模式 | 大型数组 → 结构 + 2个样本 | 对列表端点影响巨大 |
| URL模板剥去 | 删除 `forks_url`，`keys_url{/key_id}` 等 | 约30个键/对象，REST API中 |
| 空值/空值删除 | 剥去 `null`，`""`，`[]`，`{}` | 中等 |
| 子对象重复消除 | 相同的嵌套字典（例如 `owner`）只提取一次 | 对组织/用户API影响巨大 |
| 深度扁平化 | 字典超过 `max_depth` → 点表示法键 | 防止失控的嵌套 |
| JSONPath深入获取 | 仅在后续调用中提取匹配的字段 | 精确到手术级别 |
## 命令行界面
获取器和优化器也可作为独立的命令行界面，用于shell管道、脚本和钩子。
```bash
# 智能获取任何URL
uv run fetch-mcp smart_fetch https://example.com
# 智能获取JSON并使用JSONPath提取特定字段
uv run fetch-mcp smart_fetch https://api.github.com/orgs/python/repos --jsonpath '$[*].name'
# 浏览器获取JavaScript渲染或HTTP客户端阻止的页面
uv run fetch-mcp browser_fetch https://example.com
# 打开可见的浏览器进行手动CAPTCHA/登录，然后等待提取
uv run fetch-mcp browser_fetch https://example.com --headed --wait-ms 30000
# 获取PDF并提取其文本
uv run fetch-mcp pdf_fetch https://example.com/paper.pdf
# 提取PDF中的特定页面
uv run fetch-mcp pdf_fetch https://example.com/report.pdf --pages 1-5
# 优化stdin中的任何JSON
curl -s https://api.github.com/orgs/python/repos | uv run fetch-mcp optimize
# 提取特定字段的JSONPath
cat response.json | uv run fetch-mcp optimize --jsonpath '$[*].name'
# 控制嵌套深度
echo '{"deep": {"nested": {"data": 1}}}' | uv run fetch-mcp optimize --max-depth 2
# 查看节省报告
uv run fetch-mcp report
```
### 节省跟踪
每次调用`optimize_json`、`smart_fetch`和命令行界面都会将前后字符数记录到 `~/.local/share/fetch-mcp/savings.jsonl`。查看累计报告：
```bash
uv run fetch-mcp report
```
```
来源 调用 原始字符 优化字符 节省 %
------------------------------------------------------------------------------------
optimize_json 12 284,103 41,220 242,883 85.5%
smart_fetch:https://api.gith 3 59,986 24,823 35,163 58.6%
hook:mcp__jira__jira_search 5 93,052 93,052 0 0.0%
------------------------------------------------------------------------------------
总计 20 437,141 159,095 278,046 63.6%
```
`hook:*` 条目跟踪原始MCP响应大小，优化前。`optimize_json` 条目跟踪实际节省。
使用 `REQUEST_MCP_SAVINGS_LOG=/custom/path.jsonl` 覆盖日志路径。
## 安装
无需本地克隆 — 直接从GitHub使用 [uv](https://docs.astral.sh/uv/)：
```bash
uvx --from git+https://github.com/micaelmalta/fetch-mcp.git fetch-mcp
```
或本地克隆以进行开发：
```bash
git clone https://github.com/micaelmalta/fetch-mcp.git && cd fetch-mcp
uv sync --group dev
```
作为Claude技能安装：
```bash
curl -fsSL https://raw.githubusercontent.com/micaelmalta/fetch-mcp/main/install.sh | bash
```
安装不同分支或标签：
```bash
curl -fsSL https://raw.githubusercontent.com/micaelmalta/fetch-mcp/main/install.sh | REQUEST_MCP_REF=your-branch-or-tag bash
```
## 集成
### 克劳德代码
**1. 添加MCP服务器：**
```bash
claude mcp add fetch-mcp -- uvx --from git+https://github.com/micaelmalta/fetch-mcp.git fetch-mcp
```
**2. （可选）通过 `CLAUDE.md` 指示代理：**
```markdown
## JSON优化
当任何MCP工具（GitHub，Jira，Datadog，Confluence等）返回大于〜50行的JSON响应时，请在推理之前将其传递给fetch-mcp的`optimize_json`工具。您可以直接传递原始JSON或文件路径。使用jsonpath深入获取具体字段，而不是消耗整个有效载荷。
```
**3. （可选）用于日志记录和推送通知：
添加至 `~/.claude/settings.json` 以自动记录MCP响应大小并提醒代理优化：
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "mcp__github__*|mcp__jira__*|mcp__datadog__*|mcp__confluence__*",
"hooks": [
{
"type": "command",
"command": "jq -r '{tool: .tool_name, chars: (.tool_response | tostring | length)}' | jq -r '\"\\(.tool) \\(.chars)\"' | { read -r tool chars; mkdir -p ~/.local/share/fetch-mcp; echo \"{\\\"ts\\\":\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\",\\\"source\\\":\\\"hook:$tool\\\",\\\"raw_chars\\\":$chars,\\\"opt_chars\\\":$chars,\\\"saved_chars\\\":0,\\\"saved_pct\\\":0}\" >> ~/.local/share/fetch-mcp/savings.jsonl; echo \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PostToolUse\\\",\\\"additionalContext\\\":\\\"MCP响应大小为${chars}字符。请将管道传递给fetch-mcp的optimize_json以减少令牌使用。您可以直接传递原始JSON或文件路径。\\\"}}\"; }"
}
]
}
]
}
}
```
根据需要添加或删除MCP前缀。
### 光标
**1. 添加到 `.cursor/mcp.json`** （项目）或 `~/.cursor/mcp.json` （全局）：
```json
{
"mcpServers": {
"fetch-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/micaelmalta/fetch-mcp.git", "fetch-mcp"]
}
}
}
```
**2. 添加到光标规则** （设置 > 规则，或 `.cursorrules`）：
```
当任何MCP工具返回大型JSON响应（>50行）时，请将其传递给fetch-mcp的optimize_json工具。在推理之前。您可以直接传递原始JSON或文件路径。使用jsonpath参数深入获取具体字段。
```
### 开放代码
**1. 添加到 `.opencode.json`** （项目）或 `~/.opencode.json` （全局）：
```json
{
"mcpServers": {
"fetch-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/micaelmalta/fetch-mcp.git", "fetch-mcp"]
}
}
}
```
**2. 添加到 `.opencode.md`** （项目内存）：
```markdown
## JSON优化
当任何MCP工具（GitHub，Jira，Datadog，Confluence等）返回大于〜50行的JSON响应时，请在推理之前将其传递给fetch-mcp的`optimize_json`工具。您可以直接传递原始JSON或文件路径。使用jsonpath深入获取具体字段，而不是消耗整个有效载荷。
```
### 克劳德桌面版
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"fetch-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/micaelmalta/fetch-mcp.git", "fetch-mcp"]
}
}
}
```
### MCP检查器（开发）
```bash
uv run mcp dev fetch_mcp/server.py
```
### 集成摘要
| | 克劳德代码 | 光标 | 开放代码 | 克劳德桌面版 |
| --- | --- | --- | --- | --- |
| **添加MCP** | `claude mcp add` | `.cursor/mcp.json` | `.opencode.json` | `claude_desktop_config.json` |
| **指示代理** | `CLAUDE.md` | `.cursorrules` | `.opencode.md` | 服务器说明（内置） |
| **自动钩子和日志记录** | `PostToolUse` 钩子 | 不支持 | 不支持 | 不支持 |
| **命令行管道** | `\| uv run fetch-mcp optimize` | 不适用 | 不适用 | 不适用 |
## 基准测试
```bash
uv run python scripts/benchmark.py
```
获取真实页面和API端点，计算令牌与`tiktoken`（cl100k_base），并比较HTML和JSON原始输出与优化输出的成本估算。
## 依赖
| 包 | 用途 |
| --- | --- |
| [mcp](https://github.com/modelcontextprotocol/python-sdk) | 快速MCP服务器框架 |
| [httpx](https://www.python-httpx.org/) | 异步HTTP客户端 |
| [html-to-markdown](https://github.com/nichochar/html-to-markdown) | 基于Rust的HTML → Markdown（〜200 MB/s） |
| [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/) | CSS选择器提取 |
| [jsonpath-ng](https://github.com/h2non/jsonpath-ng) | JSONPath查询支持 |
| [ddgs](https://github.com/deedy5/ddgs) | DuckDuckGo搜索（无需API密钥） |
| [truststore](https://github.com/sethmlarson/truststore) | SSL的系统证书存储 |
| [pdfminer.six](https://github.com/pdfminer/pdfminer.six) | `pdf_fetch`的PDF文本提取 |
| [tiktoken](https://github.com/openai/tiktoken) | 令牌计数（仅限开发，用于基准测试） |
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器