uxarray-mcp 0.2.2__tar.gz → 0.3.0__tar.gz

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uxarray-mcp
-Version: 0.2.2
+Version: 0.3.0
 Summary: MCP server for analyzing unstructured meshes with UXarray
 Keywords: uxarray,mcp,unstructured grids,scientific computing,globus compute
 Author: Rajeev Jain, Dayan Abdulla
@@ -212,21 +212,24 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: Apache Software License
-Requires-Dist: toolregistry-server[mcp]>=0.4.0
-Requires-Dist: mcp>=1.20,<2
+Requires-Dist: toolregistry-server[mcp]>=0.5.0
+Requires-Dist: toolregistry>=0.16.0
+Requires-Dist: mcp>=1.24,<3
 Requires-Dist: holoviews>=1.19.0
 Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: uxarray>=2026.7.0
+Requires-Dist: uxarray>=2026.8.0
 Requires-Dist: sphinx>=7.0 ; extra == 'docs'
 Requires-Dist: sphinx-book-theme>=1.1.0 ; extra == 'docs'
 Requires-Dist: myst-parser>=3.0 ; extra == 'docs'
 Requires-Dist: academy-py>=0.3.1 ; extra == 'hpc'
 Requires-Dist: globus-compute-sdk>=4.5.0 ; extra == 'hpc'
-Requires-Dist: toolregistry-server[openapi]>=0.4.0 ; extra == 'openapi'
-Requires-Python: >=3.12, <3.13
+Requires-Dist: toolregistry-server[openapi]>=0.5.0 ; extra == 'openapi'
+Requires-Python: >=3.11
 Project-URL: Documentation, https://uxarray-mcp-server.readthedocs.io
 Project-URL: Source, https://github.com/UXARRAY/uxarray-mcp-server
 Project-URL: Tracker, https://github.com/UXARRAY/uxarray-mcp-server/issues
