PhysiCell Configuration Builder

PhysiCell MCP サーバー

PhysiCell サーバーは、Model Context Protocol（MCP）を通じて、PhysiCell の設定ファイルの作成、読み込み、確認、変更、検証、エクスポートを行います。physicell-settings パッケージを使用して、PhysiCell_settings.xml、Cell Rules CSV ファイル、PhysiBoSS の細胞内モデル設定を作成します。

このサーバーは設定ビルダーであり、PhysiCell シミュレーションの実行環境ではありません。PhysiCell の実行ファイルを起動したり、組織シミュレーションの出力を解析したりすることはありません。エクスポートしたファイルは、適切な PhysiCell プロジェクトに配置し、そのプロジェクトでコンパイルされたアプリケーションを使って実行する必要があります。

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

インストールと起動

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

python -m pip install mcp-biomodelling-servers

インストールした PhysiCell サーバーを起動します。

mcp-physicell-server

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

uvx --from mcp-biomodelling-servers mcp-physicell-server

対応する Python バージョン、MCP クライアントの完全な設定、ソースをチェックアウトして実行する手順については、リポジトリの README をご覧ください。

セッションと設定の状態

独立したモデルごとに PhysiCell セッションを 1 つ使用します。set_as_default=false を指定しない限り、create_session() は新しいセッションをデフォルトとして選択します。

{
  "set_as_default": true,
  "session_name": "hypoxic_tumor_v1"
}

複数の設定をアクティブにしている場合は、返された完全な session_id を必ず明示的に渡してください。set_default_session() では、曖昧さのない 8 文字のセッションプレフィックスも使用できます。

• list_sessions は、アクティブなセッション、設定の有無、コンポーネント数、読み込まれた XML の由来、PhysiBoSS の数、ワークフローの進捗状況を報告します。
• list_artifact_sessions は、現在または以前のサーバープロセスから保持されているファイルを検出します。
• get_workflow_status と get_simulation_summary は、同じワークフローの状態と推奨される次の手順を返します。
• delete_session は、メモリ内のセッション状態を完全に削除します。

ワークフローの進捗状況には、設定の構築で実行した手順が記録されます。パラメーター値が生物学的に妥当であること、必要なカスタムコードがすべて存在すること、またはエクスポートしたモデルが特定の PhysiCell プロジェクトで正常に実行されることを保証するものではありません。

新しい設定を構築する

次の順序で進めます。

1. create_session() を呼び出します。
2. analyze_biological_scenario() を使ってモデリングの目的を保存します。
3. create_simulation_domain() を使って空間、メッシュ、次元、期間を定義します。
4. 拡散性基質ごとに add_single_substrate() を 1 回呼び出します。
5. 細胞集団ごとに add_single_cell_type() を 1 回呼び出します。
6. 細胞パラメーターと、必要なすべての細胞・基質間の相互作用を設定します。
7. 正確なシグナル名と動作名を確認します。
8. モデルに必要な数のシグナル・動作ルールを追加します。
9. 必要に応じて、PhysiBoSS を通じて細胞内 MaBoSS モデルを追加し、設定します。
10. サマリーと読み取り専用リソースを確認します。
11. 細胞ルールがある場合は、まず CSV をエクスポートし、その後 XML をエクスポートします。

analyze_biological_scenario() は、指定されたテキストをセッションコンテキストとして保存します。細胞種、基質、パラメーター値、ルールを自動的に推論することはありません。

ドメインを再作成するとモデルがリセットされます

create_simulation_domain() は新しい PhysiCellConfig を作成し、セッションに現在保存されている設定を置き換えます。基質、細胞種、ルール、または PhysiBoSS モデルを追加した後にこの関数を呼び出すと、それらのコンポーネントは破棄されます。既存の設定を変更するには、2 回目のドメイン呼び出しではなく、パラメーターパッチツールを使用してください。

シミュレーション領域を定義する

平面モデルの場合：

{
  "domain_x": 2000,
  "domain_y": 2000,
  "use_2d": true,
  "dx": 20,
  "max_time": 7200,
  "session_id": "SESSION_ID"
}

2D モードでは、z の範囲はメッシュの 1 ボクセル分（dx）となり、PhysiCell の平面モードが有効になります。完全な 3D モデルの場合は、use_2d=false を設定し、正の domain_z を指定してください。

ドメインは原点を中心とします。max_time の単位は分、dx の単位はマイクロメートルです。メッシュ間隔を小さくすると空間分解能が上がり、最終的な PhysiCell シミュレーションの計算コストも通常は増加します。

基質と細胞タイプを追加する

基質

酸素、栄養素、薬剤、その他の拡散場ごとに、add_single_substrate() を個別に呼び出します。

