Mutation Clinical Trial Matching MCP

Mutation Clinical Trial Matching MCP

遺伝子変異に基づいてclinicaltrials.govで臨床試験の適合候補を検索できる、高性能な統合型Model Context Protocol（MCP）サーバーです。

ステータス

本番環境で使用可能 — このプロジェクトは大規模なアーキテクチャ変革を完了し、100%の後方互換性を維持しながら、コードを60%削減した統合コードベースを実現しました。

✅ リポジトリ品質の向上：最新のPython標準（Python 3.11+との互換性）により、コード品質が99.6%向上
✅ 高水準の型安全性：包括的な型付け標準により、型診断が69%減少
✅ 統合アーキテクチャ：実行時に選択できる同期モードと非同期モードの両方をサポートする単一サーバー
✅ コードの重複排除：4段階の包括的な統合により、コードを60%（約1,000行）削減
✅ レガシーコードの整理：廃止されたコードを3,435行削除し、プロフェッショナルなコードベース構成を実現
✅ 破壊的変更ゼロ：互換性レイヤーを通じて自動移行ガイダンスを提供し、完全な後方互換性を実現
✅ エンタープライズ機能：サーキットブレーカー、メトリクス、再試行ロジック、分散キャッシュ、監視機能
✅ 高性能：非同期アーキテクチャと並行処理により、パフォーマンスが80%向上
✅ APIのレジリエンス：統合HTTPクライアントにより、403 Forbiddenエラーを解決する堅牢なエラー処理
✅ 包括的なテスト：統合コンポーネントを網羅する114件のテストを含む完全なテストスイート
✅ 最新のツール：依存関係管理にuvを使用し、Pythonのベストプラクティスに準拠
✅ 本番環境の監視：Prometheusメトリクス、キャッシュ分析、ヘルスモニタリングダッシュボード

本サーバーは現在も積極的に利用・保守されており、統合アーキテクチャについては変更履歴に記載されています。

AIとの協働による開発

このプロジェクトは、ドメインの専門知識とLLM主導の実装を組み合わせた、人間とAIの協働によって開発されました。

• 🧠 ドメイン主導：20年以上のがん研究経験をもとに、アーキテクチャと機能要件を策定
• 🤖 AIによる実装：体系的なLLM主導によるコード生成、API設計、パフォーマンス最適化
• 🔄 品質保証：専門的な基準と本番環境での信頼性を満たすための反復的な改善
• 📈 開発アプローチ：ドメインの専門家がAIツールを効果的に活用してバイオインフォマティクスプラットフォームを構築できることを実証

手法：このAI協働型のアプローチでは、生物学の専門知識とAIの能力を組み合わせ、コード品質と信頼性の基準を維持しながら開発を加速します。

概要

このプロジェクトでは、Agentic Coding の原則に従い、Claude Desktop と clinicaltrials.gov API を統合するシステムを作成します。このサーバーでは、遺伝子変異について自然言語で問い合わせることができ、関連する臨床試験の情報を要約して返します。

flowchart LR
    Claude[Claude Desktop] <-->|MCP Protocol| Server[Unified MCP Server]
    
    subgraph Detection[Runtime Mode Detection]
        Auto[Auto-Detect Event Loop]
        Env[MCP_ASYNC_MODE]
        Config[Configuration Override]
    end
    
    subgraph Cache[Distributed Cache]
        Redis[(Redis)]
        Memory[In-Memory]
    end
    
    subgraph Flow[Unified PocketFlow]
        QueryNode[Unified Query Node] -->|trials_data| SummarizeNode[Unified Summarize Node]
    end
    
    subgraph Services[Service Abstraction Layer]
        HttpClient[Unified HTTP Client]
        TrialsService[Clinical Trials Service]
        LLMService[LLM Service]
    end
    
    subgraph Monitoring[Enterprise Features]
        Metrics[Prometheus Metrics]
        Circuit[Circuit Breaker]
        Analytics[Cache Analytics]
    end
    
    Server -->|mode selection| Detection
    Detection -->|sync/async| Flow
    Server -->|mutation| Flow
    Flow -->|service calls| Services
    Services <-->|cache| Cache
    Services -->|concurrent/sequential requests| API[Clinicaltrials.gov API]
    API -->|trial data| Services
    Flow -->|summary| Server
    Server -->|metrics| Monitoring
    Server -->|formatted response| Claude

