protein-mcp-server

公開ホスト型サーバー: https://protein.caseyjhand.com/mcp

ツール

構造研究の一連の流れをカバーする7つのツール — 発見、取得、ホモログ検索、リガンド追跡、比較、コーパスのプロファイリング、アノテーション — を、実験（PDB）および予測（AlphaFold）構造に対して単一のインターフェースから提供します：

protein_search_structures

RCSB Search v2を介した実験（PDB）と予測（計算モデル）構造にわたる統合検索。

• 自由テキスト、タンパク質配列（mmseqs2類似性検索をトリガー）、および生物種/手法/解像度フィルター

• content_type は検索範囲を experimental、predicted、または all に限定 — デフォルトの all は両方の世界の真の和集合であり、計算モデルがPDBエントリと並んで表示されます

• すべてのヒットはその source を明示します。実験ヒットはタイトル、手法、解像度、生物種で補完され、計算モデルはIDから解析されたUniProtアクセッションを保持します

• オプションの facets は、追加呼び出しなしでヒットとともに手法/生物種/リリース年の内訳を返し、各次元について値を持たないマッチ数を報告します。各次元は一度だけ指定可能です

• チェーンヒットIDをそのまま protein_get_structure に渡せます

protein_get_structure

メタデータと座標ファイルのURLを備えた構造を取得し、source に基づいてプロバイダー間で解決します。

• source: experimental はPDBエントリIDを受け取り、1回のRCSB GraphQL呼び出しでバッチ処理します。また、検索が返す計算モデルID（AF_* / MA_*）も解決し、これらはモデリングプロバイダーに帰属する source: predicted として返されます

• source: predicted はUniProtアクセッションを受け取り、pLDDT/PAE信頼度付きのAlphaFoldモデルを返します

• source: best_available はUniProtアクセッションを受け取り、最良の統合モデル（実験モデルが存在すればそれを、なければ最良の予測）を返します

• IDごとの部分成功 — 解決されなかったIDはバッチレベルのエラーではなく failed[] にリストされます

• include_coords は座標コンテンツをインライン化します。バッチが応答予算を超えた場合は構造ごとのサイズ概要を返すため、特定の構造に対して sections: [ids] を指定して再呼び出しできます

• すべての応答には、上流データのライセンスと引用を明記した attribution ブロックが含まれます（上流データライセンス を参照）

protein_find_similar

配列またはフォールドによって、構造的または進化的に関連するタンパク質を検索します。

• by: sequence は同期RCSB mmseqs2検索を実行。by: structure は実験・予測データベースに対する非同期Foldseek検索を実行

• 生の1文字配列、PDB ID、またはUniProtアクセッションからクエリ可能

• Foldseekのターゲットはデフォルトで pdb100 + afdb50。databases で上書き可能（例: afdb-swissprot、BFVD）

• ポーリング予算を超えた非同期ジョブは ticketId 付きで status: computing を返します — 再送信する代わりに ticket_id にその値を設定して再呼び出しすると、同じジョブをポーリングできます

• 各ヒットは、それが由来するエンジンとソースデータベースを明示します

protein_track_ligands

PDB全体にわたるリガンド発見と結合部位解析。

• mode: find_ligand は名前または化学式を、化学式、分子量、SMILES、InChIKey付きの化学コンポーネントIDに解決

• mode: structures_with_ligand は正確なコンポーネントIDでリガンドを含むPDBエントリを返す

• mode: binding_site は構造内のリガンドのポケットを裏打ちするタンパク質残基を接触距離付きで返す

• 結合部位は実験データのみ — 堆積された座標から計算されます（予測モデルには結合リガンドがありません）

protein_compare_structures

RCSB Structural Comparisonサービスを介した複数構造（設定された PROTEIN_MAX_COMPARE_STRUCTURES 上限まで）の構造アライメント。

• 手法: tm-align、fatcat-rigid、fatcat-flexible

• reference: first はすべての構造を最初の構造にアライメント。reference: all_pairs は完全なペアワイズ行列を計算

• オプションの構造ごとの chain はアライメントを単一のチェーンに限定

• structures[] 内で繰り返される構造は一度だけ比較されます — 繰り返しは自己アライメントとミラーリングされたペアを追加するだけで、再開メカニズムが元のものと区別できません

