SmartFetch V1.8 — MCP 可发现性

SmartFetch 接收一个公共 Web URL，并返回干净的、可供智能体使用的文本、Markdown、链接、元数据以及所使用的检索方法。它首先尝试廉价的 HTTP 检索，在需要时回退到真正的 Chromium 浏览器。

V1.8 中的变更

• 付费的 MCP fetch_webpage 工具现在声明官方的 x402 Bazaar 元数据，用于智能体发现，而不改变其执行或支付行为。

• 根目录下的 server.json 将现有的 /mcp Streamable HTTP 端点公布为仅限远程的服务器，以供官方 MCP Registry 使用。

• 此仓库更新不执行 Registry 发布、部署、Railway 变量更改或支付。

所有 V1.7 的 HTTP 支付、Bazaar 和原生 MCP 行为保持不变：

• Base Sepolia 仍是默认的 x402 网络，并继续使用 https://x402.org/facilitator，无需 CDP 凭据。

• 显式选择 Base 主网时，可以使用 Coinbase 的带认证 CDP facilitator。

• 主网启动需要两个 CDP API 凭据，并且在凭据无效或 facilitator 不受支持时按失败关闭（fail closed）。

• /meta 区分启用的测试网和主网支付模式。

• cdp-sdk、FastAPI、Uvicorn 和 x402 都被精确固定版本，以便基础设施升级是显式的。

检索引擎、提取/浏览器行为、SSRF 防护、请求限制、速率限制和并发控制均未改变。

Related MCP server: SteadyFetch

API

GET /health

返回服务健康状态/版本。

GET /meta

返回机器可读的服务描述。

POST /fetch

{
  "url": "https://example.com/article",
  "max_chars": 20000,
  "force_browser": false
}

max_chars 是可选的（最小 1,000；默认 20,000；最大 50,000）。

示例响应字段：

{
  "success": true,
  "requested_url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "status_code": 200,
  "render_method": "http",
  "title": "…",
  "content": "…",
  "markdown": "…",
  "links": [],
  "word_count": 1000,
  "content_hash": "…",
  "truncated": false,
  "elapsed_ms": 350,
  "request_id": "…",
  "service_version": "1.8.0"
}

当启用了 x402 支付保护时，POST /fetch 的 PAYMENT-REQUIRED 响应头包含一份 Bazaar 声明，其中带有 url、max_chars 和 force_browser 输入契约，以及一个有代表性的成功响应。/、/health 和 /meta 保持免费，并且不公布 Bazaar 元数据。

MCP

远程 MCP 客户端通过 Streamable HTTP 连接到 /mcp。服务器只暴露一个工具：

fetch_webpage
  url: required string
  max_chars: optional integer (default 20000, minimum 1000, maximum 50000)
  force_browser: optional boolean (default false)

该工具为智能体读取、获取、抓取或提取公共网页，并返回现有的 SmartFetch 文本、Markdown、链接和检索元数据。它使用与 POST /fetch 相同的 SSRF 校验、执行器、请求超时、并发上限、输出上限、HTTP 检索和浏览器回退；它不会向公共 API 发起 HTTP 请求。

当 x402 启用时，未支付的 tools/call 会返回原生 MCP x402 支付质询。有效支付会在检索前验证，并在工具成功执行后结算一次。网络、公共收款方和价格来自 X402_NETWORK、X402_PAY_TO 和 X402_PRICE。不接受也不要求任何卖方私钥或钱包机密。

未支付的 MCP 支付质询包含一份针对 fetch_webpage 的 Bazaar 声明，其中带有 transport streamable-http、现有输入契约以及一个有代表性的 SmartFetch 输出。其支付资源仍为 mcp://tool/fetch_webpage。现有的针对 POST /fetch 的 HTTP Bazaar 资源是独立的，并且保持不变。

根目录下的 server.json 描述了位于 https://smartfetch-production-ea53.up.railway.app/mcp 的公共远程端点。Registry 发布是单独的、需要认证的操作员操作；添加该清单并不会发布或部署该服务。

