Web Analysis MCP

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Web Analysis MCP 是一个 MCP (Model Context Protocol) 服务，整合网络搜索服务并通过 LLM 总结内容，解决直接返回过大网页内容导致 AI token 超限的问题。

**核心特性**：
- SearXNG 搜索引擎集成
- LLM 智能过滤和主题分类
- Creeper 网页爬虫
- 智能内容总结

## 必须遵守的规则
* 保持模块的单一性
* import 语句必须在文件顶部

## Commands

```bash
# 安装依赖
npm install

# 开发模式 (使用 tsx 直接运行 TypeScript)
npm run dev

# 构建 TypeScript
npm run build

# 生产模式运行
npm start

# 类型检查
npm run typecheck

# 清理构建产物
npm run clean

# 运行 MCP Inspector 测试
npm run test:inspector

# 开发模式测试（直接运行源码，无需构建）
npm run test:dev
```

## Testing

使用 MCP Inspector 进行功能测试：

### 生产环境测试
1. 确保环境变量配置完整（参考 Environment Variables）
2. 安装 Inspector：`npm install -g @modelcontextprotocol/inspector`
3. 运行 `npm run test:inspector`
4. Inspector 会自动测试所有工具并提供详细报告

### 开发环境测试（推荐）
1. 确保环境变量配置完整（参考 Environment Variables）
2. 安装 Inspector：`npm install -g @modelcontextprotocol/inspector`
3. 运行 `npm run test:dev`
4. Inspector 会直接运行源码（tsx src/index.ts），无需构建，支持实时调试

测试用例位于 `tests/inspector/` 目录：
- `web-search.test.json` - web_search 工具测试
- `error-handling.test.json` - 错误处理测试

## Architecture

### 分层设计

```
AI Client (Claude/DeepSeek)
       │ MCP Protocol (stdio)
       ▼
   server.ts ─── MCP Server，注册工具和处理器
       │
       ▼
   tools/ ─── 工具实现层，处理输入验证和结果格式化
       │
       ▼
   services/ ─── 服务层，封装外部 API 调用
       │
       ├── searxng.ts     # SearXNG 搜索服务
       ├── creeper.ts     # Creeper 网页爬虫
       ├── filter-llm.ts  # LLM 智能过滤服务
       └── summarizer.ts  # DeepSeek LLM 总结
```

### 关键模块

- **server.ts**: MCP Server 入口，注册工具和处理器
- **tools/**: 工具实现层，处理输入验证和结果格式化
- **services/**: 服务层，封装外部 API 调用
  - **searxng.ts**: SearXNG 搜索服务
  - **creeper.ts**: 网页爬虫服务
  - **filter-llm.ts**: LLM 智能过滤服务
  - **summarizer.ts**: LLM 内容总结服务
- **prompts/**: LLM 提示词模板
  - **filter.ts**: 智能过滤提示词
  - **summary/**: 各主题总结模板
- **utils/config.ts**: 环境变量配置管理

### 数据流

1. AI 客户端通过 stdio 发送 MCP 工具调用请求
2. server.ts 根据工具名分发到对应的 execute 函数
3. execute 函数调用 services 获取数据：
   - SearXNG 搜索获取结果列表
   - 可选 LLM 智能过滤（主题分类 + 关联性筛选）
   - Creeper 爬取网页内容
4. 若内容超过阈值，调用 summarizer 进行 LLM 总结
5. 返回格式化的 Markdown 结果

## Environment Variables

必需：
- `SEARXNG_BASE_URL`: SearXNG 实例地址
- `CREEPER_PATH`: Creeper 项目路径
- `SUMMARY_API_KEY`: LLM 总结服务 API Key

可选：
- **LLM 过滤配置**：
  - `FILTER_LLM_ENABLED`: 启用 LLM 智能过滤 (默认 false)
  - `FILTER_LLM_API_KEY`: 过滤服务 API Key
  - `FILTER_LLM_BASE_URL`: 过滤服务 API 地址 (默认 https://api.deepseek.com)
  - `FILTER_LLM_MODEL`: 过滤服务模型 (默认 deepseek-chat)
- **总结服务配置**：
  - `SUMMARY_BASE_URL`: 总结服务 API 地址
  - `SUMMARY_MODEL`: 总结服务模型
- **其他配置**：
  - `MAX_CONTENT_LENGTH`: 触发总结的阈值 (默认 50000)
  - `LOG_LEVEL`: 日志级别 (默认 info)

## MCP Tools

| 工具 | 用途 |
|------|------|
| `web_search` | SearXNG 搜索 + 智能过滤 + 爬取 + 总结 |