MaBoSS Boolean Network Simulator

MaBoSS MCP サーバー

Wave 2 integration guideでは、要約の読み出し、名前付きレートの編集、永続的な実行 ID、結果の上限設定、handoff 2.1 について説明しています。

MaBoSS サーバーは、モデルコンテキストプロトコル（MCP）を通じて、確率的ブールモデルの構築、設定、シミュレーション、解析、エクスポートを提供します。シミュレーションエンジンとしてpyMaBoSSを使用し、NeKo から MaBoSS、PhysiCell へと続く検証済みモデリングパイプラインに参加できます。

サーバーは Python パッケージ mcp-biomodelling-servers として配布され、stdio で通信します。

インストールと起動

3 つのバイオモデリングサーバーをすべてインストールします。

python -m pip install mcp-biomodelling-servers

インストール済みの MaBoSS サーバーを起動します。

mcp-maboss-server

または、分離された環境で実行します。

uvx --from mcp-biomodelling-servers mcp-maboss-server

サーバーは別途 MaBoSS 実行ファイルを必要としません。モデルの検証とシミュレーションには、pyMaBoSS とともにインストールされるコンパイル済みエンジン cmaboss を子 Python プロセスで使用するため、長時間のシミュレーションによってサーバーがブロックされることはありません。エンジンが受け付けないモデルを読み込むと、エンジンのメッセージとともに失敗します。

サポート対象の Python バージョン、MCP クライアントの完全な設定、ソースチェックアウト手順、共有ランタイムの動作については、リポジトリの READMEを参照してください。

セッションとモデルの状態

各モデルは MaBoSS セッションに属します。まず create_session() を呼び出し、返された session_id を保持して、複数のモデルがアクティブな場合は明示的に渡してください。session_id を省略すると、ツールはアクティブなデフォルトセッションを使用します。

• create_session は分離されたインメモリセッションを作成し、人が読みやすいラベルを付けることもできます。
• list_sessions は、アクティブなセッションと、それぞれがモデルまたはシミュレーション結果を保持しているかどうかを報告します。
• list_artifact_sessions は、以前のサーバープロセスが残したセッションアーティファクトを検出します。
• set_default_session は、session_id を省略した呼び出しで使用するセッションを選択します。
• delete_session はインメモリの状態と、デフォルトではそのアーティファクトファイルを削除します。

生成された BND、CFG、CSV、PNG、handoff ファイルは、サーバーのセッションごとの artifacts/<session_id>/ ディレクトリに保存されます。パスを推測するのではなく、list_generated_files() を使って解決済みパスを取得してください。

推奨される単独ワークフロー

単独の BNET モデルでは、次の順序で進めます。

1. create_session() を呼び出します。
2. bnet_to_bnd_and_cfg(bnet_path) で BNET を変換します。
3. 生成されたファイルを build_simulation() で読み込みます。
4. get_maboss_nodes() を呼び出し、返されたノード名のみを使用します。
5. update_maboss_parameters()、get_maboss_initial_state()、get_maboss_logical_rules() で現在の設定を確認します。
6. set_maboss_output_nodes(...) で、生物学的に意味のある出力を少数選択します。
7. 必要に応じて、パラメーター、初期状態の確率、または論理ルールを更新します。
8. run_simulation() を呼び出します。
9. get_simulation_result() で数値結果を読み取ります。
10. visualize_network_trajectories() で軌跡を描画します。
11. 必要に応じて、更新済みの BND/CFG ファイルまたは型付きの PhysiCell handoff をエクスポートします。

bnet_to_bnd_and_cfg() は output.bnd と output.cfg をセッションのアーティファクトディレクトリに書き込みます。パスを指定しない場合、build_simulation() はこれらのファイルを自動的に読み込みます。

表示可能な出力が N 個あるブールネットワークでは、最大 2^N 個の状態が生成される可能性があります。 run_simulation() の前に、必ず set_maboss_output_nodes() を呼び出してください。科学的な問いに必要な出力だけを選択することで、実行時間と結果のサイズをどちらも削減できます。

