webshift (Annibale X)

WebShift

______________________________________________________________________

什么是WebShift

WebShift是一个Rust库和MCP服务器，可以将嘈杂的网页转换为 用于LLM消费的干净、大小合适的文本。

原始HTML大多是垃圾：脚本、广告、导航菜单、cookie横幅、， 跟踪像素。将其直接输入LLM会淹没上下文窗口 有数万个无用的代币，没有推理的余地。 WebShift去除所有噪音，对文本进行消毒，并严格执行 调整预算，使模型只接收重要的内容。

你得到了什么

根据您启用的功能，WebShift可以有四种：

何时使用WebShift

• 你正在构建一个需要网络搜索的人工智能代理，你想要干净，

预算控制的文本，而不是原始HTML。

• 您正在Rust管道中处理网页，需要一个可靠的

HTML到文本清洁器，在不丢失真实内容的情况下去除噪音。

• 您需要LLM来翻译、重写或简化HTML中的文本

在不损坏标记的情况下，文本映射为您提供了一个安全的往返。

• 您需要一个作为单个二进制文件工作的MCP web搜索服务器--

没有Python，没有pip，没有venv，没有Docker（除非你想要）。

• 您需要对输出大小进行严格保证：每页上限、总预算

上限、流媒体下载限制。

何时不使用WebShift

• 你需要一个无头浏览器来渲染JavaScript繁重的SPA。

WebShift解析静态HTML——它不执行JS。

• 您需要渲染或截图一个页面，以保留其视觉布局。

WebShift处理HTML结构，但不渲染CSS或计算布局。 （注： text-map 确实为文本重写用例保留了DOM结构。)

• 你正在构建一个需要跨页面导航的网络爬虫，

填写表单或处理身份验证流程。

______________________________________________________________________

运作原理

Question
  |
  +- (optional) LLM query expansion -> multiple search variants
  |
  +- Search via backend (SearXNG, Brave, Tavily, Exa, SerpAPI, Google, Bing, HTTP)
  |
  +- Deduplicate + filter binary URLs
  |
  +- Streaming fetch with per-page size cap
  |
  +- HTML cleaning -> plain text (noise elements, scripts, nav removed)
  |
  +- Unicode/BiDi sterilization
  |
  +- BM25 deterministic reranking
  |   +- (optional) LLM-assisted tier-2 reranking
  |
  +- Budget-aware truncation across all sources
  |
  +- (optional) LLM Markdown summary with inline citations
  |
  +- Structured JSON output

______________________________________________________________________

安装

二进制（MCP服务器）

cargo install webshift-mcp

二进制文件被称为 mcp-webshift.

来源

cargo install --path crates/webshift-mcp

作为一个图书馆

# Full pipeline (search + fetch + clean + rerank)
webshift = "0.2"

# Cleaner + fetcher only (no search backends)
webshift = { version = "0.2", default-features = false }

# Text-map only (extract/replace text nodes in HTML)
webshift = { version = "0.2", default-features = false, features = ["text-map"] }

# Everything including LLM features
webshift = { version = "0.2", features = ["llm"] }

______________________________________________________________________

快速启动

1.设置搜索后端

最简单的选择是 SearXNG -免费、自托管、无API密钥：

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

没有Docker？使用云后端——请参阅 搜索后端.

2.配置您的MCP客户端

{
  "mcpServers": {
    "webshift": {
      "command": "mcp-webshift",
      "args": ["--default-backend", "searxng"]
    }
  }
}

就是这样。代理人现在有 webshift_query, webshift_fetch，以及 webshift_onboarding.

有关特定于客户端的设置，请参阅 文档/集成/.

______________________________________________________________________

MCP工具

webshift_query 参数

______________________________________________________________________

配置

解决顺序（最高优先级优先）：

1. CLI参数 — --default-backend, --brave-api-key等等。
2. 环境变量 — WEBSHIFT_* 前缀
3. 配置文件 — webshift.toml （当前目录，然后 ~/webshift.toml)
4. 内置默认值

配置文件

[server]
max_query_budget    = 32000   # total char budget across all sources
max_result_length   = 8000    # per-page char cap
max_total_results   = 20      # hard cap on results per call
max_download_mb     = 1       # streaming cap per page (MB)
search_timeout      = 8       # seconds
results_per_query   = 5
oversampling_factor = 2
adaptive_budget     = "auto"  # "auto" | "on" | "off" — budget allocation mode

[backends]
default = "searxng"

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

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

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

[backends.exa]
api_key = "..."

