cxg-census-mcp

cxg-census-mcp

LLM エージェントが CZ CELLxGENE Discover Census の単一細胞アトラスを、情報を偽ることなく検索できる MCP サーバーです。オントロジーを考慮したフィルター、コスト上限、すべての応答に付与される完全な出典情報と帰属表示を備えています。Cursor ／ Claude Desktop ／ Claude Code に追加して、「ヒト肺の細胞型構成を可視化して」のような質問を自然な英語で尋ねられます。

独立したプロジェクトであり、無関係です。 Chan Zuckerberg Initiative（CZI）、 EMBL-EBI、米国国勢調査局、その他いかなる組織とも提携、推奨、後援関係に ありません。「CELLxGENE」はCZIの商標です。ここでの言及は記述目的での 使用に限られます。

保証はありません。 MITライセンスのソースを「現状のまま」提供します。研究・調査用のツールであり、 臨床用または診断用の機器ではありません。公開前には必ず結果を検証してください。 商標およびコンテンツの帰属表示に関する完全な告知は LICENSE、 脅威モデルと既知の問題に関するポリシーは SECURITY.md を参照してください。

アルファ版（v0.1.2）。CHANGELOG.md

デモ

健康な肺とCOVID-19の肺を並べて比較。 2つのクエリを並行して実行すると、 COVIDコホートでは disease_multi_value_v7 のスキーマ差異に対応する書き換えが 適用されます。両方のデータセットセットからの帰属表示が同じチャットターンに 表示されます。

https://github.com/user-attachments/assets/c836f225-5075-4643-87aa-70d311bc5fd2

1つのクエリでヒト肺の細胞型構成を取得。 フリーテキストの「lung」は UBERON:0002048 に解決され、tissue_general を経由して処理されます。すべての CURIEにラベルが付き、すべてが単一のTier-0呼び出しで完結します。

https://github.com/user-attachments/assets/b0e10ca7-e46b-4e5f-ae63-11949d328c4d

（動画はGitHub上で再生されます。PyPIではURLのみが表示されるため、視聴するには GitHub READMEをご覧ください。）

その他のプロンプトはdocs/example-questions.mdをご覧ください。

アーキテクチャの概要

                 ┌──────────────────────────────────────────────┐
   MCP client    │   tools/        thin MCP wrappers, no logic  │
   (Claude,  ─►  │     │                                        │
    Cursor,      │     ▼                                        │
    Code, …)     │   planner/      FilterSpec → QueryPlan,      │
                 │     │           cost estimate, tier routing  │
                 │     ▼                                        │
                 │   ontology/     OLS4 + hint overlay,         │
                 │     │           CL/UBERON/MONDO expansion    │
                 │     ▼                                        │
                 │   execution/    Tier 0  facet counts         │
                 │     │           Tier 1  chunked obs scan     │
                 │     │           Tier 2  expression aggregate │
                 │     │           Tier 9  refuse → snippet     │
                 │     ▼                                        │
                 │   clients/      OLS4 (HTTPS) + Census/SOMA   │
                 │                                              │
                 │   caches/       OLS, facet, plan, filter LRU │
                 │   models/       Response envelope w/         │
                 │                 attribution + provenance     │
                 └──────────────────────────────────────────────┘
                                    │
                                    ▼
                       ┌────────────────────────┐
                       │ EBI OLS4 (ontology)    │
                       │ CZ CELLxGENE Census    │
                       │ (CC BY 4.0 data)       │
                       └────────────────────────┘

アーキテクチャの詳細については、docs/architecture.mdをご覧ください。 ツールのリファレンスについては、docs/tool-reference.mdをご覧ください。 質問の例については、docs/example-questions.mdをご覧ください。

インストール

PyPI からインストールする方法（推奨）：

uv tool install "cxg-census-mcp[census]"
cxg-census-mcp                       # speaks MCP over stdio

または、pip を使用します：

pip install "cxg-census-mcp[census]"

[census] エクストラを指定しない場合は、モックモード（決定論的なフィクスチャ）が利用されます。オフラインでのデモや、tiledbsoma の約 1 GB のネイティブ依存関係をダウンロードせずに MCP クライアントの設定を確認する場合に便利です。

ソースからインストールする方法（開発向け）：

git clone https://github.com/MaxMLang/cxg-census-mcp
cd cxg-census-mcp
uv sync --extra dev --extra census
uv run cxg-census-mcp

MCP クライアントの設定

Cursor（~/.cursor/mcp.json）と Claude Desktop（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）は、どちらも同じ形式を想定しています。PyPI からインストールした場合は、uvx を使うのが最も簡単です：

