NeKo Biological Network Builder

NeKo MCP 服务

Wave 2 集成指南介绍了有界诊断和协同轻量历史记录 API。

NeKo 服务通过模型上下文协议（MCP）构建、整理、分析和导出信号网络。它使用 NeKo 从整理过的相互作用数据库或现有的 SIF 文件构建网络，并在 NeKo 原生的分支历史记录中保留拓扑变化。

该服务作为 Python 包 mcp-biomodelling-servers 分发，并通过 stdio 通信。经过类型化且受完整性保护的交接机制，可将已完成的 NeKo 网络传递给 MaBoSS MCP 服务。

安装和启动

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

python -m pip install mcp-biomodelling-servers

启动已安装的 NeKo 服务：

mcp-neko-server

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

uvx --from mcp-biomodelling-servers mcp-neko-server

分支历史记录资源使用捆绑的 PyGraphviz 渲染；无需安装系统级 Graphviz。有关支持的 Python 版本、完整的 MCP 客户端配置和源代码检出说明，请参阅仓库 README。

会话和网络状态

每个建模假设都应有自己的 NeKo 会话。先调用 create_session()，保留返回的 session_id，并在后续调用中显式传入。新建的会话不会自动设为默认会话；如果后续调用可以省略 ID，请调用 set_default_session()。

{
  "label": "TP53-MYC resistance network"
}

• list_sessions 会报告活动的内存会话、网络维度、当前默认会话和历史记录保留设置。
• list_artifact_sessions 会查找当前或之前服务进程导出的文件。
• status 会返回单个会话的节点数和相互作用数。
• reset_network 会丢弃当前网络，同时保留会话及其设置。
• delete_session 会永久删除内存中的会话。

set_default_params() 会按会话保存补全默认值。预览和全局补全会复用所有默认值；add_nodes(autoconnect=true) 会复用符号和共识筛选条件。

推荐工作流

对数据库支持的网络，请按以下顺序操作：

1. 调用 create_session() 并保留其 ID。
2. 可选：使用 set_default_params() 配置可复用的连接设置。
3. 使用 create_network(...) 构建网络。
4. 使用 remove_bimodal_interactions() 整理有歧义的边，并在适当时调用 remove_undefined_interactions()。
5. 使用 analyze_connectivity() 检查连通性（孤立节点和完整的连通分量划分）。
6. 如果需要修复，请先调用 preview_connection_impact()，再选择会更改网络的连接策略。
7. 检查生成的拓扑和证据。
8. 使用历史记录工具，将新状态与较早的备选状态进行比较。
9. 使用 export_neko_handoff(...) 导出受完整性保护的 MaBoSS 交接数据。

在迭代构建期间，优先使用 verbosity="summary"。只有在需要实际节点、相互作用、路径或证据时，才使用 preview 或 full。

构建网络

create_network() 支持两种精选数据库后端：

• omnipath，默认值；
• signor。

根据种子基因创建网络：

{
  "list_of_initial_genes": ["EGFR", "KRAS", "TP53", "AKT1"],
  "database": "omnipath",
  "max_len": 2,
  "path_policy": "one_shortest",
  "reuse_policy": "discovered_paths",
  "only_signed": true,
  "consensus": true,
  "session_id": "SESSION_ID",
  "verbosity": "summary"
}

构建参数如下：

参数	说明
max_len	最大路径长度，范围为 1 到 4
path_policy	one_shortest、all_shortest 或 all_bounded
reuse_policy	none、discovered_paths 或 induced_subgraph
only_signed	为 true 时，仅保留带符号的相互作用
consensus	为 true 时，使用资源自身的共识符号标记；这并不总是意味着使用多个数据库或更高置信度
verbosity	summary、preview 或 full

构建过程可能会查询外部生物数据库，耗时数分钟。准备数据库资源和网络时，工具会报告 MCP 进度。

也可以改用现有的 SIF：

{
  "list_of_initial_genes": [],
  "sif_file": "/absolute/path/input.sif",
  "database": "omnipath",
  "session_id": "SESSION_ID",
  "verbosity": "summary"
}

