cxg-census-mcp

cxg-census-mcp

一个 MCP 服务，让大模型 Agent 能够查询 CZ CELLxGENE Discover Census 单细胞图谱，且不会对数据妄加解读——支持本体感知筛选、成本上限，并在每次响应中提供完整的来源追溯和署名信息。将它接入 Cursor / Claude Desktop / Claude Code，即可用英文提问，例如 “可视化人类肺部的细胞类型组成”。

独立 / 无关联。 本项目与 Chan Zuckerberg Initiative（CZI）、EMBL-EBI、美国人口普查局或任何其他机构均无关联，也未获其认可或赞助。“CELLxGENE” 是 CZI 的标记；此处仅以描述性（指称性）方式使用该名称。

不提供任何保证。 源代码基于 MIT 许可提供，按“原样”提供。这是用于研究 / 探索的工具，并非临床或诊断工具。发表前请务必核验结果。完整的商标和内容署名声明见 LICENSE，威胁模型和已知问题政策见 SECURITY.md。

Alpha（v0.1.2）。CHANGELOG.md

演示

健康肺部与 COVID-19 肺部并排对比。 发起两个并行查询；针对 COVID 队列的 disease_multi_value_v7 模式漂移重写随即生效，两个贡献数据集集合的署名信息也会在同一轮对话中呈现。

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

一次查询即可查看人类肺部的细胞类型组成。 自由文本“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] extra 时，将启用模拟模式（确定性测试数据）—— 适用于离线演示，以及在不下载约 1 GB 的 tiledbsoma 原生依赖项的情况下验证 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 的绝对路径（在 Shell 中运行 which uvx）。MCP 客户端会在非交互式子进程中启动服务，该进程不会加载 Shell 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	标准库日志级别

完整列表和验证规则：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
Agent 问题示例	docs/example-questions.md
本体解析	docs/ontology-resolution.md
Schema 变更处理	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 许可证仅适用于本仓库中的代码，不适用于上游数据、本体或第三方商标。

• 数据。 工具响应源自 CZ CELLxGENE Discover Census（经过筛选 / 聚合），该数据由 Chan Zuckerberg Initiative 根据 CC BY 4.0 分发。每个响应都包含一个 attribution 字段；下游用户必须保留署名，并注明所做的更改。
• 本体通过 EBI Ontology Lookup Service (OLS4) 从 CL、UBERON、MONDO、EFO、HANCESTRO 等获取；每个本体均有自己的许可证。
• 商标（“CELLxGENE”、“Cursor”、“Claude”、“Anthropic”、“Model Context Protocol”等）归各自所有者所有。此处仅作描述性使用，不代表存在关联。

本项目是 CZ CELLxGENE Discover Census 的客户端；它不托管、镜像或再分发 Census 数据。

完整声明请见 LICENSE。