{
  "markdown": "# PIASO-for-agents\n\n**Make the [PIASO](https://piaso.org) single-cell omics ecosystem first-class for any\ncoding agent — Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, Aider — from one\ncanonical, agent-neutral knowledge pack.**\n\nMaintained by **[The Fishell Laboratory](https://fishelllab.hms.harvard.edu)** (Harvard\nMedical School / Broad Institute). Every agent-specific format (Claude skill, Cursor rules, `AGENTS.md`,\n`llms.txt`, MCP server) is a **generated artifact** built from `canonical/` — never a\nhand-maintained copy. A CI drift check (`python build.py --check`) fails the build if any\n`dist/` artifact is out of sync with `canonical/`, and the code-block test suite runs every\ncanonical block against the **pinned component versions** on every push, nightly, and on\ncomponent releases, so the guidance cannot silently rot.\n\n**Hub v0.2.0 · piaso-mcp 0.1.0 — tested against piaso-tools 1.2.3 · cosg 1.2.0 · cytome 0.3.1 ·\nlaris 0.13.0 · emergene 1.0.2 · cytorete 0.1.1 · COSGR 1.0.0 · cytome (R) 0.1.0 (2026-09-04).**\n\n## The ecosystem\n\nIndependently-installable packages under [github.com/genecell](https://github.com/genecell), in\nfour layers. Dependencies run one way (`cytorete → piaso-tools → cosg + cytome`; `laris → cosg`),\nand `pip install piaso-tools` already brings COSG and cytome.\n\n| Layer | Component | Package | Language | Role |\n|---|---|---|---|---|\n| Analysis | [PIASO](https://github.com/genecell/PIASO) | `piaso-tools` | Python + Rust | Self-contained pipeline — reading 10x data, QC, doublets, **INFOG**, SVD / **GDR**, Leiden / UMAP, **PIASOscore**, annotation, **SCALAR**, PIASOmarkerDB client, plotting, `piaso.data`. **No scanpy required.** |\n| Storage | [cytome](https://github.com/genecell/cytome) | `cytome` | Python | Single-file SQLite `.cytome`: matrices, SQL-queryable cell/gene tables, embeddings, graphs, fragments, tissue images, provenance — what every component streams from |\n| | [cytome (R)](https://github.com/genecell/cytome-r) | `cytome` (r-universe) | R | Read / write / stream the same file into Seurat or SingleCellExperiment, no Python |\n| Methods | [COSG](https://github.com/genecell/COSG) | `cosg` | Python | Marker genes by cosine specificity — analytic p-values, GPU, batch-aware, streams from cytome |\n| | [COSGR](https://github.com/genecell/COSGR) | `COSG` (r-universe / conda-forge) | R | COSG for Seurat / SingleCellExperiment |\n| | [LARIS](https://github.com/genecell/LARIS) | `laris` | Python | Ligand–receptor interaction in **spatial** transcriptomics; exact p-values; cross-condition comparison |\n| | [Emergene](https://github.com/genecell/Emergene) | `emergene` | Python | Individual-cell differential expression across conditions |\n| | [cytorete](https://github.com/genecell/cytorete) | `cytorete` | Python | Cell-type-resolved gene regulatory networks (regulons) on the PIASO stack |\n| Data | [PIASO-data](https://github.com/genecell/PIASO-data) | — | data | Tutorial datasets (Zenodo, incl. five `.cytome` atlases) + genome references; registry read by `piaso.data` |\n\nEach component is **independently installable** — a COSG-only, cytome-only or LARIS-only user is\na first-class citizen, and every `canonical/components/*.md` assumes nothing else is installed.\nThe hub's unique value is documenting how the components **compose**, and the cross-component\nchoices no single repo can make: **SCALAR vs LARIS** (dissociated vs spatial ligand–receptor —\nsame CellChatDB either way), **AnnData vs `.cytome`** (in memory vs streamed — same function\ncalls), **COSG vs cytorete** (marker genes vs the TFs that drive them), **Python vs R** (COSG →\nCOSGR, cytome → cytome (R); everything else via a `.cytome` handoff), and **which annotation\nroute** (marker sets, reference projection, joint embedding, or a gene list against PIASOmarkerDB).\n\n### Inside `piaso-tools`\n\nFull reference: [`canonical/components/piaso.md`](canonical/components/piaso.md). Every function\ntakes `data=` as an AnnData, an open cytome Dataset or a `.cytome` path.\n\n**Methods introduced by PIASO**\n\n| Capability | Entry point | What it does |\n|---|---|---|\n| INFOG normalization | `piaso.tl.infog` | Information-content normalization of raw UMI counts + informative-gene selection |\n| GDR (marker-gene-guided DR) | `piaso.tl.runGDR` / `runGDRParallel` / `projectGDR` | Embedding whose axes are per-group COSG-marker scores; integrates batches by identity; frozen reference spaces |\n| Gene-set scoring (PIASOscore) | `piaso.tl.score` | Expression-matched-control scoring with per-cell p-values; whole pathway databases in one Rust matmul |\n| Cell-type prediction | `piaso.tl.predictCellTypeByMarker` / `predictCellTypeByGDR` | Marker-set and reference-based annotation |\n| SCALAR (single-cell LR) | `piaso.tl.specificity_matrix` + `runSCALAR` | Cell-type-resolved ligand–receptor inference for dissociated data, CellChatDB via `piaso.data.load_lr_database` |\n| Marker-guided integration | `piaso.tl.stitchSpace` | Batch correction of an embedding via COSG-marker graph pruning |\n| PIASOmarkerDB | `piaso.tl.getMarkers` / `analyzeMarkers` | Client for the curated marker database (36 studies, live API) |\n| Motif scanning | `piaso.pp.scan_motifs` + `piaso.data` motif/genome loaders | The Rust PWM engine cytorete builds on |\n\n**Pipeline building blocks (scanpy-free)**\n\n| Capability | Entry point |\n|---|---|\n| Read 10x / Cell Ranger | `piaso.pp.read_10x_h5`, `read_10x`, `importCellRanger` (→ cytome) |\n| QC, doublets, filtering | `piaso.pp.calculateCellMetrics`, `scrublet`, `filter_cells`, `calculateGroupMetrics` |\n| Embedding, graph, clusters, UMAP | `piaso.tl.runSVD`, `neighbors`, `leiden`, `umap`, `leiden_local`, `runHarmony` |\n| Datasets, genomes, motif DBs, CellChatDB | `piaso.data.load_dataset`, `fetch_genome`, `fetch_2bit`, `fetch_jaspar`, `load_lr_database` |\n| Plotting | `piaso.pl.embedding`, `dotplot`, `violin`, `scatter`, `sankey`, `stackedBarplot`, `plot_embeddings_split` (+ tissue-image overlays on cytomes), `piaso.settings.set_figure_params` |\n\n## What an agent gets\n\n- `canonical/overview.md` — the router: task → component table and the seven decision rules.\n- `canonical/components/` — self-sufficient references for PIASO, COSG (+ COSGR), cytome (+ R),\n  LARIS, Emergene, cytorete, with executed code blocks and the data-object contract of every call.\n- `canonical/workflows/` — end-to-end scRNA-seq (scanpy-free), streaming on a `.cytome`,\n  marker-based annotation + reference projection, PIASOmarkerDB annotation, ligand–receptor\n  (SCALAR and LARIS), spatial transcriptomics, gene regulatory networks.\n- `canonical/gotchas.md` (layer contracts, deprecated names, the `as_dict` tuple, species-cased\n  prefixes), `canonical/data.md` (registry, fixtures), and the **piaso.org tutorial index**\n  (generated into every target) so the agent can point the user at the executed tutorial for\n  their platform.\n\n## Install (per agent)\n\nUsers work in **their own** analysis repos, so drop the right snippet into your setup. All of\nthese are generated from `canonical/` and live under [`dist/`](dist/).\n\n**Claude Code** — add this repo as a plugin marketplace and install the `piaso` skill:\n```bash\nclaude plugin marketplace add genecell/PIASO-for-agents\nclaude plugin install piaso@PIASO-for-agents\n```\n\n**Claude.ai (web app)** — upload the generated skill as a Skill (Pro/Max/Team/Enterprise, with\ncode execution enabled). Download the [`dist/claude/skills/piaso/`](dist/claude/skills/piaso)\nfolder, zip it, then in claude.ai go to **Settings → Capabilities → Skills → Create skill** and\nupload the zip:\n```bash\n# from a clone of this repo:\ncd dist/claude/skills && zip -r piaso-skill.zip piaso    # -> upload piaso-skill.zip in claude.ai\n```\nThe local MCP server below is stdio-only, so it does **not** work in the web app — use the Skill\nupload (or the `llms.txt` URL) on claude.ai; use MCP in Claude Code / Cursor / Codex.\n\n**Cursor** — download the rule into your project's `.cursor/rules/`:\n```bash\ncurl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/cursor/.cursor/rules/piaso.mdc \\\n  -o .cursor/rules/piaso.mdc\n```\n\n**GitHub Copilot** — copy the instructions file into your repo:\n```bash\ncurl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/copilot/.github/copilot-instructions.md \\\n  -o .github/copilot-instructions.md\n```\n\n**OpenAI Codex** — add the `AGENTS.md` pointer below to your project's `AGENTS.md` (Codex's\nprimary instructions file), and/or register the MCP server (see the **MCP server** section\nbelow — Codex is covered there).\n\n**AGENTS.md (Aider / Zed / Codex / any AGENTS.md-aware agent)** — append the hub pointer to\nyour project's `AGENTS.md` (or copy [`dist/agents/AGENTS.md`](dist/agents/AGENTS.md)):\n> This project uses the PIASO single-cell omics ecosystem. Agent-neutral, tested docs for\n> every component (Python + R), plus the cross-component decision rules, live at\n> https://github.com/genecell/PIASO-for-agents\n\n**llms.txt (any model with web access)** — point the tool at:\n```\nhttps://piaso.org/llms.txt          # and https://piaso.org/llms-full.txt\n```\nThese are the hub's `dist/llms/piaso.org/` files (absolute links); the relative-link versions are\nat `dist/llms/`.\n\n## MCP server\n\n`piaso-mcp` serves the PIASO ecosystem docs, the **piaso.org tutorial index**, the **PIASO-data\nregistry** and the **live PIASOmarkerDB** — no Python packages required. Tools: `search_docs`,\n`get_api`, `compare_implementations`, `resolve_install`, `list_tutorials`, `version_matrix`,\n`check_versions` (PyPI vs tested versions), `list_datasets` / `get_dataset` (live registry), and\nthe live DB proxies `query_marker_db`, `get_markers`, `list_studies`. It is a **local stdio**\nserver (not a hosted remote endpoint), so it works in Claude Code / Cursor / VS Code / Windsurf /\nZed / Codex / Cline, but **not** in the claude.ai web app — use the Skill upload there.\n\n### Prerequisite (all clients): `uv`\n\nThe server runs via `uvx`, which ships with **`uv`**. This is the one thing \"no packages\nneeded\" doesn't cover — install it once:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux\n# or:  pipx install uv   |   pip install --user uv   |   brew install uv   |   winget install astral-sh.uv\n```\n\nThen confirm it's reachable: `uvx --version`. **If that says \"command not found\"**, uv's bin\ndir isn't on your PATH — either add it, or replace `\"uvx\"` in the configs below with the\n**absolute path** from `which uvx` (Windows: `where uvx`). First launch downloads the package\n(~30 s); later launches are cached.\n\nThe MCP **config key and file location differ per client** — pick your agent below.\n\n### Claude Code — key `mcpServers`\n\nEasiest is the CLI (no hand-editing, and it handles the PATH issue in one line):\n\n```bash\nclaude mcp add piaso --scope user -- uvx piaso-mcp\n# uvx not on PATH? use its absolute path:\nclaude mcp add piaso --scope user -- \"$(which uvx)\" piaso-mcp\n\nclaude mcp get piaso        # verify → Status: ✔ Connected\n```\n\nOr edit `~/.claude.json` (user) / project `.mcp.json`:\n\n```jsonc\n{ \"mcpServers\": { \"piaso\": { \"command\": \"uvx\", \"args\": [\"piaso-mcp\"] } } }\n```\n\n### Cursor — key `mcpServers`\n\nFile: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Same shape as Claude Code:\n\n```jsonc\n{ \"mcpServers\": { \"piaso\": { \"command\": \"uvx\", \"args\": [\"piaso-mcp\"] } } }\n```\n\nEnable it under **Settings → MCP**.\n\n### Windsurf — key `mcpServers`\n\nFile: `~/.codeium/windsurf/mcp_config.json` (open via **Settings → Cascade → MCP Servers → Manage → raw config**):\n\n```jsonc\n{ \"mcpServers\": { \"piaso\": { \"command\": \"uvx\", \"args\": [\"piaso-mcp\"] } } }\n```\n\n### VS Code (GitHub Copilot, Agent mode) — key `servers` (note: not `mcpServers`)\n\nWorkspace file `.vscode/mcp.json`, or user `settings.json` under `\"mcp\"`. VS Code also wants a `type`:\n\n```jsonc\n// .vscode/mcp.json\n{ \"servers\": { \"piaso\": { \"type\": \"stdio\", \"command\": \"uvx\", \"args\": [\"piaso-mcp\"] } } }\n```\n\nOr one-shot from the terminal:\n\n```bash\ncode --add-mcp '{\"name\":\"piaso\",\"command\":\"uvx\",\"args\":[\"piaso-mcp\"]}'\n```\n\n### Zed — key `context_servers` (different shape)\n\nFile: `~/.config/zed/settings.json`. Zed nests under `context_servers` and marks custom servers with `\"source\": \"custom\"`:\n\n```jsonc\n{\n  \"context_servers\": {\n    \"piaso\": { \"source\": \"custom\", \"command\": \"uvx\", \"args\": [\"piaso-mcp\"], \"env\": {} }\n  }\n}\n```\n\n### Codex (OpenAI Codex CLI) — TOML, table `[mcp_servers.<name>]` (not JSON!)\n\nCodex is the odd one out: its config is **TOML**, in `~/.codex/config.toml`. Add a table:\n\n```toml\n[mcp_servers.piaso]\ncommand = \"uvx\"\nargs = [\"piaso-mcp\"]\n# uvx not on PATH? give the absolute path from `which uvx`:\n# command = \"/home/you/.local/bin/uvx\"\n```\n\nOr use the CLI (handles the file for you):\n\n```bash\ncodex mcp add piaso -- uvx piaso-mcp\ncodex mcp list        # verify it's registered\n```\n\n### Cline / Continue (VS Code extensions) — key `mcpServers`\n\nCline: **MCP Servers → Configure** (writes `cline_mcp_settings.json`). Continue: `~/.continue/config` (`mcpServers`). Both use the standard shape:\n\n```jsonc\n{ \"mcpServers\": { \"piaso\": { \"command\": \"uvx\", \"args\": [\"piaso-mcp\"] } } }\n```\n\n---\n\n**After configuring, restart the client** — MCP tools are loaded at startup, so a running\nsession won't see the server until it's relaunched. If it doesn't connect, 99% of the time\nit's the `uv`/PATH prerequisite above.\n\n## Repository layout\n\n```\ncanonical/       # the ONLY hand-written content (agent-neutral markdown + meta.yaml, incl. the tutorial index)\nbuild.py         # canonical/ -> all targets (pure text transforms); --check is the CI drift guard\ndist/            # ALL GENERATED — never hand-edited (claude/ agents/ cursor/ copilot/ llms/ mcp/)\nmcp/             # piaso-mcp source (local stdio server; serves knowledge + public data only)\ntests/           # executes every canonical code block (Python + R) on the fixtures; heavy spatial/regulon runs nightly\n.claude-plugin/  # marketplace + plugin manifest (repo root, for `claude plugin marketplace add`)\n.github/         # sync-check + test CI (re-runs on component releases + nightly) + PyPI / MCP-registry publish\n```\n\nRelated tooling (independent projects, listed on piaso.org's *Agents and project tooling* page):\n[stato](https://stato.hiniki.com) — structured expertise management for long computational\nprojects; [PlanDrop](https://plandrop.ai) — plan-review-execute for Claude Code on remote machines.\n\n## Changelog\n\nSee [`CHANGELOG.md`](CHANGELOG.md) — hub content releases and `piaso-mcp` versions, with the component versions each was tested against.\n\n## Citation\n\nCite each component by its own paper — see [`canonical/meta.yaml`](canonical/meta.yaml).\nPIASO: Wu, S.J., Dai, M. *et al.* *Nature* (2026), DOI `10.1038/s41586-025-09996-8`. COSG /\nCOSGR: Dai M, Pei X, Wang X-J, *Briefings in Bioinformatics* 23(2):bbab579 (2022). LARIS: Dai M,\nTörök T, Sun D, et al., bioRxiv (2025), DOI `10.1101/2025.11.26.690796`. cytome and cytorete have\nno paper yet — cite the repositories.\n\n## Maintainers\n\nDeveloped and maintained by **[The Fishell Laboratory](https://fishelllab.hms.harvard.edu)**\n(Harvard Medical School / Broad Institute).\nContact: Min Dai — dai@broadinstitute.org.\n\n## License\n\nBSD-3-Clause. See [`LICENSE`](LICENSE).\n",
  "bytes": 15269,
  "sha": "3aa33293a8cbdcc86708e60537082498c094e3d649dcbe58483419ac5aa7da18",
  "repo_slug": "genecell/piaso-for-agents",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_genecell_piaso_mcp_ef5d6a6d/readme"
}