README.md

---
title: AlphaGenome MCP Service
emoji: 🧬
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: "4.26.0"
app_file: app.py
pinned: false
---

# AlphaGenome MCP Service

基于 AlphaGenome AI 模型的基因组数据解释 MCP 服务，支持遗传变异效应预测和可视化。

## 功能特性

### 核心工具
- **`predict_sequence`** - 分析原始 DNA 序列
- **`predict_interval`** - 预测基因组区间属性
- **`predict_variant`** - 比较参考序列和变异序列
- **`score_variant`** - 计算单个变异效应评分
- **`score_variants`** - 批量变异评分
- **`plot_predictions`** - 可视化基因组预测

### 高级工具（论文中提到的四个核心工具）
- **`score_variant_effect`** - 预测变异在多个模态中的功能后果
- **`visualize_variant_effects`** - 生成变异效应的模态特异性可视化
- **`score_variant_batch`** - 批量预测变异功能效应
- **`visualize_tf_binding`** - 可视化转录因子结合

## 支持的模态

- **基因表达** (gene_expression) - 使用 GeneMaskLFCScorer
- **剪接** (splicing) - 使用 SpliceJunctionScorer  
- **染色质可及性** (chromatin_accessibility) - 使用 CenterMaskScorer

## 支持的组织类型

- 人类 (human)
- 小鼠 (mouse)

## 部署到 Hugging Face Spaces

### 1. 克隆仓库
```bash
git clone https://huggingface.co/spaces/kabuda777/Code2MCP-alphagenome
cd Code2MCP-alphagenome
```

### 2. 本地运行
```bash
# 安装依赖
pip install -r requirements.txt

# 检查环境变量配置
python check_env.py

# 设置 API 密钥
export ALPHAGENOME_API_KEY="your_actual_api_key"

# 运行 MCP 服务
python alphagenome/mcp_output/start_mcp.py

# 或运行 FastAPI 应用
python app.py
```

### 3. Docker 部署
```bash
# 构建镜像
docker build -t alphagenome-mcp .

# 运行容器
docker run -p 7860:7860 alphagenome-mcp
```

## 使用示例

### 变异效应评分
```python
# 单个变异评分
result = score_variant_effect(
    chromosome="chr1",
    position=109274968,
    reference_bases="G",
    alternate_bases="T",
    modalities=["gene_expression", "splicing"],
    organism="human"
)

# 批量变异评分
variants = [
    {"chromosome": "chr1", "position": 109274968, "reference_bases": "G", "alternate_bases": "T"},
    {"chromosome": "chr19", "position": 8134523, "reference_bases": "G", "alternate_bases": "A"}
]
result = score_variant_batch(
    variants=variants,
    modalities=["gene_expression", "chromatin_accessibility"],
    organism="human"
)
```

### 变异效应可视化
```python
# 生成变异效应可视化
result = visualize_variant_effects(
    chromosome="chr1",
    position=109274968,
    reference_bases="G",
    alternate_bases="T",
    modalities=["gene_expression", "splicing", "chromatin_accessibility"],
    organism="human",
    context_length=2048
)
```

### 转录因子结合可视化
```python
# 可视化转录因子结合
result = visualize_tf_binding(
    chromosome="chr1",
    start=109270000,
    end=109280000,
    transcription_factors=["CTCF", "SP1", "GATA1"],
    organism="human"
)
```

## API 密钥配置

### 方法 1: 环境变量（推荐）

```bash
# 设置环境变量
export ALPHAGENOME_API_KEY="your_actual_api_key_here"

# 或创建 .env 文件
cp config.env.example .env
# 编辑 .env 文件，填入您的 API 密钥
```

### 方法 2: Hugging Face Spaces 环境变量

在 Hugging Face Spaces 设置中添加环境变量：
- 变量名：`ALPHAGENOME_API_KEY`
- 变量值：您的 AlphaGenome API 密钥

### 方法 3: Docker 环境变量

```bash
# 运行容器时设置环境变量
docker run -e ALPHAGENOME_API_KEY="your_api_key" -p 7860:7860 alphagenome-mcp
```

## 技术架构

- **FastMCP** - MCP 服务框架
- **AlphaGenome** - Google DeepMind 的基因组 AI 模型
- **FastAPI** - Web API 框架
- **Matplotlib** - 可视化库
- **TensorFlow** - 深度学习框架

## 许可证

本项目基于 Apache 2.0 许可证开源。

## 参考

- [AlphaGenome GitHub](https://github.com/google-deepmind/alphagenome)
- [Hugging Face Spaces](https://huggingface.co/spaces/kabuda777/Code2MCP-alphagenome)