モデルの確認と設定

シミュレーションパラメーター

parameters 値を指定せずに update_maboss_parameters() を呼び出すと、読み込まれたモデルでサポートされているすべてのパラメーターを確認できます。変更する値だけを指定してください：

{
  "parameters": {
    "sample_count": 10000,
    "max_time": 100,
    "time_tick": 0.5,
    "thread_count": 4
  },
  "session_id": "SESSION_ID"
}

一般的なパラメーターは次のとおりです：

パラメーター	意味
sample_count	確率的軌跡の数
max_time	シミュレーションの時間範囲
time_tick	時間点を報告する間隔
discrete_time	離散時間の切り替え。0 または 1
thread_count	シミュレーションスレッドの数

このサーバーは、読み込まれた MaBoSS のバージョンで公開されているバックエンドパラメーターも受け付けます。不明なパラメーター名を指定すると、復旧可能なツールエラーが発生します。

出力ノード

まず get_maboss_nodes() を呼び出してから、空でないサブセットを指定してください：

{
  "output_nodes": ["Apoptosis", "Proliferation"],
  "session_id": "SESSION_ID"
}

初期状態の確率

変更する前に、get_maboss_initial_state() で既存の分布を確認してください。

1 つのノードには [P(OFF), P(ON)] を指定します：

{
  "nodes": "DNA_damage",
  "probDict": [0.2, 0.8],
  "session_id": "SESSION_ID"
}

複数のノードには、JSON ネイティブの状態／確率レコードを使用します。状態ベクトルの順序は nodes の順序と一致させ、各状態には 0 または 1 のみを含め、確率の合計は 1 になるようにしてください：

{
  "nodes": ["DNA_damage", "Growth_signal"],
  "probDict": [
    {"state": [0, 0], "probability": 0.4},
    {"state": [1, 0], "probability": 0.6}
  ],
  "session_id": "SESSION_ID"
}

列挙する状態ですべての組み合わせを網羅する必要はありませんが、状態は一意である必要があり、各ベクトルの長さは nodes と同じでなければなりません。

論理ルールと変異

• get_maboss_logical_rules は現在のブールルールを返します。selected_nodes が指定されていない場合、最大 100 ノードまで返します（それを超える場合は truncated で示されます）。rule_limitation は、カスタムレート式のためにルールだけでは切り替えを記述できないノードを示します。これらのノードは get_maboss_nodes で確認してください。
• change_maboss_rule は 1 つのノードのルールを置き換え、モデルの検証で変更が拒否された場合は以前のルールに戻します。
• get_maboss_mutations は、モデルに現在保存されている変異を報告します。
• simulate_mutation は、セッションのベースシミュレーションを変更せずに、変異体のコピーを実行します。

例：

{
  "nodes": ["TP53", "AKT"],
  "state": ["ON", "OFF"],
  "session_id": "SESSION_ID"
}

変異状態は ON、OFF、または WT です。指定したすべてのノードに単一の状態を適用するか、ノードの順序に合わせた状態リストを指定できます。

シミュレーションの実行と結果の読み取り

run_simulation() は、ワーカースレッドで読み込まれたモデルを実行し、pyMaBoSS の結果をセッションに保存して、MCP の進捗状況を報告し、空でない状態確率テーブルを result.csv に書き込みます。

get_simulation_result() は、次の両方を返します：

• モデルが読み取るための Markdown 形式の状態確率テーブル、および
• 数値の軌跡テーブルを含む、JSON ネイティブの構造化コンテンツ。

同じ Markdown 形式の結果は、maboss://session/{session_id}/result からも利用できます。

ネイティブの軌跡画像

run_simulation() の後に、次を呼び出します：

{
  "session_id": "SESSION_ID",
  "until": 50
}

visualize_network_trajectories で。

省略可能な until パラメーターは、表示するシミュレーション時間の上限です。有限の数値で、0 より大きい値である必要があります。省略すると、利用可能な軌跡全体をプロットします。

このツールは次の処理を行います：