フロー内の各ノードは Unified PocketFlow Node パターンに従い、prep、exec、post メソッドを使用して、同期と非同期の両方の実行モードを自動的に処理します。

🚀 統合アーキテクチャとコード重複排除の成果

このプロジェクトでは、包括的な 4 段階のコード重複排除の取り組みが完了し、重複したコードベースから、統合された保守しやすいアーキテクチャへと移行しました。

コード重複排除の結果

指標	成果
コード削減	60% 削減（約 1,000 行を削減）
レガシーコードの整理	3,435 行を削除 ― プロフェッショナルなコードベース構造
コード品質	99.6% 改善 ― 1,702 件中 1,695 件の lint エラーを修正
型安全性	型診断が 69% 削減（48 → 15）
コンポーネントの統合	4 つの主要な統合（サーバー、ノード、サービス、HTTP）
破壊的変更	ゼロ ― 互換性レイヤーにより完全な後方互換性を実現
パフォーマンス向上	メモリ使用量を 30～40% 削減、起動を 20～30% 高速化
テストカバレッジ	統合されたすべてのコンポーネントをカバーする 114 件のテスト

統合前と統合後の比較

コンポーネント	統合前	統合後	削減率
サーバー	primary.py + sync_server.py	main.py	70%
ノード	nodes.py + async_nodes.py	unified_nodes.py	85%
サービス	query.py + async_query.py	service.py	95%
LLM クライアント	call_llm.py + async_call_llm.py	llm_service.py	95%

主なアーキテクチャの改善点

✅ 実行モードの選択：自動検出、または MCP_ASYNC_MODE による明示的な設定
✅ 信頼できる唯一の情報源：同期・非同期の実行間でビジネスロジックを統合
✅ 自動検出：実行コンテキストに基づいて実行モードをインテリジェントに選択
✅ サービスの抽象化：HTTP クライアントとサービスレイヤーを統合
✅ 設定システム：環境変数による上書きに対応した一元的な設定
✅ 後方互換性レイヤー：レガシーインポート用の完全な utils/node.py 互換モジュール
✅ 移行サポート：明確な移行ガイダンスを伴う非推奨警告

プロジェクト構成

このプロジェクトは、Agentic Coding のパラダイムに従って構成されています。

1. 要件（人間主導）：

   • 特定の遺伝子変異に関連する臨床試験を検索し、要約する
   • 変異に関する情報をコンテキストリソースとして提供する
   • Claude Desktop とシームレスに統合する

2. フロー設計（共同）：

   • ユーザーが Claude Desktop に遺伝子変異について問い合わせる
   • Claude が MCP サーバーのツールを呼び出す
   • サーバーが clinicaltrials.gov API に問い合わせる
   • サーバーが結果を処理し、要約する
   • サーバーが整形済みの結果を Claude に返す

3. ユーティリティ（共同）：

   • clinicaltrials/query.py：clinicaltrials.gov への API 呼び出しを処理する
   • utils/call_llm.py：Claude を扱うためのユーティリティ

4. ノード設計（AI 主導）：

   • utils/node.py：prep/exec/post パターンを備えたベースの Node クラスと BatchNode クラスを実装する
   • clinicaltrials/nodes.py：問い合わせと要約を行う専用ノードを定義する
   • clinicaltrials_mcp_server.py：フローの実行を統括する

5. 実装（AI 主導）：

   • プロトコルの詳細を処理する FastMCP SDK
   • すべてのレベルでのエラー処理
   • 一般的な変異に関するリソース

アーキテクチャの構成要素

統合 MCP サーバー（servers/main.py）

実行時のモード選択に対応した、Model Context Protocol を実装するメインの統合サーバーです。

