BioMASS ODE Model Builder

BioMASS ODE モデルビルダー

BioMASS 0.14 と Text2Model を使用した、根拠に基づく ODE 構築のためのステートフルな MCP サーバーです。 モデルの検査、グラフの可視化、エクスポート、範囲を限定した探索的シミュレーションに対応しています。呼び出し側のエージェントが文献を読み、メカニズムを提案します。キャリブレーションと感度分析は v1 の対象外です。

インストール

python -m pip install mcp-biomodelling-servers
mcp-biomass-server

グラフのレンダリングは標準インストールに含まれています。PyGraphviz の wheel には Graphviz がバンドルされているため、システムへの Graphviz や dot プログラムのインストールは不要です。以前の [biomass-graph] extra は、既存のインストールコマンドとの互換性のため、空のエイリアスとして残されています。PyGraphviz の wheel がないプラットフォームでは、pip がソースからビルドします。その場合、C コンパイラーと Graphviz の開発用ヘッダーが必要です。

MCP クライアントの設定例：

{
  "servers": {
    "biomass": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "mcp-biomodelling-servers", "mcp-biomass-server"]
    }
  }
}

ソースチェックアウトからは、python -m pip install '.[dev]' でインストールし、python -m BioMASS.server を実行します。このリポジトリの wheel パスのマッピングは、編集可能インストールには対応していません。

NeKo のワークフロー

1. NeKo でネットワークを整理し、生物学的コンテキストを指定して export_biomass_handoff を呼び出します。エクスポートではノード、安定したエッジ ID、参考文献、利用可能なメカニズム／コンテキストの列が保持されます。接続性は必要ありません。
2. create_session を呼び出し、返されたマニフェストパスを指定して import_neko_handoff を呼び出します。インポート時にアーティファクトの整合性を検証し、ネットワークと来歴の永続的なコピーを作成スナップショットに保存します。
3. 呼び出し側エージェントの文献ツールで論文を読みます。set_evidence には、ソース識別子、裏付けとなる引用または要約、その場所、生物学的コンテキスト、限界、ならびに支持／反証／コンテキストのみの立場を保存します。
4. build_reactions で反応を追加または編集し、set_reactions でリスト全体を置き換えます。各レコードには、安定した ID、Text2Model の記述、元となるエッジ、根拠 ID、支持済み／仮定／未レビューのステータスが含まれます。科学的注釈は任意で、エージェントが指定します。新しいレコードのデフォルトは未レビューです。これらのリンクは多対多にできます。カバーされていないエッジはカバレッジレポートに残ります。
5. configure_model で、観測量、時間範囲、条件、数値計算のデフォルト、単位、量の来歴を設定します。設定全体が置き換えられます。
6. 検査、検証、生成、可視化、必要に応じたシミュレーション、エクスポートを行います。

反応の例（ID はインポートされたエッジおよび保存済みの根拠に対応している必要があります）：

{
  "reaction_id": "binding",
  "statement": "E + S <--> ES | kf=0.003, kr=0.001 | E=100, S=50, ES=0",
  "status": "supported",
  "evidence_ids": ["binding_paper"],
  "edge_ids": ["edge_returned_by_import"]
}

先行する反応 ID を参照するには share_parameters_with を使用します。レンダラーはその ID を正しい Text2Model の行番号に解決します。反応レコードでの数値の共有は拒否されます。set_reactions で全体を置き換えると、生成されるパラメーター名が行番号に依存するため、数値の上書きと条件がクリアされます。モデルを更新した後に再確認し、これらの設定を適用し直してください。

対話形式で構築する場合は、create_session を呼び出した後、テンプレートまたは生の記述を指定して build_reactions を呼び出します。inspect_reactions は安定した ID と生成されたシンボルを返します。expected_version を使ってバッチをプレビューし、その後 preview=false で適用します。増分編集では互換性のある数値設定が保持されます。詳細はモデルの編集または docs://biomass/model_editing をご覧ください。速度論と科学的注釈はエージェントが選択し、サーバーは構文、参照、依存関係、実行を検証します。