• 軌跡の描画を pyMaBoSS の plot_trajectory(until=...) に委譲します。
• タイトなバウンディングボックスとパディングを使用して、軸の外側にある凡例が切り取られないようにします。
• PNG を MIME タイプ image/png の MCP ImageContent ブロックとして返します。
• セッション、時間範囲、アーティファクトのテキストと構造化メタデータを返します。
• 同じ PNG バイト列を、セッションのアーティファクトディレクトリ内の network_trajectory.png として保存します。

プロットをインラインで表示するには、MCP クライアントが画像コンテンツブロックのレンダリングに対応している必要があります。クライアントが結果のテキスト部分または構造化部分のみを表示する場合でも、保存されたアーティファクトは引き続き利用できます。

サーバー間の引き渡し

NeKo から MaBoSS へ

Boolean モデルが NeKo MCP サーバーから取得された場合は、import_neko_handoff(manifest_path) を優先して使用してください。このツールは次の処理を行います。

• neko-to-maboss マニフェストとアーティファクトのハッシュを検証します。
• 参照先の BNET を MaBoSS の BND ファイルと CFG ファイルに変換します。
• 変換後のノードセットを検証します。
• NeKo で宣言された出力ノードがあれば適用します。
• インポートがすべて正常に完了した後にのみモデルを読み込みます。
• 後続の PhysiCell へのハンドオフに備えて、NeKo の来歴を保持します。

マニフェストに出力ノードが宣言されていない場合は、モデルを実行またはエクスポートする前に set_maboss_output_nodes() を呼び出してください。

MaBoSS から PhysiCell へ

export_maboss_handoff(target_cell_type=...) を呼び出すと、整合性保護された maboss-to-physicell ハンドオフを作成できます。次の内容をスナップショットとして保存します。

• 現在の BND モデルと CFG モデル
• MaBoSS のパラメーターと選択された出力ノード
• オプションの、空でないシミュレーション結果 CSV
• 想定する PhysiCell の細胞型と生物学的コンテキスト
• インポート済みの場合は、上流の NeKo 系譜全体

単独の MaBoSS モデルでは biological_context を指定する必要があります。NeKo からインポートしたモデルでは、そのコンテキストを引き継ぐことができます。エクスポートでは既存のハンドオフアーティファクトの上書きが拒否されるため、保持するハンドオフごとに新しい artifact_prefix を選択してください。

単独の MaBoSS ファイルのみが必要な場合は、export_maboss_bnd_cfg() を使用してください。PhysiCell で型付きの科学的コンテキスト、整合性メタデータ、来歴が必要な場合は、export_maboss_handoff() を使用してください。

ツールリファレンス

カテゴリ	ツール
セッション	create_session, list_sessions, list_artifact_sessions, set_default_session, delete_session
インポートと読み込み	import_neko_handoff, bnet_to_bnd_and_cfg, build_simulation
確認	get_maboss_nodes, get_maboss_initial_state, get_maboss_logical_rules, get_maboss_mutations
設定	change_maboss_rule, edit_maboss_readouts, update_maboss_parameters, set_maboss_output_nodes, set_maboss_initial_state
シミュレーションと分析	run_simulation, simulate_mutation, get_simulation_result, visualize_network_trajectories
エクスポート	export_maboss_bnd_cfg, export_maboss_handoff
アーティファクト	list_generated_files, clean_generated_files

リソースとプロンプト

このサーバーは、MCP リソーステンプレートに対応したクライアント向けに、読み取り専用リソースを公開しています。

URI	内容
docs://maboss/agent_manual	エージェント向けの完全な操作マニュアル
maboss://session/{session_id}/nodes	ネットワークのノード名
maboss://session/{session_id}/parameters	現在のパラメーター
maboss://session/{session_id}/initial_state	初期状態の分布
maboss://session/{session_id}/logical_rules	Boolean ルール
maboss://session/{session_id}/mutations	現在の変異
maboss://session/{session_id}/result	メモリー上の最新の状態確率結果（保存済みの実行結果には get_simulation_result(run_id=...) を使用してください）
maboss://session/{session_id}/files	生成されたアーティファクトファイル