• 統合アーキテクチャ：同期モードと非同期モードの両方に対応する単一の実装です
• 実行時のモード選択：イベントループによる自動検出、または MCP_ASYNC_MODE の明示的な設定が可能です
• エンタープライズ向けツール：ヘルスモニタリング、メトリクス収集、キャッシュ管理（モードにより異なります）
• 自動スケーリング：堅牢な API 通信を実現するサーキットブレーカーと再試行ロジックです
• キャッシュのウォームアップ：一般的なミューテーションを自動的に事前読み込みし、即時応答を可能にします（非同期モード）
• API の耐障害性：統合 HTTP クライアントのフォールバック機構により、403 Forbidden エラーに対応します
• 後方互換性：レガシーサーバーは非推奨の警告とともにリダイレクトされます

統合サービスレイヤー

臨床試験サービス（clinicaltrials/service.py）：モード対応の処理を備えた統合 API クライアントです

• デュアルモード対応：同期（query_trials）と非同期（aquery_trials）の呼び出しで同じインターフェースを使用できます
• サーキットブレーカーの統合：障害の自動検出と復旧に対応します
• 分散キャッシュ：Redis を利用したキャッシュと、メモリ内キャッシュへのフォールバックに対応します
• メトリクス収集：詳細なパフォーマンス分析と利用状況分析を行います
• API 互換性：信頼性の高い clinicaltrials.gov API アクセスに、統合 HTTP クライアントを使用します

LLM サービス（utils/llm_service.py）：統合 LLM 対話クライアントです

• モード対応の処理：同期と非同期の両方の LLM 呼び出しに対応します
• 再試行ロジック：指数バックオフを伴う再試行機構を内蔵しています
• エラー処理：構造化ログを使用した包括的なエラー処理を備えています

統合ノード（clinicaltrials/unified_nodes.py）

同期・非同期の実行を自動で切り替える PocketFlow ノードです。

• QueryTrialsNode：API リクエストのモードを検出する統合ノードです
• SummarizeTrialsNode：再試行ロジックを備えた、LLM を活用する統合要約ノードです
• BatchQueryTrialsNode：同時実行数を制御するバッチ処理（非同期）または順次処理（同期）に対応します
• 自動検出：ノードは実行時に実行モードを自動判定します

統合基盤レイヤー

• 統合 HTTP クライアント（utils/http_client.py）：コネクションプーリングを備え、同期と非同期の両方に対応する単一の HTTP クライアントです
• 統合ノードフレームワーク（utils/unified_node.py）：モードを自動検出する基底クラスです
• 共有ユーティリティ（utils/shared.py）：共通の検証、エラー処理、メトリクス関数です
• キャッシュ戦略（utils/cache_strategies.py）：スマートなキャッシュのウォームアップと無効化に対応します（非同期モード）
• 設定システム（servers/config.py）：環境変数による上書きに対応する一元化された設定です
• レガシー互換性（servers/legacy_compat.py）：移行ガイダンスを備えた後方互換性レイヤーです

統合ノードパターンの実装

このプロジェクトでは、同期・非同期の実行を統合した拡張 PocketFlow Node パターンを実装し、AI ワークフローを構築するためのモジュール化された保守しやすい方法を提供します。

統合コアノードクラス（utils/unified_node.py）

• UnifiedNode：モードを自動検出し、同期と非同期の両方の実行に対応する基底クラスです
• UnifiedBatchNode：同時実行数を制御するバッチ処理（非同期）または順次処理（同期）に対応する拡張クラスです
• UnifiedFlow：インテリジェントなモード選択により実行を調整します

統合実装ノード（clinicaltrials/unified_nodes.py）

1. QueryTrialsNode（統合）：

   # Single implementation supporting both modes
   def prep(self, shared): return shared["mutation"]
   
   def exec(self, mutation): 
       return self.trials_service.query_trials(mutation)  # Sync version
   
   async def aexec(self, mutation): 
       return await self.trials_service.aquery_trials(mutation)  # Async version
   
   def post(self, shared, mutation, result):
       shared["trials_data"] = result
       shared["studies"] = result.get("studies", [])
       return self.get_next_node_id(result)
   

