让你的 AI 智能体在一次工具调用中完成真正的网络研究：搜索 → 阅读完整页面 → 排序 → 返回带引用的段落。
搜索工具只会给模型标题和 150 字符的摘要，所以模型只能猜测其余内容。抓取工具会给它 40 KB 的导航和样板内容，让它淹没其中。WebVector 在中间完成全部工作：执行搜索，下载并清理每个结果（HTML、PDF、Markdown），将其拆分为段落，再根据问题对这些段落排序——当有嵌入模型可用时进行语义排序，否则进行词法排序（BM25）——并且只返回能回答查询的段落，每个段落都带有 URL、标题、偏移量和分数。
无需 API 密钥，也无需下载模型即可使用：DuckDuckGo + BM25，安装包约 12 MB。
可接入任何搜索后端、嵌入提供方、向量存储或重排序器（或者在一个文件中编写你自己的）。
以库、MCP 服务器（Claude Code、Claude Desktop、Cursor、Windsurf、……）和 CLI 的形式提供。
默认礼貌且安全：robots.txt、按主机限流、SSRF 防护、大小/重定向/时间上限、无遥测。
npx -y webvector-cli search "what changed in the MCP spec in 2026?"# Web research: what changed in the MCP spec in 2026?
**[1]** Streamable HTTP — Model Context Protocol — <https://modelcontextprotocol.io/specification/2026-07-28/…> (score 1.00)
> ### Earlier Streamable HTTP Revisions
> Protocol versions 2025-03-26 through 2025-11-25 also used the Streamable HTTP transport, but in a
> different shape: servers could assign a session via the Mcp-Session-Id header … None of these
> mechanisms are part of this revision.
…
## Sources
- Streamable HTTP — Model Context Protocol — <https://…> [1]要求：Node.js ≥ 22.12（推荐 Node 24）。支持 macOS、Linux 和 Windows。
Related MCP server: MyWebSearch MCP
无需安装，无需密钥：
npx -y webvector-cli search "how does reciprocal rank fusion work" --stats你会看到这些段落，然后是一行统计信息，例如 search duckduckgo 957ms · pages 4/5 908ms · embed 0 chunks (none/bm25) · retrieve 10ms · total 1879ms。embed … none/bm25 表示你处于词法层级（参见 §5）——一旦存在模型运行时或嵌入 API 密钥，语义层级就会自动开启。
检查你的机器将使用哪种模式：
npx -y webvector-cli doctorMCP 服务器向任何 MCP 客户端暴露四个工具——web_research（主要工具）、web_fetch、web_search、webvector_status。
Claude Code
claude mcp add webvector -- npx -y webvector-mcpClaude Desktop / Cursor / Windsurf / VS Code——添加到你的 MCP 配置中（claude_desktop_config.json、~/.cursor/mcp.json、……）：
{
"mcpServers": {
"webvector": {
"command": "npx",
"args": ["-y", "webvector-mcp"],
"env": { "BRAVE_API_KEY": "optional — see §7" }
}
}
}这就是词法层级。要在设备端进行语义搜索，请同时安装模型运行时：
"args": ["-y", "-p", "@huggingface/transformers", "-p", "webvector-mcp", "webvector-mcp"]……或者只需在 env 中放入一个嵌入密钥（OPENAI_API_KEY、VOYAGE_API_KEY、GEMINI_API_KEY、COHERE_API_KEY），它就会自动升级。
通过 HTTP（适用于 Agent 框架）：npx -y webvector-mcp --http --port 3333 → http://127.0.0.1:3333/mcp（Streamable HTTP，仅限 localhost）。添加 --token <secret>（或 WEBVECTOR_MCP_TOKEN）以要求 Authorization: Bearer <secret>；绑定到任何其他地址需要 --host 0.0.0.0 --allow-remote --token …，并且应放在 TLS/你自己的认证之后。GET /health 用于存活检查。
每个 web_research 结果都会以紧凑的 Markdown（供模型使用）和 structuredContent（供你的应用使用）两种形式返回，并在运行期间发送进度通知。
npm i webvectorimport { WebVector } from 'webvector';
const wv = new WebVector(); // zero-config
const res = await wv.research('what is reciprocal rank fusion');
console.log(res.markdown); // ready to drop into a prompt
for (const p of res.passages) console.log(p.score, p.citation); // "[1] Title — https://…"
await wv.close();通过传入选项进行配置（完整列表见 §6）：
const wv = new WebVector({
search: { provider: 'brave' }, // reads BRAVE_API_KEY
embeddings: { provider: 'openai', model: 'text-embedding-3-small' },
retrieval: { topK: 8, rerank: 'cohere' },
store: { mode: 'session' }, // reuse pages across calls
});
const res = await wv.research('How does Node 24 handle AbortSignal.any?', {
relatedQueries: ['AbortSignal.any example'], // extra angles (also searched)
freshness: 'year', // day | week | month | year
domainsAllow: ['nodejs.org', 'developer.mozilla.org'],
sessionId: 'conversation-42', // pages already read this session are reused
onProgress: (p) => console.error(p.stage, p.message),
});其他调用：wv.search(query)（仅结果）、wv.fetch(url)（单个页面 → Markdown）、wv.fetchAndRetrieve(url, query)（单个页面 → 相关段落）、wv.listSessions()、wv.clearSession(id)。
把它作为工具交给模型——流行 SDK 的绑定只需一次导入即可使用：
// Vercel AI SDK
import { generateText, isStepCount } from 'ai';
import { webVectorTools } from 'webvector/ai-sdk';
await generateText({ model, tools: await webVectorTools(wv), stopWhen: isStepCount(5), prompt });
// Anthropic Messages API // OpenAI Responses API // LangChain.js
import { anthropicTools, runAnthropicTool } from 'webvector/anthropic';
import { openaiTools, runOpenAITool } from 'webvector/openai';
import { langchainTools } from 'webvector/langchain';
// Anything else: plain JSON Schema
import { webResearchToolDefinition } from 'webvector';每个的可运行版本都在 examples/ 中。
npm i -g webvector-cli # or keep using npx -y webvector-cli …
webvector search "query" [-k 8] [-p 12] [--provider brave] [--embeddings openai] [--rerank local] [--json|--md] [--stats]
webvector fetch <url> [--query "…"] # one page as Markdown, or just the passages relevant to --query
webvector serp "query" # search results only
webvector doctor [--live] # config, dependencies, provider connectivity, active tier
webvector init # writes webvector.config.yaml + .env.example
webvector config # print resolved config (secrets redacted)
webvector providers # every provider and the env var it reads
webvector mcp [--http] # run the MCP server一个旋钮——embeddings.provider，默认为 auto——决定段落如何排序：
层级 | 安装 | 排序 | 选择时机 |
词法（ | ~12 MB，无需下载 | 对完整抓取页面进行 BM25 排序 + 查询扩展 + 按来源多样性 | 没有模型运行时且没有嵌入密钥时（纯 |
语义（ | + | 混合：向量 + BM25 通过 RRF 融合，MMR 多样性，可选重排序器 | 只要两者之一可用，自动启用 |
随时升级：在包旁边执行 npm i @huggingface/transformers，或设置一个密钥。webvector doctor 会显示当前激活的层级。词法模式是一种受支持的模式，而不是回退——结果会标记为 stats.embed.provider: 'none'，并不算“降级”。
优先级：代码 → 配置文件 → 环境变量 → 默认值。配置文件：webvector.config.{ts,js,mjs,json,yaml,yml}、.webvectorrc，或 package.json 中的 webvector 键，从工作目录向上查找。值中的 ${VAR} / ${VAR:-default} 会从环境变量中填充。
webvector init 会生成一个带注释的起步配置；以下是人们实际会修改的选项：
search:
provider: duckduckgo # duckduckgo | brave | serper | serpapi | google-cse | searxng | tavily | tavily-keyless | exa | perplexity | wikipedia
fallbackProviders: [tavily-keyless, wikipedia]
resultsPerQuery: 10
embeddings:
provider: auto # auto | none | local | openai | openai-compatible | gemini | voyage | cohere | mistral | jina | ollama
model: Xenova/all-MiniLM-L6-v2 # local aliases: minilm (fast) | granite (quality) | embeddinggemma (best) | bge-small | nomic …
store:
provider: memory # memory | chroma | qdrant | pgvector
mode: ephemeral # ephemeral (per call) | session (reuse by sessionId, TTL) | persistent (external store)
retrieval:
topK: 12
hybrid: true # BM25 + vectors fused with RRF (semantic tier)
queryExpansion: true # heuristic (no LLM); pass retrieval.llm in code for LLM multi-query
maxPerSource: 3
mmr: true
rerank: false # local | cohere | voyage | jina | llm
ingestion:
maxPages: 10
maxConcurrentFetches: 8
timeoutMs: 15000
totalDeadlineMs: 45000
respectRobotsTxt: true
chunkSize: 480 # tokens
output:
markdown: true
maxPassageChars: 1500
logging:
level: warn对应的环境变量：WEBVECTOR_SEARCH_PROVIDER、WEBVECTOR_EMBEDDINGS_PROVIDER、WEBVECTOR_EMBEDDINGS_MODEL、WEBVECTOR_STORE_PROVIDER、WEBVECTOR_STORE_MODE、WEBVECTOR_TOP_K、WEBVECTOR_MAX_PAGES、WEBVECTOR_LOG_LEVEL、WEBVECTOR_MODEL_CACHE，以及下面的提供方密钥。每个选项及其默认值：docs/CONFIGURATION.md。
设置环境变量，指定提供方，完成。每个提供方的详细信息和注意事项：docs/PROVIDERS.md。
搜索 | 环境变量 | 嵌入 | 环境变量 | 存储 / 重排序器 | 环境变量 |
| — |
| — |
| — |
|
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 重排序 | — |
|
|
|
| 重排序 |
|
|
|
|
| 重排序 |
|
|
|
|
| 重排序 |
|
| — | 任何 Vercel AI SDK 模型 | — | 重排序 | — |
如果主要搜索提供方失败或被限流，会自动尝试 fallbackProviders 链，并且每次尝试都会记录在 stats.search.attempts 中。
interface ResearchResult {
query: string; queries: string[]; // the query + expansions actually used
passages: Passage[]; // ranked; each: text, url, title, score (0–1), cosine?, bm25?,
// rerankScore?, chunkIndex, startOffset, endOffset, publishedAt?,
// fetchedAt, matchedQueries, citation "[n] Title — url"
sources: SourceSummary[]; // one per page: status ok|failed|cached, chunks, bestScore, passageIndices, failure?
failures: Failure[]; // per-URL / per-stage problems with machine codes (never thrown)
stats: { search, ingest, embed, retrieve, totalMs, warnings }; // timings + counts per stage
markdown?: string; // the pre-rendered version above
degraded?: 'search_only' | 'partial'; // e.g. every fetch failed → search snippets returned instead
}两类，刻意分开：
失败是逐页的，绝不会中止一次运行：FETCH_TIMEOUT、FETCH_HTTP_ERROR、FETCH_BLOCKED_ROBOTS、FETCH_BLOCKED_SSRF、FETCH_TOO_LARGE、TOO_MANY_REDIRECTS、UNSUPPORTED_CONTENT_TYPE、PARSE_EMPTY、PARSE_FAILED。它们会进入 result.failures[] 和 sources[].failure。如果每个页面都失败，你仍然会得到搜索摘要（degraded: 'search_only'、ALL_FETCHES_FAILED）。
错误会以 WebVectorError 形式抛出，包含 code、message、remediation、retryable、provider、stage 和 toJSON()；机密信息会被脱敏。示例：MISSING_API_KEY（“设置 BRAVE_API_KEY … 或使用无密钥提供方：duckduckgo”）、MISSING_DEPENDENCY（“npm i @huggingface/transformers — 或 embeddings.provider: 'none'”）、SEARCH_BLOCKED、PROVIDER_RATE_LIMITED（带 retryAfterMs）、EMBEDDING_DIMENSION_MISMATCH（会指出两个模型；建议 store.clear() 或新建集合）、INVALID_CONFIG。
WebVector 会抓取搜索引擎选定的 URL——也就是说，攻击者可能影响这些内容——因此抓取器默认采取防御性措施：
SSRF 防护：拒绝私有、回环、链路本地、CGNAT、组播、保留、IPv4 映射 IPv6 以及 localhost/*.internal 目标；检查 DNS 应答，并对每次重定向跳转重新检查。仅对可信的本地设置（ingestion.allowPrivateNetworks）可选择退出。
上限：重定向（5 次）、响应大小（5 MB）、单请求时间（15 秒）和整个运行截止时间（45 秒）；全局和每主机并发有界。
礼仪：遵守 robots.txt（包括 Crawl-delay）、可识别的 User-Agent、每主机最小间隔、尊重 Retry-After。
解析而不执行：HTML 使用 linkedom 解析（无脚本、无子资源加载），PDF 使用 pdf.js 的无 eval 模式；调用方只会收到去除控制字符的 Markdown/纯文本。
机密：从环境变量/配置读取，绝不记录；在错误、webvector config 以及 MCP webvector_status 工具中都会进行脱敏。除非你启用页面缓存目录，否则不会向磁盘写入任何内容。
绝无遥测。
基于 HTTP 的 MCP 仅绑定到 127.0.0.1，验证 Host/Origin（DNS 重绑定防护），支持 bearer 令牌，并且在没有 --allow-remote 和令牌的情况下拒绝绑定到其他位置。
DNS 重绑定在连接时即被阻断：SSRF 检查在用于打开套接字的 DNS 查找内部运行，因此被检查的地址就是实际拨号的地址。
DuckDuckGo 说明：无密钥提供程序使用类似浏览器的 User-Agent 与 DuckDuckGo 的公共 HTML 端点通信（没有官方 API）。它本质上受速率限制且不稳定；大量或商业使用应切换到带密钥的提供程序（brave、serper、tavily）。页面抓取始终使用诚实的 WebVector/… User-Agent。
发现问题？请在 GitHub 上打开私有安全公告，而不是公开问题。
git clone https://github.com/rthomas24/web-vector
cd webvector
npm install # installs all workspaces (~1 min; includes the optional model runtime for tests)
npm run build # tsdown → packages/*/dist
# use the local build
node packages/cli/dist/cli.js search "reciprocal rank fusion" --stats
node packages/mcp/dist/bin.js # MCP server on stdio
node packages/mcp/dist/bin.js --http --port 3333 # …or HTTP
# point an MCP client at the local build
claude mcp add webvector-dev -- node /absolute/path/to/webvector/packages/mcp/dist/bin.js
# quality gates
npm test # unit tests, offline (mocked HTTP), ~5 s
npm run test:live # real network + local model + MCP stdio round-trip (~20 s)
npm run lint # biome
npm run typecheck # TypeScript 7仓库布局以及在哪里添加内容：docs/ARCHITECTURE.md。
要从另一个项目使用本地构建而不发布：在 packages/core（以及 mcp/cli）中运行 npm pack，然后在那里运行 npm i ./webvector-0.1.0.tgz，或使用 npm link。
每种提供程序类型都是 packages/core/src/types.ts 中的一个小接口——SearchProvider、EmbeddingProvider、VectorStore、ContentParser、Reranker。实现它，然后在配置中传入实例或注册名称，以便配置文件可以使用它：
import { customSearchProvider, registerSearchProvider, WebVector } from 'webvector';
const myIndex = customSearchProvider('my-index', async (query) => [
{ url: 'https://…', title: '…', snippet: '…' },
]);
new WebVector({ search: { instance: myIndex } });
// or: registerSearchProvider('my-index', (opts) => new MyProvider(opts)); → search.provider: my-indexwebvector/testing 导出了符合性检查（searchProviderConformance、embeddingProviderConformance、vectorStoreConformance），你可以将其放入任何测试运行器。
research(query)
1. search provider chain (DuckDuckGo → fallbacks) → dedupe by canonical URL → domain filters → top N
2. ingest concurrent, polite fetch → HTML (Readability→Markdown) | PDF | text → page cache
3. chunk+embed markdown-aware recursive chunks with heading breadcrumbs → content-hash dedupe → embed (batched, cached)
4. retrieve query + expansions → vector top-k lists + BM25 top-k lists → weighted RRF → cosine cutoffs
→ near-duplicate removal → per-source cap → MMR → optional rerank → top-k
5. format passages with citations, sources, failures, per-stage stats, Markdown在笔记本电脑上的典型运行：搜索约 1 秒，抓取并解析 8 个页面约 1–2.5 秒，检索 < 50 毫秒 → 约 2 秒词法 / 约 4 秒语义。
LanceDB 和 Pinecone 存储 · 用于 JS 渲染页面的无头浏览器抓取适配器 · 上下文检索（LLM 摘要的块上下文）作为可选功能 · 无需 Node 的独立二进制文件 · 共享符合性夹具的 Python 包。
MIT © Ryan Thomas
This server cannot be deployed
Scrape, crawl and search the web for AI agents via MCP.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Web search, scraping, RAG answers with citations, and translation as MCP tools.
