Mutation Clinical Trial Matching MCP

突变临床试验匹配MCP

  ](https://github.com/pickleton89/mutation-clinical-trial-matching-mcp/releases)    

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

状态

生产就绪 -该项目已完成重大建筑改造，实现了 统一代码库 代码减少60%，同时保持100%的向后兼容性：

✅ 存储库质量卓越与现代Python标准（Python 3.11+兼容性）相比，代码质量提高了99.6%\ ✅ 专业型安全：通过全面的打字标准，类型诊断减少了69%\ ✅ 统一架构：单服务器支持同步和异步模式，并具有运行时选择功能\ ✅ 重复代码删除：通过全面的四阶段整合，减少60%（约1000条线路）\ ✅ 遗留清理：删除了3435行弃用代码的专业代码库结构\ ✅ 零突破性变化：通过兼容层与自动迁移指导完全向后兼容\ ✅ 企业功能：断路器、指标、重试逻辑、分布式缓存和监控\ ✅ 高性能：异步架构，性能提高80%，并发处理\ ✅ API弹性：通过统一的HTTP客户端使用403 Forbidden错误解决方案进行稳健的错误处理\ ✅ 综合测试：包含114个测试的完整测试套件，涵盖统一组件\ ✅ 现代工具：用途 uv 用于依赖管理，并遵循Python最佳实践\ ✅ 生产监控：Prometheus指标、缓存分析和健康监控仪表板

服务器被积极使用和维护，统一的架构记录在 更新日志.

AI协同开发

该项目是通过以下方式开发的 人工智能协作，将领域专业知识与LLM指导的实施相结合：

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

方法论：这种人工智能协作方法将生物专业知识与人工智能能力相结合，在保持代码质量和可靠性标准的同时加速开发。

概述

该项目遵循代理编码原则，创建一个将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

流中的每个节点都遵循 统一的PocketFlow节点模式 随着 prep, exec，以及 post 自动处理同步和异步执行模式的方法。

🚀 统一架构和重复代码消除成就

该项目已全面完成 4阶段代码重复数据删除工作，从重复的代码库转换为统一的、可维护的架构：

重复代码删除结果

整合前与整合后

关键建筑改进

✅ 运行时模式选择：通过自动检测或显式配置 MCP_ASYNC_MODE\ ✅ 单点真理：跨同步/异步执行的统一业务逻辑\ ✅ 自动检测：基于执行上下文的智能模式选择\ ✅ 服务抽象：统一的HTTP客户端和服务层\ ✅ 配置系统：具有环境覆盖的集中配置\ ✅ 向后兼容层：完成 utils/node.py 旧版导入的兼容性模块\ ✅ 迁移支持：带有明确迁移指导的弃用警告

项目结构

本项目按照代理编码范式组织：

1. 需求 （人为主导）：

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

1. 流程设计 （协作）：

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

1. 公用事业 （协作）：

- clinicaltrials/query.py：处理API对clinicaltrials.gov的调用 - utils/call_llm.py：与Claude合作的实用程序

1. 节点设计 （AI领导）：

- utils/node.py：使用prep/exec/post模式实现基节点和BatchNode类 - clinicaltrials/nodes.py：定义用于查询和汇总的专用节点 - clinicaltrials_mcp_server.py：协调流程执行

1. 实施 （AI领导）：

- 用于处理协议细节的FastMCP SDK - 各级错误处理 - 常见突变资源

架构组件

统一MCP服务器(servers/main.py)

实现模型上下文协议的主统一服务器 运行时模式选择:

• 统一架构：支持同步和异步模式的单一实现
• 运行时模式选择：通过事件循环或显式自动检测 MCP_ASYNC_MODE 配置
• 企业工具：健康监控、指标收集、缓存管理（取决于模式）
• 自动缩放：断路器和重试逻辑，用于强大的API通信
• 缓存预热：自动预加载常见突变以实现即时响应（异步模式）
• API弹性：使用统一的HTTP客户端回退机制处理403个禁止错误
• 向后兼容：旧服务器重定向并发出弃用警告

统一服务层

临床试验服务 (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节点 自动同步/异步执行:

• 查询试验节点：对API请求进行模式检测的统一节点
• 摘要试验节点：具有重试逻辑的统一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节点模式 通过统一的同步/异步执行，提供了一种模块化、可维护的方法来构建人工智能工作流程：

统一核心节点类(utils/unified_node.py)

• 统一节点：基类支持同步和异步执行，并具有自动模式检测功能
• UnifiedMatchNode：具有并发控制（异步）或顺序处理（同步）的批处理扩展
• UnifiedFlow：通过智能模式选择协调执行

统一实施节点(clinicaltrials/unified_nodes.py)

1. 查询试验节点 （统一）：

   # 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)

1. 摘要试验节点 （统一）：

   # 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

1. 配置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"
       }
     }
   }

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

   {
     "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"
       }
     }
   }

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

