Cbioportal MCP

🚀 🧬 cBioPortal MCP Server

這是一個高性能、適用於生產環境的模型上下文協議（MCP）服務器，它能讓AI助手與來自 cBioPortal 的癌症基因組學數據實現無縫交互。該服務器採用現代異步Python架構、企業級模塊化設計和BaseEndpoint模式構建，具備極高的可靠性、可維護性，且性能提升了4.5倍。

🚀 快速開始

前提條件

• Python 3.10+ 🐍
• uv（現代包管理器） - 推薦使用 📦
• Git（可選，用於克隆項目）

⚡ 安裝與啟動

# 若需要，安裝uv
pipx install uv

# 克隆並設置項目
git clone https://github.com/yourusername/cbioportal-mcp.git
cd cbioportal-mcp
uv sync

# 啟動服務器
uv run cbioportal-mcp

🎉 大功告成！服務器已啟動，隨時可與AI助手建立連接。

✨ 主要特性

🚀 性能與架構

• ⚡ 性能提升4.5倍：採用全異步實現，支持併發API操作
• 🏗️ 企業級架構：使用BaseEndpoint模式，消除了60%的代碼重複
• 📐 模塊化設計：專業的結構，代碼量減少了71%（從1357行降至396行）
• 📦 現代包管理：基於uv的工作流，搭配pyproject.toml
• 🔄 併發操作：批量獲取研究和基因數據，支持自動分批處理

🔧 企業級特性

• ⚙️ 多層配置：命令行參數 → 環境變量 → YAML配置 → 默認值
• 📋 全面測試：8個有組織的測試套件中包含93個測試，實現全面覆蓋
• 🛡️ 輸入驗證：強大的參數驗證和錯誤處理機制
• 📊 分頁支持：高效的數據檢索，支持自動分頁
• 🔧 代碼質量：使用Ruff進行代碼檢查、格式化和全面的代碼質量檢查
• ⚡ 可配置性能：可調整批量大小和性能參數

🧬 癌症基因組學能力

• 🔍 研究管理：瀏覽、搜索和分析癌症研究
• 🧪 分子數據：訪問突變、臨床數據和分子特徵
• 📈 批量操作：併發獲取多個實體的數據
• 🔎 高級搜索：基於關鍵詞在研究和基因中進行發現

🎆 近期質量與架構改進

🚀 重大重構成果（2025年）

• 🏗️ BaseEndpoint架構：通過基於繼承的設計，消除了約60%的代碼重複
• 📝 卓越的代碼質量：集成全面的外部審查，採用現代代碼檢查工具（Ruff）
• ⚙️ 增強的可配置性：現在可以配置基因批量大小、重試邏輯和性能調優參數
• 🛡️ 強大的驗證：基於裝飾器的參數驗證和錯誤處理
• 🧪 成熟的測試：經過93個全面測試，在重大重構過程中零迴歸

📈 生產就緒狀態

• ✅ 外部代碼審查：進行了專業的代碼質量驗證和改進
• 🔧 現代Python實踐：進行類型檢查、代碼檢查、格式化，遵循最佳實踐
• 🏗️ 企業級架構：模塊化設計，職責清晰分離
• 🚀 性能優化：異步實現使性能提升4.5倍，支持可配置的批量處理

🧠🤖 人工智能協作開發

該項目展示了生物信息學軟件開發中前沿的人機協作：

• 🧠 領域專業知識：20多年的癌症研究經驗指導了架構和功能需求
• 🤖 AI實現：通過系統的大語言模型協作，實現高級代碼生成、API設計和性能優化
• 🔄 質量保證：迭代式改進，確保達到專業標準和生產可靠性
• 🏗️ 架構演進：通過AI引導的重構，採用BaseEndpoint模式，消除了60%的代碼重複
• 📈 創新方法：展示了領域專家如何有效利用AI工具構建企業級生物信息學平臺

近期成果：集成外部代碼審查，進行全面的質量改進，包括Ruff配置、可配置的性能設置和現代Python最佳實踐。