maboss_workflow_prompt は、推奨される同じ操作ルールを MCP プロンプトとして公開します。

保存されるシミュレーション実行

ファイルに保存する run_simulation および simulate_mutation の呼び出しが成功するたびに、pyMaBoSS が一時ディレクトリを解放する前に、一意の run_<uuid> アーティファクト一式が保存されます。

• エンジンに送信された正確な BND／CFG 入力（変異体の実行では変異後のコピー）と、エンジンが実際に出力したファイル。
• 元の時間インデックス Time を含む、状態確率およびノード周辺確率の完全な CSV テーブル。
• セッション／実行の識別情報、実行種別、ソースモデルのリビジョン、要求された変異、有効な設定（パラメーター、レート、初期状態、出力、読み出し値）、報告された時点、ファイルサイズ、SHA-256 ハッシュを記録した JSON インベントリ。インベントリは、ファイルの公開後に公開されます。

両方のツールは実行 ID を返します。get_simulation_result(run_id=...) と visualize_network_trajectories(run_id=...) は、整合性を検証したうえでディスクに保存された実行結果を読み取るため、サーバーの再起動後もエンジンを再実行する必要はありません。run_id を省略すると、そのセッションの最新の通常実行が選択され、解決された ID が報告されます。変異体の実行によってこの選択が置き換わることはなく、ベースモデルも変更されません。不明な実行 ID や別のセッションの実行 ID が指定された場合は、代替手段にフォールバックせずエラーになります。各プロットは新しい <run_id>.plot_<uuid>.png という名前で保存されるため、以前のプロットが上書きされることはありません。

従来の result.csv と結果リソースには、最新の最終スナップショットを保持する動作が引き続き適用され、過去の記録にはなりません。結果の保存によって、欠落した時点が補完されたり、数値的・生物学的な挙動が検証されたりすることはありません。

エンジンの失敗、またはコピー、解析、公開時のエラーが発生した場合、エンジンを再実行せずに処理が失敗し、利用可能な診断ファイルを含む不完全な記録として、別個の failed_<uuid>.json に記録されます。公開が部分的に失敗した場合は、その試行で新たに作成されたリンクのみがロールバックされます。以前に保存された実行結果はそのまま保持されます。

エラーとアーティファクトのクリーンアップ

パラメーターが無効な場合、ノードが不明な場合、モデルの状態やシミュレーション結果が存在しない場合、または科学的な処理に失敗した場合は、実行可能なメッセージとともに MCP ツールエラーとして返されます。呼び出し元は引数を修正するか、指定された前提条件を満たしてから、サーバーを再起動せずに再試行できます。

clean_generated_files(session_id=...) は、セッションのインメモリモデルを保持したまま、そのセッションのアーティファクトを削除します。delete_session(clean_files=true) は両方を削除します。これらの操作は破壊的です。再現性のために必要な BND、CFG、CSV、PNG、または引き継ぎファイルがある場合は、実行前に保持してください。

参考情報

• MaBoSS のウェブサイトとドキュメント
• pyMaBoSS のソース
• MCP Python SDK v2 のメディア結果
• MCP Python SDK v2 の構造化出力

アーティファクトは、共有キャッシュルートまたは MCP_BIOMODELLING_ARTIFACT_ROOT の下にある MaBoSS/<session_id> 名前空間に保存されます。従来のアーティファクトも引き続き検出できます。bnet_to_bnd_and_cfg は、任意の parent_manifest（検証済みの BNET ソースサイドカーまたは NeKo の引き継ぎ情報）と、derived_from（編集済みコピーの、改変されていない親アーティファクトのパス）を受け取ります。変換とモデルのエクスポートでは、.lineage.json サイドカーにハッシュが保持されます。通常の来歴情報は import_neko_handoff に代わるものではなく、承認を付与するものでもありません。パスと来歴の正確な仕様については、ルート README を参照してください。