ImmunoGraph MCP

ImmunoGraph MCP

計算エピトープ研究のための標準的な Model Context Protocol サーバーです。 配列処理、免疫学的エビデンス、構造および化学分析、ドッキング、レビュー可能なエクスポートに対応する、型付きツール 46 種を呼び出せます。結果には来歴情報が付与されるため、実際のプロバイダーからの結果を、フィクスチャや合成デモと区別できます。

課題 · 対象ユーザー · ユーザーフロー · はじめに · 3D の結果 · 全 46 種のツール · コントリビューション

重要

ImmunoGraph がサポートするのは計算研究であり、臨床的または実験的な検証ではありません。予測されたエピトープ、ドッキングポーズ、スコア、またはエクスポートされた 3D モデルは、結合、ワクチンの有効性、安全性を証明するものではありません。フィクスチャと合成結果はデモであり、その旨が明示されています。

課題

エピトープ研究のワークフローでは、配列処理、免疫予測、HLA カバレッジ、構造データベース、分子の準備、ドッキング、相互作用分析、レポート作成など、さまざまな種類のソフトウェアを扱います。各ステップで、入力形式、実行環境、科学的前提が異なります。LLM や研究アプリケーションがこれらを連携させる場合、さらに、どの入力と手法から各結果が得られたかを追跡する必要があります。出所が不明なスコアや 3D ビューは、誤解されやすいものです。

ImmunoGraph は、これらのステップに対応する型付きインターフェースを MCP ホストに提供します。ホストは個々のツールを検出して呼び出し、その出力を次の処理に渡し、明示的な出所ラベルやエクスポートされたバイト列を確認できます。これにより、レビュー可能な計算ワークフローのための独自の連携コードを減らせます。ただし、科学的判断に取って代わるものではなく、予測を単独で検証するものでもありません。

対象ユーザー

対象ユーザー	典型的な用途
計算免疫学およびワクチン研究チーム	候補の探索に向けて、配列、MHC、B 細胞、カバレッジ、構造に関するエビデンスをまとめてレビューします
構造バイオインフォマティクスおよびメディシナルケミストリーの研究者	座標を準備し、設定済みのドッキングツールを実行して、ポーズや接触を確認し、実際のファイルをエクスポートします
LLM 研究アシスタントを構築する開発者	各ステップに個別のアダプターを書く代わりに、標準 MCP を通じて型付きの科学的処理を公開します
教育者および再現性のレビュー担当者	フィクスチャでワークフローを実演し、手法の適用範囲、来歴、成果物を確認します

出力は研究と教育を目的としています。臨床上の判断、有効性の主張、実験的な検証には、独立した手法とエビデンスが必要です。

できること

探索	分析	レビューと共有
FASTA の検証、ペプチドウィンドウの生成、PDB 構造と PubChem 化合物の取得	有効化された IEDB 予測ツールの呼び出し、コンセンサスとカバレッジの計算、インストール済みの場合は RDKit、FreeSASA、fpocket、Meeko、Vina、PLIP の実行	呼び出し元が提供するエビデンスの順位付け、CSV、PDB、SDF、PDBQT、ドッキングポーズ、Mol* またはドッキングビューアー、チェックサム付き研究用 ZIP のエクスポート

これは46 個の独立したライブデータプロバイダーではなく、46 個のツールを備えた 1 つのサーバーです。各ツールは個別に呼び出せます。クライアントはワークフローの構築時に、呼び出し間で結果を渡します。

ユーザーフロー

研究者は、MCP 対応のチャットまたはアプリケーションで作業します。クライアントが呼び出しを選択し、エビデンスを引き継ぎます。ImmunoGraph は要求された各操作を実行し、型付きの結果を返します。