スタンドアロンのテキストワークフロー

import_text は、コメント、ディレクティブ、数値の行参照を含む Text2Model ドキュメント全体をそのまま保持します。ドキュメントを置き換えると、行エビデンスのマッピングも置き換わり、古い設定はクリアされます。エビデンスはインポート前に保存しておき、後から行番号でリンクできます。ドキュメントモードでは、観測量、シミュレーション条件、時間範囲をテキスト自体に記述してください。configure_model では数値のデフォルト値を上書きし、単位や出典情報を記録できます。

import_text_file は既存の UTF-8 ファイルを、ソースパスとハッシュを含めてセッションに読み込みます。build_reactions では、変更されていない行とパラメーター参照を保持しながら、内容を展開または編集できます。元のファイルが変更されることはありません。削除した場合もコメント行は残るため、後続の行番号は変わりません。同じバッチ内で、依存する観測量と条件を明示的に修正する必要があります。

examples/enzyme.txt は、小規模な実行可能な酵素モデルです。3 つのパラメーターすべて、4 つの初期値すべて（ゼロを含む）、および時間範囲が指定されているため、プレースホルダー値を有効にしなくても実行できます。

{"scenario": {"name": "enzyme"}, "session_id": "returned-session-id"}

そのオブジェクトを generate_model の後に run_simulation に渡します。明示的に仮定に基づく実行を行う場合は、scenario.allow_placeholders を true に設定してください。指定値または仮定値は、Text2Model のプレースホルダーとは区別されます。文献由来の数量にはエビデンス ID が必要です。指定されていない単位は、明示的な null 値として保持されます。

シナリオの上書き値は、条件の割り当てより前に、生成されたデフォルト値を置き換えます。各条件は、新しいデフォルト値から開始します。定常状態の準備を含め、各求解で使用された実際のパラメーターと初期値が記録されます。パラメーター共有の制約は引き続き有効です。上書きする場合は、元となるパラメーターを上書きしてください。シミュレーションでは、完全な種および観測量の CSV テーブル、軌跡のプレビュー（最大 20 種）、数値シナリオレポートが生成されます。

グラフの可視化

• visualize_model(format="png")：デフォルトの静的グラフと MCP 画像コンテンツです。
• visualize_model(format="svg")：拡大縮小可能な静的グラフです。
• visualize_model(format="html")：インタラクティブなグラフです。ブラウザーは開きません。
• export_model_graph：外部のグラフソフトウェア向けの DOT です。

静的レイアウトは dot（デフォルト）、neato、fdp、circo、twopi です。 HTML では、物理演算やレイアウトのコントロールを任意で表示できます。レイアウトの選択は静的フォーマットに適用されます。インタラクティブ HTML は、BioMASS がサポートする PyVis バージョンで使用されている vis-network の JavaScript とスタイルシートの CDN を参照するため、開くにはネットワークアクセスが必要です。グラフの成果物は変更不可能なモデルリビジョンに紐付けられ、そのリビジョンのエクスポートバンドルに含まれます。

BioMASS は、反応物と修飾因子を生成物に投影し、繰り返される種の接続を統合します。反応物と修飾因子、また活性化する修飾因子と阻害する修飾因子は区別しません。そのため、この可視化は完全な反応グラフでも、符号付きの因果ネットワークでもありません。解決されていない NeKo エッジはカバレッジレポートに残ります。インタラクティブグラフはシミュレーションのアニメーションではありません。上流のグラフチュートリアルを参照してください。

ツールとリソース

サーバーは22個のツールを公開します。

