Mutation Clinical Trial Matching MCP

突变临床试验匹配MCP

模型上下文协议 (MCP) 服务器使 Claude Desktop 能够根据突变在 clincialtrials.gov 中搜索匹配项。

地位

目前处于开发的第一阶段。它能够根据 Claude 查询中指定的突变检索试验。然而，仍然存在一些错误，需要进一步完善和补充。

概述

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

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

项目结构

该项目根据代理编码范式进行组织：

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. 实施（人工智能主导）：
   • 用于处理协议细节的 FastMCP SDK
   • 各级错误处理
   • 常见突变的资源

成分

MCP 服务器（ clinicaltrials_mcp_server.py ）

使用官方 Python SDK 实现模型上下文协议接口的主服务器。它：

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

查询模块（ clinicaltrials/query.py ）

负责查询 clinicaltrials.gov API：

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

摘要器（ llm/summarize.py ）

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

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

节点模式实现

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

核心节点类（ utils/node.py ）

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

实施节点（ clinicaltrials/nodes.py ）

1. 查询试验节点：
   # Queries 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. 总结试验节点：
   # Formats trial data into readable summaries 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 # End of flow

流程执行

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

此模式将准备、执行和后处理分离，使代码更易于维护和测试。更多详情，请参阅设计文档。

用法

1. 使用 uv 安装依赖项：
   uv pip install -r requirements.txt
2. 配置Claude桌面：
   • ~/Library/Application Support/Claude/claude_desktop_config.json中的配置应该已经设置好了
3. 启动 Claude Desktop 并提出以下问题：
   • “针对 EGFR L858R 突变有哪些临床试验？”
   • “有没有针对 BRAF V600E 突变的试验？”
   • “跟我讲讲 ALK 重排试验的情况”
4. 通过询问来利用资源：
   • “您能告诉我更多有关 KRAS G12C 突变的信息吗？”

与 Claude Desktop 集成

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

路径变量：

• {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 venv .venv uv pip install -r requirements.txt
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 （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 桌面工具的官方模型上下文协议 SDK
• 请求（ 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桌面
• 验证服务器是否正常运行

开发过程

该项目采用人工智能辅助编码方法开发，遵循代理编码原则，即人类设计，人工智能代理执行。主程序的原始构建于 2025 年 4 月 30 日。该项目的实现是通过与以下人员结对编程实现的：

• 风帆冲浪
  • ChatGPT 4.1
  • 克劳德 3.7 十四行诗

这些人工智能助手有助于将高级设计要求转化为功能代码、帮助 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文件。