Mutation Clinical Trial Matching MCP

突变临床试验匹配 MCP

一个高性能的统一模型上下文协议（MCP）服务，使 Claude Desktop 能够根据基因突变在 clinicaltrials.gov 上搜索匹配的临床试验。

状态

已可用于生产环境 —— 本项目已完成重大架构改造，在保持 100% 向后兼容的同时，实现了统一代码库，并将代码量减少了 60%：

✅ 卓越的代码库质量：采用现代 Python 标准（兼容 Python 3.11+），代码质量提升 99.6%
✅ 专业的类型安全性：通过全面的类型标注标准，将类型诊断减少 69%
✅ 统一架构：单一服务支持同步和异步模式，并可在运行时选择
✅ 代码去重：通过全面的 4 阶段整合，代码量减少 60%（约 1,000 行）
✅ 清理遗留代码：采用专业的代码库结构，移除 3,435 行弃用代码
✅ 零重大变更：完全向后兼容，并通过兼容层自动提供迁移指南
✅ 企业级功能：熔断器、指标、重试逻辑、分布式缓存和监控
✅ 高性能：采用异步架构，性能提升 80%，并支持并发处理
✅ API 弹性：通过统一 HTTP 客户端实现可靠的错误处理，解决 403 Forbidden 错误
✅ 全面测试：完整的测试套件，包含 114 项测试，覆盖统一组件
✅ 现代化工具链：使用 uv 管理依赖，并遵循 Python 最佳实践
✅ 生产环境监控：Prometheus 指标、缓存分析和运行状况监控仪表板

该服务正在积极使用和维护，其统一架构详见变更日志。

AI 协作开发

本项目通过人类与 AI 协作开发，结合领域专业知识与由大模型指导的实现：

• 🧠 领域指导：20 多年的癌症研究经验为架构和功能需求提供指导
• 🤖 AI 实现：通过系统化的大模型指导完成代码生成、API 设计和性能优化
• 🔄 质量保证：通过迭代改进，确保专业标准和生产环境可靠性
• 📈 开发方法：展示领域专家如何有效利用 AI 工具构建生物信息学平台

方法：这种 AI 协作方法结合生物学专业知识与 AI 能力，在加快开发的同时，维持代码质量和可靠性标准。

概览

本项目遵循 Agentic Coding 原则，构建了一个将 Claude Desktop 与 clinicaltrials.gov API 集成的系统。该服务支持以自然语言查询基因突变，并返回相关临床试验的摘要信息。

flowchart LR
    Claude[Claude Desktop] <-->|MCP Protocol| Server[Unified MCP Server]
    
    subgraph Detection[Runtime Mode Detection]
        Auto[Auto-Detect Event Loop]
        Env[MCP_ASYNC_MODE]
        Config[Configuration Override]
    end
    
    subgraph Cache[Distributed Cache]
        Redis[(Redis)]
        Memory[In-Memory]
    end
    
    subgraph Flow[Unified PocketFlow]
        QueryNode[Unified Query Node] -->|trials_data| SummarizeNode[Unified Summarize Node]
    end
    
    subgraph Services[Service Abstraction Layer]
        HttpClient[Unified HTTP Client]
        TrialsService[Clinical Trials Service]
        LLMService[LLM Service]
    end
    
    subgraph Monitoring[Enterprise Features]
        Metrics[Prometheus Metrics]
        Circuit[Circuit Breaker]
        Analytics[Cache Analytics]
    end
    
    Server -->|mode selection| Detection
    Detection -->|sync/async| Flow
    Server -->|mutation| Flow
    Flow -->|service calls| Services
    Services <-->|cache| Cache
    Services -->|concurrent/sequential requests| API[Clinicaltrials.gov API]
    API -->|trial data| Services
    Flow -->|summary| Server
    Server -->|metrics| Monitoring
    Server -->|formatted response| Claude

流程中的每个节点都遵循 Unified PocketFlow Node 模式，包含 prep、exec 和 post 方法，可自动处理同步和异步执行模式。

🚀 统一架构与代码去重成果

本项目已完成全面的 4 阶段代码去重工作，从重复的代码库转变为统一、易于维护的架构：

代码去重成果