ステップ	研究者またはクライアントの操作	ImmunoGraph の応答
1. 接続	stdio サーバーを MCP ホストに追加し、研究に必要なライブコネクターだけを有効にします	ホストが 46 個のツールとその入力スキーマを検出します
2. 入力の定義	FASTA 配列と研究基準を指定します	validate_sequence が配列を検証してハッシュ化し、generate_candidate_peptides が実際のペプチドウィンドウを列挙します
3. エビデンスの収集	利用可能な MHC-I/II、B 細胞、集団、その他の計算を要求します	各呼び出しはスコア、またはソースの状態を含む構造化された失敗結果を返します。ライブ予測ツールには、設定済みのサービスが必要です
4. 優先順位付け	選択したエビデンス、しきい値、カバレッジデータをスコアリングツールと制約ツールに渡します	正規化スコア、コンセンサス、除外項目、候補の順位は、提供されたエビデンスに応じて決まります
5. 構造の調査	必要に応じて PDB／化合物データを取得し、アクセシビリティ、ポケット、リガンド、ドッキング、接触の各ツールを実行します	科学計算ランタイムがインストールされている場合、座標ベースの出力、ポーズファイル、3D ビューアー HTML、分析データが得られます
6. レビューとエクスポート	ソースラベルとパラメーターを確認してから、レポート、CSV、トレース、研究用 ZIP を要求します	個別に保存および検証できる、長さと SHA-256 ハッシュ付きのファイルバイト列

このフローはモジュール式です。すべての段階を実行しなくても、ユーザーは 1 つのツールを呼び出せます。run_agentic_workflow は、呼び出し元が指定した承認済みのツール呼び出しを実行します。そうした呼び出しがない場合は、完全な研究を暗黙に開始するのではなく、計画を返します。正確な実行範囲については、アーキテクチャとツールの実態マトリックスを参照してください。

はじめに

公開リリースをインストールする

Node.js 20 以降が必要です。バージョン付きの tarball は GitHub でホストされ、npm でインストールできます。immunograph-mcp という名前は、まだ npm レジストリに公開されていません。

npm install --global https://github.com/Ajey95/immuno-graph/releases/download/v0.2.1/immunograph-mcp-0.2.1.tgz

インストールしたコマンドを、stdio サーバーに対応する MCP ホストに登録します。

{
  "mcpServers": {
    "immunograph": {
      "command": "immunograph-mcp"
    }
  }
}

サーバーは stdio 上で MCP を通信するため、ホスト経由で起動してください。ホストがグローバルにインストールされたコマンドを見つけられない場合は、その絶対パスを設定してください。GitHub リリースには、ソースと tarball の SHA-256 チェックサムも含まれています。ダウンロードした公開 tarball は、そのチェックサムと一致しました。

公開コンテナーを実行する

公式 MCP Registry のエントリーは、公開 OCI イメージを参照しています。ローカルの stdio ホストでは、次のように使用します。

{
  "mcpServers": {
    "immunograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/ajey95/immuno-graph:0.2.1",
        "node", "dist/index.js"
      ]
    }
  }
}

このコンテナーは、保護設定を適用した Streamable HTTP にも /mcp で対応しています。必須のセキュリティ設定については、HTTP デプロイを参照してください。

ソースからビルドする

git clone https://github.com/Ajey95/immuno-graph.git
cd immuno-graph
npm ci
npm run check
npm start

npm start は stdio MCP を提供します。npm run check は、ソフトウェアテスト、ビルド、全ツールの呼び出し例、セマンティック監査、依存関係の監査、パッケージのドライランを実行します。ホストでは、command に node を指定し、args に dist/index.js の絶対パスを指定してください。

仕組み

flowchart LR
    A["FASTA · PDB · SMILES"] --> H["MCP host"]
    H --> S["ImmunoGraph<br/>46 typed tools"]
    S --> D["Local calculations<br/>and exact fixtures"]
    S --> L["Optional live<br/>connectors"]
    D --> R["Results + provenance"]
    L --> R
    R --> O["Reports · 3D files · ZIP"]

どのツールを呼び出すかはホストが選択します。ImmunoGraph は型付き入力を検証し、ハンドラーを実行して、実行メタデータとソースラベルを含む構造化された成功データまたは失敗データを返します。サーバーが完全な研究を暗黙に実行したり、フィクスチャの値を実際の証拠として扱ったりすることはありません。トランスポートとモジュールの詳細については、アーキテクチャを参照してください。

技術設計

