OmicVerse MCP 运行时与故障排查

OmicVerse MCP 运行时与故障排查#

本页面介绍服务器如何管理数据、持久化、取消操作和日志。

句柄#

adata_id#

adata_id 是数据集的稳定 MCP 句柄。数据集本身保留在服务器端。

  • 使用 ov.utils.read 或 ov.datasets.* 加载

  • 将返回的句柄传递给下游工具

  • 使用 ov.persist_adata 持久化

  • 使用 ov.restore_adata 恢复

artifact_id#

绘图和导出工具可以将文件注册为 artifact，通过 artifact_id 引用。

instance_id#

P2 基于类的工具使用 instance_id 来支持多步骤分析器，如 DEG 或 metacell 工作流程。

句柄类型一览#

句柄类型

前缀

可持久化

示例

adata

adata_

是

加载的数据集

artifact

artifact_

若文件存在于磁盘则是

图表、导出文件

instance

inst_

否

P2 分析器

持久化#

使用 ov.persist_adata 写入 .h5ad 文件及元数据 sidecar。使用 ov.restore_adata 在之后的会话中恢复。

这是跨客户端重连或进程重启后的推荐恢复路径。

持久化示例#

{"tool_name": "ov.persist_adata", "arguments": {"adata_id": "adata_a1b2c3d4e5f6"}}

{"tool_name": "ov.restore_adata", "arguments": {"path": "/data/ov_persist/adata_a1b2c3d4e5f6.h5ad"}}

会话与可观测性#

常用工具：

  • ov.get_session

  • ov.list_handles

  • ov.get_metrics

  • ov.list_events

  • ov.get_trace

  • ov.list_traces

  • ov.get_health

  • ov.get_limits

示例问题：

  • What's the current session status?

  • Show me the recent tool call traces

  • Show me session metrics

  • List all image artifacts from this session

  • Clean up artifacts older than 1 hour, but show me what would be deleted first

  • Export the full artifact manifest as JSON

示例响应通常如下：

{
  "session_id": "default",
  "adata_count": 1,
  "artifact_count": 3,
  "instance_count": 0
}

[
  {"trace_id": "abc...", "tool_name": "ov.pp.pca", "duration_ms": 245.3, "ok": true}
]

{
  "adata_count": 1,
  "artifact_count": 3,
  "tool_calls_total": 8,
  "tool_calls_failed": 0,
  "artifacts_registered_total": 3
}

AnnData 检查#

在让模型分析数据之前，让其检查当前状态：

  • ov.adata.describe

  • ov.adata.peek

  • ov.adata.find_var

  • ov.adata.value_counts

  • ov.adata.inspect

这些工具减少了幻觉，使工作流程可审计。

取消操作与 Esc#

对于 adata_id 工具，OmicVerse MCP 现在通过持久化的内核支持的运行时来执行它们。

这意味着：

  • 客户端仍然看到正常的 Running... 状态

  • 取消时可以中断运行时

  • 中断后内核通常可以重用

  • 目标是尽可能保留状态，而不是为每个工具调用重建工作进程

实际上，取消操作取决于客户端和底层数值计算代码：

  • 若客户端发送适当的取消或断开信号，服务器可以中断当前运行时

  • 一些深层数值调用可能对中断响应较慢

  • 若运行时变得不健康，服务器可能需要在下次请求前恢复

日志#

stdio#

  • 协议流量使用 stdout

  • 服务器日志写入 stderr

  • 工具调用的开始/结束/失败摘要写入 stderr

streamable-http#

  • 自行运行服务器

  • 直接检查 uvicorn 和服务器日志

  • 这通常是调试连接问题最简单的方法

P2 生命周期#

P2 工具使用多步骤生命周期：

  1. create

  2. run 或特定任务操作，如 annotate / train

  3. results 或 predict

  4. destroy

示例：

ov.bulk.pydeg create -> run -> results -> destroy

instance_id 值仅保存在内存中，服务器重启后会丢失。

限制#

  • P2 工具可能出现在列表中，但在运行时仍可能不可用

  • 扩展运行时在某些环境中受到约束

  • 本地 HTTP 认证仅用于本地开发环境

  • 内置的本地 OAuth 流程仅在内存中，不应暴露给不受信任的网络

  • 服务器在工具执行方面实际上是单进程的

  • 一些长时间的数值步骤可能对中断响应较慢

  • 无结果流式传输：大型输出以完整结果返回

  • 类实例仅保存在内存中，服务器重启后会丢失

  • 并非每个扩展依赖栈在每个环境中都可用

常见问题#

工具缺失#

  • 验证启动时使用的 --phase

  • 让客户端运行 ov.list_tools

  • 对于 P2 工具，检查 ov.describe_tool 中的依赖可用性

adata_id 未找到#

句柄从未创建、已过期或属于另一个会话。使用 ov.list_handles 和 ov.get_session。

图表存在但难以找到#

使用：

  • ov.list_artifacts

  • ov.describe_artifact

  • ov.export_artifacts_manifest

长时间运行的分析阻碍进度#

  • 优先使用本地 HTTP 模式以获得可观测性

  • 在特别耗时的步骤前持久化数据集

  • 使用 ov.get_trace、ov.list_traces 和 ov.list_events 了解已运行的内容

服务器崩溃或连接丢失#

  • 检查 stderr 或 HTTP 服务器日志

  • 检查 stderr 中的 Python traceback 或导入错误

  • 重启 MCP 服务器

  • 若之前已持久化数据集，使用 ov.restore_adata

工具不可用#

  • 请求 ov.describe_tool

  • 检查缺少的可选依赖

  • 安装缺失包后重启

远程服务器连接失败#

  • 单独验证 SSH 连接，例如 ssh -i /path/to/key -p <port> user@host echo ok

  • 确保远程机器上已安装 omicverse[mcp]

  • 检查客户端配置中的远程 Python 路径

预处理步骤因缺少数据需求而失败#

  • 服务器强制执行流程顺序

  • 遵循错误响应中 suggested_next_tools 的建议

  • 典型前提条件：

    • ov.pp.pca 需要 layers["scaled"]

    • ov.pp.neighbors 需要 obsm["X_pca"]

    • ov.pp.umap 需要 uns["neighbors"]

服务器立即退出#

  • 确保已安装 mcp>=1.0

  • 若使用 streamable-http，确保已安装 uvicorn 和 starlette

Claude Code HTTP 连接显示认证/发现错误#

  • 确认服务器以 --transport streamable-http 启动

  • 验证配置的 URL 完全匹配，例如 http://127.0.0.1:8765/mcp

  • 在认证或传输方式更改后重启本地 MCP 服务器，因为本地 OAuth 注册仅在内存中

这些可观测性工具是工作流程出现意外行为时首先应使用的工具。

相关页面#

目录