mcp-webgate

mcp-webgate

网页搜索，不再撑爆 AI 的记忆。

mcp-webgate 是一款 MCP 服务，可为你的 AI 提供干净、内容有界的网页内容，兼容所有主流 AI 客户端：

• IDE：Claude Desktop、Claude Code、Zed、Cursor、Windsurf、VSCode
• CLI Agent：Gemini CLI、Claude CLI、自定义 Agent

🌱 简介

什么是 mcp-webgate？ 当 AI 使用标准的“获取 URL”工具时，它会收到页面的原始 HTML——广告、菜单、脚本、Cookie 横幅，全都包含在内。一篇新闻文章就可能向 AI 的记忆中塞入 200,000 个 token 的垃圾内容，彻底挤掉整个对话。

mcp-webgate 是一个保护性过滤器，位于 AI 与网页之间：

1. 剔除垃圾内容——通过精细的 HTML 解析移除菜单、脚本、广告和页脚，只保留可读文本
2. 严格限制每条响应的长度——无论原始页面有多大，都不会撑爆上下文窗口
3. 可选生成摘要——将结果交给次级本地大模型，生成带引用的精简 Markdown 报告；主 AI 收到的是整理完善的简报，而不是一大堆文字

最终效果：干净、内容有界且实用的网页内容，始终如此。

🔬 实例：幕后处理过程

启用大模型功能后，搜索 "mcp model context protocol"：

Query → LLM expands to 5 search variants → 20 pages found, 13 fetched in parallel

Raw HTML downloaded     5.16 MB   (~1,290,000 tokens)
After cleaning          52.1 KB   (   ~13,000 tokens)  — 99% noise stripped
After LLM summary        5.8 KB   (    ~1,450 tokens)  — structured report with citations

将 13 个来源提炼为约 1,450 个 token。 即使只用普通方式获取其中一个页面（例如一个大小为 563 KB 的安全博客），也会向 AI 的上下文中塞入 约 140,000 个 token 的原始 HTML。webgate 处理全部 13 个来源，输出一份精简简报，短到可以放在脚注里。

这是一个高强度案例（5 次查询 × 每次 5 条结果）。常规搜索即使只有 3–5 条结果，相比直接获取原始内容也能节省 95% 以上的上下文，而且 AI 收到的是结构化、经过排序的内容，而不是一大堆混杂的 HTML。

🚀 快速开始

1. 确认已安装 uvx

pip install uv

uvx 可以运行 Python 工具，而无需永久安装。你只需执行一次。

2. 设置搜索后端

最简单的选择是 SearXNG——免费、无需账号，可在本地运行：

docker run -d -p 8080:8080 --name searxng searxng/searxng

没有 Docker？改用云端后端（Brave、Tavily、Exa、SerpAPI）——请参阅后端。

3. 将 webgate 添加到 AI 客户端

请参阅集成表，选择对应的客户端。以下以 Claude Desktop 为例：