懸念事項	実装	重要な理由
クライアント間の相互運用性	公式 MCP SDK。ローカルホストには stdio、デプロイにはガード付き Streamable HTTP を使用	検出可能な単一のツール契約を、MCP 対応クライアント間で利用できます
入力と結果の契約	Zod スキーマ、型付きハンドラー、構造化された MCP の結果、明示的なエラー	クライアントは引数を検証し、プログラムからエラーを処理できます
科学的な来歴	ソースのステータス、メソッド／実行メタデータ、バージョン管理された完全一致フィクスチャ	レビュー担当者は、設定されたライブ処理とオフラインのデモンストレーションを区別できます
エクスポートの整合性	インラインのアーティファクトバイト、バイト長、SHA-256 ダイジェスト	ホストは実際の PDB／PDBQT／CSV／ZIP ファイルを保存し、検証できます
運用上の境界	オプションのコネクターとローカルの科学計算用バイナリを個別に設定	プロバイダーが見つからない場合は明示的に失敗するか、要求されたラベル付きフォールバックのみを使用します

レジストリエントリーは公開済みの OCI イメージを指します。オプションの科学計算用バイナリ、モデルのダウンロード、サードパーティサービスの利用可否は、引き続き個別のランタイム要件です。

研究ワークフロー

flowchart LR
    FASTA["Protein FASTA"] --> V["Peptide windows"]
    V --> E["Immune evidence"]
    E --> R["Constraints + ranking"]
    R --> X["Reviewable exports"]
    E -.->|Optional| S["Structure + docking"]
    S -.-> X

これらは個別の MCP 呼び出しです。ランキングとレポートは、クライアントが提供するエビデンスに依存します。ライブ予測が無効の場合、新しい任意のタンパク質について科学的な結合結果が自動的に得られることはありません。

ドッキングと 3D ファイル

設定されたライブツールでは、装飾用モデルではなく実際の座標を使用できます。

flowchart LR
    P["Protein PDB"] --> R["Meeko receptor<br/>PDBQT"]
    L["Compound / SMILES"] --> M["RDKit + Meeko ligand<br/>SDF + PDBQT"]
    R --> V["AutoDock Vina"]
    M --> V
    V --> POSE["Pose PDBQT<br/>complex PDB"]
    POSE --> VIEW["3D viewer HTML"]
    POSE --> PLIP["PLIP contacts"]
    POSE --> ZIP["Research ZIP"]

実際の 3D 結果

1IEP + イマチニブ：エクスポートされた Vina の最上位ポーズ。 この図は、LIVE_ONLY の MCP ドッキング呼び出しで生成された保存済み複合体 PDBからレンダリングされています。パネル A はタンパク質の Cα 座標をトレースしてリガンドを示し、パネル B は 5 Å 以内にあるリガンドとタンパク質の原子を示しています。レンダリングスクリプトを使うと、これらの座標から画像を再現できます。これはドッキング機能の例であり、エピトープ候補ではありません。ポーズスコアは計算による推定値であり、測定された親和性ではありません。

1UYD + PubChem CID 2244：計算された 3 つのポーズ。 この図はライブドッキング研究 ZIPから作成されています。この ZIP には、受容体、リガンド、Vina のポーズ、複合体、画像が含まれています。実行の来歴と概要にはソースと生成された 9 つのポーズが記載されており、画像にはそのうち 3 つが表示されています。吹き出しは座標から計算した距離を示します。破線の極性接触は推定された幾何学的配置であり、実験的に確認された結合ではありません。

ライブドッキングガイドでは、入力、ランタイム要件、サンプルファイル、エクスポートされたポーズチェーンの検証について説明しています。インタラクティブな 3D ビューアーは返された座標データを可視化しますが、どちらの画像も実験的な結合を証明するものではありません。

検証可能な出所情報

結果パス	意味	科学的な用途
LIVE	設定済みの外部プロバイダーまたはローカルの科学計算ランタイムが、指定された入力を処理しました	手法、パラメーター、制限事項を確認してください
FIXTURE	承認済みの完全一致するオフライン再生です	デモンストレーション専用
SYNTHETIC	デモツールが生成した決定論的な教育用データです	デモンストレーション専用
呼び出し元が指定した計算	ランキング、制約、キャリブレーション、レポートが、提供されたエビデンスを変換します	そのエビデンスの品質と出所に依存します

46-tool reality matrixには、各ツールが実際に計算または取得する内容と、実施された検証が記録されています。特に、このリリースではGraphBepiはフィクスチャ専用です。Parkerは親水性の計算であり、有効化した場合にサポートされるライブB細胞オプションはBepiPred-3.0です。

ツールカタログ

