Safefetch MCP Server

SafeFetch MCP服务器

为本地AI代理提供安全的网络获取。\ 面向本地AI代理的以安全为重点的web获取服务。

许可证：AGPL-3.0（双许可证型号，请参阅 COMMERCIAL.md)\ 反馈：GitHub Issues / Pull Requests

为什么选择SafeFetch

将其视为人工智能网络访问的“数字安全卫士”。它侧重于三件事：

• 阻止内部目标：默认SSRF护栏（方案检查、DNS/IP验证、每跳重定向验证）
• 防止资源爆炸：原始/减压尺寸限制，以阻止超大有效载荷和减压炸弹
• 改进故障排除：用于自动代理决策和重试控制的稳定JSON合约

简而言之：为AI代理提供更安全、更稳定、更可控的网络获取。

亮点

• SSRF防御：方案保护、DNS/IP检查、重定向重新验证
• 资源护栏：原始/解压缩字节限制+MIME分配列表
• 稳定的输出：用于自动化的扁平JSON合约
• 清晰的渲染边界：SSR/SSG工作完毕 httpx，纯SPA通常需要剧作家
• OpenClaw就绪：技能模板+ mcporter 例子
• 初学者友好：一个命令引导脚本

渲染模型边界

SafeFetch有两种获取模式：

• httpx 模式：默认快速安全；最适合SSR、SSG和传统的服务器渲染站点
• Playwright mode：JavaScript渲染页面和纯SPA网站的较慢无头浏览器模式

这在实践中意味着什么：

• react.dev-样式SSR/SSG页面通常在 httpx 模式，因为HTML已包含文章文本
• 纯React/Vue SPA页面通常只返回一个应用程序shell，例如 `

在 httpx` 模式

• 当SafeFetch检测到仅包含shell的HTML响应时，它会标记 shell_only=true, js_required=true
• 如果 enable_fallback=true 当Playwright可用时，SafeFetch会自动重试Playwright

先决条件

安装前，请确保您的计算机上存在以下依赖关系：

• python >= 3.10 （建议： 3.11)
• mcporter 可在您的 PATH
• OpenClaw提供本地代理/技能支持

快速检查：

python3 --version
which mcporter
mcporter --help
openclaw --version

如果 mcporter 缺少，请先安装（示例选项）：

pip install mcporter
# or
uv pip install mcporter

快速开始

~/ 和 `` 两者都代表您的本地克隆路径。用您的实际位置替换它们。

1） 安装

cd ~/safefetch-mcp-server
bash bootstrap.sh

2） 开始

bash start-mcp.sh

3） 离线自检（推荐）

source .venv/bin/activate
python -m safefetch --self-test

4） 网络自检（可选）

source .venv/bin/activate
python -m safefetch --self-test-network

如果您的网络将公共域解析为受限范围，请使用：

WEBFETCH_ALLOW_CIDRS=198.18.0.0/15 python -m safefetch --self-test-network

OpenClaw 集成

1. 合并 examples/openclaw.skills-entry.sample.json 进入 ~/.openclaw/openclaw.json (skills.entries).
2. 复制技能文件：

mkdir -p ~/.openclaw/skills/safefetch-mcp-v1
cp ~/safefetch-mcp-server/examples/SKILL.local.md ~/.openclaw/skills/safefetch-mcp-v1/SKILL.md

1. 你好，世界：

openclaw agent --local --message "Use safefetch-mcp-v1 to fetch https://httpbin.org/get. Output strict JSON only (no markdown code fences) with fields: ok, fetch_status, blocked_reason, final_url, attempts, retryable_error, security_blocked, title."

mcporter 直接调用

mcporter call --stdio "env WEBFETCH_ALLOW_CIDRS=${WEBFETCH_ALLOW_CIDRS:-} /safefetch-mcp-server/.venv/bin/python -m safefetch" fetch_url url=https://example.com caller_id=openclaw-agent max_tokens=3000

JSON响应合约

这些字段构成了一个稳定的JSON响应契约，用于代理状态检查、重试决策和故障排除：

• ok
• fetch_status
• blocked_reason
• final_url
• status_code
• content_type
• title
• content_markdown
• content_chars
• redirects
• raw_bytes
• decompressed_bytes
• attempts
• retried
• retryable_error
• last_error
• security_blocked
• render_mode
• fallback_used
• shell_only
• js_required

渲染解释字段

• render_mode: httpx 或 playwright
• fallback_used: true 当最终的成功结果来自Playwright的自动回退时
• shell_only: true 当获取的HTML看起来像客户端SPA shell而不是实际页面内容时
• js_required: true 当可能需要JavaScript渲染来获取有意义的页面内容时

环境变量

• WEBFETCH_ALLOW_CIDRS （可选）：逗号分隔的CIDR分配列表适用于特殊网络环境。

故障排除

技能在OpenClaw中无法加载

最常见的原因： mcporter 未安装或不在 PATH.

which mcporter

如果为空，请安装 mcporter，然后重新启动OpenClaw并运行：

openclaw skills list

DNS/IP意外被阻止

在某些网络环境中，公共域可能会解析为受限范围。 对这些环境使用满列表CIDR：

WEBFETCH_ALLOW_CIDRS=198.18.0.0/15 python -m safefetch --self-test-network

获取成功，但页面内容为空或极短

最常见的原因：目标是一个纯SPA网站 httpx 只收到了客户端shell。

检查JSON响应中的这些字段：

• render_mode
• fallback_used
• shell_only
• js_required

典型解释：

• render_mode=httpx, shell_only=false：常规静态/SSR/SSG获取
• render_mode=httpx, shell_only=true, js_required=true：仅限HTML shell；使用剧作家
• render_mode=playwright, fallback_used=true：已成功使用浏览器自动回退

在引导脚本中找不到Python命令

手动创建venv并重新运行：

python3.11 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

项目文件

safefetch-mcp-server/
  server.py            # compatibility entrypoint
  safefetch/           # package implementation
  requirements.txt
  bootstrap.sh
  start-mcp.sh
  test_server.py
  RELEASE.md
  examples/

发布工作流

• 离线验证： python -m safefetch --self-test
• 可选网络验证： python -m safefetch --self-test-network
• 单元测试： python -m unittest test_server.py
• 发行说明模板： RELEASE.md

安全

该项目旨在用于防御性的本地代理网络获取用例。\ 不要在生产中禁用SSRF和资源护栏。\ 有关漏洞报告，请参阅 SECURITY.md.

许可证

• 开源： GNU AGPL v3.0 (LICENSE)
• 商业条款： COMMERCIAL.md