{
  "substrate_name": "oxygen",
  "diffusion_coefficient": 100000,
  "decay_rate": 0.01,
  "initial_condition": 38,
  "units": "mmHg",
  "dirichlet_enabled": true,
  "dirichlet_value": 38,
  "session_id": "SESSION_ID"
}

ディリクレ境界が有効な場合、ツールは x 境界と y 境界に値を適用し、3D では z 境界にも適用します。dirichlet_value を省略すると、初期条件が使用されます。

細胞タイプ

get_available_cycle_models() を使って有効なサイクル名を確認し、集団ごとに add_single_cell_type() を一度呼び出します。

{
  "cell_type_name": "cancer_cell",
  "cycle_model": "Ki67_basic",
  "session_id": "SESSION_ID"
}

特定の細胞／基質ペアを設定するツールを使ったり、細胞内モデルを割り当てたりする前に、基質と細胞タイプを作成しておく必要があります。

フラットな部分更新のセマンティクス

現在、公開されている設定ツールでは、フラットなオプション引数を使用します。変更する値のみを指定してください。延期されているネストされたパラメーターオブジェクトへの再設計は、このリリースには含まれません。

各パッチは別個の設定コピー上で準備され、成功した場合にのみ公開されます。パッチに失敗しても、有効な設定は変更されません。

細胞パラメーターにパッチを適用する

configure_cell_parameters() は、次の項目をサポートします。

• volume_total；
• volume_nuclear；
• fluid_fraction；
• motility_speed；
• persistence_time；
• motility_enabled；
• apoptosis_rate；
• necrosis_rate。

少なくとも1つの値が必要です。省略した値はすべて維持されます。

{
  "cell_type": "cancer_cell",
  "motility_speed": 0.8,
  "motility_enabled": true,
  "session_id": "SESSION_ID"
}

同じ細胞タイプは、運動性の値を再指定せずに、後から変更できます。

{
  "cell_type": "cancer_cell",
  "apoptosis_rate": 0.001,
  "session_id": "SESSION_ID"
}

2回目の呼び出しでは、先に指定した運動速度と有効状態が維持されます。設定が必要な細胞タイプごとに、ツールを個別に繰り返し実行してください。

1つの細胞／基質相互作用にパッチを適用する

set_substrate_interaction() は、既存の細胞タイプ／基質のペアを1つ対象にします。

{
  "cell_type": "cancer_cell",
  "substrate": "oxygen",
  "uptake_rate": 10,
  "session_id": "SESSION_ID"
}

secretion_rate または uptake_rate の少なくとも一方が必要です。省略したレートは、既存の分泌目標値と正味輸出レートとともに維持されます。必要なペアごとにツールを繰り返し実行するか、後から再度呼び出していずれかのレートを変更してください。

シグナル、挙動、セルルール

次を使用します。

• 現在の設定で使用可能な環境、接触、細胞内、その他のシグナルには、list_all_available_signals() を使用します。
• 設定可能な細胞挙動には、list_all_available_behaviors() を使用します。
• 細胞周期の識別子には、get_available_cycle_models() を使用します。

シグナルと挙動を検出するツールは、説明と要件を構造化データとして返します。ルールを追加するときは、正確な名前を使用してください。

add_single_cell_rule() は、1つのヒル関数の関係性を追加します。

{
  "cell_type": "cancer_cell",
  "signal": "oxygen",
  "direction": "decreases",
  "behavior": "apoptosis",
  "saturation_value": 0,
  "half_max": 5,
  "hill_power": 4,
  "session_id": "SESSION_ID"
}

direction は increases または decreases です。half_max と hill_power は正の値である必要があります。シグナルと挙動の関係性ごとに、ツールを繰り返し呼び出してください。

既存の XML 設定を変更する

次のワークフローを使用します。

1. validate_xml_file(filepath) を呼び出します。
2. 構造化された結果で valid=true が報告された場合は、load_xml_configuration(filepath) を呼び出します。
3. analyze_loaded_configuration() で内容を確認します。
4. 基質、細胞タイプ、または PhysiBoSS の詳細には、list_loaded_components() を使用します。
5. 対象を絞ったパッチと追加を適用します。
6. get_simulation_summary() の内容を確認します。
7. セッション固有のファイル名でエクスポートします。

validate_xml_file() は読み取り専用です。無効な XML ファイルに対する形式の正しい検証リクエストは、valid=false とエラーの説明を含む成功したツール結果を返します。検証処理は成功しましたが、ファイルは検証に合格しませんでした。

load_xml_configuration() は、候補となる設定を検証して解析した後に、セッション状態を置き換えます。ファイルが存在しない場合、無効な場合、または読み込めない場合、現在の設定は置き換えられません。