2. SummarizeTrialsNode（統合）：

   # Unified summarization with mode detection
   def prep(self, shared): return shared["studies"]
   
   def exec(self, studies): 
       return self.llm_service.call_llm(prompt)  # Sync version
   
   async def aexec(self, studies): 
       return await self.llm_service.acall_llm(prompt)  # Async version
   
   def post(self, shared, studies, summary):
       shared["summary"] = summary
       return None  # End of flow
   

統合フローの実行

統合 MCP サーバーは、モードを自動検出してフローを作成し、実行します。

# Create unified nodes (mode determined at runtime)
query_node = QueryTrialsNode(async_mode=server.async_mode)
summarize_node = SummarizeTrialsNode(async_mode=server.async_mode)

# Use PocketFlow chaining syntax
query_node >> summarize_node

# Create unified flow
flow = UnifiedFlow(start_node=query_node, async_mode=server.async_mode)

# Run flow with shared context (automatically sync or async)
shared = {"mutation": mutation}
if server.async_mode:
    result = await flow.aexecute(shared)
else:
    result = flow.execute(shared)

統一パターンの主な利点

✅ 単一の実装：1つのコードベースで同期実行と非同期実行の両方に対応します
✅ 自動検出：ノードが最適な実行モードを自動的に判定します
✅ 実行時の選択：サーバーの起動時または実行時にモードを選択できます
✅ インターフェースの維持：同じ prep、exec、post のパターンを維持します
✅ パフォーマンスの最適化：モードに応じた最適化（タイムアウト、並行処理、バッチ制限）を行います
✅ 後方互換性：レガシーなノードパターンも、非推奨の警告付きで引き続き動作します

この統一パターンにより、PocketFlow 本来の設計が持つモジュール性とテストのしやすさを維持しながら、コードの重複を解消できます。詳細については、設計ドキュメントを参照してください。

使用方法

1. uv で依存関係をインストールします：

   uv sync
   

2. 統合サーバーを使用するように Claude Desktop を設定します：

   {
     "mcpServers": {
       "mutation-clinical-trials-mcp": {
         "command": "uv",
         "args": ["run", "python", "servers/main.py"],
         "description": "Unified clinical trials matching server with runtime mode selection"
       }
     }
   }
   

3. 任意：環境変数で実行モードを設定します：

   {
     "mcpServers": {
       "mutation-clinical-trials-mcp": {
         "command": "uv",
         "args": ["run", "python", "servers/main.py"],
         "env": {
           "MCP_ASYNC_MODE": "true"
         },
         "description": "Unified server in explicit async mode"
       }
     }
   }
   

4. Claude Desktop を起動し、次のような質問をします：

   • 「EGFR L858R 変異を対象とした臨床試験には何がありますか？」
   • 「BRAF V600E 変異を対象とした試験はありますか？」
   • 「ALK 再構成を対象とした試験について教えてください」
   • 「複数の変異を検索してください：EGFR L858R,BRAF V600E,KRAS G12C」

5. エンタープライズ監視ツールを使用します：

   • 「サーバーのヘルスステータスを取得してください」
   • 「キャッシュのパフォーマンスレポートを表示してください」
   • 「現在のメトリクスは何ですか？」

---

Claude Desktop との統合

このプロジェクトを Claude Desktop の MCP ツールとして設定できます。設定内のパスのプレースホルダーを、実際のパスに置き換えてください。

推奨設定（統合サーバー）

"mutation-clinical-trials-mcp": {
  "command": "{PATH_TO_VENV}/bin/python",
  "args": [
    "{PATH_TO_PROJECT}/servers/main.py"
  ],
  "description": "Unified clinical trials matching server with automatic mode selection."
}

レガシー互換性（引き続きサポート）

"mutation-clinical-trials-mcp-legacy": {
  "command": "{PATH_TO_VENV}/bin/python",
  "args": [
    "{PATH_TO_PROJECT}/servers/primary.py"
  ],
  "description": "Legacy async server (redirects to unified server with deprecation warnings)."
}

