# heventure-search-mcp

一个无需 API Key 即可使用的网页搜索 MCP（Model Context Protocol）服务，支持多搜索引擎并发与自动回退。

> 🔗 **基于上游项目**：[HughesCuit/heventure-search-mcp](https://github.com/HughesCuit/heventure-search-mcp) v1.5.3
>
> 本仓库在上游基础上增加了 Google CSE 引擎支持（参考 [SearXNG](https://github.com/searxng/searxng) 的 `google_cse.py` 引擎实现），以及 Bing 中文搜索语言检测修复等改进。感谢原作者 [HughesCuit](https://github.com/HughesCuit) 和 SearXNG 项目的工作。

## ✨ 特性

- **多引擎并发**：DuckDuckGo + Bing + Google + SerpAPI + Google CSE，一次查询覆盖多个搜索引擎
- **零配置可用**：不配任何 API Key 即可使用 DuckDuckGo + Bing + Google（HTML 解析）
- **按需启用**：配置 SERPAPI_KEY / TAVILY_API_KEY / GOOGLE_CSE_ID 后自动激活对应引擎
- **智能缓存**：内置 LRU 缓存，减少重复请求
- **自动重试**：网络超时自动重试，提高稳定性
- **SSRF 防护**：内置 URL 安全校验

## 🔍 支持的搜索引擎

| 引擎 | 需要 | 说明 |
|---|---|---|
| DuckDuckGo | 无 | 免费，调 API 绕过反爬 |
| Bing | 无 | 免费，动态 Accept-Language（中文→zh-CN，英文→en-US） |
| Google | 无 | 免费，HTML 解析 |
| SerpAPI | `SERPAPI_KEY` | 付费，Google 官方 API，英文搜索质量最高 |
| Google CSE | `GOOGLE_CSE_ID` | 免费，自定义搜索引擎，可限定白名单站点 |
| Tavily | `TAVILY_API_KEY` | 付费，AI 搜索引擎 |

## 📦 安装

```bash
# 克隆项目
git clone https://github.com/yourname/heventure-search-mcp.git
cd heventure-search-mcp

# 安装依赖
pip install -r requirements.txt
```

## ⚙️ 配置

所有配置通过环境变量传入，无需修改代码：

```bash
# 必需（无则仅用免费引擎）
export SERPAPI_KEY="your_serpapi_key"        # https://serpapi.com
export GOOGLE_CSE_ID="your_cse_id"           # https://programmablesearchengine.google.com
export TAVILY_API_KEY="your_tavily_key"      # https://tavily.com

# 可选
export WEB_SEARCH_SSL_VERIFY="true"          # SSL 验证（默认 true）
export SOCKS_PROXY="socks5://127.0.0.1:1080"  # SOCKS5 代理
```

## 🚀 使用

### 作为 MCP Server 运行

```bash
python -m heventure_search_mcp.server
```

### 在 QwenPaw 中配置

在 `drivers/mcp/heventure-search.yaml` 中：

```yaml
name: heventure-search
type: stdio
command: /path/to/python3
args:
  - -m
  - heventure_search_mcp.server
env:
  PYTHONPATH: /path/to/heventure_search_mcp
  SERPAPI_KEY: your_serpapi_key
  GOOGLE_CSE_ID: your_cse_id
```

### 搜索引擎选择

通过 `search_engine` 参数指定引擎：

| 值 | 引擎 |
|---|---|
| `both`（默认） | 所有可用引擎并发 |
| `duckduckgo` | 仅 DuckDuckGo |
| `bing` | 仅 Bing |
| `google` | 仅 Google（HTML） |
| `serpapi` | 仅 SerpAPI |
| `tavily` | 仅 Tavily |
| `google_cse` | 仅 Google CSE |

## 📖 API

### `web_search`

搜索网页，返回标题、URL、摘要。

**参数：**
- `query`（必需）：搜索查询字符串
- `search_engine`（可选）：搜索引擎，默认 `both`
- `max_results`（可选）：最大结果数，默认 10，最大 20

### `get_webpage_content`

获取指定网页的文本内容。

**参数：**
- `url`（必需）：要获取内容的网页 URL

## 📄 License

MIT

## 🙏 Acknowledgements

- 原始项目：[heventure-search-mcp](https://github.com/HughesCuit/heventure-search-mcp) by [HughesCuit](https://github.com/HughesCuit)
- Google CSE 引擎实现参考：[SearXNG](https://github.com/searxng/searxng) — `searx/engines/google_cse.py`

## 🏗️ 开发环境

本项目在以下环境中开发与测试：

- **Agent 框架**：[QwenPaw](https://github.com/agentscope-ai/QwenPaw)（by AgentScope team from Qwen lab）
- **运行环境**：Alibaba Cloud（新加坡节点），Linux 容器
- **Python**：3.11
- **部署方式**：作为 QwenPaw MCP 工具（stdio 模式），由 supervisor 托管