使用 sif_file 时，可以同时提供其他种子基因。若调用未能成功完成，则不会替换会话中已存储的有效网络。

编辑和整理拓扑结构

添加或移除节点和相互作用

• add_nodes 可在一次调用中添加一个或多个基因；默认情况下，会自动将每个新基因与网络中已有的任意直接邻居连接起来（成本低；不会搜索多步路径）。设置 autoconnect=false 可跳过此操作。
• remove_gene 会移除一个节点及其所有关联边。
• remove_interaction 仅移除指定的有向边。

执行破坏性编辑前，请检查当前网络：

{
  "session_id": "SESSION_ID",
  "verbosity": "preview",
  "max_rows": 50
}

调用 list_genes_and_interactions。

基因符号应与检查工具返回的标识符一致。remove_interaction(node_A, node_B) 会移除 node_A → node_B，不会移除反向边。

整理相互作用符号

• remove_bimodal_interactions 会移除被报告为同时具有激活和抑制作用的边。
• remove_undefined_interactions 会移除无法映射为布尔激活或抑制作用的边。

这些操作可简化后续的 BNET 导出，但会改变科学拓扑结构。应用后，请检查受影响的网络及其历史记录。

检查拓扑结构和证据

该服务提供简洁文本和原生 JSON 结构化结果：

• list_genes_and_interactions 返回节点和有向相互作用记录。
• filter_interactions 可按作用、来源或目标筛选，不会修改网络。
• find_paths 报告两个基因之间、长度不超过指定上限的有向路径。
• get_references 返回涉及一个或两个基因的相互作用相关文献证据。
• status 报告当前维度。

例如，检查指向凋亡的抑制性边：

{
  "effect": ["inhibition"],
  "target": "Apoptosis",
  "session_id": "SESSION_ID",
  "verbosity": "preview",
  "format": "markdown",
  "max_rows": 50
}

filter_interactions(format="json") 会更改供模型读取的文本格式；工具的结构化结果仍可独立获取。

审计和修复连通性

analyze_connectivity() 会报告孤立节点（即没有关联边的节点）以及网络的完整连通分量划分。在导出为 BNET 或进行交接导出前，请使用此工具。

探查候选变更

preview_connection_impact() 会评估可能的修复方向，但不会更改活动网络：

方法	结果
hubs	对可能有助于确定修复方向的高连接度基因进行排序
relax_max_len	模拟增大已存储的最大路径长度
unsigned	模拟允许无符号相互作用

示例：

{
  "method": "relax_max_len",
  "session_id": "SESSION_ID",
  "verbosity": "preview",
  "format": "markdown"
}

模拟方法会在副本上运行。预测的变更不会提交到会话中。

应用所选策略

请参阅 NeKo 的简明 连接策略指南， 选择符合研究问题的拓扑结构以及路径／复用策略。

bridge_components() 连接两个明确指定的分组：

{
  "comp_a": ["EGFR", "KRAS"],
  "comp_b": ["TP53", "BAX"],
  "max_len": 2,
  "mode": "OUT",
  "only_signed": true,
  "consensus": true,
  "session_id": "SESSION_ID"
}

comp_a／comp_b 必须是基因符号（例如，来自 analyze_connectivity() 输出中某个组件的 nodes 列表），不能使用 analyze_connectivity() 为每个组件报告的数字 component_id——该 ID 是报告标签，不是有效的基因名称。

mode 可设为 OUT、IN 或 ALL。

connect_targeted_nodes() 支持：

• connect_to_upstream_nodes；
• connect_subgroup。

apply_global_connection() 支持：

• complete_connection，并需明确指定 path_policy 和 reuse_policy；
• connect_network_radially，并需将 direction 设为 "OUT" 或 "IN"；
• connect_as_atopo，并需将 strategy_mode 设为 "radial" 或 "complete"，还可选用基因符号列表 outputs 来锚定拓扑。此策略会持续循环，直到网络连接到所有声明的输出，因此在大型网络上的开销没有上限。

基于数据库的连接工具可能开销很大——complete_connection 会对每一对节点执行 O(N^2) 操作，而 connect_as_atopo 的开销没有上限。每次应用所选策略后，都应重新检查组件并比较历史状态。

