piaso-mcp

面向 Agent 的 PIASO

让 PIASO 单细胞组学生态系统成为所有编码 Agent 的一等支持对象——Claude Code、Cursor、Copilot、Codex、Windsurf、Cline、Aider 均可使用同一份规范的、与 Agent 无关的知识包。

由 The Fishell Laboratory（Harvard Medical School / Broad Institute）维护。每种面向特定 Agent 的格式（Claude 技能、Cursor 规则、AGENTS.md、llms.txt、MCP 服务）都是基于 canonical/ 构建的生成产物，而非手动维护的副本。CI 漂移检查（python build.py --check）会在任何 dist/ 产物与 canonical/ 不同步时导致构建失败；代码块测试套件会在每次推送、每晚以及组件发布时，针对固定的组件版本运行所有规范代码块，因此指南不会在无人察觉的情况下过时。

Hub v0.2.2 · piaso-mcp 0.1.1——已针对 piaso-tools 1.2.6 · cosg 1.2.0 · cytome 0.3.6 · laris 0.14.0 · emergene 1.0.2 · cytorete 0.1.1 · COSGR 1.0.0 · cytome (R) 0.1.3（2026-09-29）测试。

生态系统

github.com/genecell 下可独立安装的包，分为四层。依赖关系单向流动（cytorete → piaso-tools → cosg + cytome；laris → cosg），且 pip install piaso-tools 已包含 COSG 和 cytome。

层级	组件	包	语言	作用
分析	PIASO	piaso-tools	Python + Rust	独立的完整流程——读取 10x 数据、质控、双细胞检测、INFOG、SVD / GDR、Leiden / UMAP、PIASOscore、注释、SCALAR、PIASOmarkerDB 客户端、绘图、piaso.data。无需 scanpy。
存储	cytome	cytome	Python	单文件 SQLite .cytome：矩阵、可通过 SQL 查询的细胞/基因表、嵌入、图、片段、组织图像、来源信息——所有组件都从中流式读取
	cytome (R)	cytome (r-universe)	R	在无需 Python 的情况下，将同一文件读入 Seurat 或 SingleCellExperiment，或写入该文件 / 从中流式读取
方法	COSG	cosg	Python	通过余弦特异性寻找标记基因——解析 p 值、GPU、支持批次感知，可从 cytome 流式读取
	COSGR	COSG (r-universe / conda-forge)	R	面向 Seurat / SingleCellExperiment 的 COSG
	LARIS	laris	Python	空间转录组学中的配体–受体互作；精确 p 值；跨条件比较
	Emergene	emergene	Python	不同条件下单细胞差异表达分析
	cytorete	cytorete	Python	在 PIASO 技术栈上构建细胞类型分辨的基因调控网络（调控子）
数据	PIASO-data	—	data	教程数据集（Zenodo，含五个 .cytome 图谱）+ 基因组参考；由 piaso.data 读取的注册表

