pdb2reaction MCP サーバー

pdb2reaction-mcp（エイリアス p2r-mcp）は、MCP サーバーであり、MCP に対応した任意のエージェントが stdio 上の JSON-RPC を介して すべての pdb2reaction CLI サブコマンドを駆動できるようにします。Claude Desktop / Claude Code / Cursor / Codeium のほか、公式の Python または TypeScript MCP SDK で 構築したカスタムエージェントからも利用できます。

インストール

pip install "pdb2reaction[mcp]"

これにより mcp[cli] 依存関係が追加され、2 つのコンソールスクリプト pdb2reaction-mcp および p2r-mcp（エイリアス）が登録されます。

ツール

18 個のツールがあり、それぞれが CLI サブコマンドに 1 対 1 で対応します。各ツールは次のフィールドを持つ構造化された dict を返します。

  • schema_version: エンベロープのバージョン。クライアントは各レスポンスの値を読み、対応するバージョンと照合してください。Python では pdb2reaction.mcp._runner.MCP_SUBCMD_RESULT_SCHEMA_VERSION も照合に利用できます。

  • status: ok | failed | summary_missing | summary_parse_error | summary_run_mismatch

  • exit_code: サブプロセスの終了コード

  • out_dir: stage tool の管理ディレクトリ。成功した helper tool では null

  • summary: パース済みの summary.json。管理 summary を持たない成功 helper では空 object

  • stderr_tail / stdout_tail: プロセス出力の末尾約 60 行

  • hint: CLI エラーメッセージから抽出した ; recover: <hint> サフィックス（存在する場合）

  • argv: 実行された完全な argv（再現性のため）

  • run_id: 各 subprocess 呼び出しの UUID。summary の ID が一致しない場合は summary_run_mismatch と空の summary を返します

product CLI alias は MCP server と同じ Python interpreter の python -m pdb2reaction に固定され、import 済み package root を child PYTHONPATH の先頭へ置きます。child は caller の current working directory を維持するため、relative scientific input path の意味も変わりません。

構造化されたエラーエンベロープ

サブコマンドが失敗した場合、パース済みの summary（または同階層の result.json）に拡張エラーエンベロープが含まれます。これにより、エージェントはテキストをパースせずに例外クラスの階層をパターンマッチできます。

  • error: 元の例外の str(exc)

  • error_type: 例外クラス名（例: "OptimizationError"）

  • error_class_chain: MRO のクラス名（例: ["OptimizationError", "RuntimeError", "Exception", "BaseException"]）

  • error_module: 例外クラスが定義されているモジュール

  • error_label: 上位レベルの CLI ステージラベル

ステージランナー

MCP ツール

CLI サブコマンド

目的

optimize_geometry

pdb2reaction opt

単一の分子構造を最適化

find_transition_state

pdb2reaction tsopt

TS 探索（RS-P-RFO / Dimer / TRIM / RS-I-RFO）

run_irc

pdb2reaction irc

TS 構造からの IRC 積分

compute_frequencies

pdb2reaction freq

振動解析 + 熱化学

run_single_point

pdb2reaction sp

MLIP の一点エネルギー + 原子間力（+ オプションで Hessian）

スキャン / 経路 / パイプライン

MCP ツール

CLI サブコマンド

目的

scan_1d / scan_2d / scan_3d

pdb2reaction scan / pdb2reaction scan2d / pdb2reaction scan3d

拘束駆動の距離スキャン

optimize_path

pdb2reaction path-opt

2 端点間の MEP 最適化

search_paths

pdb2reaction path-search

再帰的な反応経路探索

run_full_pipeline

pdb2reaction（all サブコマンド）

エンドツーエンド: extract → MEP → TS → IRC → freq → DFT

run_single_point_dft

pdb2reaction dft

gpu4pyscf による一点 DFT

構造 / I/O ヘルパー

MCP ツール

CLI サブコマンド

目的

extract_active_site

pdb2reaction extract

リガンド周辺の球を切り出す

add_element_info

pdb2reaction add-elem-info

PDB の元素列を修復

fix_altloc

pdb2reaction fix-altloc

PDB の代替位置（altloc）を解決

plot_trajectory

pdb2reaction trj2fig

エネルギープロファイル図（デフォルトは PNG。SVG/PDF/HTML/CSV も可）

plot_energy_diagram

