COMPASS 免疫治疗预测工具 - MCP 服务器¶

A MCP tool from Prism ToolSpace for running immune checkpoint inhibitor (ICI) response predictions using the COMPASS model. This tool processes the pateint level mRNA’s TPM (transcripts per million) tumor expression profile and cancer context to predict patient responsiveness for immunotherapy and provides interpretable insights through immune cell concept analysis.

先决条件¶

1. Install COMPASS Library¶

首先，从官方仓库安装 COMPASS 库：

# create a uv virtual enviroment for COMPASS setup
uv venv compass --python 3.10
source compass/bin/activate
uv pip install -r requirements.txt

# Install COMPASS
uv pip install immuno-compass

2. GPU Support (Optional)¶

要实现GPU加速，请在安装其他依赖项之前先安装支持CUDA的PyTorch：

# For CUDA 11.7 (adjust version as needed)
uv pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 torchaudio==0.13.1 --index-url https://download.pytorch.org/whl/cu117

模型权重设置¶

1. Download Pre-trained Models¶

从官方仓库下载预训练的 COMPASS 模型。可用的模型包括：

pft_leave_IMVigor210.pt - 在IMVigor210队列（尿路上皮癌）上进行微调 - 默认
pft_leave_Gide.pt - 在Gide队列（黑色素瘤）上进行微调
pretrainer.pt - 基础预训练模型
finetuner_pft_all.pt - 在所有可用队列上进行微调

您可以从以下位置下载模型：

官方下载页面: https://www.immuno-compass.com/download/
直接模型链接
- IMVigor210：https://www.immuno-compass.com/download/model/LOCO/pft_leave_IMVigor210.pt
- Gide: https://www.immuno-compass.com/download/model/LOCO/pft_leave_Gide.pt
- 预训练模型下载链接：https://www.immuno-compass.com/download/model/pretrainer.pt

2. Directory Structure Setup¶

为您的模型权重创建以下目录结构：

/path/to/your/compass/
├── immune-compass/
│   └── checkpoint/        # Model weights directory
│       ├── pft_leave_IMVigor210.pt
│       ├── pft_leave_Gide.pt
│       ├── pretrainer.pt
│       └── finetuner_pft_all.pt

3. Set Environment Variable¶

将 COMPASS_MODEL_PATH 环境变量设置为指向您的 COMPASS 安装路径：

# Add to your ~/.bashrc or ~/.zshrc
export COMPASS_MODEL_PATH="/path/to/your/compass"

示例设置：

# Create directory structure
mkdir -p /path/to/your/compass/checkpoint
cd /path/to/your/compass/checkpoint

# Download model weights to checkpoint directory
wget https://www.immuno-compass.com/download/model/LOCO/pft_leave_IMVigor210.pt
wget https://www.immuno-compass.com/download/model/LOCO/pft_leave_Gide.pt

# Set environment variable
export COMPASS_MODEL_PATH="/path/to/your/compass"

输入与输出规格¶

输入格式¶

该工具要求患者级别的TPM基因表达数据以pickle格式（.pkl文件）提供，其中包含一个pandas DataFrame：

行：样本/患者
列：基因（标准基因符号，例如 “CD274”、”PDCD1”、”CTLA4”）
数值：以TPM（每百万转录本数）归一化的表达量
最少：建议使用约100个基因以确保预测的可靠性

有关如何准备患者TPM档案数据的具体说明，请参阅COMPASS页面。

输出格式¶

该工具返回结构化的 JSON 响应：

{
  "prediction": {
    "is_responder": true,
    "top_concepts": [
      {
        "concept": "CD8+ T cells",
        "score": 0.85
      },
      {
        "concept": "NK cells",
        "score": 0.72
      },
      ...
    ]
  },
  "context_info": [
    "COMPASS prediction completed successfully.",
    "Sample classified as: RESPONDER",
    "Analysis based on 15672 input genes.",
    "Top 44 immune cell concepts identified."
  ]
}

输出字段：

is_responder（bool）：如果预测为响应者（概率 ≥ 阈值），则为 True
top_concepts（列表）：按重要性评分排序的免疫细胞概念
context_info（列表）：可读性强的分析摘要
error（可选）：预测失败时的错误描述

运行 MCP 服务器¶

1. Start the Server¶

# Enable the uv environment
uv source compass/bin/activate

# Set environment variable (if not in bashrc)
export COMPASS_MODEL_PATH="/path/to/your/compass"

# Run the MCP server
python compass_tool.py

2. Server Configuration¶

服务器以以下默认设置运行：

主机：0.0.0.0（接受来自任意 IP 的连接）
端口：7003（已配置以避免冲突）
传输：streamable-http
模式：无状态 HTTP

3. Server Logs¶

启动成功后，您将看到：

Starting MCP server for COMPASS Immune Response Prediction Tool...
Model: COMPASS (COMprehensive Pathway Analysis for Single-cell Sequencing)
Application: Immune Checkpoint Inhibitor Response Prediction
Server: FastMCP with streamable HTTP transport
Port: 7003 (configured to avoid conflicts with other biomedical tools)

工具使用¶

MCP 工具功能¶

服务器提供一个主要的工具功能：

run_compass_prediction(
    gene_expression_data_path: str,
    threshold: float = 0.5,
    root_path: str = None
)

参数：

gene_expression_data_path (str)：包含TPM表达数据的pickle文件路径
threshold（浮点数）：用于响应者分类的概率阈值（0.0-1.0）
- 默认值：0.5（灵敏度与特异性平衡）
- 较低的数值（约0.3）：更高的灵敏度
- 较高的数值（约0.7）：较高的特异性
root_path（字符串，可选）：自定义模型检查点目录路径

故障排除¶

常见问题¶

模型未找到错误
```
FileNotFoundError: COMPASS model checkpoint not found at /path/to/checkpoint
```
- 确保正确设置 COMPASS_MODEL_PATH
- 确认模型权重已下载至 checkpoint/ 目录下
导入错误
```
ModuleNotFoundError: No module named 'compass'
```
- 安装 COMPASS：uv pip install immuno-compass
- 确保您处于正确的 conda 环境中
输入数据格式错误
```
ValueError: Input data must be a non-empty dictionary
```
- 确保输入文件为pickle格式且具有正确的DataFrame结构
- 检查基因符号是否为标准格式（例如，“CD274”，而非“PD-L1”）

参考文献¶

COMPASS 论文：通用型人工智能预测不同癌症及治疗中的免疫疗法效果
项目网站：https://www.immuno-compass.com/
GitHub 仓库：https://github.com/mims-harvard/COMPASS
文档: https://compass.readthedocs.io/

引用¶

如果您使用此工具，请引用 COMPASS 论文：

@article{shen2024compass,
  title={Generalizable AI predicts immunotherapy outcomes across cancers and treatments},
  author={Shen, Wanxiang and Nguyen, Thinh H. and Li, Michelle M. and Huang, Yepeng and Moon, Intae and Nair, Nitya and Marbach, Daniel and Zitnik, Marinka},
  journal={medRxiv},
  year={2024}
}

许可证¶

该工具依据 MIT 许可证发布，与原始 COMPASS 项目保持一致。