网页内容过滤服务

mcp-webgate是一款MCP服务器,为AI提供干净、有界的网页内容,适用于多种AI客户端和CLI代理。

  • by x-hannibal
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 annibale-x/mcp-webgate

使用说明

mcp-webgate

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

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个令牌

字符 近似标记
8,000 ~2,000
32,000 ~8,000
96,000 ~24,000

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)

已获取的结果 每页限制 总输出
1 8000(上限) ≤8000
5 6,400 ≤ 32,000
10 3,200 ≤ 32,000
20 1,600 ≤ 32,000

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

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

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

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

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

获取的结果 LLM输入/页 LLM总输入 输出到您的AI
1 96000 96000 压缩报告
5 19200 96000 压缩报告
10 9600 96000 压缩报告
20 4800 96000 简明报告

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

快速调整指南

症状 修复
AI响应速度慢,文本太多 减少 max_query_budget (例如。 16000)
AI答案肤浅或遗漏细节 增加 max_query_budget (例如。 48000)
LLM总结很薄或遗漏了一些东西 增加 input_budget_factor (例如。 5)
LLM摘要超时或非常缓慢 减少 input_budget_factor (例如。 2)或减少 results_per_query
fetch 返回的长页面太少 增加 max_query_budget (例如。 64000)
页面下载速度慢 减少 max_download_mb (例如。 1,已默认)
服务器下载了太多垃圾 减少 max_download_mb (例如。 1)

🤖 LLM功能

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

🤔 何时启用LLM功能

情况 推荐设置 典型延迟开销
快速回答,一般研究 法学硕士 残疾的 (默认)--BM25排名的干净源,零延迟开销 无
对复杂主题的深入研究 总结 --获取引用的Markdown报告,而不是原始页面 +5-30秒
主题广泛,一个查询是不够的 扩展+总结 --LLM生成变体并综合所有结果 +6-35s
结果顺序比速度更重要 LLM重新评级 --语义排序,代价是每个查询额外调用一次LLM +1-5s

隐私: 禁用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可以对语义相关性进行第二次检查:

层级 时间 成本
BM25 (确定性) 始终 零——纯数学
LLM协助 llm_rerank_enabled = true 每个查询一次LLM调用

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

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

🔗 集成

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

平台 配置指南 注意事项
克劳德桌面 IDE集成 桌面应用程序
克劳德代码 IDE集成 CLI编码代理
Zed编辑 IDE集成 原生MCP支持
光标 IDE集成 需要代理模式
帆板运动 IDE集成 仅限全局配置
VSCode IDE集成 通过Copilot或MCP扩展
双子星命令行工具 代理集成 Google的CLI代理
Claude 命令行界面 代理集成 Anthropic的CLI代理

📦 安装

通过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).

全参考

CLI参数 环境变量 默认值 描述
--default-backend WEBGATE_DEFAULT_BACKEND searxng 活动后端
--searxng-url WEBGATE_SEARXNG_URL http://localhost:8080 SearXNG实例URL
--brave-api-key WEBGATE_BRAVE_API_KEY (空) 勇敢搜索API密钥
--tavily-api-key WEBGATE_TAVILY_API_KEY (空) Tavilly API密钥
--exa-api-key WEBGATE_EXA_API_KEY (空) Exa API密钥
--serpapi-api-key WEBGATE_SERPAPI_API_KEY (空) 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 (空) 日志文件路径(空=stderr)
--trace WEBGATE_TRACE false 在摘要引用中包含内容;还激活调试日志记录
--adaptive-budget WEBGATE_ADAPTIVE_BUDGET false 【实验】基于BM25等级的比例字符分配
--adaptive-budget-fetch-factor WEBGATE_ADAPTIVE_BUDGET_FETCH_FACTOR 3 [实验]慷慨的预排名获取倍数
--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 (空) 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-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 无 推荐自托管
勇敢搜索 API密钥 高质量, 免费套餐可用
塔维利 API密钥 面向AI的片段, 免费套餐可用
艾克萨 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默认使用神经(语义)搜索,这是在关键字后端使用它的主要原因。 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 +5s连接超时
内容中隐藏的Unicode技巧 完整的正则表达式消毒管道(零宽度、BiDi等)
速率限制(429/502/503) 指数重试回退,尊重 Retry-After 头球
不需要的域名 blocked_domains / allowed_domains 过滤器

📚 文档结构

集成指南

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

🧪 Beta状态

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

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

→ 在GitHub上打开一个问题

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

🤝 贡献

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

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

📄 许可证

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

🔗 链接


需要帮助? 检查 文档 或打开 问题 在GitHub上。