指标	成果
代码精简	减少 60%（约精简 1,000 行）
清理旧代码	移除 3,435 行——形成专业的代码库结构
代码质量	提升 99.6%——修复了 1,702 个 lint 错误中的 1,695 个
类型安全	类型诊断减少 69%（48 → 15）
组件统一	4 项主要整合（服务端、节点、服务、HTTP）
破坏性变更	零——通过兼容层实现完全向后兼容
性能提升	内存占用减少 30-40%，启动速度提升 20-30%
测试覆盖	114 项测试，覆盖所有统一后的组件

整合前后对比

组件	整合前	整合后	精简幅度
服务端	primary.py + sync_server.py	main.py	70%
节点	nodes.py + async_nodes.py	unified_nodes.py	85%
服务	query.py + async_query.py	service.py	95%
LLM 客户端	call_llm.py + async_call_llm.py	llm_service.py	95%

主要架构改进

✅ 运行模式选择：自动检测，或通过 MCP_ASYNC_MODE 显式配置
✅ 单一事实来源：统一同步/异步执行中的业务逻辑
✅ 自动检测：根据执行上下文智能选择模式
✅ 服务抽象：统一的 HTTP 客户端和服务层
✅ 配置系统：集中式配置，支持环境变量覆盖
✅ 向后兼容层：完整的 utils/node.py 兼容模块，支持旧版导入
✅ 迁移支持：提供弃用警告和明确的迁移指南

项目结构

本项目按照 Agentic Coding 范式组织：

1. 需求（由人主导）：

   • 搜索并总结与特定基因突变相关的临床试验
   • 将突变信息作为上下文资源提供
   • 与 Claude Desktop 无缝集成

2. 流程设计（协作完成）：

   • 用户向 Claude Desktop 询问基因突变
   • Claude 调用我们的 MCP 服务工具
   • 服务查询 clinicaltrials.gov API
   • 服务处理并总结结果
   • 服务将格式化结果返回给 Claude

3. 实用工具（协作完成）：

   • clinicaltrials/query.py：处理对 clinicaltrials.gov 的 API 调用
   • utils/call_llm.py：提供使用 Claude 的实用工具

4. 节点设计（由 AI 主导）：

   • utils/node.py：按照 prep/exec/post 模式实现 Node 和 BatchNode 基类
   • clinicaltrials/nodes.py：定义用于查询和总结的专用节点
   • clinicaltrials_mcp_server.py：负责协调流程执行

5. 实现（由 AI 主导）：

   • 使用 FastMCP SDK 处理协议细节
   • 各层级均包含错误处理
   • 提供常见突变的资源

架构组件

统一 MCP 服务（servers/main.py）

实现 Model Context Protocol 的主统一服务，支持运行时模式选择：

• 统一架构：单一实现，同时支持同步和异步模式
• 运行时模式选择：通过事件循环自动检测，或通过显式配置 MCP_ASYNC_MODE 选择
• 企业级工具：健康监控、指标收集、缓存管理（视模式而定）
• 自动扩缩容：通过断路器和重试逻辑，确保 API 通信可靠
• 缓存预热：自动预加载常见变更，实现即时响应（异步模式）
• API 弹性：通过统一 HTTP 客户端回退机制处理 403 Forbidden 错误
• 向后兼容：旧版服务会重定向，并显示弃用警告

统一服务层

临床试验服务（clinicaltrials/service.py）：采用感知模式处理的统一 API 客户端

• 双模式支持：同步（query_trials）和异步（aquery_trials）调用使用相同接口
• 断路器集成：自动检测故障并恢复
• 分布式缓存：使用 Redis 缓存，并在其不可用时回退到内存缓存
• 指标收集：详细的性能和使用情况分析
• API 兼容性：使用统一 HTTP 客户端，可靠访问 clinicaltrials.gov API

LLM 服务（utils/llm_service.py）：统一的 LLM 交互客户端

• 感知模式处理：支持同步和异步 LLM 调用
• 重试逻辑：内置重试机制，采用指数退避策略
• 错误处理：全面的错误处理和结构化日志记录

统一节点（clinicaltrials/unified_nodes.py）