analyze_loaded_configuration() は、ソースの来歴、ドメイン情報、コンポーネント名、既存のルール、PhysiBoSS モデル、変更に関するガイダンスを返します。list_loaded_components(component_type=...) では、substrates、cell_types、physiboss、または all を指定できます。

PhysiBoSS 統合

PhysiBoSS のサポートは、インストールされている physicell-settings パッケージで利用可能である必要があります。細胞内 MaBoSS モデルを割り当てる前に、対象となる PhysiCell の細胞タイプが存在している必要があります。

検証済みハンドオフを推奨

MaBoSS MCP サーバーから maboss-to-physicell ハンドオフをエクスポートし、次に以下を呼び出します。

{
  "manifest_path": "/path/to/maboss_to_physicell.handoff.json",
  "artifact_prefix": "cancer_cell_maboss_v1",
  "replace_existing": false,
  "session_id": "SESSION_ID"
}

import_maboss_handoff を実行します。

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

• マニフェスト、BND、CFG、任意の結果テーブル、アーティファクトのハッシュを検証します。
• 存在する場合は、完全な上流の NeKo 系譜を検証します。
• Boolean ノードと出力ノードの契約が正確であることを確認します。
• 宣言されたターゲット細胞型が存在することを確認します。
• 検証済みアーティファクトを PhysiCell セッションにコピーします。
• インポートが完全に成功した後でのみ、候補モデルを追加します。
• ターゲット細胞型用の MaBoSS コンテキストを個別に保存します。

保持するインポートごとに、新しい artifact_prefix を使用してください。既存のインポートアーティファクトは上書きされません。

異なるターゲット細胞型のモデルをインポートすると、それぞれ独立したコンテキストが維持されます。ターゲットにすでに細胞内モデルがある場合、replace_existing=true を指定しない限り、インポートは失敗します。明示的に置き換えると、そのターゲットの以前の PhysiBoSS 設定、入力リンク、出力リンク、変異がリセットされます。

設定と生物学的マッピング

インポート後、ターゲットのタイミングと継承をパッチします。

{
  "cell_type": "cancer_cell",
  "intracellular_dt": 6,
  "time_stochasticity": 0,
  "inheritance_global": true,
  "session_id": "SESSION_ID"
}

configure_physiboss_settings() は scaling と start_time にも対応しています。少なくとも 1 つの値が必須で、省略された設定はすべて保持されます。同じターゲットに対してこのツールを繰り返し呼び出すことも、複数のターゲット細胞型ごとに個別に呼び出すこともできます。

次に、必要に応じて以下を繰り返し呼び出します。

• add_physiboss_input_link：PhysiCell シグナルを Boolean ノードにマッピングします。
• add_physiboss_output_link：Boolean ノードを PhysiCell の動作にマッピングします。
• apply_physiboss_mutation：Boolean ノードを 0 または 1 に固定します。

入力リンクと出力リンクのアクションは activation または inhibition です。検出ツールで PhysiCell のシグナル名と動作名を正確に確認し、MaBoSS コンテキストにある正確な Boolean ノード名を使用してください。

MaBoSS の出力ノード、パラメーター、シミュレーションの要約はコンテキストとして保持されます。これらが PhysiBoSS のタイミングやシグナル／ノード／動作のマッピングに自動的に変換されることはありません。これらのマッピングには、明示的な生物学的判断が必要です。

get_maboss_context() ですべての保存済みコンテキストを確認するか、cell_type を指定してターゲットを選択します。

スタンドアロン BND および CFG の代替手順

型付きハンドオフマニフェストがない場合：

1. スタンドアロンのファイルパスと既知のモデルメタデータを指定して、set_maboss_context() を呼び出します。
2. 対象の細胞型に対して add_physiboss_model() を呼び出します。
3. 上記の手順で設定、リンク、変異を構成します。

この方法では、サーバー間の来歴チェーンは検証されず、完全性が保護されたアーティファクトセットもコピーされません。MaBoSS マニフェストが利用できる場合は、import_maboss_handoff() を優先してください。

読み取り専用リソースで確認する

サーバーは、静的マニュアル 1 件とセッションリソーステンプレート 7 件を公開します。

URI	内容
docs://physicell/agent_manual	エージェント操作マニュアルの全文
physicell://session/{session_id}/workflow	進捗状況と推奨される次の操作
physicell://session/{session_id}/domain	空間、メッシュ、次元、期間、時間ステップ
physicell://session/{session_id}/substrates	基質の拡散と初期条件の要約
physicell://session/{session_id}/cell_types	各細胞型の主要な表現型の値
physicell://session/{session_id}/cell_rules	シグナルと動作のルール、およびルールセットへの参照
physicell://session/{session_id}/physiboss	細胞内モデル、コンテキスト、設定、リンク、変異
physicell://session/{session_id}/files	生成されたすべてのセッションアーティファクト

