统一搜索MCP服务器
项目介绍
统一搜索 MCP 服务器 🔍
生产级别 MCP (模型上下文协议) 服务器，可以整合 Google 学术搜索、Google 网页搜索和 YouTube 搜索。
🚀 主要功能
核心搜索功能
- 🎓 Google 学术搜索: 学术论文搜索（作者、年份过滤）
- 🌐 Google 网页搜索: 使用 Google 自定义搜索 API 的网页搜索
- 📺 YouTube 搜索: 视频搜索（时长、上传日期、排序选项）
- 🔄 统一搜索: 同时从所有来源搜索
企业级功能
- 🔐 安全性: API 密钥加密、输入验证、防止 XSS/SQL 注入
- 💾 分布式缓存: 基于 Redis 的缓存及 TTL 管理
- ⚡ 速率限制: 基于 Redis 后端的可配置速率限制
- 📊 监控: Prometheus 指标、健康检查、结构化日志
- 🔄 弹性: 重试逻辑、断路器、优雅降级
- 📝 审计日志: 全面的合规审计跟踪
📋 要求
- Python 3.11+
- Redis（可选，用于分布式功能）
- API 密钥：
- Google 自定义搜索 API（用于网页搜索）
- YouTube 数据 API v3（用于 YouTube 搜索）
🛠️ 安装
通过 Smithery 快速安装
通过 Smithery 平台直接部署，会自动设置。
手动安装
- 克隆存储库：
git clone https://github.com/JDeun/unified-search-mcp-server.git
cd unified-search-mcp-server
- 创建虚拟环境：
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
- 安装依赖项：
pip install -r requirements.txt
- 配置环境：
cp .env.example .env
# 编辑 .env 文件以输入 API 密钥和设置
⚙️ 配置
环境变量
# API 密钥
GOOGLE_API_KEY=your-google-api-key
GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your-cse-id
YOUTUBE_API_KEY=your-youtube-api-key
# 安全性
MCP_ENCRYPTION_KEY=your-256-bit-key
MCP_RATE_LIMIT_SECRET=your-secret
# Redis（可选）
MCP_REDIS_URL=redis://localhost:6379/0
# 设置
MCP_ENV=production
MCP_LOG_LEVEL=INFO
MCP_CACHE_TTL=3600
如何获取 API 密钥
-
Google 自定义搜索 API：
- 访问 Google Cloud Console
- 激活 "Custom Search API"
- 创建认证信息（API 密钥）
- 在 cse.google.com 上创建自定义搜索引擎
-
YouTube 数据 API v3：
- 使用相同的 Google Cloud Console 项目
- 激活 "YouTube 数据 API v3"
- 使用相同的 API 密钥或创建新的密钥
🚀 使用方法
运行服务器
# 开发模式（标准 I/O）
python unified_search_server.py
# 生产模式（HTTP）
python unified_search_server.py --transport streamable-http
# 自定义端口
MCP_PORT=8080 python unified_search_server.py --transport streamable-http
Docker 部署
# 构建镜像
docker build -t unified-search-mcp .
# 运行容器
docker run -p 8000:8000 \
-e GOOGLE_API_KEY=your-key \
-e GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your-cse \
-e YOUTUBE_API_KEY=your-key \
unified-search-mcp
Claude Desktop 集成
在 claude_desktop_config.json 中添加：
{
"mcpServers": {
"unified-search": {
"command": "python",
"args": ["/path/to/unified_search_server.py"],
"env": {
"GOOGLE_API_KEY": "your-key",
"GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your-cse",
"YOUTUBE_API_KEY": "your-key"
}
}
}
}
📖 可用工具
unified_search
同时从所有来源搜索。
results = await unified_search(
query="人工智能",
sources=["scholar", "web", "youtube"],
num_results=10
)
search_google_scholar
搜索学术论文。
results = await search_google_scholar(
query="机器学习",
author="Yann LeCun",
year_start=2020,
year_end=2024,
num_results=10
)
search_google_web
搜索网页。
results = await search_google_web(
query="ChatGPT",
language="ko",
safe_search="medium",
num_results=10
)
search_youtube
搜索 YouTube 视频。
results = await search_youtube(
query="Python 教程",
video_duration="medium",
upload_date="month",
order="viewCount",
num_results=20
)
get_author_info
从 Google 学术搜索中获取作者信息。
info = await get_author_info("Geoffrey Hinton")
clear_cache
清除缓存的搜索结果。
await clear_cache(source="web") # 或者 None 清除全部
get_api_usage_stats
监控 API 使用量和限制。
stats = await get_api_usage_stats()
🏗️ 架构
模块化设计
src/
├── config/ # 配置及安全性
├── models/ # 数据模型及验证
├── services/ # 搜索服务实现
├── cache/ # 缓存层
├── utils/ # 实用工具（日志记录、速率限制）
├── monitoring/ # 指标及健康检查
└── mcp_server.py # 主服务器实现
安全层
- 输入验证及消毒
- 加密存储 API 密钥
- 客户端/端点级别的速率限制
- 为合规性提供审计日志
- CORS 和请求 ID 追踪
性能优化
- 基于 Redis 的分布式缓存
- HTTP 客户端连接池
- 并发执行搜索
- 指数退避智能重试
- 外部 API 断路器
📊 监控
健康检查端点
资源：health://status
指标端点
资源：metrics://stats
主要指标
- 搜索请求数量及延迟时间
- 缓存命中率
- API 配额使用情况
- 源错误率
- 超出速率限制
🔒 安全
最佳实践
- 所有 API 密钥使用 Fernet 加密
- 输入验证以防止 XSS/SQL 注入
- 速率限制以防止滥用
- 结构化日志不包含敏感数据
- 定期安全更新
合规性
- 准备 GDPR，不存储个人身份信息
- 对所有搜索进行审计追踪
- 可配置的数据保留
- API 使用量追踪
🧪 测试
运行测试：
pytest tests/ -v --cov=src
🤝 贡献
- 分叉存储库
- 创建功能分支 (
git checkout -b feature/amazing) - 提交更改 (
git commit -m 'Add feature') - 推送到分支 (
git push origin feature/amazing) - 打开 Pull Request
📝 许可证
MIT 许可证 - 更多详情参见 LICENSE 文件
🙏 致谢
⚠️ 注意事项
API 限制
- Google 网页搜索: 每天 100 次查询（免费层级）
- YouTube API: 每天 10,000 单位（约 100 次搜索）
- Google 学术搜索: 无官方 API，存在速率限制
生产考虑
- 使用 Redis 进行分布式部署
- 设置适当的 API 密钥轮换
- 监控速率限制及配额
- 设置 API 错误通知
- 定期备份配置
📞 支持
问题及疑问：
- GitHub Issues: 创建问题
- Smithery 支持: 部署相关问题
由 ❤️ 制作，供 MCP 社区使用