打开配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "webgate": {
      "command": "uvx",
      "args": ["mcp-webgate"],
      "env": {
        "WEBGATE_DEFAULT_BACKEND": "searxng",
        "WEBGATE_SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

编辑完成后，重启客户端。

4. 让 AI 开始搜索！

Search the web for: latest news on AI regulation

AI 会自动使用 webgate_query。大功告成。

🔍 工作原理

Your question
    ↓
Search backend  (SearXNG / Brave / Tavily / Exa / SerpAPI)
    ↓  [deduplicate URLs, block binary files, filter domains]
Fetch pages in parallel  (streaming — hard size cap per page)
    ↓  [optional: retry failed pages from reserve pool]
Strip HTML junk  (menus, ads, scripts, footers — lxml)
    ↓
Clean up text  (invisible chars, unicode junk, BiDi tricks)
    ↓
BM25 reranking  (best-matching results first — always active)
    ↓  [optional: LLM reranking]
Cap total output to budget
    ↓  [optional: LLM summarization → compact Markdown report]
Clean result lands in your AI's context

🛠️ 工具

webgate 为 AI 提供三个工具：

webgate_fetch — 读取单个页面

已知目标 URL 时使用此工具。AI 传入 URL 后即可获取清理过的文本，最多 max_query_budget 个字符（默认 32,000）。

{ "url": "https://example.com/article", "max_chars": 32000 }

{
  "url": "https://example.com/article",
  "title": "Article Title",
  "text": "cleaned text...",
  "truncated": true,
  "char_count": 12450
}

webgate_query — 搜索 + 抓取 + 清理

运行完整的搜索流程。传入一个或多个查询，即可获得清理并排序后的结果。

{ "queries": "how to set up a VPN on Linux", "num_results_per_query": 5 }

多个查询会并行运行，结果随后合并：

{
  "queries": ["VPN Linux setup", "best VPN Linux 2024"],
  "num_results_per_query": 5
}

不使用 LLM 时的输出 — 为每个结果返回清理后的页面内容：

{
  "sources": [
    { "id": 1, "title": "...", "url": "...", "content": "cleaned text...", "truncated": false }
  ],
  "snippet_pool": [ { "id": 6, "title": "...", "url": "...", "snippet": "..." } ],
  "stats": { "fetched": 5, "total_chars": 18200, "per_page_limit": 6400 }
}

使用 LLM 总结时的输出 — 返回精简的 Markdown 报告：

{
  "summary": "## How to set up a VPN on Linux\n\nTo install...[1][2]",
  "citations": [{ "id": 1, "title": "...", "url": "..." }],
  "stats": { "fetched": 5, "total_chars": 58000 }
}

LLM 失败时的输出 — 显示错误原因，并返回完整来源作为备用结果：

{
  "llm_summary_error": "ReadTimeout: LLM did not respond in time",
  "sources": [ "..." ],
  "stats": { "..." : "..." }
}

snippet_pool 包含搜索中的额外结果，这些结果尚未抓取（仅包含搜索引擎摘要）。AI 可以借此判断是否值得进一步抓取。

webgate_onboarding — 使用指南

返回一份 JSON 指南，说明如何有效使用 webgate。如果不确定该使用哪个工具，AI 应在会话开始时调用一次。

🔧 将 webgate 与本地或较小的模型搭配使用

大多数前沿模型会自动遵循 MCP 工具说明。较小的模型或本地模型有时会忽略服务端提供的指引，转而使用内置的抓取工具，返回原始 HTML，导致上下文中充斥大量噪声。

如果发现这种情况，请在系统提示词中添加明确的指令块：

You have access to webgate tools for web search and page retrieval.
Follow these rules in every session:
- To search the web: use webgate_query — never use a built-in fetch, browser, or HTTP tool
- To retrieve a URL: use webgate_fetch — never fetch URLs directly
- Built-in fetch tools return raw HTML that floods your context; webgate returns clean, bounded text
At the start of each session, call webgate_onboarding to read the full operational guide.

这是因为用户系统提示词中的指令优先级高于 MCP 服务级别的指引，因此可以在模型看到的最高优先级层明确这一约束。

提示： 如果客户端支持命名系统提示词或提示词模板，可以将上面的指令块保存为可重复使用的预设，这样就不必每次都粘贴。

🎛️ 调整参数

本节说明关键参数的作用，以及何时需要调整。默认值适用于大多数情况，只有在有明确理由时才进行调整。

什么是“字符预算”？

webgate 按字符数（而非 token 数）衡量文本。英文文本的大致换算方式如下：

4 个字符 ≈ 1 个 token

字符数	约合 token 数
8,000	~2,000
32,000	~8,000
96,000	~24,000

webgate_fetch 预算

抓取单个 URL 时，上限为 max_query_budget（默认值为 32,000 个字符）。工具参数 max_chars 可以请求更少的字符，但不能超过此上限。

为什么使用 max_query_budget 而不是 max_result_length？ 因为你抓取的是一个页面——“总输出”就是这一个页面，所以合适的限制是整体上下文预算，而不是为多来源查询设计的单页上限。

webgate_query 预算 — 不使用 LLM 时

不使用 LLM 时，清理后的来源会直接进入 AI 的上下文。webgate 会将 max_query_budget 分配给所有已抓取的页面，确保总量不会超出预算：

每页上限 = max_query_budget ÷ 结果数量 （上限为 max_result_length）

已抓取结果数	每页上限	总输出
1	8,000（上限）	≤ 8,000
5	6,400	≤ 32,000
10	3,200	≤ 32,000
20	1,600	≤ 32,000

无论请求多少结果，总输出始终不超过 max_query_budget——每页分配的额度会自动缩减以满足预算。

webgate_query 预算 — 使用大模型进行摘要

在辅助大模型进行摘要时，它会先压缩内容，再将结果传递给主 AI。因此，可以放心地提供更多原始素材，效果也会更好。

webgate 会通过 input_budget_factor 扩大输入预算（默认值为 3）：

大模型输入预算 = max_query_budget × input_budget_factor 默认值：32,000 × 3 = 96,000 字符

获取的结果数	每页大模型输入	大模型输入总量	输出给 AI 的内容
1	96,000	96,000	精简报告
5	19,200	96,000	精简报告
10	9,600	96,000	精简报告
20	4,800	96,000	精简报告

辅助大模型能看到每页更多内容。主 AI 只会看到最终报告——通常为 1,000–3,000 个 token——无论处理了多少个来源。这是大模型模式的主要效率优势。

快速调优指南

现象	解决方法
AI 回复较慢，文本过多	降低 max_query_budget（例如 16000）
AI 的回答较浅或遗漏细节	提高 max_query_budget（例如 48000）
大模型摘要内容单薄或有所遗漏	提高 input_budget_factor（例如 5）
大模型摘要超时或速度很慢	降低 input_budget_factor（例如 2）或降低 results_per_query
fetch 返回的长页面内容太少	提高 max_query_budget（例如 64000）
页面下载速度较慢	降低 max_download_mb（例如 1，已是默认值）
服务下载了太多无用内容	降低 max_download_mb（例如 1）

🤖 大模型功能

可选，需主动启用。当 llm.enabled = false（默认值）时，webgate 完全以确定性方式运行。启用 [llm] 配置块即可解锁三项额外功能。

🤔 何时启用大模型功能

情况	推荐配置	通常增加的延迟
需要快速回答、进行一般研究	禁用大模型（默认）——按 BM25 排序的干净来源，不增加延迟	无
深入研究复杂主题	启用摘要——获取带引用的 Markdown 报告，而非原始页面	+5–30 秒
主题范围广，一个查询不够	启用扩展 + 摘要——由大模型生成多个变体并综合所有结果	+6–35 秒
结果顺序比速度更重要	启用大模型重排——以每个查询额外调用一次大模型为代价进行语义排序	+1–5 秒

**隐私：**禁用大模型时，除网页请求外，不会有数据离开你的设备。启用大模型后，清理后的搜索结果（而非原始 HTML）会发送到配置的 base_url。将其指向本地 Ollama 实例，即可确保所有内容都留在设备上。

**延迟权衡：**每启用一项功能，每个查询就会增加一次大模型往返调用。扩展会增加约 1–5 秒；摘要会增加约 5–30 秒，具体取决于模型和内容量。交互式使用时，可从快速的本地模型（例如 Gemma 3 4B）搭配摘要功能开始尝试。

设置

[llm]
enabled  = true
base_url = "http://localhost:11434/v1"   # Ollama, OpenAI, LM Studio, vLLM, Groq...
api_key  = ""                            # empty for local models
model    = "gemma3:27b"
timeout  = 60                            # local 27B+ models may need up to 60s

也可以使用环境变量：

"env": {
  "WEBGATE_LLM_ENABLED": "true",
  "WEBGATE_LLM_BASE_URL": "http://localhost:11434/v1",
  "WEBGATE_LLM_MODEL": "gemma3:27b",
  "WEBGATE_LLM_TIMEOUT": "60"
}

base_url 支持任何兼容 OpenAI 的端点：OpenAI、Ollama、LM Studio、vLLM、Together AI、Groq 等。

查询扩展

发送单个查询且 expansion_enabled = true 时，大模型会在调用后端前自动生成互补的搜索变体。如果你已经传入多个查询，则会跳过此步骤。

"best laptop for programming"
    ↓ expansion
["best laptop for programming 2024", "developer laptop recommendations", "laptop specs for coding"]
    ↓ all search in parallel

如果大模型调用失败，则会静默回退到原始查询。

摘要

当 summarization_enabled = true 时，大模型会读取所有已获取的页面，并撰写带有行内引用的结构化 Markdown 报告。AI 会收到这份报告，而不是原始文本。

• 成功：summary + citations（精简输出——不会向 AI 传递原始内容）
• 失败：llm_summary_error 及错误原因 + 完整的 sources 作为备用内容（AI 仍可使用经过清理的内容）

报告的目标长度由 max_summary_words 指定。当其值为 0（默认值）时，将根据 max_query_budget / 5 推算——例如，预算为 32k 时，目标长度约为 6,400 个词。

重排序

返回结果前，始终会先使用 BM25（关键词重叠，零成本）进行重排序。也可以选择让大模型再进行一轮语义相关性重排序：

层级	时机	成本
BM25（确定性）	始终执行	零——纯数学计算
LLM 辅助	llm_rerank_enabled = true	每次查询调用一次大模型

LLM 重排序会增加与大模型响应时间相当的延迟。只有当结果排序比速度更重要时才启用。

流程：clean → BM25 rerank → (LLM rerank) → (LLM summarize) → output

🔗 集成

mcp-webgate 可与所有主流 AI 客户端配合使用：

平台	配置指南	备注
Claude Desktop	IDE 集成	桌面应用
Claude Code	IDE 集成	命令行编码 Agent
Zed Editor	IDE 集成	原生 MCP 支持
Cursor	IDE 集成	需要 Agent 模式
Windsurf	IDE 集成	仅支持全局配置
VSCode	IDE 集成	通过 Copilot 或 MCP 扩展
Gemini CLI	Agent 集成	Google 的命令行 Agent
Claude CLI	Agent 集成	Anthropic 的命令行 Agent

📦 安装

通过 uvx（推荐——无需安装）

uvx mcp-webgate

通过 pip / uv

pip install mcp-webgate
# or
uv add mcp-webgate

⚙️ 完整配置

可直接使用的配置文件位于 examples/ 中。

解析顺序

CLI args  >  env vars  >  webgate.toml  >  defaults

配置只会在启动时读取一次；重启服务以应用更改。

你可以通过以下三种方式配置 webgate，并按需混合使用：

• webgate.toml — 启动时依次检查 ./webgate.toml 和 ~/webgate.toml
• 环境变量 — 使用 WEBGATE_* 前缀，始终为字符串（MCP JSON 要求）
• 命令行参数 — 使用 --kebab-case；整数保持为整数，适合多实例配置

配置文件（webgate.toml）

[server]
max_download_mb    = 1        # how many MB to download per page before cutting off
max_result_length  = 8000     # max chars per page in multi-source queries (no LLM)
max_query_budget   = 32000    # total char budget for a fetch, or input pool for a query
max_search_queries = 5        # max parallel queries per call
results_per_query  = 5        # results to fetch per query
search_timeout     = 8        # seconds before giving up on a page
oversampling_factor = 2       # fetch 2× more candidates than needed (dedup reserve)
auto_recovery_fetch = false   # retry failed fetches from reserve pool
max_total_results  = 20       # hard cap: never fetch more than this many pages total
blocked_domains    = ["reddit.com", "pinterest.com"]
allowed_domains    = []       # if non-empty, only these domains are allowed
adaptive_budget    = false   # [EXPERIMENTAL] proportional char allocation based on BM25 rank
adaptive_budget_fetch_factor = 3  # generous pre-rank fetch multiplier

[backends]
default = "searxng"

[backends.searxng]
url = "http://localhost:8080"

[backends.brave]
api_key = "BSA..."

[backends.tavily]
api_key = "tvly-..."
search_depth = "basic"

[llm]
enabled  = true
base_url = "http://localhost:11434/v1"
api_key  = ""
model    = "llama3.2"
timeout  = 60
expansion_enabled     = true
summarization_enabled = true
llm_rerank_enabled    = false
max_summary_words     = 0     # 0 = max_query_budget / 5 (e.g. 6400 with budget 32000)
input_budget_factor   = 3     # LLM input = max_query_budget × factor (default: 96000)

MCP 客户端配置示例

使用环境变量（所有值都必须为字符串）：

{
  "mcpServers": {
    "webgate": {
      "command": "uvx",
      "args": ["mcp-webgate"],
      "env": {
        "WEBGATE_DEFAULT_BACKEND": "searxng",
        "WEBGATE_SEARXNG_URL": "http://localhost:8080",
        "WEBGATE_LLM_ENABLED": "true",
        "WEBGATE_LLM_TIMEOUT": "60"
      }
    }
  }
}

使用命令行参数（整数保持为整数——适合在 Zed、Cursor 等工具中运行相互独立的实例）：

{
  "mcpServers": {
    "webgate": {
      "command": "uvx",
      "args": [
        "mcp-webgate",
        "--searxng-url", "http://localhost:8080",
        "--llm-enabled",
        "--llm-model", "gemma3:27b",
        "--llm-timeout", "60"
      ]
    }
  }
}

布尔标志支持 --flag / --no-flag 语法（例如 --llm-enabled、--no-llm-rerank-enabled）。

完整参考

CLI 参数	环境变量	默认值	说明
--default-backend	WEBGATE_DEFAULT_BACKEND	searxng	当前使用的后端
--searxng-url	WEBGATE_SEARXNG_URL	http://localhost:8080	SearXNG 实例 URL
--brave-api-key	WEBGATE_BRAVE_API_KEY	(empty)	Brave Search API 密钥
--tavily-api-key	WEBGATE_TAVILY_API_KEY	(empty)	Tavily API 密钥
--exa-api-key	WEBGATE_EXA_API_KEY	(empty)	Exa API 密钥
--serpapi-api-key	WEBGATE_SERPAPI_API_KEY	(empty)	SerpAPI 密钥
--serpapi-engine	WEBGATE_SERPAPI_ENGINE	google	SerpAPI 引擎（google、bing……）
--serpapi-gl	WEBGATE_SERPAPI_GL	us	SerpAPI 国家代码
--serpapi-hl	WEBGATE_SERPAPI_HL	en	SerpAPI 语言
--max-download-mb	WEBGATE_MAX_DOWNLOAD_MB	1	每页下载大小上限（MB）
--max-result-length	WEBGATE_MAX_RESULT_LENGTH	8000	每页字符数上限（不使用 LLM 的查询）
--max-query-budget	WEBGATE_MAX_QUERY_BUDGET	32000	抓取和查询的总字符数预算
--max-search-queries	WEBGATE_MAX_SEARCH_QUERIES	5	每次调用的最大查询数
--results-per-query	WEBGATE_RESULTS_PER_QUERY	5	每次查询默认抓取的结果数
--search-timeout	WEBGATE_SEARCH_TIMEOUT	8	HTTP 请求超时时间（秒）
--oversampling-factor	WEBGATE_OVERSAMPLING_FACTOR	2	用于去重预留的搜索结果倍数
--auto-recovery-fetch	WEBGATE_AUTO_RECOVERY_FETCH	false	启用缺口填补（第 2 轮抓取）
--max-total-results	WEBGATE_MAX_TOTAL_RESULTS	20	每次调用的结果总数硬上限
--debug	WEBGATE_DEBUG	false	启用结构化调试日志
--log-file	WEBGATE_LOG_FILE	(empty)	日志文件路径（为空时输出到 stderr）
--trace	WEBGATE_TRACE	false	在摘要引文中包含内容；同时启用调试日志
--adaptive-budget	WEBGATE_ADAPTIVE_BUDGET	false	[EXPERIMENTAL] 根据 BM25 排名按比例分配字符数
--adaptive-budget-fetch-factor	WEBGATE_ADAPTIVE_BUDGET_FETCH_FACTOR	3	[EXPERIMENTAL] 宽松的排名前抓取倍数
--llm-enabled	WEBGATE_LLM_ENABLED	false	启用 LLM 功能
--llm-base-url	WEBGATE_LLM_BASE_URL	http://localhost:11434/v1	兼容 OpenAI 的端点
--llm-api-key	WEBGATE_LLM_API_KEY	(empty)	API 密钥（本地模型可留空）
--llm-model	WEBGATE_LLM_MODEL	llama3.2	模型名称
--llm-timeout	WEBGATE_LLM_TIMEOUT	30	LLM 请求超时时间（秒）
--llm-expansion-enabled	WEBGATE_LLM_EXPANSION_ENABLED	true	自动将查询扩展为多个变体
--llm-summarization-enabled	WEBGATE_LLM_SUMMARIZATION_ENABLED	true	生成带引文的 LLM 摘要
--llm-rerank-enabled	WEBGATE_LLM_RERANK_ENABLED	false	使用 LLM 辅助重新排序
--llm-max-summary-words	WEBGATE_LLM_MAX_SUMMARY_WORDS	0	摘要目标字数（0 = 自动）
--llm-input-budget-factor	WEBGATE_LLM_INPUT_BUDGET_FACTOR	3	LLM 输入预算倍数

🔌 后端

后端	认证	备注
SearXNG	无	可自托管，推荐使用
Brave Search	API 密钥	高质量，提供免费套餐
Tavily	API 密钥	面向 AI 的摘要片段，提供免费套餐
Exa	API 密钥	神经网络／语义搜索，提供免费套餐
SerpAPI	API 密钥	Google、Bing、DuckDuckGo 等搜索引擎的代理，提供免费套餐

SearXNG 快速入门（Docker）

docker run -d -p 8080:8080 --name searxng searxng/searxng

然后设置 WEBGATE_SEARXNG_URL=http://localhost:8080。

Exa 说明

Exa 默认使用神经网络（语义）搜索，这是选择它而非关键词搜索后端的主要原因。use_autoprompt 被硬编码为 false（无法由用户配置），因为 mcp-webgate 会通过自身的 LLM 扩展器处理查询扩展。

SerpAPI 说明

engine 用于选择底层搜索引擎（google、bing、duckduckgo、yandex、yahoo）。对于非英语查询，gl 和 hl 会显著影响结果质量。

🐛 调试模式

启用后，每次工具调用都会记录一条结构化日志：

• fetch：URL、下载的原始 KB、返回的清理后 KB、耗时（毫秒）
• query：使用的查询、请求/获取/失败的结果数、原始 MB、清理后 KB、总耗时（毫秒）

export WEBGATE_DEBUG=true             # log to stderr
export WEBGATE_LOG_FILE=/tmp/wg.log  # or log to file

🛡️ 防护措施摘要

这些防护措施始终启用，是本项目的核心价值所在，且无法禁用。

可能出现的问题	webgate 如何阻止
页面输出 2 MB 的 HTML	max_download_mb 硬性上限 — 下载会在传输过程中停止，不会将内容全部缓冲
清理后的文本仍然过大	每页的 max_result_length 字符数上限
大量结果涌入上下文	max_query_budget 将固定总量分配给所有结果
获取的页面过多	max_total_results 硬性上限
请求 PDF / ZIP / DOCX	二进制扩展名过滤器会在任何网络请求之前运行
连接缓慢或挂起	search_timeout + 5 秒连接超时
内容中包含不可见的 Unicode 伎俩	完整的正则表达式净化流程（零宽字符、BiDi 等）
速率限制（429 / 502 / 503）	指数退避重试，并遵循 Retry-After 标头
不需要的域名	blocked_domains / allowed_domains 过滤器

📚 文档结构

集成指南

• IDE 集成 — Claude Desktop、Claude Code、Zed、Cursor、Windsurf、VSCode
• Agent 集成 — Gemini CLI、Claude CLI、自定义 Agent
• 高级功能 — BM25/LLM 重排序内部机制、自适应预算分配

🧪 Beta 状态

mcp-webgate 目前处于 beta 阶段。核心功能稳定，且该服务已用于生产环境， 但配置 API 在 1.0 发布前仍可能发生变化。

非常欢迎反馈。 如果遇到无法按预期运行或表现异常的情况， 或者有尚未涵盖的使用场景：

→ 在 GitHub 上提交问题

错误报告、配置问题和功能请求都有助于规划未来路线。

🤝 参与贡献

欢迎贡献！详细指南请参阅 CONTRIBUTING.md，内容包括：

• 开发环境设置和工作流
• 代码风格和约定
• 测试要求
• 文档规范
• 拉取请求流程

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE。

🔗 链接

• GitHub 仓库 — 源代码和问题
• PyPI 软件包 — Python Package Index
• MCP Registry — Model Context Protocol Registry
• MCP 协议 — Model Context Protocol 规范

---

需要帮助？ 请查看文档或在 GitHub 上提交问题。