pdb2reaction energy-diagram

カテゴリ別エネルギーダイアグラム

detect_bond_changes

pdb2reaction bond-summary

2 つの PDB 間の結合変化の差分

電荷と順序付き入力

charge と ligand_charge を公開する tool では、PDB の残基情報から導出する 場合は charge を省略して per-resname ligand_charge mapping を渡します。 residue context のない XYZ は明示的な total charge が必要です。有効な GJF header は charge/multiplicity を供給します。両方を指定した場合は明示的な charge が優先します。

search_paths は reactant の input_pdb と product_pdb を必要とし、順序付き intermediate は intermediate_pdbs に渡します。1D/full-pipeline の staged scan では最初の literal を scan_lists、後続を additional_scan_stages に入れます。

オプトインの IRC 収束ガード

run_irc（CLI: pdb2reaction irc）は irc_pos_def: bool を受け付けます。これにより IRC 収束には、質量重み付き Hessian が正定値であることが追加で要求され、rms のみの 基準が局所極小に到達する前に成功と判定してしまう IRC の「ショルダー」での偽収束を 防ぎます。デフォルトは None（rms のみ、従来動作）です。

run_irc は step_size と never_stop も受け付けます。branch が数 frame で 停止する場合はまず step_size を小さくします（典型値 0.05）。 never_stop=True は gradient/energy endpoint criteria を無視して max-cycle まで 追跡しますが、数値・積分 failure は停止します。run_full_pipeline は同じ制御を irc_step_size / irc_never_stop として転送し、TS recovery 用の flatten と refine_path も公開します。

find_transition_state（CLI: pdb2reaction tsopt）は --opt-mode により 代替の TS オプティマイザも公開しています。

  • opt_mode="trim" — Helgaker (1991) の trust-region image-minimization TS opt

  • opt_mode="rsprfo" — Banerjee (1985) の restricted-step P-RFO TS opt

クライアント設定

クライアントごとに設定スキーマは異なります。次のスニペットはトップレベルの mcpServers オブジェクトを受け付けるクライアント用です。設定ファイルと スキーマは各クライアントの MCP ドキュメントで確認してください。

  • Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） / %APPDATA%\Claude\claude_desktop_config.json（Windows）

  • Cursor — ~/.cursor/mcp.json

  • その他のクライアント — 各クライアント自身の MCP サーバードキュメントを参照

{
  "mcpServers": {
    "pdb2reaction": {
      "command": "pdb2reaction-mcp",
      "args": []
    }
  }
}

明示的な環境変数の上書き（PATH / CUDA_VISIBLE_DEVICES）を含む完全な例は examples/mcp_client_config.json を参照してください。

VS Code は .vscode/mcp.json でトップレベルの servers オブジェクトを使います （VS Code MCP 設定リファレンス）。

{
  "servers": {
    "pdb2reaction": {
      "command": "pdb2reaction-mcp",
      "args": []
    }
  }
}

カスタム Python MCP クライアント

import asyncio

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(command="pdb2reaction-mcp")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "optimize_geometry",
                arguments={
                    "input_pdb": "r.pdb",
                    "charge": -1,
                    "max_cycles": 50,
                },
            )
            print(result.content)

asyncio.run(main())

サンドボックス / 安全性に関する注意

  • MCP サーバーは呼び出し元の環境の PATH、conda 環境、CUDA セットアップを継承します。 長時間実行されるツール（opt / tsopt / irc）は pdb2reaction CLI をサブプロセスで 起動するため、エージェントは各ツール呼び出しで timeout_seconds を設定し、 暴走する計算を制限してください。

  • stage tool の出力ファイルは out_dir キーワード引数の配下に置かれます（デフォルトは一意の tempfile.mkdtemp(prefix="p2r_mcp_<subcmd>_…") で、同時並行のエージェント呼び出しが 衝突しないようになっています）。

  • helper tool は out_dir を持たず、指定された出力 path へ書き込みます。expert extra_args は追加の非管理 CLI 動作を要求できますが、typed output path、 --out-dir、管理された --out-json/--no-out-json toggle は上書きできません。 filesystem policy を適用するときは返却 argv を確認してください。

  • サーバーは ~/.bashrc / ログイン環境を変更したり、ソフトウェアをインストールしたりしません。すべての MLIP の重みや PDB 入力は あらかじめディスク上に存在している必要があります。