パス変数：

• {PATH_TO_VENV}：仮想環境ディレクトリの完全なパスです。
• {PATH_TO_PROJECT}：プロジェクトファイルを含むディレクトリの完全なパスです。

インストール手順：

1. リポジトリをローカルマシンにクローンします。
2. まだ uv をインストールしていない場合は、インストールします：

   curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS/Linux
   # or
   iwr -useb https://astral.sh/uv/install.ps1 | iex    # Windows PowerShell
   

3. 仮想環境を作成し、依存関係を一度にインストールします：

   uv sync
   

4. 必要に応じて仮想環境を有効化します：

   source .venv/bin/activate    # macOS/Linux
   .venv\Scripts\activate       # Windows
   

5. 仮想環境とプロジェクトディレクトリの完全なパスを確認します。
6. これらの具体的なパスを使って設定を更新します。

例：

• macOS/Linux の場合：

  "command": "/Users/username/projects/mutation_trial_matcher/.venv/bin/python"
  

• Windows の場合：

  "command": "C:\\Users\\username\\projects\\mutation_trial_matcher\\.venv\\Scripts\\python.exe"
  

パスの確認方法：

• 仮想環境内の Python インタープリターの正確なパスを確認するには、次を実行します：
  • which python（macOS/Linux）
  • where python（Windows。venv を有効化した後）
• プロジェクトのパスには、servers/primary.py を含むディレクトリの完全なパスを指定します。

---

今後の改善

予定されている機能強化と今後の作業の包括的な一覧については、future_work.md ドキュメントを参照してください。

依存関係

このプロジェクトは、次の主要な依存関係を使用します：

• Python 3.11+ - ベースとなるランタイム環境（幅広い互換性のため 3.13+ から引き下げ）
• FastMCP（fastmcp>=2.10.2）- 高性能な非同期 MCP フレームワーク
• PocketFlow（pocketflow>=0.0.1）- Node パターンを使ってモジュール式の AI ワークフローを構築するためのフレームワーク
• Requests（requests==2.31.0）- clinicaltrials.gov API 呼び出し用の HTTP ライブラリ（レガシーテストとの互換性のための開発依存関係）
• HTTPX（httpx>=0.28.1）- Anthropic API を直接呼び出すための非同期 HTTP クライアント
• Redis（redis>=6.2.0）- オプションの分散キャッシュバックエンド
• Python-dotenv（python-dotenv==1.1.0）- 環境変数の管理

エンタープライズ機能：

• Prometheus によるメトリクス収集と監視
• フォールトトレランスのためのサーキットブレーカーパターン
• Redis バックエンドを使った分散キャッシュ
• パフォーマンス最適化のためのキャッシュウォーミング戦略

インストール手順に記載のとおり、uv sync を使ってすべての依存関係をインストールできます。

トラブルシューティング

Claude Desktop が MCP サーバーから切断される場合：

• ログを確認します：~/Library/Logs/Claude/mcp-server-mutation-clinical-trials-mcp.log
• Claude Desktop を再起動します
• uv run python servers/main.py を実行して、サーバーが正常に動作していることを確認します
• レガシーサーバー（servers/primary.py または servers/legacy/sync_server.py）を使用している場合は、非推奨の警告が出ていないか確認します

Redis 接続に関する警告：

• Redis がインストールされていない場合、Redis の接続エラーが発生するのは想定内です。サーバーはフォールバックとしてインメモリキャッシュを使用します
• 警告を解消するには：brew install redis && brew services start redis
• Redis がなくてもサーバーは問題なく動作しますが、キャッシュのパフォーマンスは低下します

起動時のキャッシュウォーミング：

• パフォーマンス最適化のため、サーバーは起動時に一般的な15種類の変異を自動的にクエリします
• これは通常の動作であり、頻繁に行われるクエリの応答時間を改善します
• 無効にするには：servers/primary.py の asyncio.run(startup_tasks()) をコメントアウトします

開発の歴史

このプロジェクトは、AI と協力しながら複数の段階を経て開発されました。

