Make the PIASO single-cell omics ecosystem first-class for any coding agent — Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, Aider — from one canonical, agent-neutral knowledge pack.
Maintained by The Fishell Laboratory (Harvard
Medical School / Broad Institute). Every agent-specific format (Claude skill, Cursor rules, AGENTS.md,
llms.txt, MCP server) is a generated artifact built from canonical/ — never a
hand-maintained copy. A CI drift check (python build.py --check) fails the build if any
dist/ artifact is out of sync with canonical/, and the code-block test suite re-runs on
every component release, so the guidance cannot silently rot.
Independently-installable packages under github.com/genecell:
| Component | Package | Language | Role |
|---|---|---|---|
| PIASO | piaso-tools |
Python (+Rust) | Umbrella single-cell toolkit — see the capability table below |
| COSG | cosg |
Python | Fast, specific marker-gene identification |
| COSGR | COSG |
R | COSG for Seurat / SingleCellExperiment |
| LARIS | laris |
Python | Ligand–receptor interaction in spatial transcriptomics |
| Emergene | emergene |
Python | Individual-cell differential expression across conditions |
| PIASO-data | — | data | Genome references + tutorial datasets |
Each component is independently installable — you can pip install cosg (or laris, or
emergene) on its own, so a COSG-only user is a first-class citizen. Note the dependency
direction, though: installing piaso-tools (and laris) also pulls in cosg, so a PIASO
user always has COSG available. The hub's unique value is documenting how the components
compose, and the cross-component choices no single repo can make (e.g. SCALAR vs LARIS for
ligand–receptor: spatial data → LARIS, dissociated single-cell → SCALAR).
The piaso package is itself a toolkit. Full references live in
canonical/components/piaso.md. Grouped by what is a
PIASO-introduced method vs. a convenience wrapper around a standard step:
Methods introduced by PIASO
| Capability | Entry point | What it does |
|---|---|---|
| INFOG normalization | piaso.tl.infog |
Information-content normalization of raw UMI counts + HVG selection |
| GDR (marker-gene-guided DR) | piaso.tl.runGDR / runGDRParallel |
Embedding whose axes are per-cluster COSG-marker scores; also does batch integration |
| Gene-set scoring | piaso.tl.score |
Optimized expression-matched-control gene-set enrichment scoring — Rust-accelerated |
| Cell-type prediction | piaso.tl.predictCellTypeByMarker / predictCellTypeByGDR |
Marker-based and reference-based annotation |
| SCALAR (single-cell LR) | piaso.tl.runSCALAR |
Cell-type-resolved ligand–receptor inference for dissociated scRNA-seq |
| Marker-guided integration | piaso.tl.stitchSpace |
Batch correction of an embedding via COSG-marker graph pruning |
| PIASOmarkerDB | piaso.tl.queryPIASOmarkerDB / getMarkers / analyzeMarkers |
Client for the curated PIASO marker-gene database (live API) |
Utilities & standard building blocks
| Capability | Entry point | What it does |
|---|---|---|
| SVD embedding | piaso.tl.runSVDLazy / runSVD |
Convenience wrapper around truncated SVD with INFOG-aware HVG (SVD itself is a standard method) |
| Local sub-clustering | piaso.tl.leiden_local |
Re-cluster selected groups locally |
Preprocessing (piaso.pp) |
piaso.pp.table / getCrossCategories / rotateSpatialCoordinates |
Table/cross-tab helpers and spatial-coordinate rotation |
Plotting (piaso.pl) |
piaso.pl.plot_embeddings_split / plot_features_violin / plotConfusionMatrix / LR plots |
Embedding, violin, confusion-matrix, and ligand–receptor plots |
Users work in their own analysis repos, so drop the right snippet into your setup. All of
these are generated from canonical/ and live under dist/.
Claude Code — add this repo as a plugin marketplace and install the piaso skill:
claude plugin marketplace add genecell/PIASO-for-agents
claude plugin install piaso@PIASO-for-agentsClaude.ai (web app) — upload the generated skill as a Skill (Pro/Max/Team/Enterprise, with
code execution enabled). Download the dist/claude/skills/piaso/
folder, zip it, then in claude.ai go to Settings → Capabilities → Skills → Create skill and
upload the zip:
# from a clone of this repo:
cd dist/claude/skills && zip -r piaso-skill.zip piaso # -> upload piaso-skill.zip in claude.aiThe local MCP server below is stdio-only, so it does not work in the web app — use the Skill
upload (or the llms.txt URL) on claude.ai; use MCP in Claude Code / Cursor / Codex.
Cursor — download the rule into your project's .cursor/rules/:
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/cursor/.cursor/rules/piaso.mdc \
-o .cursor/rules/piaso.mdcGitHub Copilot — copy the instructions file into your repo:
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/copilot/.github/copilot-instructions.md \
-o .github/copilot-instructions.mdOpenAI Codex — add the AGENTS.md pointer below to your project's AGENTS.md (Codex's
primary instructions file), and/or register the MCP server (see the MCP server section
below — Codex is covered there).
AGENTS.md (Aider / Zed / Codex / any AGENTS.md-aware agent) — append the hub pointer to
your project's AGENTS.md (or copy dist/agents/AGENTS.md):
This project uses the PIASO single-cell omics ecosystem. Agent-neutral, tested docs for every component (Python + R), plus the cross-component decision rules, live at https://github.com/genecell/PIASO-for-agents
llms.txt (any model with web access) — point the tool at:
https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/llms/llms.txt
(and llms-full.txt alongside it). These can also be served from https://piaso.org/llms.txt.
piaso-mcp serves the PIASO ecosystem docs plus the live PIASOmarkerDB — no
Python packages required. Tools: search_docs, get_api, compare_implementations,
resolve_install, list_datasets, and the live DB proxies query_marker_db,
get_markers, list_studies. It is a local stdio server (not a hosted remote endpoint),
so it works in Claude Code / Cursor / VS Code / Windsurf / Zed / Codex / Cline, but not in
the claude.ai web app — use the Skill upload there.
The server runs via uvx, which ships with uv. This is the one thing "no packages
needed" doesn't cover — install it once:
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.uvThen confirm it's reachable: uvx --version. If that says "command not found", uv's bin
dir isn't on your PATH — either add it, or replace "uvx" in the configs below with the
absolute path from which uvx (Windows: where uvx). First launch downloads the package
(~30 s); later launches are cached.
The MCP config key and file location differ per client — pick your agent below.
Easiest is the CLI (no hand-editing, and it handles the PATH issue in one line):
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: ✔ ConnectedOr edit ~/.claude.json (user) / project .mcp.json:
File: ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Same shape as Claude Code:
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }Enable it under Settings → MCP.
File: ~/.codeium/windsurf/mcp_config.json (open via Settings → Cascade → MCP Servers → Manage → raw config):
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }Workspace file .vscode/mcp.json, or user settings.json under "mcp". VS Code also wants a type:
// .vscode/mcp.json
{ "servers": { "piaso": { "type": "stdio", "command": "uvx", "args": ["piaso-mcp"] } } }Or one-shot from the terminal:
code --add-mcp '{"name":"piaso","command":"uvx","args":["piaso-mcp"]}'File: ~/.config/zed/settings.json. Zed nests under context_servers and marks custom servers with "source": "custom":
{
"context_servers": {
"piaso": { "source": "custom", "command": "uvx", "args": ["piaso-mcp"], "env": {} }
}
}Codex is the odd one out: its config is TOML, in ~/.codex/config.toml. Add a table:
[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"Or use the CLI (handles the file for you):
codex mcp add piaso -- uvx piaso-mcp
codex mcp list # verify it's registeredCline: MCP Servers → Configure (writes cline_mcp_settings.json). Continue: ~/.continue/config (mcpServers). Both use the standard shape:
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }After configuring, restart the client — MCP tools are loaded at startup, so a running
session won't see the server until it's relaunched. If it doesn't connect, 99% of the time
it's the uv/PATH prerequisite above.
canonical/ # the ONLY hand-written content (agent-neutral markdown + meta.yaml)
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) against PIASO-data fixtures
.claude-plugin/ # marketplace + plugin manifest (repo root, for `claude plugin marketplace add`)
.github/ # sync-check + test CI (re-runs on component releases + nightly)
Cite each component by its own paper — see canonical/meta.yaml.
PIASO: Wu, S.J., Dai, M. et al. Nature (2026), DOI 10.1038/s41586-025-09996-8.
Developed and maintained by The Fishell Laboratory (Harvard Medical School / Broad Institute). Contact: Min Dai — dai@broadinstitute.org.
BSD-3-Clause. See LICENSE.
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }