MaBoSS Boolean Network Simulator

MaBoSS MCP 服务

Wave 2 integration guide 介绍了摘要读数、命名速率编辑、持久化运行 ID、有界结果和 handoff 2.1。

MaBoSS 服务通过模型上下文协议（MCP）提供随机布尔模型构建、配置、模拟、分析和导出功能。它使用 pyMaBoSS 作为模拟引擎，并可参与从 NeKo 到 MaBoSS 再到 PhysiCell 的经验证建模流程。

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

安装和启动

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

python -m pip install mcp-biomodelling-servers

启动已安装的 MaBoSS 服务：

mcp-maboss-server

或者，在隔离环境中运行：

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

该服务不需要单独的 MaBoSS 可执行文件。它会在子 Python 进程中使用随 pyMaBoSS 安装的编译引擎 cmaboss 验证并模拟模型，因此长时间运行的模拟不会阻塞服务。如果加载的模型被引擎拒绝，加载操作会失败并显示引擎返回的消息。

有关支持的 Python 版本、完整的 MCP 客户端配置、源码检出说明和共享运行时行为，请参阅仓库 README。

会话和模型状态

每个模型都属于一个 MaBoSS 会话。首先调用 create_session()，保留返回的 session_id，并在有多个模型处于活动状态时显式传入该 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() 检查现有分布。

对于一个节点，提供 [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 返回当前布尔规则，最多返回 100 个节点；除非提供 selected_nodes（如果节点更多，truncated 会报告这一情况）。rule_limitation 会标记自定义速率表达式导致单凭规则无法描述其切换行为的节点；请使用 get_maboss_nodes 检查这些节点。
• change_maboss_rule 会替换一个节点的规则；如果模型验证拒绝此更改，则恢复之前的规则。
• 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 用于设置要显示的最大模拟时间。它必须是大于零的有限数值。省略此参数则绘制完整的可用轨迹。

此工具：

• 将轨迹绘制委托给 pyMaBoSS plot_trajectory(until=...)；
• 使用紧凑边界框并添加内边距，避免裁切绘图区外的图例；
• 以 MIME 类型为 image/png 的 MCP ImageContent 块返回 PNG；并
• 将完全相同的 PNG 字节保存为会话产物目录中的 network_trajectory.png。

MCP 客户端必须支持渲染图像内容块，才能内联显示图表。即使客户端只呈现结果的文本部分或结构化部分，保存的产物仍可用。

跨服务交接

NeKo 到 MaBoSS

当布尔模型来自 NeKo MCP 服务时，优先使用 import_neko_handoff(manifest_path)。此工具会：

• 验证 neko-to-maboss 清单和工件哈希；
• 将引用的 BNET 转换为 MaBoSS BND 和 CFG 文件；
• 验证转换后的节点集合；
• 在存在 NeKo 声明的输出节点时应用这些节点；
• 仅在完整导入成功后加载模型；以及
• 保留 NeKo 来源信息，以便后续交接给 PhysiCell。

如果清单未声明输出节点，请在运行或导出模型前调用 set_maboss_output_nodes()。

MaBoSS 到 PhysiCell

调用 export_maboss_handoff(target_cell_type=...)，生成受完整性保护的 maboss-to-physicell 交接包。此操作会快照：

• 当前 BND 和 CFG 模型；
• MaBoSS 参数和选定的输出节点；
• 可选的非空模拟结果 CSV；
• 目标 PhysiCell 细胞类型和生物学背景；以及
• 完整的上游 NeKo 来源链（若曾从 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	完整的 Agent 操作手册
maboss://session/{session_id}/nodes	网络节点名称
maboss://session/{session_id}/parameters	当前参数
maboss://session/{session_id}/initial_state	初始状态分布
maboss://session/{session_id}/logical_rules	布尔规则
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 输入（对于突变运行，是经过突变的副本）以及引擎实际生成的输出文件。
• 完整的状态概率和节点边际 CSV 表格，包括标记为 Time 的原始时间索引。
• JSON 清单，其中包含会话/运行身份、运行类型、源模型修订版、请求的突变、有效配置（参数、速率、初始状态、输出、读数）、报告的时间点、文件大小和 SHA-256 哈希值。清单会在其文件发布后发布。

这两个工具都会返回运行 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。