フェーズ 1（2024-04-30）：同期アーキテクチャを使用した初期プロトタイプ
フェーズ 2（2024-12）：包括的なテストとドキュメントによる機能強化
フェーズ 3（2025-01）：構成と保守性を向上させる大規模なリファクタリング
フェーズ 4（2025-01）：エンタープライズ機能を備えた完全な非同期化により、パフォーマンスが80%向上
フェーズ 5（2025-07）：API の耐障害性を向上させ、403 エラーを解決
フェーズ 6（2025-07）：コード重複排除プロジェクト - 4段階にわたる包括的な統合作業
フェーズ 7（2025-07）：リポジトリ品質の卓越性 - プロフェッショナルなコード標準とレガシーコードの整理

最近の成果（2025年7月）

コード重複排除プロジェクト：
フェーズ 1：基盤レイヤー - HTTP クライアントと共有ユーティリティを統合
フェーズ 2：サービスレイヤーの統合 - LLM サービスと Clinical Trials サービスを統合
フェーズ 3：ノードレイヤーの統合 - UnifiedNode フレームワークを強化
フェーズ 4：サーバーの統合 - アーキテクチャを完全に統一

リポジトリ品質の卓越性：

• コード品質：99.6%改善（1,702件中1,695件のリンティングエラーを修正）
• 型安全性：型診断を69%削減（48 → 15）
• プロフェッショナルな整理：非推奨コードを3,435行削除
• 互換性レイヤー：utils/node.py 互換性モジュールにより、完全な後方互換性を実現
• Python 互換性：より幅広い導入に向けて、要件を Python 3.13+ から 3.11+ に引き下げ

成果：コードを60%削減（約1,000行を削除）、破壊的変更ゼロ、同期／非同期アーキテクチャの統一、本番環境に対応したコード品質

現在のバージョン（v0.2.1）：エンタープライズ機能、自動モード選択、プロフェッショナルな型安全性、包括的な後方互換性を備えた、本番環境に対応した統合サーバーです。Claude Code との協力を通じて開発され、がん研究分野における20年以上の専門知識を活用して、AI による実装とアーキテクチャの変革を導きました。

貢献

Mutation Clinical Trial Matching MCP の改善に向けた貢献を歓迎します。参加方法は次のとおりです。

開発環境のセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/pickleton89/mutation-clinical-trial-matching-mcp.git
   cd mutation-clinical-trial-matching-mcp
   

2. 依存関係をインストールします：

   uv sync
   

3. テストを実行します：

   uv run python -m unittest discover tests/
   

貢献ガイドライン

• 新機能では PocketFlow Node パターンに従ってください
• 新しい機能には 包括的なテストを追加してください
• 関連する docstring や README のセクションを含め、ドキュメントを更新してください
• Python のベストプラクティスに従い、型ヒントを維持してください
• PR を提出する前に リンティングと型チェックを実行してください

貢献できる分野

• 大規模な臨床試験検索の パフォーマンス最適化
• 追加の変異形式と標準化
• より詳細なフィルタリングによる 要約機能の強化
• ClinicalTrials.gov 以外の 他の臨床データベースとの連携
• Claude Desktop 連携の UI/UX 改善

問題の報告

バグの報告や機能のリクエストには、GitHub Issues ページをご利用ください。

ライセンス

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

謝辞

このプロジェクトは、出発点として PocketFlow-Template-Python を使用して構築されました。この実装を可能にした基盤と構造を提供してくださった、同プロジェクトのオリジナルの貢献者の皆様に心より感謝いたします。

このプロジェクトは、オリジナルのテンプレートに記載された Agentic Coding の方法論に従っています。

---

⚠️ 免責事項

このプロジェクトはプロトタイプであり、研究およびデモンストレーションのみを目的としています。医療上の決定に使用したり、専門的な医療上の助言、診断、治療の代わりとして使用したりしないでください。大規模言語モデル（LLM）の限界により、このツールが提供する情報は不完全、不正確、または古い可能性があります。このシステムの出力に基づいて決定を下す前に、慎重に判断し、資格を有する医療専門家に相談してください。

---