# Web Analysis MCP 服务需求文档
## 1. 项目概述
### 1.1 背景
在使用 AI 处理需要网络搜索的任务时，现有方案（如 tavily-mcp）经常因为返回的网页内容过大导致 token 超限警告或错误。本项目旨在开发一个 MCP (Model Context Protocol) 服务，通过在返回给 AI 之前对网页内容进行 LLM 总结，解决内容过大的问题。
### 1.2 核心目标
- **整合网络搜索服务**：封装 Tavily 等免费网络搜索服务
- **内容智能总结**：使用 LLM 对搜索结果进行总结压缩
- **减少 Token 消耗**：避免过大的原始内容直接返回给 AI
- **可扩展架构**：支持后续接入其他搜索服务或本地部署的服务
### 1.3 技术栈要求
- **运行时**: Node.js
- **开发语言**: TypeScript
- **协议**: MCP (Model Context Protocol)
- **搜索服务**: Tavily API (主要)，后续可扩展
- **LLM 服务**: DeepSeek API (用于内容总结)
## 2. 功能需求
### 2.1 核心功能
#### 2.1.1 Web 搜索 (web_search)
| 属性 | 说明 |
|------|------|
| 功能描述 | 执行网络搜索并返回经过 LLM 总结的结果 |
| 输入参数 | `query`: 搜索关键词 (必需)<br>`max_results`: 最大结果数 (可选，默认 5)<br>`search_depth`: 搜索深度 basic/advanced (可选，默认 basic)<br>`include_domains`: 限定搜索域名 (可选)<br>`exclude_domains`: 排除搜索域名 (可选) |
| 输出 | 经过 LLM 总结的搜索结果，包含来源链接 |
| 错误处理 | 搜索失败、LLM 调用失败时返回友好错误信息 |
#### 2.1.2 URL 内容抓取与总结 (fetch_and_summarize)
| 属性 | 说明 |
|------|------|
| 功能描述 | 抓取指定 URL 的内容并进行 LLM 总结 |
| 输入参数 | `url`: 目标网页 URL (必需)<br>`summary_prompt`: 自定义总结提示词 (可选) |
| 输出 | 网页内容的 LLM 总结 |
| 错误处理 | URL 无效、抓取失败、内容为空时返回错误 |
#### 2.1.3 批量 URL 处理 (batch_fetch)
| 属性 | 说明 |
|------|------|
| 功能描述 | 批量抓取多个 URL 并整合总结 |
| 输入参数 | `urls`: URL 列表 (必需，最多 10 个)<br>`summary_prompt`: 自定义总结提示词 (可选) |
| 输出 | 所有 URL 内容的整合总结 |
| 并发控制 | 最大并发数 5，避免请求过快 |
### 2.2 与 Creeper 项目的复用
根据 `/home/lyf/workspaces/creeper` 项目分析，以下功能可通过命令行方式复用：
| Creeper 功能 | 复用方式 | 说明 |
|--------------|----------|------|
| `creeper.py` 网页爬取 | 子进程调用 | 支持 JS 动态渲染、Cookie 管理 |
| `aggregator.py` LLM 整合 | 参考实现 | 使用相同的 LLM 调用模式 |
| 翻译功能 | 可选复用 | 如需英文内容自动翻译 |
**注意**: Creeper 是 Python 项目，本项目为 Node.js + TypeScript，因此：
- 核心 MCP 逻辑使用 TypeScript 原生实现
- 复杂网页抓取场景可通过子进程调用 Creeper
- LLM 调用参考 Creeper 的 API 封装模式
### 2.3 配置管理
#### 2.3.1 环境变量配置
```bash
# Tavily API 配置
TAVILY_API_KEY=tvly-xxxxx
# LLM 总结服务配置 (DeepSeek)
SUMMARY_API_KEY=sk-xxxxx
SUMMARY_BASE_URL=https://api.deepseek.com
SUMMARY_MODEL=deepseek-chat
SUMMARY_MAX_TOKENS=4096
# 可选: Creeper 集成
CREEPER_PATH=/home/lyf/workspaces/creeper
ENABLE_CREEPER_FALLBACK=false
# 服务配置
MAX_CONTENT_LENGTH=50000 # 触发总结的内容长度阈值
CACHE_TTL=3600 # 缓存过期时间（秒）
```
## 3. 非功能需求
### 3.1 性能要求
| 指标 | 要求 |
|------|------|
| 单次搜索响应时间 | < 30 秒 |
| 单 URL 抓取响应时间 | < 15 秒 |
| 内存占用 | < 256MB |
| 并发请求支持 | 最少 5 个 |
### 3.2 可靠性要求
- 搜索服务不可用时，返回明确的错误信息
- LLM 服务不可用时，返回原始内容（截断至安全长度）
- 支持请求超时和重试机制
### 3.3 安全要求
- API Key 通过环境变量配置，不硬编码
- 支持限制搜索域名白名单/黑名单
- 日志中不记录敏感信息
## 4. 系统架构
### 4.1 整体架构
```
┌─────────────────────────────────────────────────────────┐
│ AI Client (Claude/DeepSeek) │
└─────────────────────────────────────────────────────────┘
│ MCP Protocol
▼
┌─────────────────────────────────────────────────────────┐
│ Web Analysis MCP Server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ web_search │ │fetch_summary│ │ batch_fetch │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Search & Fetch Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ Tavily │ │ Fetch │ │Creeper(可选) │ │ │
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ LLM Summary Layer │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ DeepSeek API Client │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 4.2 目录结构
```
web-analysis-mcp/
├── src/
│ ├── index.ts # MCP 服务入口
│ ├── server.ts # MCP Server 实现
│ ├── tools/
│ │ ├── web-search.ts # web_search 工具
│ │ ├── fetch-summary.ts # fetch_and_summarize 工具
│ │ └── batch-fetch.ts # batch_fetch 工具
│ ├── services/
│ │ ├── tavily.ts # Tavily API 封装
│ │ ├── fetcher.ts # 网页抓取服务
│ │ ├── summarizer.ts # LLM 总结服务
│ │ └── creeper.ts # Creeper 集成（可选）
│ ├── utils/
│ │ ├── config.ts # 配置管理
│ │ ├── logger.ts # 日志工具
│ │ └── cache.ts # 简单缓存
│ └── types/
│ └── index.ts # 类型定义
├── docs/
│ ├── 简略需求.md
│ └── requirements.md # 本文档
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md
```
## 5. MCP 工具定义
### 5.1 web_search
```typescript
{
name: "web_search",
description: "搜索网络内容并返回经过 LLM 总结的结果。适用于需要获取最新网络信息的场景。",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description: "搜索关键词"
},
max_results: {
type: "number",
description: "最大结果数量",
default: 5
},
search_depth: {
type: "string",
enum: ["basic", "advanced"],
description: "搜索深度，basic 快速但结果较少，advanced 更全面",
default: "basic"
},
include_domains: {
type: "array",
items: { type: "string" },
description: "只搜索这些域名"
},
exclude_domains: {
type: "array",
items: { type: "string" },
description: "排除这些域名"
}
},
required: ["query"]
}
}
```
### 5.2 fetch_and_summarize
```typescript
{
name: "fetch_and_summarize",
description: "抓取指定 URL 的网页内容并使用 LLM 进行总结。适用于需要深入阅读特定网页的场景。",
inputSchema: {
type: "object",
properties: {
url: {
type: "string",
description: "要抓取的网页 URL"
},
summary_prompt: {
type: "string",
description: "自定义总结提示词，指导 LLM 如何总结内容"
}
},
required: ["url"]
}
}
```
### 5.3 batch_fetch
```typescript
{
name: "batch_fetch",
description: "批量抓取多个 URL 并整合总结。适用于需要综合多个网页信息的场景。",
inputSchema: {
type: "object",
properties: {
urls: {
type: "array",
items: { type: "string" },
description: "URL 列表，最多 10 个"
},
summary_prompt: {
type: "string",
description: "自定义总结提示词"
}
},
required: ["urls"]
}
}
```
## 6. 实现优先级
### Phase 1: 核心功能 (MVP)
1. 项目初始化 (TypeScript + MCP SDK)
2. 配置管理模块
3. Tavily API 集成
4. LLM 总结服务 (DeepSeek)
5. `web_search` 工具实现
6. 基础测试
### Phase 2: 功能完善
1. `fetch_and_summarize` 工具
2. `batch_fetch` 工具
3. 缓存机制
4. 错误处理优化
5. 日志系统
### Phase 3: 扩展功能
1. Creeper 集成（处理 JS 动态页面）
2. 其他搜索服务适配
3. 自定义提示词模板
4. 性能优化
## 7. 依赖项
### 7.1 生产依赖
```json
{
"@modelcontextprotocol/sdk": "^1.0.0",
"axios": "^1.6.0",
"zod": "^3.22.0"
}
```
### 7.2 开发依赖
```json
{
"typescript": "^5.3.0",
"@types/node": "^20.0.0",
"tsx": "^4.0.0"
}
```
## 8. 测试计划
### 8.1 单元测试
- 配置加载测试
- Tavily API 封装测试
- LLM 调用测试
- 内容截断/总结逻辑测试
### 8.2 集成测试
- MCP 工具端到端测试
- 错误场景测试
- 超时处理测试
### 8.3 手动测试
使用 Claude Desktop 或 MCP Inspector 进行实际调用测试。
## 9. 风险与缓解
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Tavily API 配额限制 | 搜索次数受限 | 实现缓存，后续支持多搜索源 |
| LLM 总结质量不稳定 | 结果可能丢失关键信息 | 设计良好的提示词，保留原始来源链接 |
| 网页抓取被阻止 | 部分网站无法访问 | 集成 Creeper 作为降级方案 |
| Token 成本 | LLM 调用产生费用 | 设置合理的内容长度阈值 |
---
**文档版本**: 1.0.0
**最后更新**: 2025-12-04
**作者**: Claude Code