采用 PocketFlow 节点模式，自动执行同步或异步操作：

• QueryTrialsNode：具备模式检测功能的统一 API 请求节点
• SummarizeTrialsNode：统一的 LLM 驱动摘要节点，带重试逻辑
• BatchQueryTrialsNode：支持并发控制的批处理（异步）或顺序处理（同步）
• 自动检测：节点会在运行时自动确定执行模式

统一基础层

• 统一 HTTP 客户端（utils/http_client.py）：单一 HTTP 客户端，支持同步和异步操作，并提供连接池
• 统一节点框架（utils/unified_node.py）：提供支持自动模式检测的基类
• 共享工具（utils/shared.py）：提供通用验证、错误处理和指标函数
• 缓存策略（utils/cache_strategies.py）：智能缓存预热和失效（异步模式）
• 配置系统（servers/config.py）：集中式配置，支持环境变量覆盖
• 旧版兼容层（servers/legacy_compat.py）：提供向后兼容，并附带迁移指南

统一节点模式实现

本项目实现了增强版 PocketFlow 节点模式，支持统一的同步／异步执行，为构建 AI 工作流提供模块化、易维护的方案：

统一核心节点类（utils/unified_node.py）

• UnifiedNode：支持同步和异步执行并自动检测模式的基类
• UnifiedBatchNode：用于批处理的扩展类，支持并发控制（异步）或顺序处理（同步）
• UnifiedFlow：通过智能模式选择来编排执行

统一实现节点（clinicaltrials/unified_nodes.py）

1. QueryTrialsNode（统一）：

   # Single implementation supporting both modes
   def prep(self, shared): return shared["mutation"]
   
   def exec(self, mutation): 
       return self.trials_service.query_trials(mutation)  # Sync version
   
   async def aexec(self, mutation): 
       return await self.trials_service.aquery_trials(mutation)  # Async version
   
   def post(self, shared, mutation, result):
       shared["trials_data"] = result
       shared["studies"] = result.get("studies", [])
       return self.get_next_node_id(result)
   

2. SummarizeTrialsNode（统一）：

   # Unified summarization with mode detection
   def prep(self, shared): return shared["studies"]
   
   def exec(self, studies): 
       return self.llm_service.call_llm(prompt)  # Sync version
   
   async def aexec(self, studies): 
       return await self.llm_service.acall_llm(prompt)  # Async version
   
   def post(self, shared, studies, summary):
       shared["summary"] = summary
       return None  # End of flow
   

统一流程执行

统一 MCP 服务会自动检测模式并创建和运行流程：

# Create unified nodes (mode determined at runtime)
query_node = QueryTrialsNode(async_mode=server.async_mode)
summarize_node = SummarizeTrialsNode(async_mode=server.async_mode)

# Use PocketFlow chaining syntax
query_node >> summarize_node

# Create unified flow
flow = UnifiedFlow(start_node=query_node, async_mode=server.async_mode)

# Run flow with shared context (automatically sync or async)
shared = {"mutation": mutation}
if server.async_mode:
    result = await flow.aexecute(shared)
else:
    result = flow.execute(shared)

统一模式的主要优势

✅ 单一实现：一个代码库同时支持同步和异步执行
✅ 自动检测：节点会自动确定最佳执行模式
✅ 运行时选择：可在服务器启动时或运行期间选择模式
✅ 保留接口：继续采用相同的 prep、exec、post 模式
✅ 性能优化：针对不同模式进行优化（超时、并发、批次限制）
✅ 向后兼容：继续支持旧版节点模式，并显示弃用警告

这种统一模式消除了代码重复，同时保留了原始 PocketFlow 设计的模块化和可测试特性。更多详情请参阅设计文档。

用法

1. 使用 uv 安装依赖项：

   uv sync
   

2. 配置 Claude Desktop 使用统一服务：

   {
     "mcpServers": {
       "mutation-clinical-trials-mcp": {
         "command": "uv",
         "args": ["run", "python", "servers/main.py"],
         "description": "Unified clinical trials matching server with runtime mode selection"
       }
     }
   }
   

