Europe PMC Literature Search MCP Server

# 基于 BioMCP 设计模式的优化总结 ## 项目概述 本次优化基于 [BioMCP](https://github.com/genomoncology/biomcp) 项目的设计模式，对现有的 Europe PMC MCP 服务器进行了架构重构和性能优化。 ## 优化目标 1. ✅ 分析 BioMCP 项目的优化方案和架构设计 2. ✅ 将 main.py 中的 Europe PMC 功能整合到 src 文件夹 3. ✅ 采用模块化设计，提高代码可维护性 4. ✅ 优化异步调用机制 5. ✅ 保持向后兼容性 ## BioMCP 设计模式借鉴 ### 核心设计理念 1. **模块化架构**：每个功能域都有专门的模块 2. **统一的工具接口**：使用 `search` 和 `fetch` 方法命名 3. **智能的数据源整合**：自动集成多个数据源 4. **高性能的异步处理**：使用 aiohttp 和信号量控制并发 5. **配置化管理**：统一的配置和缓存机制 ### 借鉴的具体特性 - 📦 模块化服务类设计 (EuropePMCService) - 🔌 统一的工具接口 (search/fetch 模式) - 🛡️ 并发控制和速率限制 - 💾 智能缓存机制 - 🐛 完整的异常处理和日志记录 ## 实施步骤 ### 1. 模块化重构 **创建新的模块结构：** ``` src/ ├── __init__.py ├── europe_pmc.py ├── reference_article.py └── reference_article_async.py ``` **核心改进：** - ✅ 创建 `EuropePMCService` 类，封装所有 Europe PMC 功能 - ✅ 实现统一的服务接口 (`search_sync`, `search`, `fetch`) - ✅ 添加智能缓存机制和并发控制 - ✅ 完整的错误处理和重试机制 ### 2. main.py 重构 **优化前 (542行) → 优化后 (338行)** - ❌ 移除重复的辅助函数 - ❌ 删除内联的 API 处理逻辑 - ✅ 使用模块化服务类 - ✅ 简化工具函数实现 - ✅ 增加异步版本的工具 ### 3. 工具接口优化 **新增工具：** 1. `search_europe_pmc` - 同步搜索（兼容性保持） 2. `search_europe_pmc_async` - 异步搜索（新增） 3. `get_article_details` - 同步获取详情（兼容性保持） 4. `get_article_details_async` - 异步获取详情（新增） 5. `get_references_by_doi` - 同步参考文献（保持） 6. `get_references_by_doi_async` - 异步参考文献（保持） ## 技术优化特性 ### 1. 并发控制 ```python # 信号量控制并发数量 europe_pmc_semaphore = asyncio.Semaphore(3) # 保守的并发控制 batch_delay = 3.5 # 批次间延迟 ``` ### 2. 智能缓存 ```python # 24小时本地缓存 cache_duration = 24 * 60 * 60 # 24小时 cache_key = f"search_{query}_{start_date}_{end_date}_{max_results}" ``` ### 3. 重试机制 ```python # 指数退避重试 max_retries = 3 backoff_factor = 2 ``` ### 4. 速率限制 ```python # 遵循官方 API 速率限制 rate_limit_delay = 0.5 # Europe PMC: 1-2 seconds/request ``` ## 性能测试结果 ### Europe PMC 搜索测试 ``` 测试参数: 关键词='machine learning', 最大结果数=5 🔄 同步搜索: 2.18秒 ⚡ 异步搜索: 2.54秒 💾 缓存搜索: 0.00秒 (99.9%提升) ``` ### 参考文献获取测试 ``` 测试DOI: 10.1038/s41586-021-03819-2 (84条参考文献) 🔄 同步版本: 78.96秒 ⚡ 异步版本: 78.50秒 (0.6%提升) ``` ## 性能分析 ### 缓存效果 - ✅ **缓存机制非常有效**：第二次查询实现99.9%性能提升 - ✅ **减少API调用**：避免重复请求相同内容 ### 异步效果 - ⚠️ **Europe PMC搜索**：异步版本稍慢，可能由于HTTP开销 - ⚠️ **参考文献获取**：改进有限，主要受API响应时间限制 ### 可能的性能瓶颈 1. **Europe PMC API响应慢**：单个请求耗时0.5-2秒 2. **保守的并发控制**：信号量限制过严 3. **网络延迟**：测试环境的网络条件 ## 代码质量改进 ### 1. 模块化程度 - **优化前**：所有功能混合在 main.py 中 - **优化后**：清晰的模块分离和职责划分 ### 2. 代码可维护性 - **优化前**：重复代码，难以维护 - **优化后**：DRY原则，易于扩展 ### 3. 错误处理 - **优化前**：基础错误处理 - **优化后**：完整的异常处理和重试机制 ### 4. 可配置性 - **优化前**：硬编码配置 - **优化后**：可配置的缓存、重试、并发参数 ## 项目文件变化 ### 新增文件 - ✅ `src/europe_pmc.py` (351行) - Europe PMC 服务模块 - ✅ `test_optimization.py` (195行) - 优化测试脚本 - ✅ `基于BioMCP优化总结.md` - 本文档 ### 修改文件 - ✅ `main.py` (542→338行，-37.6%) - 简化主入口 - ✅ `src/__init__.py` - 添加新模块导出 ### 保持文件 - ✅ `src/reference_article.py` - 同步参考文献服务 - ✅ `src/reference_article_async.py` - 异步参考文献服务 - ✅ `pyproject.toml` - 项目配置 - ✅ `mcp_config_examples.json` - 配置示例 ## 向后兼容性 ✅ **完全兼容**：所有原有工具接口保持不变 ✅ **功能扩展**：新增异步版本工具 ✅ **配置兼容**：Cherry Studio 等客户端配置无需修改 ## 使用示例 ### 启动服务器 ```bash # 基本启动（stdio模式） uv run --no-project python main.py server # 查看项目信息 uv run --no-project python main.py info # 运行优化测试 uv run --no-project python test_optimization.py ``` ### 在 MCP 客户端中使用 ```json { "search_europe_pmc": { "keyword": "machine learning", "max_results": 10 }, "search_europe_pmc_async": { "keyword": "deep learning", "max_results": 5 } } ``` ## 总结与展望 ### 成功实现 1. ✅ **模块化设计**：清晰的架构分离 2. ✅ **代码质量**：37.6%代码减少，可维护性大幅提升 3. ✅ **缓存优化**：99.9%缓存性能提升 4. ✅ **向后兼容**：无破坏性变更 5. ✅ **扩展能力**：易于添加新的数据源 ### 待优化方向 1. 🔄 **并发参数调优**：测试更激进的并发设置 2. 🔄 **API响应优化**：研究 Europe PMC API 的最佳实践 3. 🔄 **缓存策略**：实现更智能的缓存失效机制 4. 🔄 **监控指标**：添加详细的性能监控和指标 ### 经验总结 1. **缓存是最有效的优化**：减少重复API调用效果显著 2. **模块化设计的价值**：提高代码质量和可维护性 3. **API瓶颈**：外部API响应时间是主要限制因素 4. **BioMCP模式的优势**：统一接口和模块化设计非常有价值 --- ## 致谢 感谢 [genomoncology/biomcp](https://github.com/genomoncology/biomcp) 项目提供的优秀设计模式和架构参考。基于其设计理念，我们成功实现了模块化重构和性能优化。