- “EGFR L858R突变有哪些临床试验？” - “有BRAF V600E突变的试验吗？” - “告诉我关于ALK重组的试验” - “寻找多种突变：EGFR L858R、BRAF V600E、KRAS G12C”

1. 使用企业监控工具：

- “获取服务器运行状况” - “显示缓存性能报告” - “目前的指标是什么？”

______________________________________________________________________

与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

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

   uv sync

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

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

1. 确定虚拟环境和项目目录的完整路径。
2. 使用这些特定路径更新您的配置。

示例：

• 在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 （Windows，激活venv后）

• 对于项目路径，请使用包含以下内容的目录的完整路径 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==2.31.0)-clinicaltrials.gov API调用的HTTP库（遗留测试兼容性的开发依赖性）
• HTTPX (httpx>=0.28.1)-用于直接Anthropic API调用的异步HTTP客户端
• 瑞迪斯 (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
• 重新启动克劳德桌面
• 使用验证服务器是否正常运行 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个常见突变以优化性能
• 这是正常行为，可以改善频繁查询的响应时间
• 禁用：注释掉 asyncio.run(startup_tasks()) 在……里面 servers/primary.py

发展历程

该项目经历了人工智能协作开发的多个阶段：

第一阶段 （2024-04-30）：使用同步架构的初始原型\ 第2阶段 （2024-12）：通过全面的测试和记录得到增强\ 第三期 （2025-01）：为改进组织和可维护性而进行的重大重构\ 阶段4 （2025-01）：具有企业功能的完全异步迁移，性能提高80%\ 阶段5 （2025-07）：API弹性改进和403错误解决\ 第6阶段 (2025-07): 重复代码删除项目 -全面的四阶段统一努力\ 第7阶段 (2025-07): 存储库质量卓越 -专业代码标准和遗留清理

近期成就（2025年7月）

重复代码删除项目:\ 第一阶段：基础层-统一的HTTP客户端和共享实用程序\ 第2阶段：服务层整合-统一的LLM和临床试验服务\ 第三期：节点层统一-增强型统一节点框架\ 阶段4：服务器整合-完整的统一架构

存储库质量卓越:

• 代码质量：99.6%的改进（1702个掉毛错误中的1695个已修复）
• 类型安全：类型诊断减少69%（48→15）
• 专业清洁：删除3435行弃用代码
• 相容层：完全向后兼容 utils/node.py 兼容性模块
• Python兼容性：将Python 3.13+的要求降低到3.11+，以获得更广泛的采用

结果：代码减少60%（消除约1000行），零中断更改，统一的同步/异步架构，生产就绪代码质量

当前版本（v0.2.1）：生产就绪的统一服务器，具有企业功能、自动模式选择、专业类型安全和全面的向后兼容性。通过与Claude Code合作开发，利用20多年癌症研究领域的专业知识来指导人工智能的实施和架构转型。

贡献

我们欢迎为改进突变临床试验匹配MCP做出贡献！以下是您如何参与其中：

开发设置

1. 克隆存储库:

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

1. 安装依赖项:

   uv sync

1. 运行测试:

   uv run python -m unittest discover tests/

贡献指南

• 遵循PocketFlow节点模式 对于新功能
• 添加综合测试 对于任何新功能
• 更新文档 包括相关的文档字符串和README部分
• 遵循Python最佳实践 并维护类型提示
• 运行linting和类型检查 在提交PR之前

贡献领域

• 性能优化 用于大规模临床试验检索
• 其他突变格式 标准化
• 增强的摘要功能 具有更详细的过滤功能
• 与其他临床数据库集成 超越ClinicalTrials.gov
• UI/UX改进 用于Claude Desktop集成

报告问题

请使用 报告错误或请求功能的页面。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

该项目是使用 PocketFlow模板Python 作为一个起点。特别感谢该项目的原始贡献者为实现这一目标提供了基础和结构。

该项目遵循原始模板中概述的代理编码方法。

______________________________________________________________________

⚠️ 免责声明

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

______________________________________________________________________