• 各ペアは独立した非同期ジョブであり、並行性上限とペアごとの部分成功でファンアウトされます — 予算が尽きても計算中のペアはジョブ uuid 付きで status: computing を返し、失敗したペアは他のペアを沈めることなくその行を劣化させます

• 以前の応答の pairs[] からコピーした一致する { a, b, uuid } エントリを resume[] に設定して再呼び出しすると、再送信する代わりに計算中のペアのジョブをポーリングできます

• ペアごとにTM-score、RMSD、アライメント済み残基数を返し、さらに modeledResidues と coverage を返します — それぞれ [a, b] タプルで、coverageはその構造自身のモデル化残基数に対する0〜100のパーセンテージです

protein_analyze_collection

オプションのスコープクエリに基づいてPDBを分布とトレンドにプロファイリング — RCSBのサーバーサイドファセットエンジンを基盤としています（1回の呼び出し、コンパクトなバケット、行のプルなし）。

• method、organism、polymer_type、resolution、release_year、または molecular_weight でグループ化

• 内訳用に1つの group_by 次元、またはクロス集計用に2つの異なる次元（最初が2番目をネスト）。繰り返しの次元は拒否されます

• interval は値ヒストグラムのビン幅、または日付ヒストグラムの期間（year / month / quarter）を設定

• 自由テキストの query、organism、method、または max_resolution でスコープ。content_type は構造の世界を選択

• bucket_limit は応答ごとではなく次元レベルごとのバケットを制限します — クロス集計では親次元と各親バケット内のネストされた子に別々に適用されるため、最大 bucket_limit × (1 + bucket_limit) 個のバケットが返されます。各レベルは独自の切り捨てをフラグし、bucketsReturned は実現された合計を提供します

• すべての次元は missingValueCount を報告します — スコープ内でその属性に値を持たないマッチであり、したがっていかなるバケットにも入りません（resolution の内訳はNMRエントリをカバーせず、method も resolution も計算モデルをカバーしません）

protein_get_annotations

タンパク質の配列および機能アノテーション。

• UniProtの特徴（ドメイン、結合部位、PTM）と自然配列変異

• 関連するGO用語付きのInterProドメイン/ファミリー帰属（Pfam、PROSITE、…）

• UniProtアクセッションを直接指定するか、PDB IDを指定 — 構造の配列クロスリファレンスを介してUniProtアクセッションに解決されます

• マルチチェーンPDBエントリは複数のアクセッションにマッピングされる場合があります。デフォルトは決定論的な最下位オーサーチェーンの選択で、代替案は ambiguity の下にリストされます。chain（オーサーチェーンID、例: A）を渡すと特定のチェーンを選択できます

• include は取得するアノテーションクラスをスコープします: features、domains、variants、または all

• すべての応答には、上流データのライセンスと引用を明記した attribution ブロックが含まれます（上流データライセンス を参照）

Related MCP server: UniProt MCP Server

リソース

すべてのリソースデータはツールからもアクセス可能です — pdb://{entry_id} は source: experimental の protein_get_structure をミラーし、af://{uniprot} は source: predicted のそれをミラーします。多くのMCPクライアントはツールのみでリソースを表示しません。サマリーはツールを通じて引き続きアクセス可能です。

機能

@cyanheads/mcp-ts-core をベースに構築:

• 宣言的なツール・リソース定義 — プリミティブごとに単一ファイル、フレームワークが登録と検証を処理

• 統合されたエラーハンドリング — ハンドラーが throw し、フレームワークが捕捉・分類・整形

• プラグ可能な認証: none、jwt、oauth

• 交換可能なストレージバックエンド: in-memory、filesystem、Supabase、Cloudflare KV/R2/D1

• 構造化ログとオプションの OpenTelemetry トレーシング

• STDIO および Streamable HTTP トランスポート

タンパク質特化:

• 実験構造 (PDB) と予測構造 (AlphaFold / 3D-Beacons) を統合した単一のフェデレーションサーフェス — 検索・取得・比較は両方のユニバースを同一に扱う

• すべての上流プロバイダーでキーレス — RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro、Foldseek で API キーの準備は不要

• コーパス分析は RCSB のファセットエンジン上でサーバーサイド実行 — 分布・ヒストグラム・クロス集計を1回の呼び出しで実現、行のプルも SQL ワークスペースも不要