3. 可选：通过环境变量配置执行模式：

   {
     "mcpServers": {
       "mutation-clinical-trials-mcp": {
         "command": "uv",
         "args": ["run", "python", "servers/main.py"],
         "env": {
           "MCP_ASYNC_MODE": "true"
         },
         "description": "Unified server in explicit async mode"
       }
     }
   }
   

4. 启动 Claude Desktop，并提出以下问题：

   • “有哪些针对 EGFR L858R 突变的临床试验？”
   • “有没有针对 BRAF V600E 突变的试验？”
   • “介绍一下针对 ALK 重排的试验”
   • “搜索多种突变：EGFR L858R、BRAF V600E、KRAS G12C”

5. 使用企业监控工具：

   • “获取服务器健康状态”
   • “显示缓存性能报告”
   • “当前指标有哪些？”

---

与 Claude Desktop 集成

你可以将此项目配置为 Claude Desktop MCP 工具。在配置中使用路径占位符，并替换为实际路径：

推荐配置（统一服务）

"mutation-clinical-trials-mcp": {
  "command": "{PATH_TO_VENV}/bin/python",
  "args": [
    "{PATH_TO_PROJECT}/servers/main.py"
  ],
  "description": "Unified clinical trials matching server with automatic mode selection."
}

旧版兼容性（仍受支持）

"mutation-clinical-trials-mcp-legacy": {
  "command": "{PATH_TO_VENV}/bin/python",
  "args": [
    "{PATH_TO_PROJECT}/servers/primary.py"
  ],
  "description": "Legacy async server (redirects to unified server with deprecation warnings)."
}

路径变量：

• {PATH_TO_VENV}：虚拟环境目录的完整路径。
• {PATH_TO_PROJECT}：包含项目文件的目录的完整路径。

安装说明：

1. 将代码仓库克隆到本地计算机。
2. 如果尚未安装 uv，请先安装：

   curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS/Linux
   # or
   iwr -useb https://astral.sh/uv/install.ps1 | iex    # Windows PowerShell
   

3. 一步创建虚拟环境并安装依赖项：

   uv sync
   

4. 需要时激活虚拟环境：

   source .venv/bin/activate    # macOS/Linux
   .venv\Scripts\activate       # Windows
   

5. 确定虚拟环境和项目目录的完整路径。
6. 使用这些具体路径更新配置。

示例：

• 在 macOS/Linux 上：

  "command": "/Users/username/projects/mutation_trial_matcher/.venv/bin/python"
  

• 在 Windows 上：

  "command": "C:\\Users\\username\\projects\\mutation_trial_matcher\\.venv\\Scripts\\python.exe"
  

查找路径的提示：

• 若要查找虚拟环境中 Python 解释器的确切路径，请运行：
  • which python（macOS/Linux）
  • where python（激活 venv 后的 Windows）
• 对于项目路径，请使用包含 servers/primary.py 的目录的完整路径。

---

未来改进

如需查看计划中的增强功能和未来工作的完整列表，请参阅 future_work.md 文档。

依赖项

此项目依赖以下关键依赖项：

• Python 3.11+ - 基础运行环境（从 3.13+ 下调，以提升兼容性）
• FastMCP (fastmcp>=2.10.2) - 高性能异步 MCP 框架
• PocketFlow (pocketflow>=0.0.1) - 使用 Node 模式构建模块化 AI 工作流的框架
• Requests (requests==2.31.0) - 用于调用 clinicaltrials.gov API 的 HTTP 库（作为开发依赖项，用于兼容旧版测试）
• HTTPX (httpx>=0.28.1) - 用于直接调用 Anthropic API 的异步 HTTP 客户端
• Redis (redis>=6.2.0) - 可选的分布式缓存后端
• Python-dotenv (python-dotenv==1.1.0) - 环境变量管理

企业功能：

• Prometheus 指标收集与监控
• 用于容错的熔断器模式
• 使用 Redis 后端的分布式缓存
• 用于性能优化的缓存预热策略

所有依赖项均可按照安装说明中的描述，使用 uv sync 安装。

故障排除

如果 Claude Desktop 与 MCP 服务断开连接：