@@ -282,6 +285,78 @@ You are most likely one of:
    project, or lab. → [Local install](#local-install), then the full
    [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md) including
    service-account migration and the MEP allowlist.
+5. **Just trying it out, or running an agent harness** — you don't want to
+   install a scientific Python stack at all. → [Docker](#docker).
+
+---
+
+## Docker
+
+The container is the fastest way to run the server without resolving
+`uxarray`, `netcdf4`, `matplotlib`, and friends on your own machine. It ships
+five small mesh fixtures so there is something to analyze immediately.
+
+```bash
+docker build -t uxarray-mcp:local .
+docker run --rm -i uxarray-mcp:local          # stdio, what MCP clients spawn
+```
+
+Point Claude Code at it:
+
+```bash
+claude mcp add uxarray-docker --transport stdio -- \
+  docker run --rm -i uxarray-mcp:local
+```
+
+To analyze your own meshes, mount them — `/work` is the working directory:
+
+```bash
+docker run --rm -i -v /path/to/my/data:/work uxarray-mcp:local
+```
+
+For an agent harness that wants HTTP instead of stdio:
+
+```bash
+docker run --rm -p 8001:8001 uxarray-mcp:local \
+  serve --transport http --host 0.0.0.0
+```
+
+Verify an image end-to-end — handshake, tool surface, and one real
+computation checked against an analytic result:
+
+```bash
+python3 scripts/container_smoke_test.py --image uxarray-mcp:local
+```
+
+**The image is local-only, on purpose.** The HPC extras
+(`globus-compute-sdk`, `academy-py`) are not installed, and the baked config
+pins `execution_mode: local`. A sealed container should not hold Globus
+credentials or reach a Slurm endpoint — and an image that *could* submit
+remote work is not one you should point an untrusted agent at. If you want
+HPC, run the server on the host where your identity lives; see
+[docs/remote-hpc.md](docs/remote-hpc.md).
+
+**Baked fixtures** live at `/data/uxarray` and are generated at build time by
+[`scripts/generate_container_fixtures.py`](scripts/generate_container_fixtures.py)
+rather than committed as binaries, so what's in them is readable as code. Each
+one targets a specific blind spot:
+
+| Fixture | Why it exists |
+|---|---|
+| `global` | Coarse global mesh, unit sphere — the everyday case. |
+| `earth_radius` | Declares R = 6371 km, so a missing radius scaling shows up in the numbers instead of hiding behind R = 1. |
+| `multi_level` | Four levels 100 apart; a wrong level selection is unmistakable. |
+| `time_level` | Three times × four levels, value `1000*t + 100*(k+1)` — the magnitude says which slice was taken. |
+| `regional` | A sliver mesh, so remap-coverage failures have something to fail against. |
+
+`MANIFEST.json` records a content hash per fixture — hashing decoded arrays
+rather than file bytes, so it stays stable across NetCDF library versions. The
+build verifies it, and you can re-check any image:
+
+```bash
+docker run --rm -i --entrypoint python uxarray-mcp:local - --verify \
+  < scripts/generate_container_fixtures.py
+```
 
 ---
 
@@ -407,6 +482,13 @@ Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 Full schema: [docs/tools.md](docs/tools.md).
 
+**Protocol version.** We do not implement MCP directly; servers are built
+through `toolregistry-server`, which depends on the `mcp` Python SDK. As of
+`toolregistry-server` 0.5.0 and `toolregistry` 0.16.0 the SDK cap is lifted, so
+we resolve `mcp` 2.1.1 and negotiate spec **`2026-07-28`** (stateless core,
+cacheable list results, MRTR). 0.16.0 also widens the recognized content-block
+set to audio, `resource_link`, and embedded resources.
+
 **Once you've configured an HPC endpoint** (optional — see
 [Going beyond your laptop](#going-beyond-your-laptop) below): most tools above
 also take `use_remote: bool` and `endpoint: str`, falling back to local if the

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/README.md

@@ -45,6 +45,78 @@ You are most likely one of:
    project, or lab. → [Local install](#local-install), then the full
    [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md) including
    service-account migration and the MEP allowlist.
+5. **Just trying it out, or running an agent harness** — you don't want to
+   install a scientific Python stack at all. → [Docker](#docker).
+
+---
+
+## Docker
+
+The container is the fastest way to run the server without resolving
+`uxarray`, `netcdf4`, `matplotlib`, and friends on your own machine. It ships
+five small mesh fixtures so there is something to analyze immediately.
+
+```bash
+docker build -t uxarray-mcp:local .
+docker run --rm -i uxarray-mcp:local          # stdio, what MCP clients spawn
+```
+
+Point Claude Code at it:
+
+```bash
+claude mcp add uxarray-docker --transport stdio -- \
+  docker run --rm -i uxarray-mcp:local
+```
+
+To analyze your own meshes, mount them — `/work` is the working directory:
+
+```bash
+docker run --rm -i -v /path/to/my/data:/work uxarray-mcp:local
+```
+
+For an agent harness that wants HTTP instead of stdio:
+
+```bash
+docker run --rm -p 8001:8001 uxarray-mcp:local \
+  serve --transport http --host 0.0.0.0
+```
+
+Verify an image end-to-end — handshake, tool surface, and one real
+computation checked against an analytic result:
+
+```bash
+python3 scripts/container_smoke_test.py --image uxarray-mcp:local
+```
+
+**The image is local-only, on purpose.** The HPC extras
+(`globus-compute-sdk`, `academy-py`) are not installed, and the baked config
+pins `execution_mode: local`. A sealed container should not hold Globus
+credentials or reach a Slurm endpoint — and an image that *could* submit
+remote work is not one you should point an untrusted agent at. If you want
+HPC, run the server on the host where your identity lives; see
+[docs/remote-hpc.md](docs/remote-hpc.md).
+
+**Baked fixtures** live at `/data/uxarray` and are generated at build time by
+[`scripts/generate_container_fixtures.py`](scripts/generate_container_fixtures.py)
+rather than committed as binaries, so what's in them is readable as code. Each
+one targets a specific blind spot:
+
+| Fixture | Why it exists |
+|---|---|
+| `global` | Coarse global mesh, unit sphere — the everyday case. |
+| `earth_radius` | Declares R = 6371 km, so a missing radius scaling shows up in the numbers instead of hiding behind R = 1. |
+| `multi_level` | Four levels 100 apart; a wrong level selection is unmistakable. |
+| `time_level` | Three times × four levels, value `1000*t + 100*(k+1)` — the magnitude says which slice was taken. |
+| `regional` | A sliver mesh, so remap-coverage failures have something to fail against. |
+
+`MANIFEST.json` records a content hash per fixture — hashing decoded arrays
+rather than file bytes, so it stays stable across NetCDF library versions. The
+build verifies it, and you can re-check any image:
+
+```bash
+docker run --rm -i --entrypoint python uxarray-mcp:local - --verify \
+  < scripts/generate_container_fixtures.py
+```
 
 ---
 
@@ -170,6 +242,13 @@ Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 Full schema: [docs/tools.md](docs/tools.md).
 
+**Protocol version.** We do not implement MCP directly; servers are built
+through `toolregistry-server`, which depends on the `mcp` Python SDK. As of
+`toolregistry-server` 0.5.0 and `toolregistry` 0.16.0 the SDK cap is lifted, so
+we resolve `mcp` 2.1.1 and negotiate spec **`2026-07-28`** (stateless core,
+cacheable list results, MRTR). 0.16.0 also widens the recognized content-block
+set to audio, `resource_link`, and embedded resources.
+
 **Once you've configured an HPC endpoint** (optional — see
 [Going beyond your laptop](#going-beyond-your-laptop) below): most tools above
 also take `use_remote: bool` and `endpoint: str`, falling back to local if the

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uxarray-mcp"
-version = "0.2.2"
+version = "0.3.0"
 description = "MCP server for analyzing unstructured meshes with UXarray"
 readme = "README.md"
 keywords = [
@@ -16,17 +16,20 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: Apache Software License",
 ]
-requires-python = ">=3.12,<3.13"
+requires-python = ">=3.11"
 dependencies = [
-    "toolregistry-server[mcp]>=0.4.0",
-    "mcp>=1.20,<2",
+    "toolregistry-server[mcp]>=0.5.0",
+    "toolregistry>=0.16.0",
+    "mcp>=1.24,<3",
     "holoviews>=1.19.0",
     "matplotlib>=3.9.0",
     "pyyaml>=6.0",
-    "uxarray>=2026.7.0",
+    "uxarray>=2026.8.0",
 ]
 
 [[project.authors]]
@@ -41,7 +44,7 @@ email = "dayanabdulla000@gmail.com"
 file = "LICENSE"
 
 [project.optional-dependencies]
-openapi = ["toolregistry-server[openapi]>=0.4.0"]
+openapi = ["toolregistry-server[openapi]>=0.5.0"]
 hpc = [
     "academy-py>=0.3.1",
     "globus-compute-sdk>=4.5.0",
@@ -70,7 +73,7 @@ dev = [
 ]
 
 [tool.mypy]
-python_version = "3.12"
+python_version = "3.11"
 check_untyped_defs = true
 ignore_missing_imports = true
 warn_unused_ignores = true
@@ -88,9 +91,6 @@ ignore_missing_imports = true
 module = "uxarray_mcp.remote.agent"
 warn_unused_ignores = false
 
-[tool.ruff]
-extend-exclude = ["docs/architecture.html"]
-
 [tool.ruff.lint]
 extend-select = ["I"]
 

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "uxarray-mcp"
-version = "0.2.2"
+version = "0.3.0"
 description = "MCP server for analyzing unstructured meshes with UXarray"
 readme = "README.md"
 keywords = ["uxarray", "mcp", "unstructured grids", "scientific computing", "globus compute"]
@@ -10,7 +10,9 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: Apache Software License",
 ]
 authors = [
@@ -18,25 +20,41 @@ authors = [
     { name = "Dayan Abdulla", email = "dayanabdulla000@gmail.com" },
 ]
 license = { file = "LICENSE" }
-# Pinned to 3.12 until globus/globus-compute#2139 lands a published submitter ↔
-# worker compatibility story. HPC sites broadly ship Python 3.12 conda stacks
-# today; matching that minor version on the submitter side avoids WorkerLost
-# from pickle protocol skew. Revisit when upstream confirms multi-version
-# support and broaden requires-python back to >=3.11.
-requires-python = ">=3.12,<3.13"
+# The floor is 3.11; there is deliberately no upper bound.
+#
+# This used to read ">=3.12,<3.13" because of globus/globus-compute#2139: a
+# 3.13 submitter against a 3.12 worker raises WorkerLost on non-trivial
+# payloads. That is a real constraint, but it belongs to the *HPC* path only,
+# and pinning the whole package for it made every local-only user -- the large
+# majority -- pay for a feature they never enable. It also blocked the conda
+# recipe and any container base that is not exactly 3.12.
+#
+# The constraint is now enforced where it actually applies: `uxarray_mcp.remote`
+# checks the submitter's Python at import time and refuses to configure an
+# endpoint from an unsupported interpreter, and `remote.health` already warns on
+# submitter/worker minor-version skew at probe time. A local install on 3.11 or
+# 3.13 works and never touches that code.
+#
+# All runtime dependencies (uxarray, mcp, toolregistry-server, holoviews)
+# declare >=3.10, so 3.11 is a conservative floor.
+requires-python = ">=3.11"
 dependencies = [
-    "toolregistry-server[mcp]>=0.4.0",
-    # toolregistry-server 0.4.x imports McpError, renamed to MCPError in mcp 2.
-    "mcp>=1.20,<2",
+    "toolregistry-server[mcp]>=0.5.0",
+    # Imported directly (ToolRegistry, ToolTag), so it is declared directly
+    # rather than leaned on transitively. 0.16.0 is the release that teaches
+    # is_content_block_list about audio/resource_link/resource; on 0.15.0 those
+    # blocks are silently stringified into one TextContent instead of failing.
+    "toolregistry>=0.16.0",
+    "mcp>=1.24,<3",
     "holoviews>=1.19.0",
     "matplotlib>=3.9.0",
     "pyyaml>=6.0",
-    "uxarray>=2026.7.0",
+    "uxarray>=2026.8.0",
 ]
 
 [project.optional-dependencies]
 openapi = [
-    "toolregistry-server[openapi]>=0.4.0",
+    "toolregistry-server[openapi]>=0.5.0",
 ]
 hpc = [
     "academy-py>=0.3.1",
@@ -66,7 +84,9 @@ dev = [
 ]
 
 [tool.mypy]
-python_version = "3.12"
+# Type-check against the floor, not the container's interpreter: 3.11 is the
+# lowest version we claim to support, so that is where checking has to happen.
+python_version = "3.11"
 check_untyped_defs = true
 ignore_missing_imports = true
 warn_unused_ignores = true
@@ -91,7 +111,6 @@ requires = ["uv_build>=0.9.26,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.ruff]
-extend-exclude = ["docs/architecture.html"]
 
 [tool.ruff.lint]
 extend-select = ["I"]

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/src/uxarray_mcp/__init__.py

@@ -3,4 +3,4 @@
 from uxarray_mcp.tools import inspect_mesh
 
 __all__ = ["inspect_mesh"]
-__version__ = "0.2.2"
+__version__ = "0.3.0"

uxarray_mcp-0.3.0/src/uxarray_mcp/app.py

@@ -0,0 +1,137 @@
+"""UXarray application — subclass of toolregistry_server.App.
+
+Provides :class:`UXarrayApp`, the central server application that builds
+the UXarray tool registry and dispatches to protocol adapters (MCP, OpenAPI).
+
+Identity (product name, version, description) flows automatically to
+MCP server name, OpenAPI title, and CLI banner.
+
+Example::
+
+    from uxarray_mcp.app import UXarrayApp
+
+    app = UXarrayApp()
+    app.serve_mcp(transport="stdio", profile="core")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from toolregistry_server import ServerIdentity
+from toolregistry_server.app import App
+
+from . import __version__
+from .registry import Profile
+
+if TYPE_CHECKING:
+    from toolregistry import ToolRegistry
+
+UXARRAY_IDENTITY = ServerIdentity(
+    name="UXarray MCP",
+    version=__version__,
+    description="Mesh analysis tools for AI agents",
+)
+
+
+#: How long a client may cache our ``tools/list`` response, in milliseconds.
+#: The tool surface is fixed at startup by the profile and does not change
+#: while the server runs, so re-listing on every turn is pure overhead --
+#: the catalog was measured at 74% of the payload on short conversations.
+#: Five minutes bounds how long a client can hold a stale surface if a
+#: future version does start mutating the registry at runtime.
+#:
+#: ``ttlMs`` and ``cacheScope`` are MCP spec 2026-07-28 fields and they do
+#: reach the wire on the modern transport: ``mcp`` 2.1.1 has
+#: ``MODERN_PROTOCOL_VERSIONS == ("2026-07-28",)`` and ``ListToolsResult``
+#: inherits ``CacheableResult``, so a client sending the modern
+#: ``MCP-Protocol-Version`` header sees them serialized. Only the legacy
+#: ``initialize`` handshake caps out earlier (``LATEST_HANDSHAKE_VERSION`` is
+#: 2025-11-25); on that path the SDK strips fields the negotiated era does
+#: not define, and the hints simply cost nothing.
+LIST_TOOLS_TTL_MS = 300_000
+
+#: The surface depends only on the profile, not on the user or session, so
+#: a shared cache entry is correct.
+LIST_TOOLS_CACHE_SCOPE = "public"
+
+
+class UXarrayApp(App):
+    """UXarray-specific server application.
+
+    Overrides :meth:`prepare_registry` to build the UXarray tool
+    registry with profile-based tool surface selection, and
+    :meth:`serve_mcp` so the ``tools/list`` cache hints survive to the wire.
+    """
+
+    def __init__(self, identity: ServerIdentity | None = None) -> None:
+        super().__init__(identity=identity or UXARRAY_IDENTITY)
+
+    def prepare_registry(self, **kwargs) -> ToolRegistry:
+        """Build the UXarray tool registry.
+
+        Keyword Args:
+            profile: Tool surface profile (``"core"`` or
+                ``"deferred-full"``). Defaults to ``"core"``.
+        """
+        from .registry import build_registry
+
+        profile = kwargs.get("profile", "core")
+        return build_registry(profile=profile)
+
+    def serve_mcp(self, **kwargs) -> None:
+        """Start an MCP server that actually advertises our cache hints.
+
+        The inherited path (``App.serve`` -> ``MCPAdapter.create_and_run``)
+        constructs the adapter itself and does not forward
+        ``list_tools_ttl_ms`` / ``list_tools_cache_scope``; they fall into
+        ``run(**kwargs)`` and are dropped without an error. A server started
+        that way advertises the SDK default of ``ttlMs=0``, i.e. immediately
+        stale, so every turn re-lists the whole catalog. Constructing the
+        adapter here is the only way the hints reach the wire on the CLI
+        path, which is the one users actually run.
+        """
+        from toolregistry_server.adapters.mcp import MCPAdapter
+
+        kwargs.setdefault("identity", self.identity)
+        registry = self.prepare_registry(**kwargs)
+        route_table = self._make_route_table(registry)
+
+        identity = kwargs.pop("identity")
+        name = kwargs.pop("name", identity.name)
+        kwargs.pop("profile", None)
+
+        MCPAdapter(
+            route_table,
+            name=name,
+            list_tools_ttl_ms=LIST_TOOLS_TTL_MS,
+            list_tools_cache_scope=LIST_TOOLS_CACHE_SCOPE,
+        ).run(**kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Convenience helpers for tests and scripts
+# ---------------------------------------------------------------------------
+
+
+def make_registry(*, profile: Profile = "core") -> ToolRegistry:
+    """Build the tool registry for the requested profile."""
+    return UXarrayApp().prepare_registry(profile=profile)
+
+
+def make_mcp_server(*, profile: Profile = "core"):
+    """Build a configured MCP server ready for any transport.
+
+    Carries the same ``tools/list`` cache hints as :meth:`UXarrayApp.serve_mcp`
+    so tests and scripts exercise the surface the CLI actually serves.
+    """
+    from toolregistry_server.adapters.mcp import route_table_to_mcp_server
+    from toolregistry_server.route_table import RouteTable
+
+    registry = make_registry(profile=profile)
+    return route_table_to_mcp_server(
+        RouteTable(registry),
+        "UXarray MCP",
+        list_tools_ttl_ms=LIST_TOOLS_TTL_MS,
+        list_tools_cache_scope=LIST_TOOLS_CACHE_SCOPE,
+    )

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/src/uxarray_mcp/cli.py

@@ -308,8 +308,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("core", "deferred-full"),
         default="core",
         help=(
-            "core: gateway + control + list_datasets + prompts (~31 tools). "
-            "deferred-full: also load 32 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (33 tools). "
+            "deferred-full: also load 33 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )
@@ -330,8 +330,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("core", "deferred-full"),
         default="core",
         help=(
-            "core: gateway + control + list_datasets + prompts (~31 tools). "
-            "deferred-full: also load 32 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (33 tools). "
+            "deferred-full: also load 33 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )

uxarray_mcp-0.3.0/src/uxarray_mcp/content_blocks.py

@@ -0,0 +1,114 @@
+"""MCP content blocks in the shape the adapter actually recognizes.
+
+``toolregistry-server`` converts a tool result into MCP content only when the
+result is a list of **plain dicts** whose ``type`` is one that
+``toolregistry.llm.content_blocks.is_content_block_list`` knows. A list of
+``mcp.types`` models fails that test, so the whole result is JSON-serialized
+into a single ``TextContent`` and the image reaches the caller as a Python
+``repr`` inside a string -- no error, just a picture that is no longer a
+picture. The wire shape is therefore built here, once, instead of at each
+call site.
+
+Two asymmetries in the adapter are easy to get wrong and are encoded here so
+no caller has to remember them:
+
+* an ``image`` carries its MIME type *inside* ``source``, while every other
+  block carries it on the block itself;
+* the adapter reads only ``uri``, ``name`` and the MIME type off a
+  ``resource_link`` -- a title, description or size passed on the block is
+  silently dropped, so those belong in the accompanying metadata instead.
+
+Recognized types are ``text``, ``image``, ``audio``, ``resource_link`` and
+``resource`` as of ``toolregistry`` 0.16.0; on 0.15.0 the last three are not
+recognized and degrade to stringified text, which is why the floor moved.
+"""
+
+from typing import Any
+
+#: Block types the adapter converts natively. Kept local rather than imported
+#: from toolregistry so that a version skew shows up as a failing test here
+#: rather than as silently stringified output in production.
+WIRE_BLOCK_TYPES = frozenset({"text", "image", "audio", "resource_link", "resource"})
+
+DEFAULT_IMAGE_MIME = "image/png"
+
+
+def text_block(text: str) -> dict[str, Any]:
+    """Build a ``text`` content block."""
+    return {"type": "text", "text": text}
+
+
+def image_block(
+    data_b64: str, *, mime_type: str = DEFAULT_IMAGE_MIME
+) -> dict[str, Any]:
+    """Build an ``image`` content block from base64-encoded bytes.
+
+    The MIME type goes inside ``source``: that is where the adapter looks
+    for an image, and it is mandatory in practice because ``ImageContent``
+    declares ``mime_type`` with no default.
+    """
+    return {
+        "type": "image",
+        "source": {"type": "base64", "media_type": mime_type, "data": data_b64},
+    }
+
+
+def resource_link_block(
+    uri: str, name: str, *, mime_type: str | None = None
+) -> dict[str, Any]:
+    """Build a ``resource_link`` content block.
+
+    ``uri`` and ``name`` are required -- the adapter subscripts both, so a
+    missing key surfaces as an opaque internal error rather than a
+    validation message.
+    """
+    block: dict[str, Any] = {"type": "resource_link", "uri": uri, "name": name}
+    if mime_type is not None:
+        block["mimeType"] = mime_type
+    return block
+
+
+def is_wire_blocks(value: Any) -> bool:
+    """Whether *value* is a list the adapter will treat as content blocks.
+
+    Mirrors ``is_content_block_list``: a non-empty list in which every
+    element is a dict carrying a recognized ``type``.
+    """
+    return (
+        isinstance(value, list)
+        and bool(value)
+        and all(
+            isinstance(item, dict) and item.get("type") in WIRE_BLOCK_TYPES
+            for item in value
+        )
+    )
+
+
+def block_image_data(block: Any) -> str | None:
+    """Read base64 image bytes back out of a block, or None.
+
+    Tools that compose other tools' output (the orchestrator, the
+    benchmarks) need to unpack a block without re-deriving its layout.
+    """
+    if isinstance(block, dict) and block.get("type") == "image":
+        source = block.get("source")
+        if isinstance(source, dict):
+            return source.get("data")
+        return None
+    # An mcp.types model may still arrive from an older code path.
+    return getattr(block, "data", None)
+
+
+def block_uri(block: Any) -> str | None:
+    """Read a ``resource_link`` URI back out of a block, or None."""
+    if isinstance(block, dict):
+        return block.get("uri") if block.get("type") == "resource_link" else None
+    uri = getattr(block, "uri", None)
+    return None if uri is None else str(uri)
+
+
+def block_text(block: Any) -> str | None:
+    """Read the text back out of a ``text`` block, or None."""
+    if isinstance(block, dict):
+        return block.get("text") if block.get("type") == "text" else None
+    return getattr(block, "text", None)

{uxarray_mcp-0.2.2 → uxarray_mcp-0.3.0}/src/uxarray_mcp/domain/__init__.py

@@ -5,7 +5,8 @@ Functions here contain the pure domain logic used by both local tools
 """
 
 from .area import compute_area_stats
-from .mesh import load_dataset, load_grid
+from .mesh import is_healpix_spec, load_dataset, load_grid, parse_healpix_zoom
+from .remap_coverage import compute_target_coverage, method_is_conservative
 from .variable import compute_variable_info
 from .vector_calc import (
     compute_azimuthal_mean,
@@ -18,7 +19,11 @@ from .zonal import compute_zonal_anomaly_stats, compute_zonal_mean_stats
 __all__ = [
     "load_grid",
     "load_dataset",
+    "is_healpix_spec",
+    "parse_healpix_zoom",
     "compute_area_stats",
+    "compute_target_coverage",
+    "method_is_conservative",
     "compute_variable_info",
     "compute_zonal_mean_stats",
     "compute_zonal_anomaly_stats",