[backends.serpapi]
api_key = "..."
engine  = "google"    # google | bing | duckduckgo | yandex

[backends.google]
api_key = "..."
cx      = "..."       # Custom Search Engine ID

[backends.bing]
api_key = "..."
market  = "en-US"

[backends.http]
url           = "https://my-search.example.com/api/search"
query_param   = "q"
count_param   = "limit"
results_path  = "data.items"     # dot-path to results array in JSON response
title_field   = "title"
url_field     = "link"
snippet_field = "description"

[backends.http.headers]
"Authorization" = "Bearer my-token"

[llm]
enabled               = false
base_url              = "http://localhost:11434/v1"   # OpenAI-compatible
api_key               = ""
model                 = "gemma3:27b"
timeout               = 60
expansion_enabled     = true
summarization_enabled = true
llm_rerank_enabled    = false

对于具有所有三种配置方法（TOML、env变量、CLI参数）的每个设置 以及简单的语言描述，请参阅完整 配置参考.

关键环境变量

WEBSHIFT_DEFAULT_BACKEND=searxng
WEBSHIFT_SEARXNG_URL=http://localhost:8080
WEBSHIFT_BRAVE_API_KEY=BSA-xxx
WEBSHIFT_GOOGLE_API_KEY=xxx
WEBSHIFT_GOOGLE_CX=xxx
WEBSHIFT_BING_API_KEY=xxx
WEBSHIFT_LLM_ENABLED=true
WEBSHIFT_LLM_BASE_URL=http://localhost:11434/v1
WEBSHIFT_LLM_MODEL=gemma3:27b

______________________________________________________________________

搜索后端

______________________________________________________________________

LLM功能（可选）

所有选择加入-默认情况下禁用，除非启用，否则任何数据都不会离开您的计算机。

跨语言规范化（奖金）： 当BM25重新排序页面时 外语（如中文、日语、阿拉伯语），法学硕士总结者仍然 以提示语言生成最终报告。试剂接收干净的， 无论源页面中的语言组合如何，都能获得可读的输出。

适用于任何与OpenAI兼容的API（OpenAI、Ollama、vLLM、LM Studio等）：

[llm]
enabled  = true
base_url = "http://localhost:11434/v1"
model    = "gemma3:27b"

______________________________________________________________________

防洪保护

始终活跃——核心价值主张：

______________________________________________________________________

图书馆使用情况

use webshift::{Config, clean, fetch, query};

// Clean raw HTML — cap output at 8000 chars
let result = clean("
Hello world
", 8000);
println!("{}", result.text);

// Pass 0 to disable the per-page cap entirely (no truncation)
let full = clean("
Hello world
", 0);
assert!(!full.truncated);

// Fetch and clean a single page
let config = Config::default();
let page = fetch("https://example.com", &config).await?;

// Full search pipeline
let results = query(&["rust async programming"], &config).await?;
for source in &results.sources {
    println!("[{}] {} — {} chars", source.id, source.title, source.content.len());
}

// Backend partial failures (CAPTCHA, rate-limits, engine outages) are surfaced
// in `warnings` rather than as Err. Empty sources + non-empty warnings means
// "all backends blocked" — distinct from a legitimate "no matches found".
if results.sources.is_empty() && !results.warnings.is_empty() {
    eprintln!("all backends failed: {:?}", results.warnings);
}

文本映射：在不破坏标记的情况下重写HTML内容

提取文本节点，操纵它们（翻译、重写、简化），并重建 具有完整结构、属性和链接的HTML。

use webshift::{extract_text_nodes, replace_text_nodes, TextReplacement};

let html = r#"
Hello world
"#;
let map = extract_text_nodes(html);
// map.nodes = [(0, "Hello"), (1, "world")]

let replacements = vec![
    TextReplacement { id: 0, text: "Ciao".into() },
    TextReplacement { id: 1, text: "mondo".into() },
];
let result = replace_text_nodes(html, &replacements).unwrap();
// → 
Ciao mondo

// href untouched, tags intact, only text changed.

需要 features = ["text-map"]。参见 用例#11 查看完整的翻译示例。

功能开关

______________________________________________________________________

集成

______________________________________________________________________

Beta状态

WebShift已启用 测试版核心功能稳定，服务器每天使用， 但是API表面在1.0之前仍然可能改变。

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

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

贡献

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

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

许可证

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

链接

• **** --源代码和问题
• 博士 -API文件
• MCP注册表 --模型上下文协议注册表上的WebShift
• MCP协议 --模型上下文协议规范

______________________________________________________________________