• 检查日志：~/Library/Logs/Claude/mcp-server-mutation-clinical-trials-mcp.log
• 重启 Claude Desktop
• 使用 uv run python servers/main.py 验证服务是否正常运行
• 如果使用旧版服务（servers/primary.py 或 servers/legacy/sync_server.py），请检查是否存在弃用警告

Redis 连接警告：

• 如果未安装 Redis，出现 Redis 连接错误是正常的——服务会使用内存缓存作为备用方案
• 要消除警告：brew install redis && brew services start redis
• 即使不使用 Redis，服务也能正常运行，只是缓存性能会有所降低

启动时预热缓存：

• 服务启动时会自动查询 15 个常见突变，以优化性能
• 这是正常行为，可缩短频繁查询的响应时间
• 要禁用此功能：在 servers/primary.py 中注释掉 asyncio.run(startup_tasks())

开发历程

本项目经过多个阶段的 AI 协作开发：

阶段 1（2024-04-30）：使用同步架构的初始原型
阶段 2（2024-12）：通过全面测试和文档完善项目
阶段 3（2025-01）：重大重构，提升组织性和可维护性
阶段 4（2025-01）：全面迁移至异步架构，加入企业级功能，性能提升 80%
阶段 5（2025-07）：改进 API 弹性并解决 403 错误
阶段 6（2025-07）：代码去重项目——全面的 4 阶段统一工作
阶段 7（2025-07）：卓越仓库质量——专业代码规范和旧代码清理

近期成果（2025 年 7 月）

代码去重项目：
阶段 1：基础层——统一 HTTP 客户端和共享工具
阶段 2：服务层整合——统一 LLM 和临床试验服务
阶段 3：节点层统一——增强 UnifiedNode 框架
阶段 4：服务整合——实现完整的统一架构

卓越仓库质量：

• 代码质量：提升 99.6%（修复了 1,702 个 lint 错误中的 1,695 个）
• 类型安全：类型诊断减少 69%（48 → 15）
• 专业清理：移除 3,435 行已弃用代码
• 兼容层：通过 utils/node.py 兼容模块实现完整的向后兼容
• Python 兼容性：最低版本要求从 Python 3.13+ 降至 3.11+，以便更多用户采用

成果：代码量减少 60%（约 1,000 行），零破坏性变更，统一的同步/异步架构，达到生产就绪水平的代码质量

当前版本（v0.2.1）：生产就绪的统一服务，具备企业级功能、自动模式选择、专业的类型安全和全面的向后兼容性。项目由 Claude Code 协作开发，借助 20 多年的癌症研究领域专业知识，指导 AI 实现和架构转型。

贡献

欢迎为 Mutation Clinical Trial Matching MCP 提交改进！以下是参与方式：

开发环境设置

1. 克隆仓库：

   git clone https://github.com/pickleton89/mutation-clinical-trial-matching-mcp.git
   cd mutation-clinical-trial-matching-mcp
   

2. 安装依赖项：

   uv sync
   

3. 运行测试：

   uv run python -m unittest discover tests/
   

贡献指南

• 新功能请遵循 PocketFlow Node 模式
• 为任何新功能添加全面的测试
• 更新文档，包括相关的文档字符串和 README 部分
• 遵循 Python 最佳实践并保留类型提示
• 提交 PR 前运行代码检查和类型检查

可贡献的方向

• 针对大规模临床试验搜索进行性能优化
• 增加突变格式并进行标准化
• 增强摘要能力，支持更详细的筛选
• 与 ClinicalTrials.gov 之外的其他临床数据库集成
• 改进 Claude Desktop 集成的 UI/UX

报告问题

请通过 GitHub Issues 页面报告错误或请求新功能。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

本项目以 PocketFlow-Template-Python 为起点构建。特别感谢该项目的原始贡献者，他们提供了基础和结构，使本项目的实现成为可能。

本项目遵循原始模板中概述的 Agentic Coding 方法。

---

⚠️ 免责声明

本项目是一个原型，仅用于研究和演示。请勿将其用于医疗决策，也不可将其作为专业医疗建议、诊断或治疗的替代。由于大模型（LLM）的局限性，此工具提供的信息可能不完整、不准确或过时。用户应谨慎行事，并在根据本系统的输出做出任何决定前咨询合格的医疗专业人员。

---