内容
# chomp-mcp
[中文文档](./README.zh-CN.md)
> Generated by SCSE.
## 项目生成过程
项目从需求阶段生成，项目描述如下所示。本地父目录已编辑。
```bash
PROJECT_DESCRIPTION="$(cat <<'EOF'
<exact project description shown below>
EOF
)"
scse generate "$PROJECT_DESCRIPTION" --from requirements --output "<REDACTED_PARENT_DIR>/generated-web-research-mcp"
```
**提示（项目描述）：**
> # 项目描述：scse-chomp-mcp（带 digest 能力的联网调研 MCP server）
>
> ## 项目定位
> 为 scse-agent（以及任何遵循 MCP 协议的 LLM 客户端）提供"开箱即用、自带摘要（digest）"的联网调研能力。解决 LLM agent 的"信息茧房"问题：当用户需求涉及 agent 不熟悉的外部框架、开源项目、依赖库、API、最新技术时，agent 可以通过本 MCP server 联网调研，并直接拿到结构化的精炼结论，而不是一堆原始网页链接。
>
> 核心理念：**调用方永远收到精炼摘要，绝不收到原始网页正文**，从而避免长内容污染 agent 上下文。
>
> ## 技术栈
> - 语言：TypeScript（Node.js 18+），ESM 模块
> - MCP 协议：@modelcontextprotocol/sdk，stdio 传输（JSON-RPC over stdin/stdout）
> - 无任何付费第三方 API 依赖；零 API key 要求（除最后的 LLM 摘要复用调用方配置的 LLM）
>
> ## 架构：Search → Scrape → Deduplicate → LLM-Synthesize 四段 pipeline
>
> 本 MCP server 的核心是一条可复用的调研 pipeline，所有对外工具都基于这条 pipeline 构建：
>
> 1. **Search（搜索）**：调用 SearXNG 元搜索引擎（聚合 Google/Bing/DuckDuckGo 等多个引擎结果），获取候选结果列表（标题、URL、摘要片段）。SearXNG 零 API key、零费用、隐私友好。
>
> 2. **Scrape（抓取）**：对候选 URL 并发抓取网页正文。主路径使用轻量纯 Node 方案：HTTP 请求 + cheerio 解析 HTML + @mozilla/readability 提取正文（Firefox 阅读模式同款算法）。遇到需要 JavaScript 渲染的页面（如部分 SPA 文档站点），降级使用 Puppeteer 无头浏览器渲染后再提取。每页正文做长度截断（可配置上限，默认每页 8000 字符），防止单页过长。
>
> 3. **Deduplicate（去重降噪）**：搜索结果常有同一内容多源转载（同一篇文章出现在多个博客/CSDN/掘金）。先做 URL 规范化（去 tracking 参数、统一协议、去 fragment），再做内容级去重（基于段落指纹，如对正文分段后取 hash 集合比对相似度，相似度超阈值的视为重复只保留得分最高的一条）。去重是保证后续摘要质量的关键——不降噪会被噪音淹没。
>
> 4. **LLM-Synthesize（LLM 摘要）**：把去重后的多段正文喂给 LLM，产出针对原始查询的结构化摘要。这是整个 pipeline 的灵魂：LLM 不是简单拼接，而是综合多个来源、去伪存真、提炼出"这个问题/这个库/这个技术的关键事实、核心用法、集成方式、注意事项"。摘要格式为结构化文本，包含：直接回答（Answer）、关键要点（Key Points）、来源引用（Sources，含 URL）。**LLM 配置通过环境变量注入**（见下方配置），MCP server 内部调用 LLM，调用方无需关心。
>
> ## 对外工具（MCP tools）
>
> 本 MCP server 对外暴露两个工具，二者都内置完整或部分 pipeline，且都内置 LLM Synthesize，调用方永远拿到精炼结果：
>
> ### 工具 1：web_search
> - 用途：对一个查询（query）做完整联网调研，返回结构化摘要。这是主工具，覆盖"我不了解 X，帮我查清楚"的场景。
> - 参数：
> - `query`（string，必填）：调研查询，例如 "如何用 TypeScript 实现 MCP server"、"RuoYi-Vue3 最新版本如何集成 MyBatis-Plus"
> - `max_results`（integer，可选，默认 5）：从 SearXNG 拉取并进入 pipeline 的最大候选结果数（影响耗时和摘要质量，建议 3-8）
> - `focus`（string，可选）：调研焦点提示，引导摘要侧重某个方面，例如 "集成步骤" / "API 用法" / "版本兼容性"
> - 返回：结构化摘要文本（Answer + Key Points + Sources），非原始网页。
>
> ### 工具 2：web_fetch
> - 用途：对一个已知的具体 URL 做抓取 + 摘要，返回该页关键信息。覆盖"我已经知道要看这个文档/repo/页面，帮我提取要点"的场景。
> - 参数：
> - `url`（string，必填）：目标 URL
> - `focus`（string，可选）：提取焦点，例如 "安装方法" / "配置参数" / "CHANGELOG"
> - 返回：该页的结构化摘要文本，非原始正文。
>
> ## 模块划分
>
> 本项目按职责拆分为以下模块（供需求阶段进一步细化 User Stories）：
>
> ### 模块 SR（search-retrieval）：搜索获取
> 负责调用 SearXNG、解析返回的 JSON、规整成统一的候选结果结构（title/url/snippet/score）。处理 SearXNG 公共实例不可达时的错误、超时、重试。支持通过环境变量切换到自托管的 SearXNG 实例。
>
> ### 模块 SC（scrape-extract）：抓取提取
> 负责把 URL 转成纯文本正文。主路径 cheerio+readability，降级路径 Puppeteer。处理 HTTP 错误（404/403/超时）、编码识别、正文长度截断、非 HTML 资源（如直接是 JSON/XML 的 API 文档）的特殊处理。
>
> ### 模块 DD（deduplicate）：去重降噪
> 负责 URL 规范化和内容级去重。URL 规范化：去 utm_* 等 tracking 参数、统一大小写、去 fragment、统一尾斜杠。内容去重：对正文分段、计算段落指纹、比对相似度、合并近重复项。
>
> ### 模块 SY（synthesize）：LLM 摘要
> 负责与 LLM 交互产出结构化摘要。封装 LLM 客户端（OpenAI 兼容接口），管理摘要 prompt（要求产出 Answer/Key Points/Sources 结构、要求引用来源 URL、要求简洁），处理 LLM 调用失败、超时、token 超限（分批摘要后再合并）。
>
> ### 模块 PL（pipeline-orchestration）：编排层
> 负责把上述四段编排成完整的 web_search 工具流程，以及 web_fetch 的子流程（Scrape→Synthesize）。管理并发抓取的并发度限制、整体超时、错误隔离（单个 URL 失败不影响整体）。
>
> ### 模块 MC（mcp-server）：MCP 服务入口
> 负责 MCP server 的生命周期：stdio transport 监听、JSON-RPC 消息处理、工具定义注册（web_search/web_fetch 的 inputSchema）、工具调用分发到 PL 编排层、工具响应格式化。这是 scse-agent（或任何 MCP 客户端）连接的入口。
>
> ## 跨模块约定
>
> **配置（全部通过环境变量，零配置文件）**
> - `SEARXNG_URL`（可选，默认指向一个公共 SearXNG 实例）：SearXNG 搜索端点，可指向自托管实例
> - `LLM_API_KEY`（必填）：LLM 服务的 API key（用于 Synthesize 环节）
> - `LLM_BASE_URL`（可选，默认 OpenAI 官方）：OpenAI 兼容的 LLM 接口地址（支持对接任何兼容服务）
> - `LLM_MODEL`（可选，默认 gpt-4o-mini）：摘要使用的模型名
> - `SCRAPE_TIMEOUT_MS`（可选，默认 15000）：单页抓取超时
> - `MAX_CONTENT_CHARS`（可选，默认 8000）：单页正文截断上限
> - `MAX_CONCURRENCY`（可选，默认 3）：并发抓取数
>
> **错误处理**
> - 所有外部调用（SearXNG、网页抓取、LLM）都要有超时和重试，单点失败不击穿整体 pipeline
> - 工具返回的错误信息要友好可读，包含失败原因和建议（例如 SearXNG 不可达时提示"请检查 SEARXNG_URL 或改用自托管实例"）
> - LLM 摘要失败时，降级返回"已抓取正文的结构化拼接（截断）"作为保底，而不是整体失败
>
> **可观测性**
> - 关键步骤输出 stderr 日志（不影响 stdio JSON-RPC 通信）：搜索到 N 条结果、成功抓取 M 页、去重后剩 K 页、摘要 token 数
>
> **MCP 工具响应规范**
> - 响应必须是 MCP 标准的 content 数组（type: text），文本内容即结构化摘要
> - 摘要末尾必须附 Sources（来源 URL 列表），让调用方能追溯
>
> **项目交付物**
> - 可直接 `node dist/index.js` 启动的 MCP server
> - package.json 声明 bin，支持 `npx chomp-mcp`
> - docker-compose.yml（可选）：提供自托管 SearXNG 的最简部署，方便用户升级到更稳定/私有的搜索后端
> - README.md：包含安装、配置、在 scse-agent 中接入的方法（mcpServers 配置示例）、自托管 SearXNG 的方法
>
> ## 在 MCP 客户端中接入示例（README 需包含）
>
> MCP 客户端的配置文件中添加：
> ```json
> {
> "mcpServers": {
> "chomp-mcp": {
> "command": "node",
> "args": ["/absolute/path/to/chomp-mcp/dist/index.js"],
> "env": {
> "LLM_API_KEY": "sk-xxx",
> "LLM_BASE_URL": "https://api.openai.com/v1",
> "LLM_MODEL": "gpt-4o-mini"
> }
> }
> }
> }
> ```
> 接入后 scse-agent 的 agent loop 会自动发现 `mcp__web-research__web_search` 和 `mcp__web-research__web_fetch` 工具并按需调用。
> ## 质量要求
> - TypeScript 严格模式编译通过（tsc --noEmit 零错误）
> - MCP server 能被 @modelcontextprotocol/sdk 的 StdioClientTransport 正常连接并发现两个工具
> - web_search 对真实查询返回结构化摘要（非空、含 Sources）
> - web_fetch 对真实 URL 返回结构化摘要
> - 单次 web_search（max_results=5）端到端耗时目标 < 30 秒（搜索+抓取+摘要）
---
## 项目概述
**chomp-mcp** 是一个 MCP（Model Context Protocol）服务器，为 LLM 代理和任何 MCP 兼容的客户端提供开箱即用、带摘要能力的联网调研能力。它解决了信息茧房问题：当用户的需求涉及外部框架、开源项目、依赖库、API 或前沿技术时，agent 可以通过此 MCP 服务器联网调研，并直接获得结构化的精炼结论——而不是一堆原始网页链接。
**核心理念：** 调用方永远收到精炼摘要，绝不收到原始网页正文，从而避免长内容污染 agent 上下文窗口。
### 架构：Search → Scrape → Deduplicate → LLM-Synthesize
服务器的核心是一条可复用的研究 pipeline。两个暴露的工具都基于这条 pipeline 构建：
1. **Search** — 查询 SearXNG 元搜索引擎（聚合 Google/Bing/DuckDuckGo 等结果），获取候选结果列表（标题、URL、摘要片段）。SearXNG 需要零 API key、无费用、且隐私友好。
2. **Scrape** — 并发抓取候选 URL 的网页正文。主路径：HTTP 请求 + jsdom + @mozilla/readability。降级路径：Puppeteer 无头浏览器，用于 JavaScript 渲染的页面。内容截断至可配置的限制（默认 8,000 字符/页）。
3. **Deduplicate** — URL 规范化（去除跟踪参数、统一协议/片段），然后进行内容级去重（段落指纹 + Jaccard 相似度比较）。近似重复项被合并，保留评分最高的项目。
4. **LLM-Synthesize** — 将去重后的内容输入 LLM，生成结构化摘要（答案 + 要点 + 来源，含 URL）。通过分批和合并处理 token 溢出。LLM 失败时，降级返回原始内容的截断拼接作为保底。
### 模块交互
```
MCP 客户端（stdio JSON-RPC）
│
▼
┌─────────────────────────────────┐
│ MC（mcp-server） │ 工具调度、验证、响应格式化
│ web_search / web_fetch │
└──────────────┬──────────────────┘
│
▼
┌─────────────────────────────────┐
│ PL（pipeline-orchestration） │ 并发、超时、错误隔离
│ 运行 web_search / web_fetch │
└──┬──────┬──────┬──────┬─────────┘
│ │ │ │
▼ ▼ ▼ ▼
SR SC DD SY
搜索 抓取 去重 合成
```
- **web_search** 流经所有四个阶段：SR → SC → DD → SY
- **web_fetch** 流经两个阶段：SC → SY
---
## 项目结构
```
chomp-mcp/
├── package.json # 项目清单、脚本、依赖
├── tsconfig.json # TypeScript 严格模式编译配置
├── tsconfig.test-check.json # 测试类型检查的 TypeScript 配置
├── README.md # 英文文档
├── README.zh-CN.md # 中文文档
├── .gitignore
│
├── src/
│ ├── index.ts # 入口点 - 启动 MCP 服务器
│ │
│ ├── shared/ # 跨模块共享代码
│ │ ├── types/
│ │ │ ├── index.ts # 导出所有共享类型
│ │ │ ├── search.ts # SearchResult, SearchOptions
│ │ │ ├── scrape.ts # ScrapeResult, ExtractionMethod
│ │ │ ├── content.ts # ContentItem（搜索结果 + 抓取内容）
│ │ │ ├── deduplicate.ts # DeduplicatedItem, DDConfig
│ │ │ └── digest.ts # DigestResult, SourceRef
│ │ ├── utils/
│ │ │ ├── errors.ts # 基础错误类 + 错误类别
│ │ │ ├── logger.ts # 输出到 stderr 的结构化日志
│ │ │ ├── env.ts # 环境变量解析与默认值
│ │ │ ├── semaphore.ts # 异步并发限制器
│ │ │ └── url-utils.ts # URL 验证、SSRF 检查助手
│ │ └── config/
│ │ └── index.ts # 集中配置单例
│ │
│ └── modules/
│ ├── mcp-server/ # MC - MCP 协议入口点
│ │ ├── index.ts # 公共导出：createServer()、startServer()
│ │ ├── server.ts # 服务器生命周期、StdioServerTransport
│ │ ├── tool-definitions.ts # web_search + web_fetch 工具模式
│ │ ├── tool-handlers.ts # 工具调用调度到 PL 函数
│ │ └── validation.ts # 基于 Zod 的参数验证
│ │
│ ├── pipeline-orchestration/ # PL - 端到端 pipeline 协调器
│ │ ├── index.ts # 公共导出：runWebSearch()、runWebFetch()
│ │ ├── orchestrator.ts # 顶级 pipeline 入口 + 配置加载
│ │ ├── web-search-pipeline.ts # Search → Scrape → Dedup → Synthesize
│ │ ├── web-fetch-pipeline.ts # Scrape → Synthesize
│ │ ├── concurrency-limiter.ts # 基于信号量的 MAX_CONCURRENCY
│ │ └── timeout-guard.ts # Pipeline 超时与 AbortController
│ │
│ ├── search-retrieval/ # SR - SearXNG 元搜索引擎客户端
│ │ ├── index.ts # 公共导出：search()、错误
│ │ ├── searxng-client.ts # HTTP GET 到 SearXNG /search
│ │ ├── response-parser.ts # JSON 响应 → 规范化结果
│ │ ├── result-normalizer.ts # 评分规范化、去重、截断
│ │ ├── retry-failover.ts # 指数退火 + 多实例故障转移
│ │ ├── instance-pool.ts # 公共实例列表 + 轮换
│ │ └── errors.ts # SearchError, SearchTimeoutError 等
│ │
│ ├── scrape-extract/ # SC - URL → 纯文本内容
│ │ ├── index.ts # 公共导出：scrape()
│ │ ├── scraper.ts # 主抓取调度器（主路径 → 降级路径）
│ │ ├── http-fetcher.ts # 原生 fetch，带重定向、超时、重试
│ │ ├── content-extractor.ts # jsdom + Readability 提取
│ │ ├── puppeteer-renderer.ts # 无头浏览器降级路径，用于 JS 页面
│ │ ├── encoding-detector.ts # 字符集检测 + iconv-lite 转换
│ │ ├── content-type-router.ts # 按 Content-Type 路由（HTML/JSON/XML/文本）
│ │ ├── truncator.ts # MAX_CONTENT_CHARS 的词边界截断
│ │ ├── url-validator.ts # URL 格式 + 私有 IP SSRF 验证
│ │ └── types.ts # ScrapeOptions, ScrapeConfig, 内部类型
│ │
│ ├── deduplicate/ # DD - 纯去重/去噪变换
│ │ ├── index.ts # 公共导出：deduplicate()
│ │ ├── deduplicator.ts # 完整 pipeline 入口（URL 去重 → 内容去重）
│ │ ├── url-normalizer.ts # 跟踪参数剥离、方案/端口/片段统一
│ │ ├── paragraph-segmenter.ts # 文本分割 → 段落分割
│ │ ├── fingerprinter.ts # FNV-1a 32 位哈希 → 指纹集
│ │ ├── similarity-computer.ts # 指纹集的 Jaccard 相似度
│ │ ├── content-merger.ts # 分组 + 合并近似重复项，保留最佳
│ │ ├── stats.ts # DedupStats 累积器 + stderr 摘要
│ │ └── types.ts # DDConfig, DedupStats, FingerprintedItem
│ │
│ └── synthesize/ # SY - LLM 合成 → 结构化摘要
│ ├── index.ts # 公共导出：synthesize()、synthesizeSingle()
│ ├── synthesizer.ts # 主合成调度器
│ ├── llm-client.ts # OpenAI 兼容客户端初始化 + 重试
│ ├── prompt-builder.ts # 系统 + 用户提示构造
│ ├── response-parser.ts # 多策略摘要解析来自 LLM 文本
│ ├── batch-merger.ts # Token 溢出批量和合并逻辑
│ ├── degradation-handler.ts # 降级处理程序
│ ├── token-estimator.ts # 启发式 token 计数（EN/CJK 感知）
│ └── types.ts # SynthesizeConfig, LLMResponse, 错误类
│
└── tests/ # 测试文件（镜像 src/ 结构）
├── shared/
└── modules/
├── mcp-server/
├── pipeline-orchestration/
├── search-retrieval/
├── scrape-extract/
├── deduplicate/
└── synthesize/
```
---
## 快速开始
### 要求
- **Node.js** 18 LTS 或更高版本
- **npm**（随 Node.js 捆绑）
- **LLM API key**（OpenAI 兼容）- 综合阶段所需
### 1. 安装依赖
```bash
npm install
```
### 2. 构建项目
```bash
npm run build
```
此命令运行 `tsc` 并将编译后的 JavaScript 输出到 `dist/`。
### 3. 运行 MCP 服务器
#### 生产环境（编译后）
```bash
LLM_API_KEY="sk-your-api-key" node dist/index.js
```
#### 开发环境（使用 tsx，无构建步骤）
```bash
LLM_API_KEY="sk-your-api-key" npm run dev
```
### 4. 类型检查（无输出）
```bash
npm run typecheck
```
### 5. 运行测试
```bash
npm test
```
### 环境变量
所有配置均通过环境变量进行 - 零配置文件。
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `LLM_API_KEY` | **是** | - | LLM 服务的 API key（OpenAI 兼容） |
| `LLM_BASE_URL` | 否 | `https://api.openai.com/v1` | LLM API 基地址 |
| `LLM_MODEL` | 否 | `gpt-4o-mini` | 综合使用的模型名称 |
| `SEARXNG_URL` | 否 | 公共实例 | SearXNG 搜索端点（自托管 URL） |
| `SCRAPE_TIMEOUT_MS` | 否 | `15000` | 每页抓取超时 |
| `MAX_CONTENT_CHARS` | 否 | `8000` | 每页最大内容字符数 |
| `MAX_CONCURRENCY` | 否 | `3` | 并发抓取限制 |
| `DEDUP_SIMILARITY_THRESHOLD` | 否 | `0.85` | 近似重复检测的 Jaccard 阈值 |
| `MIN_PARAGRAPH_CHARS` | 否 | `20` | 指纹识别的最小段落长度 |
| `DEDUP_EXTRA_TRACKING_PARAMS` | 否 | （空）| 要剥离的额外跟踪参数，以逗号分隔 |
### 自托管 SearXNG
`web_search` 使用自托管的 SearXNG 实例效果最佳。下面示例启动 SearXNG 在 `127.0.0.1:8080`，启用 JSON 响应，并优选 Bing，因为某些公共引擎可能速度慢或在受限网络环境中不可用。
创建本地 SearXNG 目录：
```bash
mkdir -p ./searxng-local
cd ./searxng-local
```
创建 `settings.yml`：
```yaml
use_default_settings: true
server:
secret_key: "<REPLACE_WITH_RANDOM_SECRET>"
limiter: false
image_proxy: false
search:
safe_search: 0
autocomplete: ""
formats:
- html
- json
ui:
static_use_hash: true
outgoing:
request_timeout: 10.0
max_request_timeout: 15.0
engines:
- name: bing
engine: bing
shortcut: bi
disabled: false
base_url: https://cn.bing.com
- name: google
disabled: true
- name: duckduckgo
disabled: true
- name: brave
disabled: true
- name: startpage
disabled: true
- name: wikipedia
disabled: true
- name: wikidata
disabled: true
```
创建 `docker-compose.yml`：
```yaml
services:
searxng:
image: ghcr.io/searxng/searxng:latest
container_name: searxng-local
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./settings.yml:/etc/searxng/settings.yml:ro
environment:
- SEARXNG_BASE_URL=http://127.0.0.1:8080/
```
如果从 `ghcr.io` 拉取镜像速度慢，请用受信任的镜像替换，并保持相同的容器配置。
启动 SearXNG：
```bash
docker compose up -d
```
验证 JSON 搜索：
```bash
curl 'http://127.0.0.1:8080/search?q=Model%20Context%20Protocol&format=json'
```
在 chomp-mcp 中使用此值：
```bash
SEARXNG_URL="http://127.0.0.1:8080"
```
不要在 `SEARXNG_URL` 中包含 `/search`；chomp-mcp 在内部追加 `/search`。
---
### 从MCP客户端连接
将服务器添加到您的MCP客户端配置中，例如Trae或Claude Desktop。下面是示例，路径、API密钥、基本网址和模型名称已被删除：请替换为自己的值。
```json
{
"mcpServers": {
"chomp-mcp": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CHOMP_MCP>/dist/index.js"
],
"env": {
"LLM_API_KEY": "<REDACTED_LLM_API_KEY>",
"LLM_BASE_URL": "<OPENAI_COMPATIBLE_BASE_URL>",
"LLM_MODEL": "<MODEL_NAME>",
"LLM_TIMEOUT_MS": "120000",
"LLM_MAX_CONTEXT_TOKENS": "1000000",
"SEARXNG_URL": "http://127.0.0.1:8080",
"SEARXNG_TIMEOUT_MS": "15000",
"SCRAPE_TIMEOUT_MS": "30000",
"MAX_CONTENT_CHARS": "30000",
"MAX_CONCURRENCY": "2",
"PIPELINE_TIMEOUT_MS": "240000"
}
}
}
}
```
连接后，客户端将发现`web_search`和`web_fetch`工具。
示例提示：
```text
使用chomp-mcp搜索"模型上下文协议"并总结技术细节。
```
```text
使用chomp-mcp获取https://modelcontextprotocol.io/docs/getting-started/intro并总结核心概念。
```
---
## API概述
该服务器通过stdio JSON-RPC传输暴露两个MCP工具。没有HTTP REST端点 - 所有通信都通过stdin/stdout使用MCP协议进行。
### 工具：`web_search`
执行完整的网络研究流程（搜索 → 抓取 → 去重 → 合成），并返回结构化的摘要。
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `query` | 字符串 | 是 | — | 研究查询（最多500个字符） |
| `max_results` | 整数 | 否 | `5` | SearXNG的最大候选结果（推荐3-8） |
| `focus` | 字符串 | 否 | — | 研究重点提示，指导摘要（最多500个字符） |
**返回：** 包含以下内容的摘要文本：
- **答案** — 查询的直接合成答案
- **关键点** — 关键发现的项目符号列表
- **来源** — 带有标题的引用URL
### 工具：`web_fetch`
获取特定URL并合成其内容的摘要（抓取 → 合成）。
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `url` | 字符串 | 是 | — | 要获取和总结的目标URL |
| `focus` | 字符串 | 否 | — | 提取焦点提示（最多500个字符） |
**返回：** 结构化摘要文本（与`web_search`相同格式）。
### 响应格式
所有工具响应都是MCP标准的`content`数组，类型为"text"。文本内容是结构化的摘要。错误响应使用`isError: true`和人类可读的错误消息。超过25,000个字符的响应会截断并带有标记。
---
## 模块概述
### MC — MCP服务器（`src/modules/mcp-server/`）
MCP协议入口点。管理服务器生命周期、stdio传输、工具注册、参数验证（Zod）和工具调用调度到管道编排层。所有处理程序都包装在try/catch中，以确保服务器稳定性。
**关键文件：** `server.ts`（生命周期）、`tool-definitions.ts`（工具模式）、`tool-handlers.ts`（调度）、`validation.ts`（Zod验证）
### PL — 管道编排（`src/modules/pipeline-orchestration/`）
端到端管道协调器。为`web_search`编排搜索 → 抓取 → 去重 → 合成流程，为`web_fetch`编排抓取 → 合成流程。管理并发限制（基于信号量）、整体管道超时（AbortController）和每个URL的错误隔离。
**关键文件：** `orchestrator.ts`（入口 + 配置）、`web-search-pipeline.ts`、`web-fetch-pipeline.ts`、`concurrency-limiter.ts`、`timeout-guard.ts`
### SR — 搜索检索（`src/modules/search-retrieval/`）
SearXNG元搜索引擎客户端。发送HTTP GET请求到SearXNG，解析JSON响应，规范化结果（分数规范化，URL去重，字段截断）。支持自托管和公共实例模式，具有自动故障转移和指数退避重试。
**关键文件：** `searxng-client.ts`（HTTP客户端）、`response-parser.ts`（JSON解析）、`result-normalizer.ts`（规范化）、`retry-failover.ts`（重试逻辑）、`instance-pool.ts`（实例轮换）、`errors.ts`（错误层次结构）
### SC — 抓取提取（`src/modules/scrape-extract/`）
URL到干净文本的提取。主要路径：原生`fetch` + jsdom + @mozilla/readability。备用路径：Puppeteer无头浏览器，用于JavaScript渲染页面。处理HTTP重定向、超时、字符集检测（iconv-lite）、内容类型路由（HTML/JSON/XML/文本/二进制）、词边界截断和SSRF保护（私有IP阻止）。
**关键文件：** `scraper.ts`（编排器）、`http-fetcher.ts`（HTTP重试）、`content-extractor.ts`（Readability）、`puppeteer-renderer.ts`（JS渲染）、`content-type-router.ts`、`encoding-detector.ts`、`truncator.ts`、`url-validator.ts`
### DD — 去重（`src/modules/deduplicate/`）
纯去重和降噪转换。URL规范化剥离跟踪参数（utm_*等），统一方案/端口/片段。内容级去重使用段落分割、FNV-1a 32位指纹和Jaccard相似性比较。近重复项通过Union-Find合并，保留最高评分项。永不抛出 - 所有错误都被捕获并记录。
**关键文件：** `deduplicator.ts`（管道入口）、`url-normalizer.ts`、`paragraph-segmenter.ts`、`fingerprinter.ts`、`similarity-computer.ts`、`content-merger.ts`、`stats.ts`
### SY — 合成（`src/modules/synthesize/`）
LLM驱动的合成，生成结构化摘要。初始化OpenAI兼容客户端，构造系统/用户提示，使用重试调用LLM（瞬态错误指数退避，单独超时重试）。通过批处理和合并处理令牌溢出。在不可恢复的失败时，降级为原始内容的备用摘要。永不拒绝Promise给调用者。
**关键文件：** `synthesizer.ts`（编排器）、`llm-client.ts`（客户端 + 重试）、`prompt-builder.ts`（提示）、`response-parser.ts`（多策略解析）、`batch-merger.ts`（令牌溢出）、`degradation-handler.ts`（备用）、`token-estimator.ts`（EN/CJK感知）
### 共享（`src/shared/`）
跨模块类型定义（`SearchResult`、`ScrapeResult`、`ContentItem`、`DeduplicatedItem`、`DigestResult`、`SourceRef`），`AppError`基类，具有`ErrorCategory`鉴别器，以及实用函数（记录器、环境解析、信号量、URL帮助程序）。
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器