piaso-mcp

PIASO-for-agents

PIASO のシングルセルオミクスエコシステムを、Claude Code、Cursor、Copilot、Codex、Windsurf、Cline、Aider など、あらゆる コーディングエージェントで第一級の機能として利用できるようにします。エージェントに依存しない、単一の 標準ナレッジパックから実現します。

The Fishell Laboratory（Harvard Medical School / Broad Institute）がメンテナンスしています。エージェント固有の形式（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 配下の、個別にインストール可能なパッケージを 4 つのレイヤーに分類しています。依存関係は一方向です（cytorete → piaso-tools → cosg + cytome、laris → cosg）。 また、pip install piaso-tools で COSG と cytome もインストールされます。

レイヤー	コンポーネント	パッケージ	言語	役割
解析	PIASO	piaso-tools	Python + Rust	自己完結型パイプライン — 10x データの読み込み、QC、ダブレット、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、5 つの .cytome アトラスを含む）とゲノム参照データ；piaso.data が読み取るレジストリ

各コンポーネントは個別にインストール可能です。COSG のみ、cytome のみ、LARIS のみを使うユーザーも第一級の利用者であり、すべての canonical/components/*.md は他のコンポーネントがインストールされていることを前提としません。このハブ独自の価値は、コンポーネントを組み合わせる方法と、単一のリポジトリでは決められないコンポーネント横断の選択肢を文書化することです。具体的には、SCALAR と LARIS のどちらを使うか（解離と空間のリガンド–受容体解析 — どちらも同じ CellChatDB を使用）、AnnData と .cytome のどちらを使うか（メモリ内処理とストリーミング処理 — 関数呼び出しは同じ）、COSG と cytorete のどちらを使うか（マーカー遺伝子と、その発現を駆動する TF）、Python と R のどちらを使うか（COSG → COSGR、cytome → cytome (R)；それ以外はすべて .cytome を介して受け渡し）、そしてどのアノテーション経路を使うか（マーカーセット、参照への投影、共同埋め込み、または PIASOmarkerDB に対する遺伝子リスト）です。

piaso-tools の概要

完全なリファレンスは canonical/components/piaso.md です。すべての関数は、AnnData、オープン済みの cytome Dataset、または .cytome パスを data= に指定して受け取ります。

PIASO で導入されたメソッド

機能	エントリーポイント	内容
INFOG 正規化	piaso.tl.infog	生の UMI カウントの情報量正規化と、情報量の多い遺伝子の選択
GDR（マーカー遺伝子誘導 DR）	piaso.tl.runGDR / runGDRParallel / projectGDR	軸がグループごとの COSG マーカースコアである埋め込み。ID によるバッチ統合と、固定された参照空間に対応
遺伝子セットスコアリング（PIASOscore）	piaso.tl.score	細胞ごとの p 値を伴う発現量マッチング対照スコアリング。Rust の単一 matmul で経路データベース全体を処理
細胞型予測	piaso.tl.predictCellTypeByMarker / predictCellTypeByGDR	マーカーセットおよび参照ベースのアノテーション
SCALAR（単一細胞 LR）	piaso.tl.specificity_matrix + runSCALAR	解離データに対する細胞型解像度のリガンド–受容体推論。CellChatDB は piaso.data.load_lr_database から利用可能
マーカー誘導統合	piaso.tl.stitchSpace	COSG マーカーグラフの刈り込みによる埋め込みのバッチ補正
PIASOmarkerDB	piaso.tl.getMarkers / analyzeMarkers	キュレーション済みマーカーデータベース（36 件の研究、ライブ API）のクライアント
モチーフスキャン	piaso.pp.scan_motifs + piaso.data のモチーフ／ゲノムローダー	cytorete の基盤となる Rust PWM エンジン

パイプライン構築ブロック（scanpy 不要）

機能	エントリーポイント
10x / Cell Ranger の読み込み	piaso.pp.read_10x_h5、read_10x、importCellRanger（→ cytome）
QC、ダブレット、フィルタリング	piaso.pp.calculateCellMetrics、scrublet、filter_cells、calculateGroupMetrics
埋め込み、グラフ、クラスター、UMAP	piaso.tl.runSVD、neighbors、leiden、umap、leiden_local、runHarmony
データセット、ゲノム、モチーフ DB、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

エージェントが利用できる内容

• canonical/overview.md — ルーター。タスク → コンポーネントの対応表と、7 つの判断ルールを記載しています。
• 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 のチュートリアルインデックス（すべてのターゲットに生成されます）。これにより、エージェントはユーザーのプラットフォーム向けに実行済みのチュートリアルを案内できます。

インストール（エージェント別）

ユーザーはそれぞれの分析リポジトリで作業するため、セットアップに適したスニペットを追加してください。これらはすべて canonical/ から生成され、dist/ にあります。

Claude Code — このリポジトリをプラグインマーケットプレイスとして追加し、piaso スキルをインストールします：

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

Claude.ai（ウェブアプリ） — 生成されたスキルをスキルとしてアップロードします（Pro/Max/Team/Enterprise。コード実行を有効にしてください）。dist/claude/skills/piaso/ フォルダーをダウンロードして ZIP に圧縮し、claude.ai で Settings → Capabilities → Skills → Create skill に移動して ZIP をアップロードします：

# 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 ではスキルのアップロード（または 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 対応の任意のエージェント） — ハブへのポインターをプロジェクトの AGENTS.md に追記するか、dist/agents/AGENTS.md をコピーします：

このプロジェクトでは、PIASO のシングルセルオミクスエコシステムを使用しています。すべてのコンポーネント（Python + R）についてエージェントに依存しないテスト済みドキュメントと、コンポーネント間の判断ルールをまとめたハブは、次の場所にあります： 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（ライブレジストリ）、ライブ DB プロキシの query_marker_db、get_markers、list_studies。これはローカルの stdio サーバー（ホスト型リモートエンドポイントではありません）で、Claude Code / Cursor / VS Code / Windsurf / Zed / Codex / Cline では動作しますが、claude.ai のウェブアプリでは動作しません。そちらではスキルをアップロードしてください。

前提条件（すべてのクライアント）：uv

サーバーは uv に同梱されている uvx を使って実行します。「パッケージ不要」には含まれないのはこれだけなので、一度インストールしてください：

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 の設定キーとファイルの場所はクライアントごとに異なります。以下からエージェントを選んでください。

Claude Code — キー mcpServers

最も簡単なのは CLI の使用です（手動編集が不要で、PATH の問題も 1 行で解決できます）：

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、エージェントモード）— キー 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 サーバー → 設定（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 の エージェントとプロジェクト用ツール ページに掲載）： stato — 長期にわたる計算プロジェクト向けの構造化された専門知識管理；PlanDrop — リモートマシン上での Claude Code 向け、計画・レビュー・実行。

変更履歴

CHANGELOG.md をご覧ください — ハブのコンテンツリリースと 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 をご覧ください。