Cbioportal MCP

🚀 🧬 cBioPortal MCP Server

このサーバーは、高性能で本番環境でも使用可能なModel Context Protocol (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%削減 (1,357 → 396行)
• 📦 最新のパッケージ管理：pyproject.tomlを使用したuvベースのワークフロー
• 🔄 並行操作：自動バッチ処理による研究と遺伝子の一括取得

🔧 エンタープライズ機能

• ⚙️ 多層構成：CLI引数 → 環境変数 → YAML設定 → デフォルト
• 📋 包括的なテスト：8つの整理されたテストスイートで93のテストを実行し、完全なカバレッジを実現
• 🛡️ 入力検証：堅牢なパラメータ検証とエラーハンドリング
• 📊 ページネーションサポート：自動ページネーションによる効率的なデータ取得
• 🔧 コード品質：Ruffによるリンティング、フォーマット、および包括的なコード品質チェック
• ⚡ パフォーマンス調整可能：バッチサイズとパフォーマンスを調整可能

🧬 がんゲノミクス機能

• 🔍 研究管理：がん研究の閲覧、検索、分析
• 🧪 分子データ：突然変異、臨床データ、分子プロファイルへのアクセス
• 📈 一括操作：複数のエンティティを並行して取得
• 🔎 高度な検索：研究と遺伝子をキーワードで検索

🎆 最近の品質とアーキテクチャの改善

🚀 主要なリファクタリング成果 (2025年)

• 🏗️ BaseEndpointアーキテクチャ：継承ベースの設計により、コードの重複を約60%削減
• 📝 コード品質の向上：最新のリンティング (Ruff) を使用した包括的な外部レビューの統合
• ⚙️ 構成可能性の強化：遺伝子バッチサイズ、リトライロジック、およびパフォーマンス調整を構成可能に
• 🛡️ 堅牢な検証：デコレータベースのパラメータ検証とエラーハンドリング
• 🧪 テストの成熟度：主要なリファクタリングを通じて、93の包括的なテストで回帰がゼロ

📈 本番環境での可用性

• ✅ 外部コードレビュー：専門的なコード品質検証と改善が実施された
• 🔧 最新のPythonプラクティス：型チェック、リンティング、フォーマット、およびベストプラクティスの遵守
• 🏗️ エンタープライズアーキテクチャ：関心事の明確な分離を持つモジュール設計
• 🚀 パフォーマンス最適化：構成可能なバッチ処理による4.5倍の非同期改善

🧠🤖 AI協調開発

このプロジェクトは、バイオインフォマティクスソフトウェア開発における最先端の人間とAIの協調を実証しています。

• 🧠 ドメインエキスパートの知識：20年以上のがん研究の経験に基づいたアーキテクチャと機能要件の設計
• 🤖 AIによる実装：体系的なLLM協調による高度なコード生成、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

# 1コマンドでセットアップ (仮想環境の作成 + 依存関係のインストール)
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 .

⚙️ 構成

🎛️ 多層構成システム

サーバーは、優先順位が CLI引数 > 環境変数 > 設定ファイル > デフォルト である柔軟な構成をサポートしています。

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  # 並行操作のための構成可能な遺伝子バッチサイズ

環境変数 🌍

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  # 遺伝子バッチサイズを構成
export CBIOPORTAL_RETRY_MAX_ATTEMPTS=5

CLIオプション 💻

# 基本的な使用方法
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 Desktopとの統合

Claude Desktopの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 Desktopを再起動します。

🔧 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 .

🧪 テスト

8つのカテゴリで93のテストを含む包括的なテストスイート：

• 🔄 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 Desktopとの接続問題

• ✅ 直接のスクリプトパスを使用 (オプション1) して、最も信頼性の高い接続を確保します。
• ✅ MCP構成のパスが絶対パスであることを確認します ( ~ や相対パスは使用しない)。
• ✅ 編集可能モードでプロジェクトをインストールします：プロジェクトディレクトリで uv pip install -e . を実行します。
• ✅ 仮想環境の .venv/bin/cbioportal-mcp スクリプトが存在することを確認します。
• ✅ オプション2の場合：uv がシステムのPATHに含まれていること、および cwd がプロジェクトディレクトリを指していることを確認します。
• ✅ Claude Desktopのログを確認して、詳細なエラーを確認します。

パフォーマンス問題

• 🔧 構成で 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研究の患者の臨床データを見つけてください。"
"小児脳腫瘍に利用可能な分子プロファイルはどれですか？"

🧬 ゲノミクス分析

"2つのがん研究間の突然変異頻度を比較してください。"
"卵巣がんのDNA修復経路に含まれるすべての遺伝子を取得してください。"
"RNA-seqと突然変異データの両方を持つ研究を見つけてください。"
"神経膠芽腫で最も頻繁に突然変異する遺伝子は何ですか？"

📊 一括操作

"複数のがん研究のデータを並行して取得してください。"
"がん遺伝子のリストの情報を効率的に取得してください。"
"複数の研究間の臨床特性を比較してください。"
"いくつかのがんタイプの分子プロファイルを取得してください。"

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

🙏 謝辞

• 🧬 cBioPortal - オープンアクセスのがんゲノミクスデータプラットフォーム
• 🔗 Model Context Protocol - AIツールとのシームレスなやり取りを可能にする
• ⚡ FastMCP - 高性能のMCPサーバーフレームワーク
• 📦 uv - 最新のPythonパッケージ管理
• 🤖 AI協調開発 - 科学ソフトウェア開発における人間とAIのパートナーシップの力を実証する

🌟 革新的な人間とAIの協調によって構築された本番環境で使用可能なバイオインフォマティクスプラットフォーム！ 🧬✨

ドメインエキスパートの知識とAI支援開発の力を活用したエンタープライズグレードの科学ソフトウェアを実証します。