Europe PMC Literature Search MCP Server

# 将获取全文功能整合到get_article_details中的技术分析报告 ## 1. 当前系统架构分析 ### 1.1 现有组件 1. **EuropePMC Service**: 提供文献详情获取功能（get_article_details_sync/async） 2. **PubMed Service**: 提供PubMed搜索和引用文献获取功能，以及PMC全文获取功能（get_pmc_fulltext_html） 3. **Article Detail Tools**: 文献详情工具模块，暴露get_article_details API ### 1.2 现有调用链路 ``` 用户调用 -> Article Detail Tools (get_article_details) -> EuropePMC Service (fetch) -> EuropePMC Service (get_article_details_sync/async) ``` ### 1.3 功能定位 - **EuropePMC**: 主要面向Europe PMC数据库的文献详情获取 - **PubMed**: 主要面向PubMed数据库的搜索和引用文献获取，以及PMC全文获取 ## 2. 整合可行性分析 ### 2.1 技术可行性 ✓ - 两个服务都在同一项目中，可以相互调用 - 都使用相同的日志系统和错误处理机制 - 代码结构清晰，易于扩展 ### 2.2 功能互补性 ✓ - EuropePMC服务擅长文献元数据获取 - PubMed服务擅长PMC全文获取 - 整合后可以实现"一站式"文献详情+全文获取 ### 2.3 性能影响 ✓ - 可以通过条件判断避免不必要的PMC请求 - 支持异步并行获取，提高整体性能 - 增加缓存机制进一步优化性能 ## 3. 整合方案设计 ### 3.1 整体架构 ``` 用户调用 -> Article Detail Tools (get_article_details) -> EuropePMC Service (fetch) -> EuropePMC Service (get_article_details_sync/async) -> [条件判断] -> PubMed Service (get_pmc_fulltext_html) -> 返回整合结果 ``` ### 3.2 整合策略 1. **优先获取元数据**: 首先通过EuropePMC获取文献基本详情 2. **条件判断**: 检查返回结果中是否包含PMC ID 3. **全文获取**: 如果有PMC ID且用户需要全文，则调用PMC全文获取 4. **结果合并**: 将元数据和全文数据合并返回 ### 3.3 API设计变更 1. **新增参数**: 添加`include_fulltext`参数控制是否获取全文 2. **结果扩展**: 在返回结果中添加`fulltext`相关字段 3. **向后兼容**: 保持现有API接口不变 ## 4. 具体实现方案 ### 4.1 修改点分析 #### 4.1.1 EuropePMC Service - 修改`get_article_details_sync/async`方法，在返回结果中添加PMC全文获取逻辑 - 添加依赖注入机制，注入PubMed服务实例 #### 4.1.2 Article Detail Tools - 修改工具函数参数，添加`include_fulltext`选项 - 保持现有API接口不变，新增可选参数 ### 4.2 实现步骤 #### 步骤1: 修改EuropePMC Service依赖注入 ```python # 在EuropePMCService构造函数中添加PubMed服务依赖 def __init__(self, logger: Optional[logging.Logger] = None, pubmed_service=None): self.logger = logger or logging.getLogger(__name__) self.pubmed_service = pubmed_service # 注入PubMed服务 # ...其他初始化代码 ``` #### 步骤2: 修改get_article_details_sync方法 ```python def get_article_details_sync(self, identifier: str, id_type: str = "pmid", include_fulltext: bool = False) -> Dict[str, Any]: # 1. 获取基础文献详情 result = self._get_basic_details(identifier, id_type) # 2. 如果需要全文且结果中有PMC ID，则获取全文 if include_fulltext and result.get("article") and result["article"].get("pmc_id"): pmc_id = result["article"]["pmc_id"] fulltext_result = self.pubmed_service.get_pmc_fulltext_html(pmc_id) if not fulltext_result.get("error"): result["article"]["fulltext"] = { "html": fulltext_result.get("fulltext_html"), "available": fulltext_result.get("fulltext_available", False), "title": fulltext_result.get("title"), "authors": fulltext_result.get("authors"), "abstract": fulltext_result.get("abstract") } return result ``` #### 步骤3: 修改Article Detail Tools ```python @mcp.tool() def get_article_details( identifier: str, id_type: str = "pmid", mode: str = "sync", include_fulltext: bool = False ) -> Dict[str, Any]: """获取特定文献的详细信息（增强版） 新增参数: - include_fulltext: 可选，是否包含全文内容，默认False """ europe_pmc_service = article_detail_tools_deps['europe_pmc_service'] result = europe_pmc_service.fetch(identifier, id_type=id_type, mode=mode, include_fulltext=include_fulltext) return result ``` ### 4.3 错误处理和性能优化 #### 4.3.1 超时控制 - 为全文获取设置独立超时时间 - 避免全文获取影响整体响应速度 #### 4.3.2 缓存机制 - 为全文内容添加缓存 - 实现分级缓存策略（内存缓存+磁盘缓存） #### 4.3.3 错误降级 - 全文获取失败不影响基础详情返回 - 提供详细的错误信息帮助用户诊断 ## 5. 风险评估与应对 ### 5.1 技术风险 1. **API限制**: PMC API可能有严格的速率限制 - 应对: 实现智能速率控制和重试机制 2. **网络延迟**: 全文获取可能增加响应时间 - 应对: 设置合理超时，支持异步获取 3. **数据格式变化**: PMC XML格式可能发生变化 - 应对: 添加格式兼容层，定期更新解析逻辑 ### 5.2 性能风险 1. **内存消耗**: 全文内容可能较大 - 应对: 实现流式处理，控制内存使用 2. **并发瓶颈**: 大量并发请求可能导致性能下降 - 应对: 优化并发控制，实现请求队列 ## 6. 预期收益 ### 6.1 用户价值 - **一站式服务**: 用户只需一次调用即可获取文献详情和全文 - **性能提升**: 减少网络往返次数，提高整体获取效率 - **功能增强**: 提供更完整的文献信息服务 ### 6.2 系统价值 - **架构优化**: 实现服务间协同，提升系统整体能力 - **代码复用**: 减少重复实现，提高开发效率 - **维护简化**: 统一的调用入口，降低维护成本 ## 7. 实施计划 ### 7.1 第一阶段：基础整合（1-2天） 1. 修改EuropePMC Service，添加PubMed服务依赖注入 2. 实现基础的全文获取逻辑 3. 更新Article Detail Tools，添加新参数 ### 7.2 第二阶段：功能完善（2-3天） 1. 实现错误处理和降级机制 2. 添加缓存机制优化性能 3. 完善日志记录和监控 ### 7.3 第三阶段：测试验证（1-2天） 1. 编写单元测试和集成测试 2. 进行性能基准测试 3. 验证边界情况和错误处理 ### 7.4 第四阶段：文档更新（0.5天） 1. 更新API文档 2. 添加使用示例 3. 编写迁移指南 --- *文档创建时间: 2025年9月8日*