mudm-mcp 0.1.0__tar.gz

mudm_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novagen Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mudm_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: mudm-mcp
+Version: 0.1.0
+Summary: Local MCP server to discover, access, and locally analyze the muDM static spatial-data catalog.
+Author: Bengt Ljungquist
+License-Expression: MIT
+Project-URL: Homepage, https://ngrf.mudm.io
+Project-URL: Repository, https://github.com/NovagenResearch/mudm-mcp
+Project-URL: Issues, https://github.com/NovagenResearch/mudm-mcp/issues
+Keywords: mcp,mudm,spatial-data,spatial-transcriptomics,connectomics,llm,agents,duckdb,parquet
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: duckdb<3,>=1.4
+Requires-Dist: pyarrow>=16.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: brotli>=1.2.0
+Requires-Dist: certifi>=2024.2.2
+Dynamic: license-file
+
+# mudm-mcp
+
+Ask an AI assistant about the [muDM](https://ngrf.mudm.io) spatial-data catalog: about 100 public datasets of
+spatial transcriptomics and proteomics (Xenium, CODEX, CosMx, MERSCOPE, MIBI, Visium), *Drosophila* EM connectomes
+and 3D reference anatomy.
+
+`mudm-mcp` is a small [Model Context Protocol](https://modelcontextprotocol.io) server that runs **on your own
+machine**. Your assistant (Claude Code, Claude Desktop, Cursor, …) starts it, and through it can find datasets,
+describe them, query per-cell and per-neuron attributes, count cells in a region, and download data for local
+analysis. There is no account, no API key and no hosted backend: it reads the public static catalog.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+**Claude Code**
+
+```bash
+claude mcp add mudm -- uvx mudm-mcp
+```
+
+Start a new session and type `/mcp`: `mudm` should be listed as connected.
+
+**Claude Desktop** — add this to `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart:
+
+```json
+{
+  "mcpServers": {
+    "mudm": { "command": "uvx", "args": ["mudm-mcp"] }
+  }
+}
+```
+
+If Claude Desktop reports that it cannot find `uvx`, give its full path instead (run `which uvx`; typically
+`/Users/you/.local/bin/uvx`).
+
+**Any other MCP host** — register a stdio server with the command `uvx mudm-mcp`.
+
+**From a source checkout** — no PyPI needed; use this to run an unreleased version. Clone this repository, then
+give the host the checkout's path instead of `uvx mudm-mcp`:
+
+```bash
+claude mcp add mudm -- uv run --directory /path/to/mudm-mcp mudm-mcp
+```
+
+The first launch downloads the Python dependencies (about 0.5 GB into uv's cache, a few seconds on a fast
+connection); later launches start in under a second. The first `query_facets` call also fetches DuckDB's
+`httpfs` extension (about 20 MB) from DuckDB's extension server.
+
+Then ask, for example:
+
+- *"Find a mouse brain spatial transcriptomics dataset in muDM and describe it."*
+- *"How many cells are in the 500 µm square from (2000, 2000) to (2500, 2500) of that section?"*
+- *"How many Kenyon cells are in the hemibrain connectome, by type?"*
+- *"Which genes have the most transcripts in the Xenium mouse brain coronal section?"*
+
+[`docs/demo.md`](docs/demo.md) is a ten-minute walk-through of these prompts with the answers to expect.
+
+To remove the server again: `claude mcp remove mudm` (or delete the entry from the Claude Desktop config).
+
+## Tools
+
+| Tool | What it does | Downloads data? |
+|---|---|---|
+| `search_datasets` | Find datasets by free text (`"mouse brain"`) or by modality, organism, technique, tissue | no |
+| `describe_dataset` | What a dataset contains: assay, license, citation, layers, columns, attributes, units, sizes per zoom | no |
+| `query_facets` | SQL over the per-cell / per-neuron attribute table (gene counts, markers, cell types), read in place | no |
+| `count_features` | Count cells inside a rectangle given in micrometres, optionally grouped by a tag (2D datasets) | a few MB, once |
+| `get_access` | URLs and a decode snippet for reading the data directly, outside this server | no |
+| `download` | Fetch one zoom level of the feature Parquet into the local cache | yes (size-gated) |
+| `query` | SQL (DuckDB) over the downloaded features | no, but needs `download` first |
+| `sample_patches` | Sample tiles as spatial patches, with per-feature geometry summaries (for ML) | no, but needs `download` first |
+| `get_lod` | Summarise one level of detail of the downloaded data | no, but needs `download` first |
+
+## Things worth knowing
+
+**Units.** Datasets store their vertices in different units: Xenium in image pixels (0.2125 µm each), the other
+2D platforms in micrometres, the connectomes in nanometres, the reference anatomy in metres. `describe_dataset`
+reports the stored unit and the factor to micrometres, and every tool argument or result named `*_um` is in
+micrometres, already converted.
+
+**Geometry is not GeoParquet.** Feature geometry is muDM binary tile geometry (packed float32 vertices), so SQL
+cannot filter on coordinates. Use `count_features` for regions and `sample_patches` for geometry;
+`get_access` returns a three-line Python snippet for decoding it yourself.
+
+**Downloads are size-gated.** A download estimated above 500 MB is not started; the tool reports the size and
+cheaper options, and proceeds only with `confirm_large=true`. (The hemibrain at full resolution is about 300 GB.)
+Most questions need no download at all: `query_facets` reads the remote file in place.
+
+**SQL is sandboxed and bounded.** `query` and `query_facets` accept one read-only `SELECT`. The DuckDB connection
+can read only the dataset it was opened for: no other files or URLs, no writes. Results are capped (200 rows by
+default) and flagged `truncated` when more exist.
+
+**Cache.** Downloads and catalog metadata live in `~/.cache/mudm-mcp/` (override with `MUDM_CACHE_DIR` or
+`--cache-dir`). Catalog metadata refreshes after 24 hours. Delete the directory to reclaim space.
+
+**Another catalog.** `--base-url` (or `MUDM_BASE_URL`) points the server at a different muDM static catalog,
+including a local build directory.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -x --tb=short      # offline tests
+uv run pytest -m live                    # contract tests against the live catalog
+uv run python scripts/host_smoke.py      # drive the server over stdio, end to end
+```
+
+## Part of the muDM family
+
+- [`mudm`](https://github.com/NovagenResearch/mudm) — the data model
+- [`mudm-tools`](https://github.com/NovagenResearch/mudm-tools) — the tiling/conversion engine and viewers
+- `mudm-data` — produces and serves the static catalog this client reads
+
+## License
+
+MIT. The datasets carry their own licenses and citations; `describe_dataset` reports them.

mudm_mcp-0.1.0/README.md

@@ -0,0 +1,117 @@
+# mudm-mcp
+
+Ask an AI assistant about the [muDM](https://ngrf.mudm.io) spatial-data catalog: about 100 public datasets of
+spatial transcriptomics and proteomics (Xenium, CODEX, CosMx, MERSCOPE, MIBI, Visium), *Drosophila* EM connectomes
+and 3D reference anatomy.
+
+`mudm-mcp` is a small [Model Context Protocol](https://modelcontextprotocol.io) server that runs **on your own
+machine**. Your assistant (Claude Code, Claude Desktop, Cursor, …) starts it, and through it can find datasets,
+describe them, query per-cell and per-neuron attributes, count cells in a region, and download data for local
+analysis. There is no account, no API key and no hosted backend: it reads the public static catalog.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+**Claude Code**
+
+```bash
+claude mcp add mudm -- uvx mudm-mcp
+```
+
+Start a new session and type `/mcp`: `mudm` should be listed as connected.
+
+**Claude Desktop** — add this to `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart:
+
+```json
+{
+  "mcpServers": {
+    "mudm": { "command": "uvx", "args": ["mudm-mcp"] }
+  }
+}
+```
+
+If Claude Desktop reports that it cannot find `uvx`, give its full path instead (run `which uvx`; typically
+`/Users/you/.local/bin/uvx`).
+
+**Any other MCP host** — register a stdio server with the command `uvx mudm-mcp`.
+
+**From a source checkout** — no PyPI needed; use this to run an unreleased version. Clone this repository, then
+give the host the checkout's path instead of `uvx mudm-mcp`:
+
+```bash
+claude mcp add mudm -- uv run --directory /path/to/mudm-mcp mudm-mcp
+```
+
+The first launch downloads the Python dependencies (about 0.5 GB into uv's cache, a few seconds on a fast
+connection); later launches start in under a second. The first `query_facets` call also fetches DuckDB's
+`httpfs` extension (about 20 MB) from DuckDB's extension server.
+
+Then ask, for example:
+
+- *"Find a mouse brain spatial transcriptomics dataset in muDM and describe it."*
+- *"How many cells are in the 500 µm square from (2000, 2000) to (2500, 2500) of that section?"*
+- *"How many Kenyon cells are in the hemibrain connectome, by type?"*
+- *"Which genes have the most transcripts in the Xenium mouse brain coronal section?"*
+
+[`docs/demo.md`](docs/demo.md) is a ten-minute walk-through of these prompts with the answers to expect.
+
+To remove the server again: `claude mcp remove mudm` (or delete the entry from the Claude Desktop config).
+
+## Tools
+
+| Tool | What it does | Downloads data? |
+|---|---|---|
+| `search_datasets` | Find datasets by free text (`"mouse brain"`) or by modality, organism, technique, tissue | no |
+| `describe_dataset` | What a dataset contains: assay, license, citation, layers, columns, attributes, units, sizes per zoom | no |
+| `query_facets` | SQL over the per-cell / per-neuron attribute table (gene counts, markers, cell types), read in place | no |
+| `count_features` | Count cells inside a rectangle given in micrometres, optionally grouped by a tag (2D datasets) | a few MB, once |
+| `get_access` | URLs and a decode snippet for reading the data directly, outside this server | no |
+| `download` | Fetch one zoom level of the feature Parquet into the local cache | yes (size-gated) |
+| `query` | SQL (DuckDB) over the downloaded features | no, but needs `download` first |
+| `sample_patches` | Sample tiles as spatial patches, with per-feature geometry summaries (for ML) | no, but needs `download` first |
+| `get_lod` | Summarise one level of detail of the downloaded data | no, but needs `download` first |
+
+## Things worth knowing
+
+**Units.** Datasets store their vertices in different units: Xenium in image pixels (0.2125 µm each), the other
+2D platforms in micrometres, the connectomes in nanometres, the reference anatomy in metres. `describe_dataset`
+reports the stored unit and the factor to micrometres, and every tool argument or result named `*_um` is in
+micrometres, already converted.
+
+**Geometry is not GeoParquet.** Feature geometry is muDM binary tile geometry (packed float32 vertices), so SQL
+cannot filter on coordinates. Use `count_features` for regions and `sample_patches` for geometry;
+`get_access` returns a three-line Python snippet for decoding it yourself.
+
+**Downloads are size-gated.** A download estimated above 500 MB is not started; the tool reports the size and
+cheaper options, and proceeds only with `confirm_large=true`. (The hemibrain at full resolution is about 300 GB.)
+Most questions need no download at all: `query_facets` reads the remote file in place.
+
+**SQL is sandboxed and bounded.** `query` and `query_facets` accept one read-only `SELECT`. The DuckDB connection
+can read only the dataset it was opened for: no other files or URLs, no writes. Results are capped (200 rows by
+default) and flagged `truncated` when more exist.
+
+**Cache.** Downloads and catalog metadata live in `~/.cache/mudm-mcp/` (override with `MUDM_CACHE_DIR` or
+`--cache-dir`). Catalog metadata refreshes after 24 hours. Delete the directory to reclaim space.
+
+**Another catalog.** `--base-url` (or `MUDM_BASE_URL`) points the server at a different muDM static catalog,
+including a local build directory.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -x --tb=short      # offline tests
+uv run pytest -m live                    # contract tests against the live catalog
+uv run python scripts/host_smoke.py      # drive the server over stdio, end to end
+```
+
+## Part of the muDM family
+
+- [`mudm`](https://github.com/NovagenResearch/mudm) — the data model
+- [`mudm-tools`](https://github.com/NovagenResearch/mudm-tools) — the tiling/conversion engine and viewers
+- `mudm-data` — produces and serves the static catalog this client reads
+
+## License
+
+MIT. The datasets carry their own licenses and citations; `describe_dataset` reports them.

mudm_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mudm-mcp"
+version = "0.1.0"
+description = "Local MCP server to discover, access, and locally analyze the muDM static spatial-data catalog."
+readme = "README.md"
+authors = [{ name = "Bengt Ljungquist" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.15"
+keywords = ["mcp", "mudm", "spatial-data", "spatial-transcriptomics", "connectomics", "llm", "agents", "duckdb", "parquet"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "mcp>=2.3,<3", # official Model Context Protocol Python SDK (stdio server)
+    "duckdb>=1.4,<3", # local query engine over downloaded tiles
+    "pyarrow>=16.0", # read muDM Parquet locally; zero-copy into NumPy/Torch
+    "httpx>=0.27", # fetch the static catalog + tiles (download / optional range reads)
+    "numpy>=2.4.6",
+    "brotli>=1.2.0", # the catalog's JSON is served brotli-encoded
+    "certifi>=2024.2.2",
+]
+
+[project.urls]
+Homepage = "https://ngrf.mudm.io"
+Repository = "https://github.com/NovagenResearch/mudm-mcp"
+Issues = "https://github.com/NovagenResearch/mudm-mcp/issues"
+
+[project.scripts]
+mudm-mcp = "mudm_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/"]
+pythonpath = ["src/"]
+markers = ["live: needs network access to ngrf.mudm.io"]
+addopts = "-m 'not live'"

mudm_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mudm_mcp-0.1.0/src/mudm_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""muDM MCP — a local MCP server (client of the static muDM catalog) for agent/LLM discovery,
+access, and local analysis of muDM spatial datasets."""
+
+__version__ = "0.1.0"

mudm_mcp-0.1.0/src/mudm_mcp/catalog_client.py

@@ -0,0 +1,236 @@
+"""Read the static muDM catalog: a CLIENT of `pyramids.json` (mudm.PyramidJSON) + per-dataset
+`tilejson.json` (mudm.TileModel) + derived `croissant.json`. No backend — fetches static files over
+http(s) (cached to a local dir) or reads a local build dir (`file://` / plain path) for dev/tests.
+"""
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+DEFAULT_JSON_TTL_S = 24 * 3600.0
+
+
+def default_cache_dir(host: str) -> Path:
+    return Path.home() / ".cache" / "mudm-mcp" / (host or "local")
+
+
+class DatasetNotFound(KeyError):
+    """Unknown dataset id; ``suggestions`` holds up to 5 close catalog ids."""
+
+    def __init__(self, dataset_id: str, known_ids: list[str]):
+        super().__init__(f"dataset {dataset_id!r} not found in pyramids.json")
+        self.dataset_id = dataset_id
+        self.suggestions = difflib.get_close_matches(dataset_id, known_ids, n=5, cutoff=0.5)
+
+
+def _zoom_of(part: str) -> int:
+    """'zoom=9/cells_part_000.mu.parquet' -> 9."""
+    return int(part.split("/", 1)[0].split("=", 1)[1])
+
+
+class CatalogClient:
+    """Resolve + cache the catalog artifacts. ``base_url`` may be an http(s) origin (default
+    ``https://ngrf.mudm.io``) or a local directory (a `build_site --out` dir, as `file://…` or a path).
+
+    Cached catalog JSON is refetched once it is older than ``json_ttl_s`` (default 24 h), so a long-lived
+    install follows catalog updates; if the refetch fails (offline) the stale copy is served."""
+
+    def __init__(self, base_url: str, cache_dir: str | Path | None = None,
+                 json_ttl_s: float = DEFAULT_JSON_TTL_S):
+        self.base_url = str(base_url).rstrip("/")
+        self.json_ttl_s = float(json_ttl_s)
+        parsed = urlparse(self.base_url)
+        self.is_http = parsed.scheme in ("http", "https")
+        if self.is_http:
+            self.cache_dir = Path(cache_dir) if cache_dir else default_cache_dir(parsed.netloc)
+            self._local_root: Path | None = None
+        else:  # file:// or a plain local path
+            self._local_root = Path(parsed.path if parsed.scheme == "file" else self.base_url)
+            self.cache_dir = Path(cache_dir) if cache_dir else self._local_root
+
+    # --- paths ---
+    @staticmethod
+    def _rel(parts) -> str:
+        return "/".join(str(p).strip("/") for p in parts if str(p).strip("/"))
+
+    def url(self, *parts: str) -> str:
+        """Absolute URL (http origin) or local path (local origin) of a site-relative path."""
+        rel = self._rel(parts)
+        return f"{self.base_url}/{rel}" if self.is_http else str(self._local_root / rel)
+
+    # --- fetch / cache ---
+    def fetch(self, *parts: str) -> bytes:
+        """Bytes of a catalog-relative path (e.g. ``fetch("datasets", id, "tilejson.json")``)."""
+        rel = self._rel(parts)
+        if not self.is_http:
+            return (self._local_root / rel).read_bytes()
+        cached = self.cache_dir / rel
+        have = cached.is_file()
+        if have and (time.time() - cached.stat().st_mtime) < self.json_ttl_s:
+            return cached.read_bytes()
+        import httpx  # lazy: file:// dev/tests need no network/httpx
+        try:
+            resp = httpx.get(f"{self.base_url}/{rel}", follow_redirects=True, timeout=60.0)
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            if have:  # expired but unreachable: a stale catalog beats no catalog
+                return cached.read_bytes()
+            raise
+        cached.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cached.with_name(cached.name + ".part")
+        tmp.write_bytes(resp.content)
+        os.replace(tmp, cached)
+        return resp.content
+
+    def fetch_json(self, *parts: str) -> dict:
+        return json.loads(self.fetch(*parts))
+
+    def _try_fetch_json(self, *parts: str) -> dict | None:
+        """``fetch_json`` that returns None when the file does not exist (local miss / HTTP 4xx)."""
+        try:
+            return self.fetch_json(*parts)
+        except FileNotFoundError:
+            return None
+        except Exception as exc:  # httpx.HTTPStatusError without importing httpx eagerly
+            status = getattr(getattr(exc, "response", None), "status_code", None)
+            if status is not None and 400 <= status < 500:  # S3/CloudFront answer 403 for a missing key
+                return None
+            raise
+
+    def download_file(self, rel_parts, out_path) -> int:
+        """Stream a (possibly large) leaf file to ``out_path`` (http GET or local copy); returns bytes
+        written. Atomic: the data goes to ``<out_path>.part`` and is renamed only when complete, so an
+        interrupted download never leaves a truncated file under the final name. Unlike ``fetch`` this
+        does not hold the body in memory or use the JSON cache (parquet leaves are served uncompressed)."""
+        rel = self._rel(rel_parts)
+        out = Path(out_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out.with_name(out.name + ".part")
+        try:
+            if not self.is_http:
+                with open(self._local_root / rel, "rb") as src, open(tmp, "wb") as fh:
+                    while chunk := src.read(1 << 20):
+                        fh.write(chunk)
+            else:
+                import httpx  # lazy
+                with httpx.stream("GET", f"{self.base_url}/{rel}", follow_redirects=True,
+                                  timeout=120.0) as resp:
+                    resp.raise_for_status()
+                    with open(tmp, "wb") as fh:
+                        for chunk in resp.iter_bytes():
+                            fh.write(chunk)
+            size = tmp.stat().st_size
+            os.replace(tmp, out)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+        return size
+
+    # --- sizes ---
+    def part_size(self, base: str, part: str) -> int | None:
+        """Size in bytes of one leaf (local ``stat``; HTTP ``HEAD``, else a 1-byte ranged GET). None if
+        it cannot be determined."""
+        rel = self._rel([base, part])
+        if not self.is_http:
+            p = self._local_root / rel
+            return p.stat().st_size if p.is_file() else None
+        import httpx  # lazy
+        url = f"{self.base_url}/{rel}"
+        try:
+            r = httpx.head(url, follow_redirects=True, timeout=30.0)
+            if r.status_code == 200 and "content-length" in r.headers:
+                return int(r.headers["content-length"])
+            r = httpx.get(url, headers={"Range": "bytes=0-0"}, follow_redirects=True, timeout=30.0)
+            total = r.headers.get("content-range", "").rsplit("/", 1)[-1]
+            return int(total) if total.isdigit() else None
+        except httpx.HTTPError:
+            return None
+
+    def estimate_bytes(self, base: str, parts: list[str], sample: int = 4) -> int | None:
+        """Total size of ``parts``: exact when there are at most ``sample`` of them, else the mean of
+        ``sample`` evenly spaced parts times the count. None if no size could be read."""
+        if not parts:
+            return 0
+        if len(parts) <= sample:
+            sizes = [self.part_size(base, p) for p in parts]
+            return None if any(s is None for s in sizes) else sum(sizes)
+        step = len(parts) / sample
+        sizes = [s for s in (self.part_size(base, parts[int(i * step)]) for i in range(sample)) if s is not None]
+        return round(sum(sizes) / len(sizes) * len(parts)) if sizes else None
+
+    # --- catalog accessors ---
+    def pyramids(self) -> dict:
+        """The unified 2D+3D catalog (mudm.PyramidJSON)."""
+        return self.fetch_json("pyramids.json")
+
+    def entries(self) -> list[dict]:
+        return self.pyramids().get("pyramids", [])
+
+    def entry(self, dataset_id: str) -> dict:
+        """The catalog entry (PyramidEntry: id/label/kind + OPEN facet metadata) for one dataset."""
+        entries = self.entries()
+        for e in entries:
+            if e.get("id") == dataset_id:
+                return e
+        raise DatasetNotFound(dataset_id, [str(e.get("id")) for e in entries])
+
+    def descriptor(self, dataset_id: str) -> dict:
+        """The per-dataset muDM TileModel descriptor (assets[] + TileLayer schema + multiscale coords)."""
+        return self.fetch_json("datasets", dataset_id, "tilejson.json")
+
+    def croissant(self, dataset_id: str) -> dict:
+        """The derived Croissant JSON-LD (schema.org/Dataset + cr:)."""
+        return self.fetch_json("datasets", dataset_id, "croissant.json")
+
+    def viewer_descriptor(self, dataset_id: str) -> tuple[str, dict] | None:
+        """The VIEWER's descriptor ``(<site-relative dir>, tilejson)`` that sits next to the tiles
+        (``tiles/<id>/`` for 3D, ``tiles2d/<id>/`` for 2D). Its asset hrefs are relative to that dir. Used
+        as a fallback when the agent descriptor (``datasets/<id>/tilejson.json``) omits an asset."""
+        entry = self.entry(dataset_id)
+        feats = (entry.get("features") or "").strip("/")
+        dirs = [feats.rsplit("/", 1)[0]] if "/" in feats else []
+        dirs += [d for d in (f"tiles/{dataset_id}", f"tiles2d/{dataset_id}") if d not in dirs]
+        for d in dirs:
+            doc = self._try_fetch_json(d, "tilejson.json")
+            if doc is not None:
+                return d, doc
+        return None
+
+    @staticmethod
+    def _asset(descriptor: dict, role: str) -> dict | None:
+        return next((a for a in descriptor.get("assets") or [] if a.get("role") == role), None)
+
+    def features(self, dataset_id: str) -> dict | None:
+        """The download index of a dataset's ``features.parquet``:
+        ``{base, parts, zooms, full_res_zoom, source}`` — ``base`` is the site-relative directory holding
+        the ``zoom=<z>/…`` leaves, ``source`` is ``"agent"`` or ``"viewer"`` (which descriptor carried it).
+        None when neither descriptor lists parquet parts."""
+        entry = self.entry(dataset_id)
+        entry_base = (entry.get("features") or "").strip("/")
+        asset = self._asset(self.descriptor(dataset_id), "features")
+        source, viewer_dir = "agent", None
+        if not (asset and asset.get("parts")):
+            found = self.viewer_descriptor(dataset_id)
+            asset = self._asset(found[1], "features") if found else None
+            if not (asset and asset.get("parts")):
+                return None
+            source, viewer_dir = "viewer", found[0]
+        href = str(asset.get("href") or "")
+        if entry_base:
+            base = entry_base
+        elif viewer_dir is not None:
+            base = self._rel([viewer_dir, href or "features.parquet"])
+        elif href.startswith(self.base_url + "/"):
+            base = href[len(self.base_url) + 1:].strip("/")
+        else:
+            raise ValueError(f"{dataset_id}: cannot locate features.parquet (href {asset.get('href')!r} is "
+                             f"outside {self.base_url})")
+        parts = list(asset["parts"])
+        zooms = sorted(int(z) for z in (asset.get("zooms") or {_zoom_of(p) for p in parts}))
+        full = asset.get("full_res_zoom")
+        return {"base": base, "parts": parts, "zooms": zooms,
+                "full_res_zoom": int(full) if full is not None else zooms[-1], "source": source}

mudm_mcp-0.1.0/src/mudm_mcp/facets.py

@@ -0,0 +1,68 @@
+"""query_facets — SQL over a dataset's facet store (a per-cell / per-neuron attribute table published
+as ONE parquet file next to the tiles), read in place over HTTP range requests: no download.
+
+Facet stores by assay: Xenium ``expression`` (long: cell_id, gene, count) · CODEX / CosMx / MERSCOPE /
+MIBI ``markers`` (wide: one column per marker or gene) · connectomes and reference anatomy ``properties``
+(wide: one row per neuron / structure with cell_type, synapse counts, …). Visium has none.
+"""
+from __future__ import annotations
+
+from .catalog_client import CatalogClient
+from .sandbox import open_sandbox, run_select
+from .tools import facet_assets
+
+MAX_SCHEMA_COLUMNS = 60
+
+
+def _names(cols: list[str], cap: int = MAX_SCHEMA_COLUMNS) -> str:
+    more = f", … (+{len(cols) - cap} more)" if len(cols) > cap else ""
+    return ", ".join(cols[:cap]) + more
+
+
+def query_facets(client: CatalogClient, dataset_id: str, sql: str, facet: str | None = None,
+                 max_rows: int = 200) -> dict:
+    """Run ONE read-only SELECT against a dataset's facet store, exposed as the view ``facets`` (the
+    store's own name, e.g. ``expression`` or ``properties``, works as an alias).
+
+    ``facet`` picks the store by name when a dataset has several. Returns the bounded result of
+    ``run_select`` plus ``facet``, ``source`` (the file's URL) and ``schema`` — the file's REAL columns,
+    which can differ from what the descriptor advertises (``missing_columns`` lists advertised-but-absent
+    ones)."""
+    import duckdb  # lazy
+
+    client.entry(dataset_id)  # unknown id -> DatasetNotFound with suggestions
+    stores = facet_assets(client, dataset_id)
+    if not stores:
+        raise ValueError(f"{dataset_id} has no facet store (Visium datasets have none). "
+                         "describe_dataset lists a dataset's facets; download + query reads the features.")
+    names = [s["name"] for s in stores]
+    if facet:
+        store = next((s for s in stores if s["name"] == facet), None)
+        if store is None:
+            raise ValueError(f"{dataset_id} has no facet store named {facet!r}; available: {', '.join(names)}")
+    elif len(stores) > 1:
+        raise ValueError(f"{dataset_id} has several facet stores; pass facet= one of: {', '.join(names)}")
+    else:
+        store = stores[0]
+
+    con = open_sandbox("facets", store["url"])
+    try:
+        # Agents often write FROM <store name> (e.g. FROM expression) because that is the name
+        # describe_dataset shows: accept it as an alias of the `facets` view instead of failing.
+        if store["name"].isidentifier() and store["name"].lower() != "facets":
+            con.execute(f'CREATE VIEW "{store["name"]}" AS SELECT * FROM facets')
+        schema = [{"name": r[0], "type": r[1]} for r in con.execute("DESCRIBE facets").fetchall()]
+        cols = [c["name"] for c in schema]
+        try:
+            result = run_select(con, sql, max_rows=max_rows)
+        except (duckdb.BinderException, duckdb.CatalogException) as exc:
+            first = str(exc).split("\n", 1)[0]
+            raise ValueError(f"{first} The view is named `facets`. Available columns: {_names(cols)}") from exc
+    finally:
+        con.close()
+    out = {**result, "facet": store["name"], "layout": store["layout"], "source": store["url"],
+           "n_columns": len(schema), "schema": schema[:MAX_SCHEMA_COLUMNS]}
+    missing = [c for c in store["columns"] if c not in cols]
+    if missing:
+        out["missing_columns"] = missing[:MAX_SCHEMA_COLUMNS]
+    return out