本地运行

python -m pip install -r requirements.txt
python -m smartfetch.server

然后：

curl http://127.0.0.1:8787/health
curl -X POST http://127.0.0.1:8787/fetch \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

Windows 用户可以运行 setup_windows.bat，然后运行 start_windows.bat。

当 X402_ENABLED 未设置或为 false 时，启动不需要支付设置，/fetch 在本地和远程测试中保持免费。

x402 支付模式

除非显式启用，否则支付保持禁用。Base Sepolia 是默认网络，只需要公共收款地址：

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:84532

省略时，X402_PRICE 和 X402_NETWORK 使用所示值。默认价格保持为 $0.005。

必须显式选择 Base 主网，它使用 Coinbase 的带认证 CDP facilitator：

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:8453
CDP_API_KEY_ID=YOUR_CDP_API_KEY_ID
CDP_API_KEY_SECRET=YOUR_CDP_API_KEY_SECRET

主网需要两个 CDP 凭据。缺少、无效或不可用的凭据、不支持的 Base 主网精确支付，或任何 facilitator/中间件初始化失败都会中止启动。当选择主网时，SmartFetch 绝不会回退到免费访问或测试网 facilitator。除 Base Sepolia 和 Base 主网外的所有网络都会被拒绝。

只有 POST /fetch 受保护。/health、/ 和 /meta 始终免费。启用后的 /meta 响应报告 x402-enabled-testnet 或 x402-enabled-mainnet，而不暴露配置值。

SmartFetch 使用 X402_PAY_TO 作为公共收款地址，不需要 CDP_WALLET_SECRET。切勿提供卖方 MetaMask 私钥或恢复短语：SmartFetch 不需要、不读取、不接受、不记录也不存储这两者中的任何一个。

本地验证

python tests/security_smoke.py
python tests/api_local_smoke.py

api_local_smoke.py 仅在测试进程内部有意启用私有网络访问，以便可以使用 localhost 夹具。

容器

docker build -t smartfetch:v1.8 .
docker run --rm -p 8787:8787 smartfetch:v1.8

容器会自动安装 Chromium。

公共部署

本包已支持 Docker。Railway 可以部署附带的 Dockerfile 和 railway.json；任何能够提供出站 HTTPS 和足够 RAM 以运行一个 Chromium 进程的 Docker 主机也应该可以工作。

推荐的初始环境变量：

MAX_CONCURRENT_BROWSERS=1
MAX_CONCURRENT_FETCHES=4
DEFAULT_MAX_OUTPUT_CHARS=20000
MAX_OUTPUT_CHARS=50000
FETCH_TIMEOUT_SECONDS=12
BROWSER_TIMEOUT_SECONDS=15
TOTAL_REQUEST_TIMEOUT_SECONDS=25
RATE_LIMIT_PER_MINUTE=30
RATE_LIMIT_BURST=10
X402_ENABLED=false

请勿在生产环境中设置 ALLOW_PRIVATE_NETWORK=1。

关于 SSRF 的重要部署说明

已包含应用层 URL 验证，但浏览器渲染可能会执行页面子资源。对于付费的公共部署，浏览器容器还应通过主机/网络出口策略与云元数据和私有 RFC1918 网络隔离。我们将在移除临时速率限制之前以及在 x402 启动之前再次加强这一点。

测试公共部署

在 Windows 上运行 test_remote_windows.bat，粘贴公共 URL，并上传 tests/remote_20_results.json。

或者：

python tests/remote_20.py https://YOUR-PUBLIC-URL

我们的部署门槛仍然是 18/20 最低，包括全部五个强制浏览器请求。

支付启动状态

V1.8 保留了现有的 Base Sepolia 和 Base 主网支付配置。此仓库更改本身不会发布到 MCP Registry、部署服务或修改 Railway 变量。活跃的支付网络由 X402_NETWORK 控制：Base Sepolia 为 eip155:84532，Base 主网为 eip155:8453。