BioMASS ODE Model Builder

BioMASS ODE 模型构建器

一个有状态的 MCP 服务，使用 BioMASS 0.14 和 Text2Model 构建有证据支持的 ODE。 支持模型检查、图形可视化、导出和有界探索性模拟。调用方 Agent 负责阅读文献并提出机制。 校准和敏感性分析不在 v1 范围内。

安装

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

图形渲染已包含在标准安装中：PyGraphviz wheels 内含 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. 使用调用方 Agent 的文献工具阅读论文。set_evidence 会存储来源标识符、支持性段落或摘要、位置、生物学背景、局限性，以及支持/矛盾/仅背景的立场。
4. build_reactions 用于添加或编辑反应；set_reactions 会替换完整列表。每条记录都包含稳定 ID、Text2Model 陈述、起始边、证据 ID，以及受支持/假设/未审阅状态。科学注释为可选项，由 Agent 提供；新记录默认处于未审阅状态。这些链接可以是多对多关系；未覆盖的边会保留在覆盖率报告中。
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"]
}

使用 share_parameters_with 引用较早的反应 ID。渲染器会将该 ID 解析为对应的 Text2Model 行号。反应记录中不接受数值共享。使用 set_reactions 完整替换反应列表时，会清除数值覆盖和条件，因为生成的参数名称取决于行号；检查修订后的模型后，请重新应用这些设置。

进行对话式构建时，调用 create_session，然后使用模板或原始陈述调用 build_reactions。inspect_reactions 会返回稳定 ID 和生成的符号。使用 expected_version 预览批次，然后设置 preview=false 应用更改。增量编辑会保留兼容的数值设置。详情请参阅模型编辑或 docs://biomass/model_editing。 Agent 负责选择动力学以及任何科学注释；服务负责验证语法、引用、依赖项和执行。

独立文本工作流

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，获取 Agent 指引。会话资源通过 biomass://session/{session_id} 提供 /model、/evidence、/coverage、/files 和 /revision/{revision}。

在编写反应之前，Agent 应阅读以下离线 MCP 资源：

资源	参考资料
docs://biomass/reaction_syntax	支持的语法和生成的动力学
docs://biomass/authoring_examples	经过测试的工具参数示例
docs://biomass/network_to_reactions	从证据到机制的编写指南
docs://biomass/model_editing	对话式构建、模板和文件编辑

这些参考资料随服务一同提供，并在其初始化说明、Agent 手册、工作流提示词和编写工具说明中列出。它们记录了受支持的 BioMASS 0.14 子集。无需单独的技能。语法示例会在测试中转换；完整的示例工作流也会生成并模拟。带符号的边不会自动确定机制、动力学定律，也不会自动对应每条边生成一个反应。

修订、验证与限制

每个会话都有锁定的编写状态和持久化的 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，且显示完整路径；它们不会迁移、删除或自动恢复。