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辅助开发在企业级科学软件中的强大力量。