web-fetch

Web Fetch

所有网页内容的检索都使用 curl（Bash）或内置的 WebFetch 工具。无需 MCP 服务——Claude Code 的原生工具可以覆盖 Fetch MCP 的所有操作，而且控制力更强。

快速参考

Fetch MCP 工具	替代方式	使用场景
fetch_html	curl -s URL	需要原始 HTML 进行解析时
fetch_json	curl -s URL | jq '.'	API 响应、结构化数据
fetch_markdown	WebFetch	可读的页面内容（默认输出为 Markdown）
fetch_txt	curl -s URL 或 WebFetch	提取纯文本

**默认选择：**一般页面内容使用 WebFetch。需要请求头、身份验证、POST 请求体或控制原始格式时使用 curl。

---

WebFetch（内置工具）

WebFetch 工具会获取 URL 并返回整洁的 Markdown 内容。它可以处理由 JavaScript 渲染的页面，剥离导航和模板内容，并返回易读文本。

适用于：文档页面、文章、博客文章、README 文件——以及任何需要可读文本而非原始 HTML 的内容。

限制：不支持自定义请求头、POST 请求体或 Cookie 管理。遇到这些情况请使用 curl。

---

curl 用法模式

获取 HTML

curl -sL "https://example.com/page"

标志	用途
-s	静默模式——不显示进度条
-L	跟随重定向（3xx）
-o file.html	保存到文件，而非标准输出
-I	仅获取请求头（HEAD 请求）
-i	在输出中包含响应头

使用 xmllint 或 python3 获取内容并提取特定元素：

curl -sL "https://example.com" | python3 -c "
from html.parser import HTMLParser
import sys

class TitleParser(HTMLParser):
    def __init__(self):
        super().__init__()
        self.in_title = False
        self.title = ''
    def handle_starttag(self, tag, attrs):
        self.in_title = tag == 'title'
    def handle_data(self, data):
        if self.in_title:
            self.title += data
    def handle_endtag(self, tag):
        if tag == 'title':
            self.in_title = False

p = TitleParser()
p.feed(sys.stdin.read())
print(p.title)
"

获取 JSON

curl -s "https://api.example.com/v1/data" \
  -H "Accept: application/json" | jq '.'

筛选并重塑 JSON 响应：

# Extract specific fields
curl -s "https://api.example.com/users" | jq '.[] | {name, email}'

# Filter by condition
curl -s "https://api.example.com/items" | jq '[.[] | select(.status == "active")]'

# Count results
curl -s "https://api.example.com/items" | jq 'length'

# Get nested value
curl -s "https://api.example.com/config" | jq '.database.host'

获取纯文本

# Strip HTML tags for plain text
curl -sL "https://example.com/page" | python3 -c "
import html.parser, sys

class Stripper(html.parser.HTMLParser):
    def __init__(self):
        super().__init__()
        self.text = []
    def handle_data(self, d):
        self.text.append(d)
    def get_text(self):
        return ''.join(self.text)

s = Stripper()
s.feed(sys.stdin.read())
print(s.get_text())
"

也可以使用 WebFetch，它会返回整洁的 Markdown——对于大多数用途而言，与纯文本足够接近。

---

身份验证请求

Bearer 令牌

curl -s "https://api.example.com/data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json"

请求头中的 API 密钥

curl -s "https://api.example.com/data" \
  -H "X-API-Key: $API_KEY"

查询参数中的 API 密钥

curl -s "https://api.example.com/data?api_key=$API_KEY"

Basic 身份验证

curl -s -u "username:$PASSWORD" "https://api.example.com/data"

将凭据存储在环境变量中。切勿在命令中硬编码令牌或密码。

---

POST、PUT、PATCH、DELETE

带 JSON 请求体的 POST

curl -s -X POST "https://api.example.com/items" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{
    "name": "item-name",
    "value": 42
  }' | jq '.'

带表单数据的 POST

curl -s -X POST "https://api.example.com/upload" \
  -F "file=@./document.pdf" \
  -F "description=Uploaded via curl"

PUT（完整更新）

curl -s -X PUT "https://api.example.com/items/123" \
  -H "Content-Type: application/json" \
  -d '{"name": "updated-name", "value": 99}' | jq '.'

PATCH（部分更新）

curl -s -X PATCH "https://api.example.com/items/123" \
  -H "Content-Type: application/json" \
  -d '{"value": 100}' | jq '.'

DELETE

curl -s -X DELETE "https://api.example.com/items/123" \
  -H "Authorization: Bearer $API_TOKEN"

---

高级用法模式

分页

PAGE=1
while true; do
  RESPONSE=$(curl -s "https://api.example.com/items?page=$PAGE&per_page=50" \
    -H "Authorization: Bearer $API_TOKEN")
  COUNT=$(echo "$RESPONSE" | jq 'length')
  echo "$RESPONSE" | jq '.[]'
  [ "$COUNT" -lt 50 ] && break
  PAGE=$((PAGE + 1))
done

超时与重试

curl -s --connect-timeout 10 --max-time 30 \
  --retry 3 --retry-delay 2 \
  "https://api.example.com/data"

检查响应头

curl -sI "https://example.com" | grep -i "content-type"

保存响应及状态码

HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" "https://api.example.com/data")
echo "Status: $HTTP_CODE"
cat /tmp/response.json | jq '.'

Cookie 处理

# Save cookies
curl -s -c /tmp/cookies.txt "https://example.com/login" \
  -d "user=admin&pass=$PASSWORD"

# Reuse cookies
curl -s -b /tmp/cookies.txt "https://example.com/dashboard"

---

错误处理

HTTP 状态码	含义	解决方法
301/302	重定向	添加 -L 标志以跟随重定向
401	未经授权	检查令牌/凭据；确认已设置环境变量
403	禁止访问	权限不足或受到 IP 限制
404	未找到	检查 URL 路径；资源可能已被删除
429	请求过多	遵循 Retry-After 请求头；在请求之间增加延迟
500	服务器错误	重试一次；若问题持续存在，请向上游报告
SSL error	证书问题	不要使用 -k（不安全）——应修复根本原因
Timeout	网络/服务器响应缓慢	增大 --max-time；检查连接状态

执行复杂操作前，先确认 URL 是否可访问：

curl -sI -o /dev/null -w "%{http_code}" "https://example.com"

---

局限

• WebFetch 不支持自定义标头、POST 正文或 Cookie。对于需要身份验证或有状态的请求，请使用 curl。
• curl 不会渲染 JavaScript。对于 JavaScript 内容较多的 SPA，优先使用能够处理渲染后内容的 WebFetch。
• 大型响应可能会超出上下文限制。将数据通过管道传递给 jq、head 或 python3，先提取所需数据，再加载到上下文中。
• 二进制内容（图像、PDF、压缩包）应使用 -o 保存到磁盘，而不是通过管道输出到标准输出。

---

校准规则

1. 读取网页时默认使用 WebFetch。 它会返回整洁的 Markdown、处理 JavaScript 渲染，且无需任何标志。只有在需要标头、身份验证、POST 或原始格式控制时，才切换到 curl。
2. 始终通过 jq 处理 JSON。 将原始 JSON 放入上下文会浪费令牌。只筛选所需字段。
3. 绝不要硬编码凭据。 使用 $ENV_VAR 引用。如果变量未设置，请立即报告错误。
4. 默认跟随重定向。 除非需要检查重定向链，否则始终在 curl 中使用 -L。
5. 每次调用 curl 时优先使用 -s（静默模式）。 进度条会给输出增加噪声。