Metadata-Version: 2.4
Name: heventure-search-mcp
Version: 1.1.2
Summary: 一个无需API key的网页搜索MCP服务器，支持DuckDuckGo和必应搜索
Home-page: https://github.com/HughesCuit/heventure-search-mcp
Author: HughesCuit
License: MIT
Project-URL: Homepage, https://github.com/HughesCuit/heventure-search-mcp
Project-URL: Repository, https://github.com/HughesCuit/heventure-search-mcp
Project-URL: Issues, https://github.com/HughesCuit/heventure-search-mcp/issues
Project-URL: Documentation, https://github.com/HughesCuit/heventure-search-mcp#readme
Keywords: mcp,search,web,duckduckgo,bing,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: beautifulsoup4>=4.11.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: pydantic>=2.0.0
Dynamic: home-page
Dynamic: requires-python

# MCP Web Search Server

一个无需API key的网页搜索MCP（Model Context Protocol）服务器，支持DuckDuckGo和必应搜索引擎提供网页搜索功能。

## 功能特性

- 🔍 **多引擎搜索**: 支持DuckDuckGo和必应搜索引擎，无需API key
- 📄 **网页内容获取**: 获取指定网页的文本内容
- 🚀 **异步处理**: 基于asyncio的高性能异步处理
- 🛡️ **安全可靠**: 不需要任何外部API密钥，保护隐私
- 🌐 **多种搜索方式**: 支持API和HTML两种搜索方式
- ⚡ **灵活选择**: 可选择单一搜索引擎或组合使用

## 安装方式

### 方式一：通过 PyPI 安装（推荐）

```bash
# 从 PyPI 安装
pip install heventure-search-mcp

# 然后运行
heventure-search-mcp
```

### 方式二：通过 uvx 安装

```bash
# 从 PyPI 运行
uvx heventure-search-mcp

# 或者从 GitHub 运行
uvx --from git+https://github.com/HughesCuit/heventure-search-mcp.git server.py
```

### 方式三：通过 pip 从源码安装

```bash
# 直接从 GitHub 安装
pip install git+https://github.com/HughesCuit/heventure-search-mcp.git

# 然后运行（三种方式任选其一）
heventure-search-mcp                    # 使用命令行工具
python -m server                        # 直接运行模块
python -c "import server; import asyncio; asyncio.run(server.main())"  # 编程方式
```

### 方式四：手动安装依赖

```bash
# 克隆仓库
git clone https://github.com/HughesCuit/heventure-search-mcp.git
cd heventure-search-mcp

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

## 使用方法

### 直接运行服务器

```bash
python server.py
```

### 作为MCP服务器使用

在你的MCP客户端配置中添加此服务器：

```json
{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}
```

### 在Trae AI中使用

在Trae AI中添加此MCP服务器，请使用以下配置：

```json
{
  "mcpServers": {
    "heventure-search-mcp": {
      "command": "uvx",
      "args": [
        "heventure-search-mcp"
      ]
    }
  }
}
```

或者如果你已经本地安装了包：

```json
{
  "mcpServers": {
    "heventure-search-mcp": {
      "command": "python",
      "args": [
        "-m",
        "heventure_search_mcp"
      ]
    }
  }
}
```

## 可用工具

### 1. web_search

搜索网页内容，支持多种搜索引擎

**参数:**
- `query` (string, 必需): 搜索查询词
- `max_results` (integer, 可选): 最大结果数量 (默认: 10, 范围: 1-20)
- `search_engine` (string, 可选): 搜索引擎选择 (默认: "both")
  - `"duckduckgo"`: 仅使用DuckDuckGo搜索
  - `"bing"`: 仅使用必应搜索
  - `"both"`: 同时使用两个搜索引擎

**示例:**
```json
{
  "query": "Python编程教程",
  "max_results": 5,
  "search_engine": "both"
}
```

**使用不同搜索引擎:**
```json
// 仅使用DuckDuckGo
{
  "query": "机器学习算法",
  "search_engine": "duckduckgo"
}

// 仅使用必应
{
  "query": "人工智能发展",
  "search_engine": "bing"
}
```

### 2. get_webpage_content

获取指定网页的文本内容

**参数:**
- `url` (string, 必需): 要获取内容的网页URL

**示例:**
```json
{
  "url": "https://example.com"
}
```

## 技术实现

### 搜索引擎

本服务支持多个搜索引擎，提供更全面的搜索结果：

#### DuckDuckGo
1. **无需API key**: 提供免费的搜索API
2. **隐私保护**: 不跟踪用户搜索历史
3. **即时答案**: 支持即时答案和相关主题
4. **多种接口**: 支持API和HTML两种访问方式

#### 必应搜索
1. **丰富结果**: 提供详细的搜索结果和摘要
2. **高质量**: 微软搜索引擎的高质量结果
3. **HTML解析**: 通过HTML页面解析获取结果
4. **补充搜索**: 与DuckDuckGo形成良好互补

### 搜索策略

1. **DuckDuckGo策略**: 优先使用API，不足时使用HTML解析
2. **必应策略**: 通过HTML页面解析获取搜索结果
3. **组合策略**: 当选择"both"时，合并两个引擎的结果
4. **结果优化**: 自动去重、排序和格式化结果

### 内容提取

- 使用BeautifulSoup解析HTML内容
- 自动移除脚本和样式标签
- 清理和格式化文本内容
- 限制内容长度避免过长响应

## 项目结构

```
mcp_dev/
├── server.py          # 主服务器文件
├── requirements.txt   # 项目依赖
├── README.md         # 项目说明
└── config.json       # MCP配置示例
```

## 配置说明

### 用户代理

服务器使用标准的浏览器用户代理字符串来避免被网站阻止：

```python
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
```

### 超时设置

- 网页内容获取超时: 10秒
- 搜索请求超时: 默认aiohttp超时

### 内容限制

- 网页内容最大长度: 2000字符
- 最大搜索结果数: 20个

## 错误处理

服务器包含完善的错误处理机制：

- 网络请求失败自动重试
- 解析错误优雅降级
- 详细的错误日志记录
- 用户友好的错误消息

## 注意事项

1. **网络依赖**: 需要稳定的网络连接
2. **速率限制**: 请合理使用，避免过于频繁的请求
3. **内容准确性**: 搜索结果来自第三方，请自行验证内容准确性
4. **法律合规**: 请遵守相关法律法规和网站使用条款

## 开发和发布

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/HughesCuit/heventure-search-mcp.git
cd heventure-search-mcp

# 安装开发依赖
pip install -e .
pip install build twine

# 运行测试
python test_server.py

# 运行基准测试
python benchmark.py
```

### 发布到PyPI

项目包含自动化发布脚本：

```bash
# 发布到TestPyPI（测试）
python publish.py test

# 发布到正式PyPI
python publish.py prod

# 仅构建包
python publish.py build

# 清理构建文件
python publish.py clean
```

**发布前准备：**

1. 配置PyPI API Token：
   ```bash
   # 在 ~/.pypirc 中配置
   [pypi]
   username = __token__
   password = your-api-token
   
   [testpypi]
   username = __token__
   password = your-test-api-token
   ```

2. 更新版本号（在 `pyproject.toml` 中）
3. 更新 `CHANGELOG.md`（如果有）
4. 确保所有测试通过

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个项目！