グループ	ツール数	例
予測	6	FASTA検証、ペプチドウィンドウ、MHC-I/II、B細胞
エビデンスと優先順位付け	9	スコア正規化、コンセンサス、HLAカバレッジ、ランキング
制約	5	重複範囲、重複データ、しきい値、候補ルール
構造	7	RCSB/AlphaFold、アクセシビリティ、ポケット、Mol*
化学	5	PubChem、RDKit記述子、リガンド調製
ドッキング	5	受容体調製、Vina、ポーズクラスタリング、PLIP
レポートとユーティリティ	9	CSV／レポートデータ、説明、ワークフロートレース、ZIP
合計	46	1つのMCPサーバー

ツールカタログ全体と入力コントラクトを参照してください。ツール呼び出しを試すには、次の入力でvalidate_sequenceを実行します。

{
  "fasta": ">protein\nACDEFGHIK",
  "profileVersion": "mvp-v1.0"
}

正規化された配列、長さ、SHA-256識別子、または構造化された検証エラーが返されます。

ライブコネクターを有効にする

ほとんどのライブコネクターはデフォルトで無効になっています。MCPサーバーの環境変数でフラグを設定し、該当するプロバイダーのランタイムをインストールするか、そのネットワークエンドポイントへのアクセスを許可してください。.env.exampleに設定が記載されています。

機能	スイッチ	追加要件
IEDB MHC-I/II、BepiPred-3.0、集団カバレッジ	IEDB_LIVE_ENABLED、IEDB_BCELL_ENABLED、IEDB_POPULATION_COVERAGE_ENABLED	該当するIEDB APIへのアクセス
RCSB PDB、AlphaFold DB、PubChem	RCSB_PDB_ENABLED、ALPHAFOLD_DB_ENABLED、PUBCHEM_ENABLED	プロバイダーへのネットワークアクセス
RDKit、Meeko、FreeSASA、fpocket	環境設定を参照	Pythonパッケージまたはネイティブバイナリのインストール
AutoDock VinaとPLIP	VINA_ENABLED、PLIP_ENABLED	ランタイムがインストールされ、有効な座標入力があること

必要なプロバイダーまたはバイナリが利用できない場合、ツールは明示的な失敗を返すか、要求されたポリシーに従ってフォールバックであることを明示した結果を返します。npm tarballとコンテナーには、オプションの科学計算バイナリやモデルのダウンロードは含まれていません。

HTTPデプロイ

npm run start:httpはローカルでhttp://127.0.0.1:3000/mcpを提供し、ヘルスチェックにはGET /healthを使用します。リモートエンドポイントでは、HOST=0.0.0.0、長いIMMUNOGRAPH_API_KEY、厳密なIMMUNOGRAPH_ALLOWED_HOSTSとIMMUNOGRAPH_ALLOWED_ORIGINSを設定し、イングレスでTLSを終端してください。イメージはデフォルトでHTTPエントリーポイントを実行します。イメージを公開しても、マネージドエンドポイントは作成されません。デプロイ前にSECURITY.mdをお読みください。

検証と適用範囲

CI ワークフローでは、Node.js 20 および 22 を使用して Windows と Linux をチェックします。標準的な MCP クライアントを使用して、ドキュメントに記載されている 46 個すべての例を実行しています。セマンティック監査では、計算、来歴、成果物のハッシュをチェックします。v0.2.1 コンテナーのリリース実行では、Docker stdio、保護された HTTP、およびテスト用 TLS イングレスを通じて、46 個のツールの検出と実際の呼び出しをテストしました。プロトコル監査では、すべてのツールがパラメーターの説明と構造化された結果スキーマを提供していることもチェックします。これらのチェックで確認できるのはソフトウェアの動作とパッケージングであり、すべての科学的手法の正確性やサードパーティーサービスの継続的な可用性ではありません。

エピトープ研究ではよく知られているように、Grifoni et al.（2020）やFerreira et al.（2021）などの研究では、配列解析、予測、保存性など、さまざまなツールから得られる証拠を組み合わせています。ImmunoGraph を使うと、計算処理間の受け渡しを確認しやすくなりますが、独立したレビューと実験による検証は引き続き必要です。

貢献とサポート

貢献と再現可能なバグ報告を歓迎します。CONTRIBUTING.mdを確認し、issueを作成してください。セキュリティに関する懸念はSECURITY.mdから報告してください。リリース済みの変更はCHANGELOG.mdに記載されています。ImmunoGraph はMIT ライセンスのもとで利用できます。