方法：這種協作方法將深厚的生物學領域知識與AI驅動的開發能力相結合，在保持嚴格的代碼質量和科學準確性的同時，加速創新。

📦 安裝指南

🔥 選項1：uv（推薦）

採用現代、快速的包管理方式，自動處理環境：

# 安裝uv
pipx install uv
# 或者使用Homebrew安裝：brew install uv

# 克隆倉庫
git clone https://github.com/yourusername/cbioportal-mcp.git
cd cbioportal-mcp

# 一鍵設置（創建虛擬環境並安裝依賴）
uv sync

🐍 選項2：pip（傳統方式）

使用標準的Python包管理方法：

# 創建虛擬環境
python -m venv cbioportal-mcp-env

# 激活環境
# Windows: cbioportal-mcp-env\Scripts\activate
# macOS/Linux: source cbioportal-mcp-env/bin/activate

# 安裝依賴
pip install -e .

⚙️ 配置

🎛️ 多層配置系統

服務器支持靈活的配置，優先級為：命令行參數 > 環境變量 > 配置文件 > 默認值

YAML配置 📄

創建config.yaml文件以進行持久化設置：

# cBioPortal MCP Server Configuration
server:
  base_url: "https://www.cbioportal.org/api"
  transport: "stdio"
  client_timeout: 480.0
  
logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

api:
  rate_limit:
    enabled: false
    requests_per_second: 10
  retry:
    enabled: true
    max_attempts: 3
    backoff_factor: 1.0
  cache:
    enabled: false
    ttl_seconds: 300
  batch_size:
    genes: 100  # Configurable gene batch size for concurrent operations

環境變量 🌍

export CBIOPORTAL_BASE_URL="https://custom-instance.org/api"
export CBIOPORTAL_LOG_LEVEL="DEBUG"
export CBIOPORTAL_CLIENT_TIMEOUT=600
export CBIOPORTAL_GENE_BATCH_SIZE=50  # Configure gene batch size
export CBIOPORTAL_RETRY_MAX_ATTEMPTS=5

命令行選項 💻

# 基本用法
uv run cbioportal-mcp

# 自定義配置
uv run cbioportal-mcp --config config.yaml --log-level DEBUG

# 自定義API端點
uv run cbioportal-mcp --base-url https://custom-instance.org/api

# 生成示例配置
uv run cbioportal-mcp --create-example-config

🔌 使用與集成

🖥️ Claude桌面集成

在Claude桌面MCP設置中進行配置：

選項1：直接腳本路徑（推薦）

{
  "mcpServers": {
    "cbioportal": {
      "command": "/path/to/your/project/cbioportal_MCP/.venv/bin/cbioportal-mcp",
      "env": {
        "CBIOPORTAL_LOG_LEVEL": "INFO"
      }
    }
  }
}

選項2：uv run（替代方案）

{
  "mcpServers": {
    "cbioportal": {
      "command": "uv",
      "args": ["run", "cbioportal-mcp"],
      "cwd": "/path/to/your/project/cbioportal_MCP",
      "env": {
        "CBIOPORTAL_LOG_LEVEL": "INFO"
      }
    }
  }
}

重要設置步驟：

1. 將/path/to/your/project/cbioportal_MCP替換為實際的項目路徑
2. 確保項目以可編輯模式安裝：uv pip install -e .
3. 更新配置後重啟Claude桌面

🔧 VS Code集成

在工作區設置中添加以下內容：

{
  "mcp.servers": {
    "cbioportal": {
      "command": "uv",
      "args": ["run", "cbioportal-mcp"],
      "cwd": "/path/to/cbioportal-mcp"
    }
  }
}

🏃‍♂️ 命令行使用

# 開發服務器，啟用調試日誌
uv run cbioportal-mcp --log-level DEBUG

# 生產服務器，使用自定義配置
uv run cbioportal-mcp --config production.yaml

# 使用自定義cBioPortal實例
uv run cbioportal-mcp --base-url https://private-instance.org/api

🏗️ 架構

📁 現代項目結構