{
  "mcpServers": {
    "cxg-census": {
      "command": "/absolute/path/to/uvx",
      "args": ["--from", "cxg-census-mcp[census]", "cxg-census-mcp"]
    }
  }
}

uvx には絶対パスを指定してください（シェルで which uvx を実行して確認できます）。MCP クライアントは、シェルの rc ファイルを読み込まない非対話型サブプロセスでサーバーを起動するため、単に "uvx" と指定すると No such file or directory エラーになります。

ソースをクローンした場合は、チェックアウト先を指定します：

{
  "mcpServers": {
    "cxg-census": {
      "command": "/absolute/path/to/uv",
      "args": ["--directory", "/path/to/cxg-census-mcp", "run", "cxg-census-mcp"]
    }
  }
}

Claude Code：

claude mcp add cxg-census -- /absolute/path/to/uvx --from "cxg-census-mcp[census]" cxg-census-mcp

クライアントを終了して再起動すると（macOS では ⌘Q。ウィンドウを閉じるだけでは不十分です）、MCP パネルに 13 個のツールを持つサーバーが表示されます。

ツール（全 13 個）

ワークフロー： census_summary、get_census_versions、count_cells、 list_datasets、gene_coverage、aggregate_expression、preview_obs、 export_snippet、get_server_limits。

インスペクション： resolve_term、expand_term、term_definition、 list_available_values。

さらに MCP の resources（cxg-census-mcp://docs/{slug} にある Markdown ドキュメント）、 prompts（census_workflow、disambiguation）、および連携型の progress / cancellation 通知も利用できます。詳細については、 docs/tool-reference.mdをご覧ください。

設定

すべての環境変数には CXG_CENSUS_MCP_ プレフィックスが付きます。主な変数：

変数	デフォルト	用途
CXG_CENSUS_MCP_CENSUS_VERSION	stable	固定する Census リリース
CXG_CENSUS_MCP_CACHE_DIR	platformdirs default	ディスクキャッシュのルート
CXG_CENSUS_MCP_MOCK_MODE	0	1 の場合、実際の Census ハンドルを開きません
CXG_CENSUS_MCP_LOG_LEVEL	WARNING	stdlib のログレベル

全変数と検証については、src/cxg_census_mcp/config.pyをご覧ください。

開発と運用

クイックループ：

make install-all                 # uv sync --extra dev --extra census
make lint typecheck test         # ruff + mypy + pytest (mock mode)
make cov                         # tests + coverage HTML in ./htmlcov
make audit                       # pip-audit on locked production deps

キャッシュの事前ウォームアップ、スキーマの差分確認、コンテナーのビルド、メトリクスのダンプ、プランキャッシュのバキューム、週次のヒント／ファセット更新などの運用タスクは、 Makefileにあり、 docs/operational-playbook.mdに記載されています。

ドキュメント一覧

トピック	場所
システムアーキテクチャ	docs/architecture.md
ツールリファレンス	docs/tool-reference.md
エージェントへの質問例	docs/example-questions.md
オントロジーの解決	docs/ontology-resolution.md
スキーマの変更への対応	docs/schema-drift-format.md
Census のバージョン固定	docs/version-pinning.md
進行状況／キャンセル	docs/progress-and-cancellation.md
エラーモデル	docs/error-model.md
既知の制限事項	docs/limitations.md
運用手順書	docs/operational-playbook.md
変更履歴	CHANGELOG.md

ライセンスと帰属表示

ソースコード：MIT。 MIT ライセンスの対象は、このリポジトリ内のコードのみであり、上流の データ、オントロジー、サードパーティの商標は対象外です。

• データ。 ツールの応答は、Chan Zuckerberg Initiative が CC BY 4.0 の下で配布する CZ CELLxGENE Discover Census から派生（フィルタリング／集計）したものです。 すべての応答には attribution フィールドが含まれます。下流のユーザーは 帰属表示を保持し、変更が加えられたことを明示する必要があります。
• オントロジーは、CL、UBERON、MONDO、EFO、HANCESTRO などから EBI Ontology Lookup Service（OLS4）を介して取得されます。それぞれに独自の ライセンスがあります。
• 商標（「CELLxGENE」、「Cursor」、「Claude」、「Anthropic」、「Model Context Protocol」など）は、それぞれの所有者に帰属します。ここでの使用は 説明目的に限られ、提携関係を示すものではありません。

このプロジェクトは CZ CELLxGENE Discover Census のクライアントであり、 Census データをホスト、ミラー、再配布するものではありません。

詳細な告知は LICENSE をご覧ください。