# pickleton89
## 基本信息
- Slug: `pickleton89-mutation-clinical-trial-matching-mcp`
- Source: modelscope
- Publisher: @pickleton89/mutation-clinical-trial-matching-mcp
- Categories: health-and-wellness / rag-systems / search
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@pickleton89/mutation-clinical-trial-matching-mcp
## 简介
暂无描述。
## MCP Server 详情

# 突变临床试验匹配 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)


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

## 使用方法

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](docs/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](docs/memory_vs_windsurfrules.md)。

### 2. 使用Context7访问指南

**重要提示**：本项目基于[PocketFlow-Template-Python](https://github.com/The-Pocket/PocketFlow-Template-Python)仓库，该仓库包含一个全面的`.windsurfrules`文件。然而，Windsurf对规则文件设置了6,000字符的限制，这意味着无法将完整的PocketFlow指南完全加载到Windsurf的记…