MCP Webgate

mcp-webgate

](https://www.python.org/downloads/)    

不会破坏人工智能记忆的网络搜索。

mcp-webgate是一个mcp服务器，它为您的AI提供干净、有界的web内容——跨越所有主要的AI客户端：

• 月中日：克劳德桌面，克劳德代码，Zed，光标，风帆，VSCode
• CLI代理：Gemini CLI、Claude CLI、自定义代理

🌱 温和的介绍

什么是mcp-webgate？ 当你的人工智能使用标准的“获取URL”工具时，它会获取页面的原始HTML——广告、菜单、脚本、cookie横幅等等。一篇新闻文章可以倾倒 200000代币 将垃圾放入人工智能的内存中，抹去你的整个对话。

mcp-webgate 是一个位于人工智能和网络之间的保护过滤器：

1. 剥去垃圾 --通过精确的HTML解析删除菜单、脚本、广告、页脚；只有可读文本才能通过
2. 严格限制每个响应 --无论原始页面有多大，任何页面都无法炸毁你的上下文窗口
3. （可选）总结 --通过二级本地LLM传递结果，该LLM会生成一份包含引用的紧凑Markdown报告；你的主要人工智能会得到一个精心制作的简报，而不是一堵文字墙

结果：干净、有界、有用的网络内容——总是如此。

🔬 真实示例：引擎盖下发生了什么

寻找 *“mcp模型上下文协议”* 具有LLM功能：

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个来源被提炼成约1450个代币。 一个天真的获取只是 *一* 其中一些页面（例如563 KB的安全博客）将转储 约140000个代币 将原始HTML导入AI的上下文中。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客户端

请参阅 集成 为您的特定客户准备桌子。作为一个快速的例子，对于 克劳德桌面:

打开配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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 --阅读一页

当你已经知道你想要的网址时，使用这个。AI传递URL并返回清理后的文本——最多 max_query_budget 字符（默认32000）。

{ "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 包含搜索中未提取的额外结果（仅限搜索引擎片段）。人工智能可以使用这些来决定是否值得更多的获取。

webgate_onboarding --操作指南

返回一个JSON指南，解释如何有效地使用webgate。如果人工智能对使用哪种工具有疑问，应在会话开始时调用一次。

🔧 将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测量文本 字符 （不是代币）。英文文本的粗略转换：

4个字符≈1个令牌

webgate_fetch 预算

当你获取一个URL时，上限是 max_query_budget （默认值 32000个字符).刀具参数 max_chars 可以要求更少，但永远不会超过这个上限。

为什么 max_query_budget 而不是 max_result_length? 因为你获取的是一页——“总输出”就是这一页，所以正确的限制是整体上下文预算，而不是为多源查询设计的每页上限。

webgate_query 预算——无法学硕士

没有LLM，清理后的源直接进入你的AI的上下文。webgate分销 max_query_budget 在所有提取的页面中，总页数永远不会超过预算：

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

总产量总是最多 max_query_budget，无论您请求多少结果，每页共享都会自动缩小以进行补偿。

webgate_query 预算——附法学硕士摘要

当二级LLM进行总结时 *压缩* 在将结果传递给主人工智能之前，先处理内容。这意味着给它更多的原材料是安全和有益的。

webgate通过以下方式扩大输入 input_budget_factor （默认值 3):

LLM投入预算 = max_query_budget × input_budget_factor 默认值：32000×3= 96000个字符

二级LLM每页看到的内容要多得多。你的主要人工智能只看到最终报告——通常 1000–3000个代币 --无论处理了多少个源。这是LLM模式的主要效率优势。

快速调整指南

🤖 LLM功能

可选，选择加入。当 llm.enabled = false （默认），webgate是完全确定的。启用 [llm] block解锁三个额外功能。

🤔 何时启用LLM功能

隐私： 禁用LLM后，除了web请求外，没有数据离开您的计算机。启用LLM后，清理后的搜索结果（不是原始HTML）将发送到配置的 base_url。将其指向本地Ollama实例，以保持设备上的所有内容。

延迟权衡： 每个启用的功能为每个查询添加一个LLM往返。膨胀增加~1-5s；根据型号和内容量的不同，摘要会增加5~30s。对于交互式使用，使用快速本地模型（例如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变量：

"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兼容的端点： 开放人工智能, 奥拉玛, LM 工作室, vLLM, 共同AI, Groq以及其他。

查询扩展

当您发送单个查询和 expansion_enabled = true，LLM在到达后端之前会自动生成互补的搜索变体。如果您已经传递了多个查询，则跳过此步骤。

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

如果LLM失败，则自动返回到原始查询。

摘要

当 summarization_enabled = true，LLM读取所有提取的页面，并编写一份带有内联引用的结构化Markdown报告。您的AI接收报告而不是原始文本。

• 成功: summary + citations （精益输出——没有原始内容传递给你的人工智能）
• 失败: llm_summary_error 原因+完整 sources 作为后备（你的AI仍然可以处理清理后的内容）

报告长度目标为 max_summary_words.何时 0 （默认），它来源于 max_query_budget / 5 --例如，对于32k的预算，目标是6400个单词。

重新排序

结果在返回之前总是按照BM25（关键字重叠，零成本）重新排序。可选地，LLM可以对语义相关性进行第二次检查：

LLM重新分级会增加与LLM响应时间成比例的延迟。仅当结果排序比速度更重要时才启用它。

管道： clean → BM25 rerank → (LLM rerank) → (LLM summarize) → output

🔗 集成

mcp-webgate适用于所有主要的AI客户端：

📦 安装

通过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要求）
• CLI参数 — --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客户端配置示例

使用env变量 （所有值都必须是字符串）：

{
  "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"
      }
    }
  }
}

使用CLI参数 （整数保持为整数——非常适合在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).

全参考

🔌 后端

SearXNG快速入门（Docker）

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

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

考试笔记

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

🛡️ 保护概述

这些保护措施始终处于活动状态——它们是核心价值主张，不能被禁用。

📚 文档结构

集成指南

• IDE集成 --克劳德桌面，克劳德代码，Zed，光标，风帆，VSCode
• 代理集成 --Gemini CLI、Claude CLI、自定义代理
• 高级功能 --BM25/LLM内部重新排序，自适应预算分配

🧪 Beta状态

mcp webgate加入 测试版核心功能稳定，服务器用于生产， 但是配置API在1.0之前仍然可能改变。

非常欢迎反馈。 如果某件事没有按预期工作，表现得很奇怪， 或者你有一个未涵盖的用例：

→

错误报告、配置问题和功能请求都有助于制定路线图。

🤝 贡献

欢迎投稿！请看 贡献.md 有关以下内容的详细指南：

• 开发设置和工作流程
• 代码风格和惯例
• 测试要求
• 文件标准
• 拉取请求流程

📄 许可证

MIT许可证——见 许可证 了解详情。

🔗 链接

• **** --源代码和问题
• PyPI包 --Python包索引
• MCP注册表 --模型上下文协议注册表
• MCP协议 --模型上下文协议规范

______________________________________________________________________