• 非同期アライメントと Foldseek ジョブは制限付き予算内でポーリングし、ブロックせずにジョブチケット (ticketId / ペアごとの uuid) を返す — ticket_id または resume[] エントリで再呼び出しすると、再送信ではなく同じジョブをポーリング

エージェント向け出力:

• すべてのレスポンスに来歴情報 — 各ヒットは source (experimental / predicted)、それを生成したエンジンとデータベース、有効クエリ / 総件数のエコーを保持し、エージェントがカバレッジを推論可能

• グレースフルな部分失敗 — バッチ取得とペアワイズ比較は、リクエスト全体を失敗させるのではなく、項目ごとの行 (failed[]、ペアごとの status) を返し、それぞれに実行可能な回復テキストを付与

• 判別可能な出力契約 — 型付きの source と status のユニオン、再開チケット付きの computing 結果、予算超過の概要により、呼び出し側は文字列解析ではなくデータに基づいて分岐可能

はじめに

公開ホステッドインスタンス

公開インスタンスが https://protein.caseyjhand.com/mcp で利用可能です — インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントから接続できます:

{
  "mcpServers": {
    "protein": {
      "type": "streamable-http",
      "url": "https://protein.caseyjhand.com/mcp"
    }
  }
}

セルフホスト

以下を MCP クライアントの設定ファイルに追加してください。API キーは不要です — すべての上流プロバイダーはキーレスです。

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用 (Bun は不要):

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用:

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-mcp-server:latest"]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.3.2 以上 (または Node.js v24+)。

• アカウントや API キーは不要 — RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro、Foldseek はすべて公開・キーレスです。

インストール

1. リポジトリをクローン:

git clone https://github.com/cyanheads/protein-mcp-server.git

2. ディレクトリに移動:

cd protein-mcp-server

3. 依存関係をインストール:

bun install

設定

すべての上流プロバイダーはキーレスであるため、サーバーは設定なしでそのまま動作します。以下の変数はすべてオプションです。

プロバイダーのベース URL 上書きとチューニング上限の完全なリストは .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドと実行:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• チェックとテストの実行:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t protein-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server

Dockerfile はデフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、ログは /var/log/protein-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます — 省略するには --build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構造

開発ガイド

開発ガイドラインとアーキテクチャルールについては CLAUDE.md/AGENTS.md を参照してください。要約:

• ハンドラーは throw し、フレームワークが捕捉 — ツールロジックに try/catch は不要

• リクエストスコープのログには ctx.log、テナントスコープのストレージには ctx.state を使用

• 新しいツールとリソースは src/mcp-server/*/definitions/index.ts のバレルを介して登録

• 外部 API 呼び出しをラップ: 生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落フィールドを捏造しない

コントリビューション

Issue とプルリクエストを歓迎します。提出前にチェックとテストを実行してください:

bun run devcheck
bun run test

上流データのライセンス

構造・アノテーションデータは公開の上流データベースから取得され、それぞれ独自のライセンスが適用されます。protein_get_structure と protein_get_annotations は、すべてのレスポンスに attribution ブロックを付与します — その特定のレスポンスに貢献した各ソースのライセンス、引用、ホームページが含まれるため、帰属義務はこのドキュメントだけでなく、データとともに下流のコンシューマーへ伝搬します。CC BY / CC BY-SA ソースは再配布時の帰属表示が必要です。CC0 ソースは引用のみ (帰属は推奨、必須ではありません)。

best_available は 3D-Beacons を通じて予測モデルを統合するため、attribution ブロックは実際に貢献したプロバイダー (AlphaFold DB、SWISS-MODEL、BFVD など) をクレジットします。キュレーションされたライセンスエントリを持たないプロバイダーには、捏造されたライセンスではなく、3D-Beacons に戻る See provider terms フォールバックが付与されます。InterPro 独自のドメイン/ファミリー分類は CC0 ですが、それに付随する GO タームは別途 CC BY 4.0 であり、実際に貢献した場合のみそれぞれ独立してクレジットされます。各ソースの完全な引用は、関連するツールレスポンスの attribution ブロックに含まれます。これは上流の データ ライセンスを対象としています — サーバー自身のコードは別途ライセンスされます (ライセンス を参照)。

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。