每个组件都可独立安装——仅使用 COSG、cytome 或 LARIS 的用户也享有一等支持，每个 canonical/components/*.md 都不假设安装了其他任何组件。Hub 的独特价值在于说明各组件如何组合，并记录单个代码库无法决定的跨组件选择：SCALAR 还是 LARIS（解离样本还是空间配体–受体分析——两者均使用同一 CellChatDB）、AnnData 还是 .cytome（内存处理还是流式处理——函数调用相同）、COSG 还是 cytorete（标记基因还是驱动这些基因的 TF）、Python 还是 R（COSG → COSGR、cytome → cytome (R)；其他一切通过 .cytome 交接），以及选择哪种注释路径（标记集、参考投影、联合嵌入，或使用基因列表查询 PIASOmarkerDB）。

piaso-tools 内部

完整参考文档：canonical/components/piaso.md。每个函数都接受 data=，其值可以是 AnnData、已打开的 cytome Dataset 或 .cytome 路径。

PIASO 引入的方法

功能	入口点	功能说明
INFOG 归一化	piaso.tl.infog	对原始 UMI 计数进行信息含量归一化，并筛选信息性基因
GDR（标记基因引导的 DR）	piaso.tl.runGDR / runGDRParallel / projectGDR	生成嵌入，其坐标轴为各组的 COSG 标记评分；按身份整合批次；支持冻结的参考空间
基因集评分（PIASOscore）	piaso.tl.score	使用表达匹配对照进行评分，并计算每个细胞的 p 值；通过一次 Rust 矩阵乘法处理整个通路数据库
细胞类型预测	piaso.tl.predictCellTypeByMarker / predictCellTypeByGDR	基于标记基因集和参考数据进行注释
SCALAR（单细胞 LR）	piaso.tl.specificity_matrix + runSCALAR	针对解离数据进行细胞类型分辨的配体–受体推断；通过 piaso.data.load_lr_database 使用 CellChatDB
标记引导的整合	piaso.tl.stitchSpace	通过 COSG 标记图剪枝对嵌入进行批次校正
PIASOmarkerDB	piaso.tl.getMarkers / analyzeMarkers	精选标记数据库的客户端（36 项研究，实时 API）
基序扫描	piaso.pp.scan_motifs + piaso.data 基序/基因组加载器	Rust PWM 引擎，cytorete 以此为基础构建

管线构建模块（无需 scanpy）

功能	入口点
读取 10x / Cell Ranger	piaso.pp.read_10x_h5、read_10x、importCellRanger（→ cytome）
质控、双细胞检测、过滤	piaso.pp.calculateCellMetrics、scrublet、filter_cells、calculateGroupMetrics
嵌入、图、聚类、UMAP	piaso.tl.runSVD、neighbors、leiden、umap、leiden_local、runHarmony
数据集、基因组、基序数据库、CellChatDB	piaso.data.load_dataset、fetch_genome、fetch_2bit、fetch_jaspar、load_lr_database
绘图	piaso.pl.embedding、dotplot、violin、scatter、sankey、stackedBarplot、plot_embeddings_split（以及 cytome 上的组织图像叠加图）、piaso.settings.set_figure_params

Agent 可获得的内容

• canonical/overview.md — 路由指南：任务 → 组件表，以及七条决策规则。
• canonical/components/ — PIASO、COSG（及 COSGR）、cytome（及 R）、LARIS、Emergene、cytorete 的自包含参考文档，其中包含已执行的代码块，以及每次调用的数据对象约定。
• canonical/workflows/ — 端到端 scRNA-seq（无需 scanpy）、在 .cytome 上流式处理、基于标记的注释 + 参考投影、PIASOmarkerDB 注释、配体–受体（SCALAR 和 LARIS）、空间转录组学、基因调控网络。
• canonical/gotchas.md（层约定、已弃用名称、as_dict 元组、物种名区分大小写的前缀）、canonical/data.md（注册表、测试数据），以及 piaso.org 教程索引（已生成到每个目标中），以便 Agent 将用户引导至适用于其平台的已执行教程。

安装（按 Agent）

用户在自己的分析仓库中工作，因此请将相应代码片段放入你的配置中。以下内容均由 canonical/ 生成，位于 dist/ 下。

Claude Code — 将此仓库添加为插件市场，并安装 piaso 技能：

claude plugin marketplace add genecell/PIASO-for-agents
claude plugin install piaso@PIASO-for-agents

Claude.ai（网页应用） — 将生成的技能作为 Skill 上传（Pro/Max/Team/Enterprise，并启用代码执行）。下载 dist/claude/skills/piaso/ 文件夹，将其压缩，然后在 claude.ai 中前往 Settings → Capabilities → Skills → Create skill 并上传压缩包：

# from a clone of this repo:
cd dist/claude/skills && zip -r piaso-skill.zip piaso    # -> upload piaso-skill.zip in claude.ai

下方的本地 MCP 服务仅支持 stdio，因此无法在网页应用中使用；在 claude.ai 中请上传 Skill（或使用 llms.txt URL）；在 Claude Code / Cursor / Codex 中使用 MCP。

Cursor — 将规则下载到项目的 .cursor/rules/：

curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/cursor/.cursor/rules/piaso.mdc \
  -o .cursor/rules/piaso.mdc

GitHub Copilot — 将说明文件复制到仓库中：

curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/copilot/.github/copilot-instructions.md \
  -o .github/copilot-instructions.md

OpenAI Codex — 将下方的 AGENTS.md 指引添加到项目的 AGENTS.md（Codex 的主要说明文件），和/或注册 MCP 服务（参见下方的 MCP 服务部分，那里涵盖了 Codex）。

AGENTS.md（Aider / Zed / Codex / 任何兼容 AGENTS.md 的 Agent） — 将中心指引附加到项目的 AGENTS.md（或复制 dist/agents/AGENTS.md）：

此项目使用 PIASO 单细胞组学生态系统。每个组件（Python + R）的中立于 Agent、经过测试的文档，以及跨组件决策规则，均位于 https://github.com/genecell/PIASO-for-agents

llms.txt（任何可访问网络的模型） — 将工具指向：

https://piaso.org/llms.txt          # and https://piaso.org/llms-full.txt

这些是中心的 dist/llms/piaso.org/ 文件（绝对链接）；相对链接版本位于 dist/llms/。

MCP 服务

piaso-mcp 提供 PIASO 生态系统文档、piaso.org 教程索引、PIASO-data 注册表和实时 PIASOmarkerDB，无需 Python 包。工具包括：search_docs、get_api、compare_implementations、resolve_install、list_tutorials、version_matrix、check_versions（PyPI 与已测试版本对比）、list_datasets / get_dataset（实时注册表），以及实时数据库代理 query_marker_db、get_markers、list_studies。它是本地 stdio服务（不是托管的远程端点），因此可在 Claude Code / Cursor / VS Code / Windsurf / Zed / Codex / Cline 中使用，但不能在 claude.ai 网页应用中使用；请在网页应用中上传 Skill。

前置条件（所有客户端）：uv

此服务通过 uvx 运行，而 uvx 随 uv 一同提供。这是“无需安装软件包”未涵盖的一项要求——只需安装一次：

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or:  pipx install uv   |   pip install --user uv   |   brew install uv   |   winget install astral-sh.uv

然后确认它可用：uvx --version。如果显示“command not found”，说明 uv 的 bin 目录不在 PATH 中——请将其添加到 PATH，或在下方配置中将 "uvx" 替换为 which uvx 返回的绝对路径（Windows：where uvx）。首次启动时会下载软件包（约 30 秒）；后续启动会使用缓存。

各客户端的 MCP 配置键和文件位置各不相同——请在下方选择你的 Agent。

Claude Code — 键 mcpServers

最简单的方式是使用 CLI（无需手动编辑，并且可以用一行命令处理 PATH 问题）：

claude mcp add piaso --scope user -- uvx piaso-mcp
# uvx not on PATH? use its absolute path:
claude mcp add piaso --scope user -- "$(which uvx)" piaso-mcp

claude mcp get piaso        # verify → Status: ✔ Connected

或者编辑 ~/.claude.json（用户级）/ 项目中的 .mcp.json：

{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }

Cursor — 键 mcpServers

文件：~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）。格式与 Claude Code 相同：

{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }

在 Settings → MCP 中启用。

Windsurf — 键 mcpServers

文件：~/.codeium/windsurf/mcp_config.json（通过 Settings → Cascade → MCP Servers → Manage → raw config 打开）：

{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }

VS Code（GitHub Copilot，Agent 模式）— 键 servers（注意：不是 mcpServers）

工作区文件 .vscode/mcp.json，或 "mcp" 下的用户 settings.json。VS Code 还要求设置 type：

// .vscode/mcp.json
{ "servers": { "piaso": { "type": "stdio", "command": "uvx", "args": ["piaso-mcp"] } } }

或者在终端中一次性运行：

code --add-mcp '{"name":"piaso","command":"uvx","args":["piaso-mcp"]}'

Zed — 键 context_servers（格式不同）

文件：~/.config/zed/settings.json。Zed 使用 context_servers 作为嵌套配置，并通过 "source": "custom" 标记自定义服务：

{
  "context_servers": {
    "piaso": { "source": "custom", "command": "uvx", "args": ["piaso-mcp"], "env": {} }
  }
}

Codex（OpenAI Codex CLI）— TOML，表 [mcp_servers.<name>]（不是 JSON！）

Codex 与众不同：它的配置是 TOML，位于 ~/.codex/config.toml。添加一个表：

[mcp_servers.piaso]
command = "uvx"
args = ["piaso-mcp"]
# uvx not on PATH? give the absolute path from `which uvx`:
# command = "/home/you/.local/bin/uvx"

也可以使用 CLI（会自动处理文件）：

codex mcp add piaso -- uvx piaso-mcp
codex mcp list        # verify it's registered

Cline / Continue（VS Code 扩展）— 键 mcpServers

Cline：MCP Servers → Configure（写入 cline_mcp_settings.json）。Continue：~/.continue/config（mcpServers）。两者都使用标准格式：

{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }

---

配置完成后，请重启客户端——MCP 工具会在启动时加载，因此正在运行的会话要等到重新启动后才能看到服务。如果无法连接，99% 的情况下都是上述 uv/PATH 前置条件导致的。

仓库结构

canonical/       # the ONLY hand-written content (agent-neutral markdown + meta.yaml, incl. the tutorial index)
build.py         # canonical/ -> all targets (pure text transforms); --check is the CI drift guard
dist/            # ALL GENERATED — never hand-edited (claude/ agents/ cursor/ copilot/ llms/ mcp/)
mcp/             # piaso-mcp source (local stdio server; serves knowledge + public data only)
tests/           # executes every canonical code block (Python + R) on the fixtures; heavy spatial/regulon runs nightly
.claude-plugin/  # the marketplace (repo root, for `claude plugin marketplace add`); the plugin is dist/claude
.github/         # sync-check + test CI (re-runs on component releases + nightly) + PyPI / MCP-registry publish

相关工具（独立项目，列于 piaso.org 的 Agents and project tooling 页面）： stato — 面向长期计算项目的结构化专业知识管理；PlanDrop — 在远程机器上为 Claude Code 提供计划审核与执行。

更新日志

请参阅 CHANGELOG.md——其中记录了 hub 内容发布和 piaso-mcp 版本，以及各版本经过测试的组件版本。

引用

请分别引用各组件对应的论文——参见 canonical/meta.yaml。 PIASO：Wu, S.J., Dai, M. et al. Nature (2026)，DOI 10.1038/s41586-025-09996-8。COSG / COSGR：Dai M, Pei X, Wang X-J，Briefings in Bioinformatics 23(2):bbab579 (2022)。LARIS：Dai M, Török T, Sun D, et al.，bioRxiv (2025)，DOI 10.1101/2025.11.26.690796。cytome 和 cytorete 尚无论文——请引用其代码仓库。

维护者

由 The Fishell Laboratory 开发和维护 （Harvard Medical School / Broad Institute）。 联系：Min Dai — [email protected]。

许可证

BSD-3-Clause。请参阅 LICENSE。