cbioportal-mcp/
├── 📁 cbioportal_mcp/           # 主包目錄
│   ├── 📊 server.py             # 主MCP服務器實現
│   ├── 🌐 api_client.py         # 專用HTTP客戶端類
│   ├── ⚙️ config.py             # 多層配置系統
│   ├── 📋 constants.py          # 集中管理的常量
│   ├── 📁 endpoints/            # 特定領域的API模塊
│   │   ├── 🏗️ base.py           # BaseEndpoint模式（減少60%的重複）
│   │   ├── 🔬 studies.py        # 癌症研究與搜索
│   │   ├── 🧬 genes.py          # 基因操作與突變
│   │   ├── 🧪 samples.py        # 樣本數據管理
│   │   └── 📈 molecular_profiles.py # 分子與臨床數據
│   └── 📁 utils/                # 共享工具
│       ├── 📄 pagination.py     # 高效的分頁邏輯
│       ├── ✅ validation.py     # 輸入驗證
│       └── 📝 logging.py        # 日誌配置
├── 📁 tests/                    # 全面的測試套件（93個測試）
├── 📁 docs/                     # 文檔
├── 📁 scripts/                  # 開發工具
└── 📄 pyproject.toml           # 現代Python項目配置

🎯 設計原則

• 🔧 模塊化：通過特定領域的模塊，實現清晰的職責分離
• ⚡ 異步優先：全異步實現，以獲得最佳性能
• 🏗️ BaseEndpoint模式：基於繼承的架構，消除了60%的代碼重複
• 🛡️ 強大可靠：通過裝飾器實現全面的輸入驗證和錯誤處理
• 🧪 可測試：93個測試確保可靠性，防止迴歸
• 🔄 可維護：簡潔的代碼架構，複雜度降低71%
• 📝 代碼質量：使用Ruff進行代碼檢查、格式化，遵循現代Python實踐

🛠️ 可用工具

服務器為AI助手提供了12個高性能工具：

🌟 性能特性

• ⚡ 併發操作：get_multiple_*方法使用asyncio.gather進行並行處理
• 📦 智能分批：對大型基因列表進行自動分批處理
• 📄 高效分頁：使用異步生成器實現內存高效的數據流式傳輸
• ⏱️ 性能指標：報告執行時間和批量計數

🚀 性能

📊 基準測試結果

我們的異步實現帶來了顯著的性能提升：

🏃‍♂️ 順序獲取研究： 1.31秒（10個研究）
⚡ 併發獲取研究：  0.29秒（10個研究）
🎯 性能提升：      4.57倍！

🔥 異步優勢

• 🚀 快4.5倍：併發API請求比順序操作更快
• 📦 批量處理：高效的批量操作，可處理多個實體
• ⏱️ 非阻塞：異步I/O防止請求阻塞
• 🧮 智能分批：對大型數據集進行自動優化

💡 性能提示

• 使用get_multiple_studies併發獲取多個研究
• 利用get_multiple_genes自動分批處理基因列表
• 在配置中配置concurrent_batch_size以獲得最佳性能
• 監控響應元數據中的執行指標

👨‍💻 開發

🔨 開發工作流

# 設置開發環境
uv sync

# 運行測試
uv run pytest

# 運行並統計覆蓋率
uv run pytest --cov=.

# 運行特定測試文件
uv run pytest tests/test_server_lifecycle.py

# 更新快照
uv run pytest --snapshot-update

# 檢查代碼
uv run ruff check .

# 格式化代碼
uv run ruff format .

🧪 測試

全面的測試套件包含93個測試，分為8個類別：

• 🔄 test_server_lifecycle.py - 服務器啟動/關閉和工具註冊
• 📄 test_pagination.py - 分頁邏輯和邊界情況
• 🚀 test_multiple_entity_apis.py - 併發操作和批量獲取
• ✅ test_input_validation.py - 參數驗證和錯誤處理
• 📸 test_snapshot_responses.py - API響應一致性（syrupy）
• 💻 test_cli.py - 命令行界面和參數解析
• 🛡️ test_error_handling.py - 錯誤場景和網絡問題
• ⚙️ test_configuration.py - 配置系統驗證

