# Search MCP Server

一个基于Node.js的MCP (Model Context Protocol) 服务器，提供浏览器搜索和网页访问功能，符合MCP标准协议规范。

## 功能特性

- 🔍 **browser_search**: 使用Google搜索API获取搜索结果
- 🌐 **browser_visit**: 智能网页分析，支持多URL并发处理
- 🤖 **LLM智能摘要**: 使用AI模型进行证据提取和内容分析
- 📡 **MCP标准**: 符合Model Context Protocol规范
- 🔧 **多API支持**: Serper API / Google Custom Search API
- 🔄 **自动重试**: 智能重试机制，确保稳定性
- 🚀 **并发处理**: 支持最多5个URL同时处理
- 💡 **容错设计**: 多层备用方案，渐进增强
- 🌍 **多模型支持**: 兼容OpenAI、Azure、本地模型等
- 📝 **结构化输出**: 关键证据+总结+相关性评估

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制环境变量模板：
```bash
cp .env.example .env
```

编辑 `.env` 文件，配置API密钥：

```env
# 搜索API配置（二选一）
# 推荐使用Serper API
SERPER_API_KEY=your_serper_api_key_here

# 或者使用Google Custom Search API
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_CSE_ID=your_custom_search_engine_id_here

# LLM配置（用于智能摘要，强烈推荐）
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=your_llm_api_key_here
LLM_MODEL_NAME=gpt-3.5-turbo

# 可选：自定义头部（JSON格式）
LLM_CUSTOM_HEADERS={}

# 可选：Jina Reader API（提升内容提取质量）
JINA_API_KEY=your_jina_api_key_here
```

### 3. 启动服务

#### 启动MCP服务器
```bash
# 标准MCP服务器（stdio通信）
npm start

# 或者启动HTTP网关（用于远程访问）
npm run start-gateway
```

**注意：**
- 标准MCP服务器通过stdio进行通信，需要被MCP客户端调用
- HTTP网关模式在3001端口提供RESTful API，支持远程访问

## MCP客户端配置

### Claude Desktop配置

在Claude Desktop的配置文件中添加此MCP服务器：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "search-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:3001/sse",
      "timeout": 60
    }
  }
}
```

### 其他MCP客户端

任何支持MCP协议的客户端都可以通过stdio传输与此服务器通信。

## 工具说明

### browser_search

使用Google搜索API获取搜索结果。

**输入参数：**
- `query` (string, 必需): 搜索查询字符串
- `top_k` (integer, 可选): 返回结果数量，默认10，最大10

**输出格式：**
```json
{
  "results": [
    {
      "title": "搜索结果标题",
      "snippet": "搜索结果摘要",
      "url": "https://example.com"
    }
  ]
}
```

### browser_visit

智能网页分析工具，支持单个或多个URL的并发处理，使用AI进行内容分析和证据提取。

**输入参数：**
- `url` (string|array, 必需): 单个URL字符串或URL数组（最多5个）
- `goal` (string, 必需): 分析目标，描述你想从页面中获取什么信息

**功能特性：**
- 🤖 **AI智能分析**: 使用LLM进行证据提取和内容总结
- 🔄 **自动重试**: 失败时自动重试最多3次，指数退避
- 🚀 **并发处理**: 多URL同时处理，提高效率
- 📊 **综合分析**: 多URL时进行跨源信息整合和对比
- 🛡️ **容错机制**: Jina Reader → 直接抓取，LLM → 关键词摘要

**输出格式：**

*单URL输出：*
```
关键证据：[具体信息和数据]
总结：[基于证据的结论]
相关性评估：[内容匹配度说明]
```

*多URL输出：*
```
## 网页1: [URL]
[单独分析结果]

## 网页2: [URL]
[单独分析结果]

## 综合分析
[跨网页整合分析]

## 处理失败的URL
[失败原因说明]
```

## 使用示例

### 在Claude Desktop中使用

1. 配置好MCP服务器后，重启Claude Desktop
2. 在对话中，Claude会自动识别可用的工具
3. 你可以直接询问需要搜索或访问网页的问题

**示例对话：**

*基础搜索：*
- "帮我搜索一下最新的Node.js版本信息"
- "搜索关于MCP协议的相关资料"

*单网页分析：*
- "请访问https://nodejs.org，目标是了解最新版本的新特性"
- "分析这个技术博客，提取关于AI发展趋势的关键观点"

*多网页对比分析：*
- "同时分析这3个新闻网站关于某事件的报道，对比不同观点"
- "访问多个技术文档，整理API使用方法的最佳实践"

### 测试MCP服务器

你可以使用MCP客户端工具来测试服务器：

```bash
# 安装MCP客户端工具
npm install -g @modelcontextprotocol/inspector

# 测试服务器
mcp-inspector node src/index.js
```

## 开发模式

使用nodemon进行开发：
```bash
npm run dev
```

## 配置说明

### LLM提供商支持

**OpenAI**
```env
LLM_API_URL=https://api.openai.com/v1
LLM_MODEL_NAME=gpt-3.5-turbo
```

**Azure OpenAI**
```env
LLM_API_URL=https://your-resource.openai.azure.com/
LLM_MODEL_NAME=gpt-35-turbo
LLM_CUSTOM_HEADERS={"api-version": "2023-12-01-preview"}
```

**本地模型（Ollama）**
```env
LLM_API_URL=http://localhost:11434/v1
LLM_MODEL_NAME=llama2
```

**DeepSeek**
```env
LLM_API_URL=https://api.deepseek.com/v1
LLM_MODEL_NAME=deepseek-chat
```

### 功能层级

1. **最小配置**: 仅搜索API → 基础搜索 + 关键词摘要
2. **推荐配置**: 搜索API + LLM → 智能搜索 + AI摘要
3. **完整配置**: 搜索API + LLM + Jina → 最佳体验

## 注意事项

1. **API配置**: 如果没有配置搜索API密钥，服务器将使用模拟数据进行测试
2. **智能摘要**: 配置LLM后可获得更准确的内容分析和证据提取
3. **内容提取**: 优先使用Jina Reader API，失败时回退到直接抓取
4. **并发限制**: 单次最多处理5个URL，避免过载
5. **重试机制**: 自动重试失败的请求，指数退避策略
6. **内容截断**: 超长内容智能截断到16000字符，避免token限制

## 技术栈

- **Node.js**: 运行时环境
- **@modelcontextprotocol/sdk**: MCP协议SDK
- **Axios**: HTTP客户端
- **Cheerio**: HTML解析
- **Stdio传输**: 标准输入输出通信

## 许可证

MIT License