分支网络历史记录

NeKo 会自动为其支持的拓扑变更操作记录快照。MCP 服务会直接公开 NeKo 原生的历史记录，因此撤销、重做、检出和比较都能保留精确的 NeKo 网络状态。

列出状态

list_network_history() 会返回：

• 当前状态的确切 ID；
• 保留的状态 ID；
• 父子关系；
• 每个状态的节点数和边数；
• 配置的保留上限。

状态 ID 是标识符，不是列表位置。导航或比较之前，务必通过 list_network_history() 获取这些 ID。

导航

使用单一工具 navigate_network_history()：

{
  "action": "checkout",
  "state_id": 3,
  "session_id": "SESSION_ID"
}

支持的操作如下：

操作	state_id 行为
undo	移至父状态；必须省略 state_id
redo	移至子状态；只有一个明确的子状态时，可以省略该 ID
checkout	移至确切的已保存状态；必须提供 state_id

导航不会删除其他已保存状态。如果检出较早的状态后又对其进行修改，NeKo 会保留之前的后续状态，并在单独的分支上记录新的拓扑。

比较而不导航

compare_network_states(state_a, state_b) 会报告新增和删除的节点及相互作用，但不会更改当前检出的状态：

{
  "state_a": 2,
  "state_b": 5,
  "session_id": "SESSION_ID"
}

配置保留策略

set_network_history_limit(max_states) 用于设置每个会话的策略：

• null 表示保留不受限的历史记录；
• 整数必须至少为 2；
• 在构建网络前设置的策略会在创建网络时生效；
• 降低上限可能会立即且不可逆地清除较早的快照。

降低上限前，请调用 list_network_history()。

渲染历史记录

读取：

neko://session/{session_id}/history

即可获取只读 HTML，其中包含 NeKo 的内嵌 SVG 历史记录图。此资源不会更改当前检出的状态。服务使用随附的 PyGraphviz 渲染 NeKo 的历史有向图，而不是使用外部 dot 可执行文件；渲染失败时会返回资源错误。

导出与 MaBoSS 交接

独立导出

export_network(format="sif") 会写入独立的制表符分隔相互作用网络。export_network(format="bnet") 会为 MaBoSS 写入布尔模型。

BNET 导出要求网络连通。它会清理布尔规则中无效的名称，并报告重命名的节点，以及标识符规范化后移除的重复规则。使用 list_bnet_files() 查看会话中的 BNET 构件。

已验证的 NeKo 到 MaBoSS 交接

如果下一步要在 MaBoSS MCP 服务中进行模拟，优先使用 export_neko_handoff()：

{
  "biological_context": "EGFR-driven survival and apoptosis decision",
  "output_nodes": ["Apoptosis", "Proliferation"],
  "artifact_prefix": "egfr_decision_v1",
  "session_id": "SESSION_ID"
}

交接过程：

• 要求网络已连接，且 biological_context 非空；
• 写入经过清理的 BNET 和带版本号的 JSON 清单；
• 记录精确的布尔节点、已声明的输出、节点重命名、已移除的重复项、软件包版本、会话来源信息，以及当前的 NeKo 历史状态；
• 使用工件完整性元数据保护这两个文件；
• 将请求的原始 NeKo 输出名称转换为与之完全对应的清理后 BNET 名称；并且
• 拒绝覆盖已有的工件文件对。

每次保留交接文件时，都要为 artifact_prefix 选择一个新值。可以省略 output_nodes，但此时 MaBoSS 必须在运行模拟前选择一小组输出节点。

将返回的清单路径传递给 MaBoSS import_neko_handoff()。也可以将独立的 BNET 路径传递给 MaBoSS bnet_to_bnd_and_cfg()，但该方式不会保留带类型的科学上下文和来源清单。

工具参考