ワークフローとファイルのリソースは、有効なセッションであれば、シミュレーションドメインが存在する前でも利用できます。ドメイン、基質、細胞型、細胞ルール、PhysiBoSS の各リソースには設定が必要です。これらのリソースは読み取り専用であり、不足しているセッションを作成したり、ワークフローの進捗を変更したりしません。

physicell_workflow_prompt と get_help() では、同じ操作マニュアルを参照できます。

XML と細胞ルールをエクスポートする

ルールがある場合のエクスポート順序

Cell Rule が 1 つ以上ある場合：

1. 最初に export_cell_rules_csv() を呼び出します。
2. このツールは CSV を書き出し、有効なルールセットへの参照をメモリ内の設定に登録します。
3. その後 export_xml_configuration() を呼び出し、生成される XML にそのルールセットへの参照を含めます。

{
  "filename": "tumor_rules.csv",
  "session_id": "SESSION_ID"
}

続けて：

{
  "filename": "tumor_settings.xml",
  "session_id": "SESSION_ID"
}

Cell Rule がない場合は、XML のエクスポートのみが必要です。

XML と CSV のファイル名には、ディレクトリを含まないベース名を指定し、対応する .xml または .csv の拡張子を使用してください。出力先は次の範囲に限定されます。

<configured-or-user-cache-root>/PhysiCell/{session_id}/

エクスポートファイル名を再利用すると、そのセッションの成果物が更新されます。複数バージョンの設定を保持する必要がある場合は、異なるファイル名を選択してください。

list_generated_files() は、アクティブなセッションの XML と CSV の成果物を報告します。session_id="all" を渡すと、全セッションのこれらのファイル形式をまとめて取得できます。 list_artifact_sessions() と files リソースでは、その他の保持されている引き継ぎ用成果物も確認できます。

XML は、対応するコンパイル済み PhysiCell プロジェクトに渡すことができます。サーバーは、プロジェクト固有の C++ 拡張を検証したり、エクスポートされたモデルを実行したりすることはできません。

ツールリファレンス

カテゴリ	ツール
セッションとワークフロー	create_session、list_sessions、list_artifact_sessions、set_default_session、get_workflow_status、get_simulation_summary、delete_session
MaBoSS のコンテキストと引き継ぎ	import_maboss_handoff、set_maboss_context、get_maboss_context
既存の XML	validate_xml_file、load_xml_configuration、analyze_loaded_configuration、list_loaded_components
ドメインとシナリオ	analyze_biological_scenario、create_simulation_domain
基質と細胞	add_single_substrate、add_single_cell_type、configure_cell_parameters、set_substrate_interaction
検索とルール	get_available_cycle_models、list_all_available_signals、list_all_available_behaviors、add_single_cell_rule
PhysiBoSS	add_physiboss_model、configure_physiboss_settings、add_physiboss_input_link、add_physiboss_output_link、apply_physiboss_mutation
エクスポートと成果物	export_xml_configuration、export_cell_rules_csv、list_generated_files、clean_generated_files
ヘルプ	get_help

構造化出力と検証結果

セッションの検索、ワークフローの状態、XML の検証と分析、コンポーネントの調査、シグナル／ビヘイビアの検索、コンテキストの確認、検証済みの引き継ぎデータのインポート、エクスポート、成果物ツールは、モデルが読み取りやすい簡潔なテキストに加えて、JSON ネイティブの構造化結果を返します。

無効な引数、前提条件の不足、安全でないファイル名、設定変更の失敗、整合性エラーは、復旧方法の案内とともに MCP ツールエラーとして返されます。有効な validate_xml_file() の呼び出しでも valid=false が返されることがあります。これは、ファイルの有効性が要求された科学的な結果であるためです。

クリーンアップ

clean_generated_files(session_id=...) は、メモリ内の設定を保持したまま、選択したセッションのすべての成果物を削除します。再現性のために必要な XML、CSV、BND、CFG、結果、または引き継ぎファイルは、呼び出す前に保持してください。

設定状態と成果物の両方を破棄する場合は、delete_session() を呼び出す前に生成ファイルをクリーンアップしてください。

参考資料

• PyPI の physicell-settings
• PhysiCell プロジェクト
• PhysiCell Studio のドキュメント
• PhysiBoSS
• MCP Python SDK v2 の構造化出力
• MCP Python SDK v2 のリソース

上記のアーティファクトツリーは、インストール済みパッケージではなく、 $MCP_BIOMODELLING_ARTIFACT_ROOT/PhysiCell/<session_id> または ルート README に記載されている共有ユーザーキャッシュのデフォルトの場所に置かれるようになりました。 従来のパッケージ内アーティファクトも、フルパスと legacy マーカーを使って引き続き確認できます。既存の PhysiBoSS の引き継ぎおよび承認要件に変更はありません。