ファミリー	ツール
セッション	create_session、list_sessions、close_session、restore_session
作成	import_neko_handoff、import_text、import_text_file、set_evidence、set_reactions、build_reactions、configure_model
検査	inspect_model、inspect_reactions、validate_model
生成	generate_model
可視化	visualize_model、export_model_graph
シミュレーション	run_simulation
成果物	export_model_bundle、list_generated_files、list_artifact_sessions、clean_generated_files

エージェント向けの指示については、docs://biomass/agent_manual を読むか、biomass_workflow_prompt をリクエストしてください。セッションリソースは、biomass://session/{session_id} の配下で /model、/evidence、/coverage、/files、/revision/{revision} を公開します。

反応を書き始める前に、エージェントは次のオフライン MCP リソースを読む必要があります。

リソース	リファレンス
docs://biomass/reaction_syntax	サポートされる構文と生成される速度論
docs://biomass/authoring_examples	テスト済みのツール引数の例
docs://biomass/network_to_reactions	エビデンスから機構を作成するガイド
docs://biomass/model_editing	対話型の構築、テンプレート、ファイル編集

これらのリファレンスはサーバーに同梱されており、初期化手順、エージェントマニュアル、ワークフロープロンプト、作成ツールの説明からリンクされています。サポートされる BioMASS 0.14 のサブセットについて説明しています。別個のスキルは必要ありません。構文の例はテストで変換されます。また、完全なワークフローの例も生成およびシミュレーションされます。符号付きエッジから機構、速度法則、またはエッジごとに1つの反応が自動的に決まるわけではありません。

改訂、検証、制限

各セッションにはロックされた作成状態と永続的な JSON スナップショットがあります。ワーカーは個別のディレクトリと新しいインタープリターを使用します。生成された改訂には整合性インベントリがあり、作成内容を編集すると現在の改訂ポインターはクリアされますが、以前の改訂は保持されます。元のモデルとエビデンスを確認するには、古い改訂を明示的に選択してください。失敗したジョブでは診断ログのみが保持されます。

構文の妥当性、生成の成功、エビデンスの網羅性、数値実行は、それぞれ別の結果です。いずれも生物学的な妥当性を証明するものではありません。check_generation=true を指定した検証では使い捨てのワーカーを使用し、改訂は公開されません。

受け付ける式は、有限の定数、算術演算、およびモデルシンボルへの参照（該当する場合は p[name]、u[name]、init[name]）で構成されます。Python の呼び出し、属性、インポート、任意の Python モデルパッケージはサポートされません。識別子は英字で始まり、英字、数字、単一のアンダースコアを使用します。数値反応値は有限かつ非負である必要があります。

ワーカーのタイムアウトはデフォルトで 60 秒で、1～300 秒に設定できます。v1 の制限は、1 MiB／テキスト 2000 行、種 500 個／反応 1000 個、条件 20 個、整数の時間サンプル 10001 個です。タイムアウト時には、POSIX システム上でワーカーとその子プロセスが終了します。これらのプロセスは実行時状態を分離するものであり、OS サンドボックスではありません。

エクスポートには、生成された Python、元のテキスト、数値設定、エビデンス、前提、網羅性、バージョンメタデータ、グラフ、保存済み実行が含まれます。ZIP を展開し、python run_simulation.py を実行すると保存済みシナリオが一覧表示されます。その後、python run_simulation.py simulate_<run_id> を実行すると、そのシナリオを再現できます。スクリプトは記録された実際の数値条件を使用します。requirements.txt では BioMASS 0.14.0 が固定されています。セッションを閉じてもアーティファクトは保持されます。クリーンアップでは作成状態と系統情報を保持したまま、生成された改訂と実行が削除されます。

アーティファクトと復元可能なセッションスナップショットは、$MCP_BIOMODELLING_ARTIFACT_ROOT/BioMASS/<session_id>、またはルート README に記載されている共有ユーザーキャッシュのデフォルトの場所に保存されます。従来のパッケージ内ディレクトリは legacy=true と完全な場所を付けて引き続き一覧表示されます。これらは移行、削除、自動復元されません。