🛠️ 開發工具與質量基礎設施

• 📦 uv：現代包管理（比pip快10 - 100倍）
• 🧪 pytest：支持異步的測試框架，包含93個全面測試
• 📸 syrupy：用於API響應一致性的快照測試
• 🔍 Ruff：快速的代碼檢查、格式化和代碼質量強制工具
• 📊 pytest-cov：代碼覆蓋率報告和質量指標
• 🏗️ BaseEndpoint：繼承模式，消除60%的代碼重複
• ⚙️ 類型檢查：全面的類型註解，提高代碼安全性
• 🛡️ 驗證裝飾器：自動參數驗證和錯誤處理

🤝 貢獻代碼

1. 🍴 分叉 倉庫
2. 🌿 創建 一個功能分支 (git checkout -b feature/amazing-feature)
3. ✅ 測試 你的更改 (uv run pytest)
4. 📝 提交 清晰的提交信息 (git commit -m 'Add amazing feature')
5. 🚀 推送 到分支 (git push origin feature/amazing-feature)
6. 🔄 創建 一個拉取請求

🔧 故障排除

🚨 常見問題

服務器無法啟動

# 檢查Python版本
python --version  # 應為3.10+

# 驗證依賴項
uv sync

# 檢查是否有衝突
uv run python -c "import mcp, httpx, fastmcp; print('Dependencies OK')"

Claude桌面連接問題

• ✅ 使用直接腳本路徑（選項1）以獲得最可靠的連接
• ✅ 驗證MCP配置中的路徑為絕對路徑（無~或相對路徑）
• ✅ 以可編輯模式安裝：在項目目錄中運行uv pip install -e .
• ✅ 確保虛擬環境中的.venv/bin/cbioportal-mcp腳本存在
• ✅ 對於選項2：檢查uv是否在系統路徑中，並且cwd指向項目目錄
• ✅ 查看Claude桌面日誌以獲取詳細錯誤信息

性能問題

• 🔧 在配置中增加concurrent_batch_size
• 🔧 調整系統的max_concurrent_requests參數
• 🔧 使用get_multiple_*方法進行批量操作
• 🔧 監控與cBioPortal API的網絡延遲

配置問題

# 生成示例配置
uv run cbioportal-mcp --create-example-config

# 驗證配置
uv run cbioportal-mcp --config your-config.yaml --log-level DEBUG

# 檢查環境變量
env | grep CBIOPORTAL

🌐 API連接性

# 測試cBioPortal API可訪問性
curl https://www.cbioportal.org/api/cancer-types

# 使用自定義實例進行測試
curl https://your-instance.org/api/studies

💡 示例與用例

🔍 研究查詢

"有哪些可用於乳腺癌研究的癌症研究？"
"搜索具有基因組數據的黑色素瘤研究"
"獲取肺癌研究中TP53基因的突變數據"
"查找TCGA - BRCA研究中患者的臨床數據"
"有哪些可用於兒童腦腫瘤的分子特徵？"

🧬 基因組分析

"比較兩個癌症研究中的突變頻率"
"獲取卵巢癌DNA修復途徑中的所有基因"
"查找同時具有RNA測序和突變數據的研究"
"膠質母細胞瘤中最常見的突變基因有哪些？"

📊 批量操作

"併發獲取多個癌症研究的數據"
"高效獲取癌症基因列表的信息"
"比較多個研究的臨床特徵"
"檢索幾種癌症類型的分子特徵"

📜 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• 🧬 cBioPortal - 開放訪問的癌症基因組學數據平臺
• 🔗 模型上下文協議 - 實現無縫的AI工具交互
• ⚡ FastMCP - 高性能MCP服務器框架
• 📦 uv - 現代Python包管理工具
• 🤖 人工智能協作 - 展示了人機合作在科學軟件開發中的強大力量

🌟 通過創新的人機協作構建的生產就緒生物信息學平臺！ 🧬✨

展示了領域專業知識與AI輔助開發在企業級科學軟件中的強大力量。