Piaso MCP

PIASO-for-agents

Make the [PIASO](https://piaso.org) 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](https://fishelllab.hms.harvard.edu) (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 runs every canonical block against the pinned component versions on every push, nightly, and on component releases, so the guidance cannot silently rot.

Hub v0.2.2 · piaso-mcp 0.1.1 — tested against 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).

The ecosystem

Independently-installable packages under github.com/genecell, in four layers. Dependencies run one way (cytorete → piaso-tools → cosg + cytome; laris → cosg), and pip install piaso-tools already brings COSG and cytome.

Each component is independently installable — a COSG-only, cytome-only or LARIS-only user is a first-class citizen, and every canonical/components/*.md assumes nothing else is installed. The hub's unique value is documenting how the components compose, and the cross-component choices no single repo can make: SCALAR vs LARIS (dissociated vs spatial ligand–receptor — same CellChatDB either way), AnnData vs `.cytome` (in memory vs streamed — same function calls), COSG vs cytorete (marker genes vs the TFs that drive them), Python vs R (COSG → COSGR, cytome → cytome (R); everything else via a .cytome handoff), and which annotation route (marker sets, reference projection, joint embedding, or a gene list against PIASOmarkerDB).

Inside piaso-tools

Full reference: canonical/components/piaso.md. Every function takes data= as an AnnData, an open cytome Dataset or a .cytome path.

Methods introduced by PIASO

Pipeline building blocks (scanpy-free)

What an agent gets

• canonical/overview.md — the router: task → component table and the seven decision rules.
• canonical/components/ — self-sufficient references for PIASO, COSG (+ COSGR), cytome (+ R), LARIS, Emergene, cytorete, with executed code blocks and the data-object contract of every call.
• canonical/workflows/ — end-to-end scRNA-seq (scanpy-free), streaming on a .cytome, marker-based annotation + reference projection, PIASOmarkerDB annotation, ligand–receptor (SCALAR and LARIS), spatial transcriptomics, gene regulatory networks.
• canonical/gotchas.md (layer contracts, deprecated names, the as_dict tuple, species-cased prefixes), canonical/data.md (registry, fixtures), and the piaso.org tutorial index (generated into every target) so the agent can point the user at the executed tutorial for their platform.

Install (per agent)

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-agents

Claude.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.ai

The 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.mdc

GitHub 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.md

OpenAI 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://piaso.org/llms.txt          # and https://piaso.org/llms-full.txt

These are the hub's dist/llms/piaso.org/ files (absolute links); the relative-link versions are at dist/llms/.

MCP server

piaso-mcp serves the PIASO ecosystem docs, the piaso.org tutorial index, the PIASO-data registry and the live PIASOmarkerDB — no Python packages required. Tools: search_docs, get_api, compare_implementations, resolve_install, list_tutorials, version_matrix, check_versions (PyPI vs tested versions), list_datasets / get_dataset (live registry), 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.

Prerequisite (all clients): uv

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.uv

Then 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.

Claude Code — key mcpServers

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: ✔ Connected

Or edit ~/.claude.json (user) / project .mcp.json:

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

Cursor — key mcpServers

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.

Windsurf — key mcpServers

File: ~/.codeium/windsurf/mcp_config.json (open via Settings → Cascade → MCP Servers → Manage → raw config):

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

VS Code (GitHub Copilot, Agent mode) — key servers (note: not mcpServers)

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:

cod