HelloWorld
登录
p

pickleton89

health-and-wellnessrag-systemssearch

291 查看 · 2026-07-07 更新

突变临床试验匹配 MCP

一个 Model Context Protocol (MCP) 服务器，使 Claude Desktop 能够基于突变在 clincialtrials.gov 上搜索匹配项。

状态

目前处于开发的第一阶段。它可以根据 Claude 查询中提供的突变来检索试验。但是，仍然存在一些 bug，并且需要进一步的改进和添加功能。

概述

该项目遵循 Agentic 编码原则，创建了一个将 Claude Desktop 与 clinicaltrials.gov API 集成的系统。该服务器允许进行关于基因突变的自然语言查询，并返回相关临床试验的摘要信息。

mermaid flowchart LR Claude[Claude Desktop] <-->|MCP Protocol| Server[MCP Server]

subgraph Flow[PocketFlow]
    QueryNode[Query Node] -->|trials_data| SummarizeNode[Summarize Node]
end

Server -->|mutation| Flow
QueryNode -->|API Request| API[Clinicaltrials.gov API]
API -->|Trial Data| QueryNode
Flow -->|summary| Server
Server -->|Return| Claude

流程中的每个节点都遵循 PocketFlow 节点模式，具有 prep、exec 和 post 方法：

项目结构

该项目按照 Agentic 编码范式组织：

  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 服务器 (clinicaltrials_mcp_server.py)

主服务器实现了 Model Context Protocol 接口，使用官方 Python SDK。它：

  • 注册并暴露工具供 Claude 使用
  • 提供有关常见突变的信息资源
  • 处理与 Claude Desktop 的通信

查询模块 (clinicaltrials/query.py)

负责查询 clinicaltrials.gov API，包括：

  • 强健的错误处理
  • 输入验证
  • 详细的日志记录

摘要生成器 (llm/summarize.py)

处理并格式化临床试验数据：

  • 按阶段组织试验
  • 提取关键信息（NCT ID、摘要、条件等）
  • 创建可读的 Markdown 摘要

节点模式实现

该项目实现了 PocketFlow 节点模式，为构建 AI 工作流提供了一种模块化、可维护的方法：

核心节点类 (utils/node.py)

  • Node：具有 prep、exec 和 post 方法的基类，用于处理数据
  • BatchNode：扩展用于批量处理多个项目
  • Flow：按顺序协调节点的执行

实现节点 (clinicaltrials/nodes.py)

  1. QueryTrialsNode: python

    查询 clinicaltrials.gov API

    def prep(self, shared): return shared["mutation"] def exec(self, mutation): return query_clinical_trials(mutation) def post(self, shared, mutation, result): shared["trials_data"] = result shared["studies"] = result.get("studies", []) return "summarize"

  2. SummarizeTrialsNode: python

    将试验数据格式化为可读的摘要

    def prep(self, shared): return shared["studies"] def exec(self, studies): return format_trial_summary(studies) def post(self, shared, studies, summary): shared["summary"] = summary return None # 流程结束### 流程执行

MCP 服务器创建并运行流程：

python

创建节点

query_node = QueryTrialsNode() summarize_node = SummarizeTrialsNode()

创建流程

flow = Flow(start=query_node) flow.add_node("summarize", summarize_node)

使用共享上下文运行流程

shared = {"mutation": mutation} result = flow.run(shared)

这种模式将准备、执行和后处理分开，使代码更易于维护和测试。更多细节请参阅设计文档。

使用方法

  1. 使用 uv 安装依赖项：

    uv pip install -r requirements.txt

  2. 配置 Claude Desktop：

    • 配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json 应该已经设置好

  3. 启动 Claude Desktop 并提出如下问题：

    • "EGFR L858R 突变有哪些可用的临床试验？"
    • "BRAF V600E 突变是否有任何试验？"
    • "告诉我关于 ALK 重排的试验"

  4. 通过提问来使用资源：

    • "你能告诉我更多关于 KRAS G12C 突变的信息吗？"

与 Claude Desktop 集成

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

json "mutation-clinical-trials-mcp": { "command": "{PATH_TO_VENV}/bin/python", "args": [ "{PATH_TO_PROJECT}/clinicaltrials_mcp_server.py" ], "description": "将基因突变与相关的临床试验匹配，并提供摘要。" }

路径变量：

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

安装说明：

  1. 将仓库克隆到本地机器。

  2. 如果还没有安装 uv，请先安装： bash curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux

    或者

    iwr -useb https://astral.sh/uv/install.ps1 | iex # Windows PowerShell

  3. 创建一个虚拟环境并在一步中安装依赖项： bash uv venv .venv uv pip install -r requirements.txt

  4. 在需要时激活虚拟环境： bash source .venv/bin/activate # macOS/Linux .venvScriptsactivate # Windows

  5. 确定您的虚拟环境和项目目录的完整路径。

  6. 使用这些特定路径更新您的配置。

示例：

  • 在 macOS/Linux 上： json "command": "/Users/username/projects/mutation_trial_matcher/.venv/bin/python"

  • 在 Windows 上： json "command": "C:\Users\username\projects\mutation_trial_matcher\.venv\Scripts\python.exe"

查找路径提示：

  • 要找到虚拟环境中 Python 解释器的确切路径，请运行：
    • which python (macOS/Linux)
    • where python (Windows, 在激活 venv 后)
  • 对于项目路径，使用包含 clinicaltrials_mcp_server.py 的目录的完整路径。

未来改进

有关计划中的增强功能和未来工作的全面列表，请参阅 future_work.md 文档。

依赖项

该项目依赖于以下关键依赖项：

  • Python 3.7+ - 基础运行时环境
  • PocketFlow (pocketflow>=0.0.1) - 用于构建基于 Node 模式的模块化 AI 工作流的框架
  • MCP SDK (mcp[cli]>=1.0.0) - 用于构建 Claude Desktop 工具的官方 Model Context Protocol SDK
  • Requests (requests==2.31.0) - 用于向 clinicaltrials.gov 发送 API 请求的 HTTP 库
  • Python-dotenv (python-dotenv==1.1.0) - 用于从 .env 文件加载环境变量

所有依赖项都可以按照安装说明使用 uv 进行安装。

故障排除

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

  • 查看日志：~/Library/Logs/Claude/mcp-server-clinicaltrials-mcp.log
  • 重启 Claude Desktop
  • 确认服务器正在正确运行

开发过程此项目采用AI辅助编码方法开发，遵循了Agentic Coding原则，即由人类设计而AI代理执行。主分支上的原始程序构建于2025年4月30日。实现过程通过与以下AI助手进行结对编程完成：

  • Windsurf
    • ChatGPT 4.1
    • Claude 3.7 Sonnet

这些AI助手在将高层次的设计需求转化为功能性代码、API集成以及根据最佳实践来构建项目方面发挥了重要作用。

处理 .windsurfrules 字符限制

来自模板仓库的PocketFlow .windsurfrules 文件包含了全面的项目规则，但Windsurf对规则文件设定了6,000字符的限制。这意味着你不能直接在项目中包含整套指南，重要的规则可能会被省略或截断。

为了解决这个问题，有以下两种推荐方案：

1. 使用Windsurf 🪁 内存存储规则

你可以利用Windsurf的记忆功能来存储完整的PocketFlow规则集，即使它们超过了.windsurfrules文件的限制。这种方法允许你在与Windsurf对话时引用所有项目惯例和最佳实践，确保不会因为截断而丢失任何内容。有关逐步说明及内存与规则文件之间的详细比较，请参阅 docs/memory_vs_windsurfrules.md。

2. 使用Context7访问指南

重要提示：本项目基于PocketFlow-Template-Python仓库，该仓库包含一个全面的.windsurfrules文件。然而，Windsurf对规则文件设置了6,000字符的限制，这意味着无法将完整的PocketFlow指南完全加载到Windsurf的记忆中。

为了解决这一限制，我们创建了详细的指导说明，教你如何使用Context7 MCP服务器在开发过程中访问PocketFlow指南。这种方法让你能够充分利用PocketFlow的设计模式和最佳实践，而不受字符限制的影响。

关于如何结合使用Context7与PocketFlow的综合指南，请参考我们的Context7指南。该指南包括：

  • 在Windsurf中配置Context7 MCP的分步说明
  • 访问PocketFlow文档的自然语言提示
  • 检索特定实现模式的例子
  • 如何保存重要模式作为记忆以供将来参考

按照这份指南，你可以在开发和扩展此项目的同时保持与PocketFlow Agentic Coding原则的一致性。

致谢

本项目基于PocketFlow-Template-Python作为起点进行构建。特别感谢该项目原贡献者提供的基础结构，使得本实现成为可能。

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

本项目根据MIT许可证发布 - 详情请见LICENSE文件。

⚠️ 免责声明

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

服务配置

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

来源