类别	工具
会话	create_session、list_sessions、list_artifact_sessions、set_default_session、status、reset_network、delete_session
构建和编辑	create_network、set_default_params、add_nodes、remove_gene、remove_interaction
整理	edit_interactions、remove_bimodal_interactions、remove_undefined_interactions
检查和证据	list_genes_and_interactions、filter_interactions、find_paths、get_references、analyze_connectivity、analyze_gene_set
连接策略	preview_connection_impact、bridge_components、connect_targeted_nodes、apply_global_connection
分支历史	list_network_history、navigate_network_history、compare_network_states、set_network_history_limit
导出和工件	export_network、export_neko_handoff、export_biomass_handoff、list_bnet_files、clean_generated_files

资源和提示词

名称或 URI	内容
docs://neko/agent_manual	推荐的 Agent 工作流和操作规则
neko://session/{session_id}/history	以行内 SVG HTML 呈现的分支历史
neko_workflow_prompt	作为 MCP 提示词提供的操作手册

结构化输出和错误

检查、会话、历史、导出和交接工具除了提供简洁的模型可读文本外，还会返回 JSON 原生结构化结果。这样，MCP 主机无需解析 Markdown，即可获取精确的节点、相互作用、状态 ID、维度、路径、来源信息和工件元数据。

无效标识符、缺少先决条件、不支持的策略、数据库操作失败、未连接时尝试导出，以及其他建模失败，都会作为 MCP 工具错误返回，并附带恢复指南。请更正参数或完成指定的先决操作，然后在同一会话中重试。

工件清理

clean_generated_files(session_id=...) 会删除所选会话的导出工件，但不会重置其内存中的网络。这是破坏性操作。调用前，请保留复现所需的任何 SIF、BNET 或交接文件。

如果要同时丢弃网络状态和工件，请先清理生成的文件，再调用 delete_session()。

延伸阅读

• NeKo 文档
• 探索 NeKo 中的网络历史
• NeKo 源码
• MCP Python SDK v2 结构化输出
• MCP Python SDK v2 资源

导出 ODE 构建交接文件

export_biomass_handoff(biological_context, artifact_prefix="neko_to_biomass", session_id=...) 会写入网络 JSON 和受完整性保护的 neko-to-biomass 清单。它会保留原始节点标识符、稳定的边 ID、所有引用，以及可用的机制、数据库和上下文列。重复的相同交互会合并其引用列表。非连通和无符号交互仍可用于证据整理。

使用 BioMASS 的 import_neko_handoff 导入清单。调用方 Agent 随后会阅读文献，并提出带有证据或明确假设的反应。此导出不会指定速率定律或动力学参数。现有的 export_neko_handoff 仍会为 MaBoSS 导出布尔模型。

工件存储使用共享缓存根目录或 MCP_BIOMODELLING_ARTIFACT_ROOT， 并采用 NeKo/<session_id> 命名空间。旧版包内工件仍会列出其位置。请参阅根 README 的工件存储部分。

create_network 接受可选的 parent_manifest 和 derived_from 参数，用于导入 SIF。 父清单必须是 SIF 导出中经过验证的 .lineage.json；若使用经过编辑的副本，则必须通过 derived_from 指定未修改的父 SIF。SIF/BNET 导出会在同级 .lineage.json 文件中保留源哈希，且不受交接审批影响。

有证据支持的交互编辑（Wave 2）

借助更新后的 NeKo 整理 API，edit_interactions 可接受针对现有节点的至多 20 个显式 add 或 set_effect 操作。每项操作都需要提供效应、理由和出版物证据。如果提供了其他引文，则 PMID 为可选项；绝不会编造缺失的引用。请从 status 获取确切的网络/状态 ID，并与会话 ID 一起传入。过时的请求、含糊的端点或冲突的添加都会失败，且不会部分修改批次。此功能不授予科学授权。

检查结果会保留手动来源，并将原始证据与编辑理由分开。现有历史记录工具会提供有界摘要和精确状态详情资源。使用 export_network(format='history') 保存保留的分支、快照和说明，然后使用 Network.from_history(path) 恢复。数据库身份报告的仅是构建时使用的名称。

SIF/BNET 导出和交接文件会包含经过验证的历史记录/溯源伴随文件。请将引用的文件放在一起，并使用配套的 MCP 包读取新清单。有关约定的 API、兼容性表、来源要求和测得的接口开销，请参阅 Wave 2 集成。