内容
# 清洁搜索 🧹
一款为 AI 代理提供 **干净、无垃圾搜索结果** 的轻量级 MCP（模型上下文协议）服务。在 LLM 接收到结果之前，过滤掉内容农场、恶意软件网站、SEO 垃圾和低质量内容。
## 功能特点
- **三款搜索引擎** — Yandex + Bing + DuckDuckGo 自动备用
- **超过 17.6 万域名封禁列表** — 自动从 25+ 个社区来源更新，涵盖恶意软件/诈骗/广告/追踪器/内容农场
- **三层过滤** — 域名黑名单 → 内容规则 → 质量评分
- **内容提取** — 通过 trafilatura + selectolax 获取完整页面文本
- **结果评分** — 0-1 质量评分（官方文档 0.8 > 教程 0.6 > 垃圾 0）
- **最近最少使用缓存** — 搜索缓存 6 小时，获取缓存 24 小时，自动清理
- **用户黑名单** — 动态添加域名，报告不良结果
- **深度模式** — 可选的 Playwright 备用方案，用于 JS 密集型页面
- **无重依赖** — 纯 HTTP，无需浏览器
## 快速开始
```bash
pip install -r requirements.txt
python main.py
```
## MCP 客户端配置
```json
{
"mcpServers": {
"clean-search": {
"command": "python",
"args": ["/path/to/clean_search_mcp/main.py"]
}
}
}
```
## 本地测试
```bash
python test_local.py "您的搜索查询" -n 5
python test_local.py "您的查询" -n 5 --no-content # 跳过页面内容
python test_local.py "您的查询" --deep # 使用 Playwright 备用方案
```
## API
### `clean_search(query, max_results=5, with_content=True, deep_mode=False)`
| 参数 | 默认值 | 描述 |
|-------|---------|-------------|
| `query` | 必需 | 搜索查询 |
| `max_results` | 5 | 返回结果数（最多 10 个） |
| `with_content` | True | 包含提取的页面文本 |
| `deep_mode` | False | 为 JS 页面使用 Playwright 备用方案 |
返回 `[{title, url, snippet, content, score}]`，按质量排序。
### `add_user_blacklist(domain)`
将域名添加到个人封禁列表。
### `report_bad_result(url)`
举报低质量 URL（自动封禁域名）。
## 配置
编辑 `config.py` 以调整：
- **搜索引擎**：启用/禁用 Yandex、Bing、DuckDuckGo
- **黑名单来源**：添加或删除社区封禁列表 URL
- **评分权重**：调整域名权重、内容质量奖励
- **缓存**：TTL、最大文件数、清理间隔
- **代理**：为 HTTP/Playwright 设置 `PROXY`
## 依赖项
```
mcp, httpx, selectolax, trafilatura, duckduckgo-search
```
所有轻量级 pip 包。Playwright 为可选（仅限深度模式）。
## 许可证
MIT
