PhysiCell Configuration Builder

PhysiCell MCP 服务

Wave 2 集成指南介绍了已存储配置的回读、类型化输入、必需底物的可见性以及可移植软件包。

PhysiCell 服务通过模型上下文协议（MCP）创建、加载、检查、修改、验证和导出 PhysiCell 配置文件。它使用 physicell-settings 软件包生成 PhysiCell_settings.xml、Cell Rules CSV 文件和 PhysiBoSS 细胞内模型设置。

此服务是配置构建器，不是 PhysiCell 仿真运行时。它不会启动 PhysiCell 可执行文件，也不会分析组织仿真输出。导出的文件必须放入合适的 PhysiCell 项目中，并使用该项目编译后的应用程序运行。

此服务通过 mcp-biomodelling-servers Python 软件包分发，并通过 stdio 通信。

安装和启动

安装全部三个生物建模服务：

python -m pip install mcp-biomodelling-servers

启动已安装的 PhysiCell 服务：

mcp-physicell-server

也可以在隔离环境中运行：

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

请参阅仓库 README，了解受支持的 Python 版本、完整的 MCP 客户端配置以及源码检出说明。

会话和配置状态

每个独立模型使用一个 PhysiCell 会话。除非提供 set_as_default=false，否则 create_session() 会将新会话设为默认会话：

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

有多个配置处于活动状态时，请在每次调用中显式传入完整的 session_id。set_default_session() 也接受无歧义的八字符会话前缀。

• 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()。
5. 对每种细胞群体调用一次 add_single_cell_type()。
6. 配置细胞参数以及每项必需的细胞/底物相互作用。
7. 查找准确的信号和行为名称。
8. 根据模型需要添加任意数量的信号-行为规则。
9. 可选：通过 PhysiBoSS 附加并配置细胞内 MaBoSS 模型。
10. 检查摘要和只读资源。
11. 存在细胞规则时，先导出其 CSV，再导出 XML。

analyze_biological_scenario() 会将提供的文本保存为会话上下文。它不会自动推断细胞类型、底物、参数值或规则。

重新创建域会重置模型

create_simulation_domain() 会创建新的 PhysiCellConfig，并替换会话中当前存储的配置。在添加底物、细胞类型、规则或 PhysiBoSS 模型后调用它，会丢弃这些组件。要修改现有配置，请使用参数补丁工具，不要再次调用域创建工具。

定义模拟域

对于平面模型：

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

在 2D 模式下，z 轴范围为一个网格体素（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"
}

启用 Dirichlet 边界时，该工具会将此值应用于 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。

至少需要提供一个值。所有省略的值都会保留。

{
  "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"
}

第二次调用会保留之前设置的运动速度和启用状态。对每种需要配置的细胞类型分别调用此工具。

更新一个细胞/基质相互作用

set_substrate_interaction() 针对一个已存在的细胞类型/基质组合：

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

必须提供 secretion_rate 或 uptake_rate 中的至少一个。省略的速率会保留，现有的分泌目标和净输出速率也会保留。对每个所需组合分别调用此工具，也可以稍后再次调用以更新某个速率。结果包含该组合实际存储的相互作用值、配置版本以及 changed；如果请求的值已经匹配，则 changed 为 false。

信号、行为和 Cell Rules

使用：

• list_all_available_signals() 获取当前配置中可用的环境、接触、细胞内及其他信号；
• list_all_available_behaviors() 获取可配置的细胞行为；
• get_available_cycle_models() 获取细胞周期标识符。

信号和行为发现工具会以结构化数据的形式返回描述和要求。添加规则时，请使用其准确名称。

add_single_cell_rule() 用于添加一个 Hill 函数关系：

{
  "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. 使用 list_loaded_components() 获取基质、细胞类型或 PhysiBoSS 详情。
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 集成

已安装的 physicell-settings 包必须支持 PhysiBoSS。要附加细胞内 MaBoSS 模型，目标 PhysiCell 细胞类型必须已存在。

首选的已验证交接流程

从 MaBoSS MCP 服务导出 maboss-to-physicell 交接数据，然后在 import_maboss_handoff 上调用：

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

此工具会：

• 验证清单、BND、CFG、可选结果表和工件哈希；
• 在存在完整上游 NeKo 血统信息时进行验证；
• 检查精确的布尔节点和输出节点契约；
• 检查声明的目标细胞类型是否存在；
• 将已验证的工件复制到 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。至少需要提供一个值，并且所有省略的设置都会保留。可对同一目标重复调用此工具，也可分别对多个目标细胞类型调用。

然后根据需要重复调用：

• add_physiboss_input_link：将 PhysiCell 信号映射到布尔节点，并返回已存储的输入映射；
• add_physiboss_output_link：将布尔节点映射到 PhysiCell 行为；
• apply_physiboss_mutation：将布尔节点固定为 0 或 1。

输入和输出链接操作为 activation 或 inhibition。使用发现工具查找精确的 PhysiCell 信号和行为名称，并使用 MaBoSS 上下文中的精确布尔节点名称。

MaBoSS 输出节点、参数和模拟摘要会作为上下文保留。它们不会自动转换为 PhysiBoSS 时间设置或信号／节点／行为映射；这些需要明确的生物学决策。

使用 get_maboss_context() 检查所有已存储的上下文，或提供 cell_type 以选择一个目标。

独立 BND 和 CFG 回退方案

如果不存在类型化交接清单：

1. 调用 set_maboss_context()，并传入独立文件路径和已知模型 元数据；
2. 针对目标细胞类型调用 add_physiboss_model()；
3. 按上述说明配置设置、链接和突变。

此路径不会验证跨服务的来源链，也不会复制受完整性保护的制品集。只要 MaBoSS 清单可用，就应优先使用 import_maboss_handoff()。

使用只读资源进行检查

该服务提供一份静态手册和七个会话资源模板：

URI	内容
docs://physicell/agent_manual	完整的 Agent 操作手册
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 和细胞规则

存在规则时的导出顺序

存在至少一条细胞规则时：

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"
}

如果没有细胞规则，则只需导出 XML。

XML 和 CSV 文件名必须是纯文件名，不含目录部分，并且必须使用对应的 .xml 或 .csv 后缀。输出仅限于：

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

重复使用导出文件名会更新该会话制品。如果需要保留多个配置版本，请选择不同的 文件名。

list_generated_files() 会报告当前会话的 XML 和 CSV 制品；传入 session_id="all" 可汇总所有会话中的这些文件类型。list_artifact_sessions() 和文件资源也会公开其他保留的交接制品。

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、configure_simulation_inputs
发现和规则	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、export_configuration_bundle、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 交接和审批要求保持不变。