uxarray-mcp 0.1.2__tar.gz → 0.2.0__tar.gz

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uxarray-mcp
-Version: 0.1.2
+Version: 0.2.0
 Summary: MCP server for analyzing unstructured meshes with UXarray
 Keywords: uxarray,mcp,unstructured grids,scientific computing,globus compute
 Author: Rajeev Jain, Dayan Abdulla
@@ -299,6 +299,7 @@ uv tool install --python 3.12 uxarray-mcp
 # Or from a fresh clone (developer path)
 git clone https://github.com/UXARRAY/uxarray-mcp-server.git
 cd uxarray-mcp-server && uv sync --python 3.12
+# or: bash SETUP.sh   (does the sync + runs the local test suite in one step)
 ```
 
 > **Why `--python 3.12`?** The server uses Globus Compute to submit work to
@@ -350,8 +351,9 @@ client's MCP docs.
 uxarray-mcp doctor
 ```
 
-Should print `local execution: ok` and (if no endpoints configured) skip the
-remote checks.
+Prints a JSON diagnostic report. With no endpoints configured it reports a
+passing local setup and skips the remote checks; the process exits `0` when
+`passed` is true.
 
 ### Step 5 — Ask the AI to do something
 
@@ -361,6 +363,19 @@ In your client, try:
 
 That's it for local use.
 
+**A few more things to try:**
+
+- `Use run_analysis with operation="inspect_mesh" and grid_path="healpix:4"` —
+  no sample file needed; HEALPix meshes are generated on the fly.
+- `Run a complete scientific analysis on healpix:4` — the autonomous
+  Analyze → Plan → Execute → Verify agent (see
+  [docs/scientific-agent.md](docs/scientific-agent.md)).
+- `Create a session called baseline-analysis, register <grid> and <data> in
+  it, then run the workflow for <variable>` — persisted, resumable
+  multi-step runs (see [docs/workflows.md](docs/workflows.md)).
+- `Diagnose my configured endpoint status` — once you've added an endpoint
+  below, this is the fastest way to check it's healthy.
+
 ---
 
 ## Going beyond your laptop
@@ -380,21 +395,55 @@ Both paths assume you've finished local install above.
 
 ## What the MCP exposes
 
-Intent-shaped tools, not raw UXarray bindings:
+Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 - `get_capabilities` — what can I do with this mesh?
 - `analyze_dataset` — deterministic first-look: inspect, validate, area, zonal mean, plots.
 - `run_analysis` — one operation at a time (gradient, curl, subset, remap, …).
 - `plot_dataset` — mesh, geographic, variable, or zonal-mean plots.
-- `diagnose_endpoint`, `probe_path_access` — endpoint health + file readability.
 - `run_workflow`, `resume_workflow`, `get_status`, `get_result`, `manage_session` —
   persisted sessions and multi-step workflows.
 
-Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
-The dispatcher falls back to local if the endpoint is unhealthy.
-
 Full schema: [docs/tools.md](docs/tools.md).
 
+**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
+endpoint is unhealthy. Two more tools exist purely for that case:
+`diagnose_endpoint` and `probe_path_access` (endpoint health + file
+readability). Ignore all of this until you actually have an endpoint to point
+at.
+
+---
+
+## Transparency & correctness safeguards
+
+Because agent-driven analysis needs to be *trustworthy*, every result is
+auditable and the server actively flags common scientific pitfalls:
+
+- **Provenance on everything.** Each result carries a `_provenance` block:
+  the tool that ran, timestamp, input arguments, `execution_venue`
+  (`local` or `hpc:<endpoint>`), and the UXarray/Python versions used.
+- **Derivative unit convention is never hidden.** `gradient`, `curl`, and
+  `divergence` echo `scale_by_radius` in both the result and provenance, so a
+  unit-sphere result can never be mistaken for a physical (per-metre) one.
+  Gradient and curl default to physical scaling, matching UXarray; pass
+  `scale_by_radius=False` explicitly for unit-sphere output.
+- **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
+  when the two inputs are the same field, or when neither carries a
+  velocity/flux-like `units` attribute — the classic "vorticity from two random
+  scalars" mistake now surfaces a warning in `_provenance.warnings` and a
+  machine-actionable `scientific_status` with stable warning codes.
+- **Applicability is not suitability.** `get_capabilities` reports whether
+  vector operations are structurally computable separately from whether
+  metadata supports physical interpretation.
+- **Local/remote version drift is surfaced.** Remote results record the
+  worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
+  warning when it differs from the local version, so silent numerical
+  differences between venues can't slip through.
+- **Validation gating.** `analyze_dataset` validates a dataset (NaN/Inf/fill
+  checks) before computing statistics like the zonal mean.
+
 ---
 
 ## CLI reference
@@ -410,6 +459,24 @@ Full schema: [docs/tools.md](docs/tools.md).
 
 ---
 
+## Upgrading
+
+```bash
+uv tool upgrade --python 3.12 uxarray-mcp        # or your original install method
+```
+
+> **⚠️ Restart your AI client after upgrading.** MCP servers are launched once
+> when your client (Claude Desktop, Claude Code, Cursor, …) starts and are **not
+> hot-reloaded**. After upgrading the package, **fully quit and reopen your AI
+> client** so it relaunches `uxarray-mcp serve` with the new code. Until you do,
+> the running server keeps executing the *old* version — new tools and fixes
+> won't appear, and you may see confusing errors (for example, a `use_remote`
+> call on an HPC-only path failing with "file not found" because the old,
+> local-only tool is still loaded). If in doubt, run `uxarray-mcp doctor` and
+> check the reported version.
+
+---
+
 ## Risks (read before relying on output)
 
 AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.0}/README.md

@@ -63,6 +63,7 @@ uv tool install --python 3.12 uxarray-mcp
 # Or from a fresh clone (developer path)
 git clone https://github.com/UXARRAY/uxarray-mcp-server.git
 cd uxarray-mcp-server && uv sync --python 3.12
+# or: bash SETUP.sh   (does the sync + runs the local test suite in one step)
 ```
 
 > **Why `--python 3.12`?** The server uses Globus Compute to submit work to
@@ -114,8 +115,9 @@ client's MCP docs.
 uxarray-mcp doctor
 ```
 
-Should print `local execution: ok` and (if no endpoints configured) skip the
-remote checks.
+Prints a JSON diagnostic report. With no endpoints configured it reports a
+passing local setup and skips the remote checks; the process exits `0` when
+`passed` is true.
 
 ### Step 5 — Ask the AI to do something
 
@@ -125,6 +127,19 @@ In your client, try:
 
 That's it for local use.
 
+**A few more things to try:**
+
+- `Use run_analysis with operation="inspect_mesh" and grid_path="healpix:4"` —
+  no sample file needed; HEALPix meshes are generated on the fly.
+- `Run a complete scientific analysis on healpix:4` — the autonomous
+  Analyze → Plan → Execute → Verify agent (see
+  [docs/scientific-agent.md](docs/scientific-agent.md)).
+- `Create a session called baseline-analysis, register <grid> and <data> in
+  it, then run the workflow for <variable>` — persisted, resumable
+  multi-step runs (see [docs/workflows.md](docs/workflows.md)).
+- `Diagnose my configured endpoint status` — once you've added an endpoint
+  below, this is the fastest way to check it's healthy.
+
 ---
 
 ## Going beyond your laptop
@@ -144,21 +159,55 @@ Both paths assume you've finished local install above.
 
 ## What the MCP exposes
 
-Intent-shaped tools, not raw UXarray bindings:
+Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 - `get_capabilities` — what can I do with this mesh?
 - `analyze_dataset` — deterministic first-look: inspect, validate, area, zonal mean, plots.
 - `run_analysis` — one operation at a time (gradient, curl, subset, remap, …).
 - `plot_dataset` — mesh, geographic, variable, or zonal-mean plots.
-- `diagnose_endpoint`, `probe_path_access` — endpoint health + file readability.
 - `run_workflow`, `resume_workflow`, `get_status`, `get_result`, `manage_session` —
   persisted sessions and multi-step workflows.
 
-Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
-The dispatcher falls back to local if the endpoint is unhealthy.
-
 Full schema: [docs/tools.md](docs/tools.md).
 
+**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
+endpoint is unhealthy. Two more tools exist purely for that case:
+`diagnose_endpoint` and `probe_path_access` (endpoint health + file
+readability). Ignore all of this until you actually have an endpoint to point
+at.
+
+---
+
+## Transparency & correctness safeguards
+
+Because agent-driven analysis needs to be *trustworthy*, every result is
+auditable and the server actively flags common scientific pitfalls:
+
+- **Provenance on everything.** Each result carries a `_provenance` block:
+  the tool that ran, timestamp, input arguments, `execution_venue`
+  (`local` or `hpc:<endpoint>`), and the UXarray/Python versions used.
+- **Derivative unit convention is never hidden.** `gradient`, `curl`, and
+  `divergence` echo `scale_by_radius` in both the result and provenance, so a
+  unit-sphere result can never be mistaken for a physical (per-metre) one.
+  Gradient and curl default to physical scaling, matching UXarray; pass
+  `scale_by_radius=False` explicitly for unit-sphere output.
+- **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
+  when the two inputs are the same field, or when neither carries a
+  velocity/flux-like `units` attribute — the classic "vorticity from two random
+  scalars" mistake now surfaces a warning in `_provenance.warnings` and a
+  machine-actionable `scientific_status` with stable warning codes.
+- **Applicability is not suitability.** `get_capabilities` reports whether
+  vector operations are structurally computable separately from whether
+  metadata supports physical interpretation.
+- **Local/remote version drift is surfaced.** Remote results record the
+  worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
+  warning when it differs from the local version, so silent numerical
+  differences between venues can't slip through.
+- **Validation gating.** `analyze_dataset` validates a dataset (NaN/Inf/fill
+  checks) before computing statistics like the zonal mean.
+
 ---
 
 ## CLI reference
@@ -174,6 +223,24 @@ Full schema: [docs/tools.md](docs/tools.md).
 
 ---
 
+## Upgrading
+
+```bash
+uv tool upgrade --python 3.12 uxarray-mcp        # or your original install method
+```
+
+> **⚠️ Restart your AI client after upgrading.** MCP servers are launched once
+> when your client (Claude Desktop, Claude Code, Cursor, …) starts and are **not
+> hot-reloaded**. After upgrading the package, **fully quit and reopen your AI
+> client** so it relaunches `uxarray-mcp serve` with the new code. Until you do,
+> the running server keeps executing the *old* version — new tools and fixes
+> won't appear, and you may see confusing errors (for example, a `use_remote`
+> call on an HPC-only path failing with "file not found" because the old,
+> local-only tool is still loaded). If in doubt, run `uxarray-mcp doctor` and
+> check the reported version.
+
+---
+
 ## Risks (read before relying on output)
 
 AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,

uxarray_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "uxarray-mcp"
+version = "0.2.0"
+description = "MCP server for analyzing unstructured meshes with UXarray"
+readme = "README.md"
+keywords = [
+    "uxarray",
+    "mcp",
+    "unstructured grids",
+    "scientific computing",
+    "globus compute",
+]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+]
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "toolregistry-server[mcp]>=0.4.0",
+    "holoviews>=1.19.0",
+    "matplotlib>=3.9.0",
+    "pyyaml>=6.0",
+    "uxarray>=2026.6.0",
+]
+
+[[project.authors]]
+name = "Rajeev Jain"
+email = "rajeeja@gmail.com"
+
+[[project.authors]]
+name = "Dayan Abdulla"
+email = "dayanabdulla000@gmail.com"
+
+[project.license]
+file = "LICENSE"
+
+[project.optional-dependencies]
+openapi = ["toolregistry-server[openapi]>=0.4.0"]
+hpc = [
+    "academy-py>=0.3.1",
+    "globus-compute-sdk>=4.5.0",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-book-theme>=1.1.0",
+    "myst-parser>=3.0",
+]
+
+[project.scripts]
+uxarray-mcp = "uxarray_mcp.cli:main"
+
+[project.urls]
+Documentation = "https://uxarray-mcp-server.readthedocs.io"
+Source = "https://github.com/UXARRAY/uxarray-mcp-server"
+Tracker = "https://github.com/UXARRAY/uxarray-mcp-server/issues"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10.0",
+    "pre-commit>=4.3.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.15.2",
+]
+
+[tool.mypy]
+python_version = "3.12"
+check_untyped_defs = true
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_return_any = false
+exclude = [
+    "tests/",
+    "docs/",
+]
+
+[[tool.mypy.overrides]]
+module = "yaml"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "uxarray_mcp.remote.agent"
+warn_unused_ignores = false
+
+[tool.ruff]
+extend-exclude = ["docs/architecture.html"]
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.ruff.lint.per-file-ignores]
+"notebooks/*.py" = ["E402"]
+"notebooks/*.ipynb" = ["E402"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["uxarray_mcp"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

uxarray_mcp-0.1.2/pyproject.toml → uxarray_mcp-0.2.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "uxarray-mcp"
-version = "0.1.2"
+version = "0.2.0"
 description = "MCP server for analyzing unstructured meshes with UXarray"
 readme = "README.md"
 keywords = ["uxarray", "mcp", "unstructured grids", "scientific computing", "globus compute"]
@@ -93,6 +93,10 @@ extend-exclude = ["docs/architecture.html"]
 
 [tool.ruff.lint]
 extend-select = ["I"]
+# Notebooks (and their jupytext-paired .py scripts) intentionally scatter
+# imports across per-cell (# %%) blocks, so E402 (module-import-not-at-top)
+# is expected style there, not a lint violation.
+per-file-ignores = { "notebooks/*.py" = ["E402"], "notebooks/*.ipynb" = ["E402"] }
 
 [tool.ruff.lint.isort]
 known-first-party = ["uxarray_mcp"]

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.0}/src/uxarray_mcp/__init__.py

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

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.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 (~27 tools). "
-            "deferred-full: also load 30 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (~31 tools). "
+            "deferred-full: also load 32 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )
@@ -317,7 +317,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--transport",
         choices=("stdio", "sse", "http"),
         default="stdio",
-        help="MCP transport. stdio for Claude Desktop subprocess use.",
+        help="MCP transport. stdio for subprocess use by MCP clients.",
     )
     serve.add_argument("--host", default="127.0.0.1", help="Bind host for SSE/HTTP.")
     serve.add_argument("--port", type=int, default=8001, help="Port for SSE/HTTP.")
@@ -330,8 +330,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("core", "deferred-full"),
         default="core",
         help=(
-            "core: gateway + control + list_datasets + prompts (~27 tools). "
-            "deferred-full: also load 30 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (~31 tools). "
+            "deferred-full: also load 32 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )
@@ -347,7 +347,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--execution-mode",
         default="auto",
         choices=["local", "auto", "hpc"],
-        help="Default execution mode (default: auto).",
+        help=(
+            "Default execution mode (default: auto). 'auto' runs local-only "
+            "until you add an endpoint with `endpoints add`, then uses it "
+            "automatically. Most users never need to change this."
+        ),
     )
     setup.add_argument("--force", action="store_true", help="Overwrite existing file.")
     setup.set_defaults(func=cmd_setup)
@@ -377,12 +381,42 @@ def build_parser() -> argparse.ArgumentParser:
     ep_remove.add_argument("name")
     ep_remove.set_defaults(func=cmd_endpoints_remove)
 
-    doctor = sub.add_parser("doctor", help="Validate HPC readiness.")
-    doctor.add_argument("--sample-path", action="append", default=[])
-    doctor.add_argument("--timeout-seconds", type=int, default=180)
-    doctor.add_argument("--endpoint", default=None)
-    doctor.add_argument("--skip-remote-probe", action="store_true")
-    doctor.add_argument("--no-netcdf", action="store_true")
+    doctor = sub.add_parser(
+        "doctor",
+        help="Check that the install is healthy (local-only or HPC).",
+        description=(
+            "Run local-only by default; add an HPC endpoint (`endpoints add`) "
+            "to also validate remote readiness. With no endpoint configured, "
+            "this reports a passing local-only result — HPC is opt-in."
+        ),
+    )
+    doctor.add_argument(
+        "--sample-path",
+        action="append",
+        default=[],
+        help="Remote file path to test-read (repeatable). Requires an endpoint.",
+    )
+    doctor.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=180,
+        help="Seconds to wait for the remote worker probe (ignored if no endpoint).",
+    )
+    doctor.add_argument(
+        "--endpoint",
+        default=None,
+        help="Named endpoint to validate. Omit to check the default/local-only setup.",
+    )
+    doctor.add_argument(
+        "--skip-remote-probe",
+        action="store_true",
+        help="Skip submitting a test job to the endpoint (config/auth checks only).",
+    )
+    doctor.add_argument(
+        "--no-netcdf",
+        action="store_true",
+        help="Skip opening --sample-path as NetCDF; just check readability.",
+    )
     doctor.set_defaults(func=cmd_doctor)
 
     claude = sub.add_parser(

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.0}/src/uxarray_mcp/domain/area.py

@@ -14,11 +14,16 @@ def compute_area_stats(grid: Any) -> dict:
     Returns
     -------
     dict
-        Keys: total_area, mean_area, min_area, max_area, area_units, n_face
+        Keys: total_area, mean_area, min_area, max_area, area_units, n_face.
+        ``area_units`` is ``None`` when the grid carries no ``units``
+        attribute at all -- reporting a fabricated ``"m^2"`` default in
+        that case would silently invent metadata the source file never
+        provided, which is the exact failure mode this server's
+        provenance and guardrail mechanisms exist to prevent.
     """
     face_areas = grid.face_areas
 
-    area_units = "m^2"
+    area_units = None
     if hasattr(face_areas, "attrs") and "units" in face_areas.attrs:
         area_units = face_areas.attrs["units"]
 

{uxarray_mcp-0.1.2 → uxarray_mcp-0.2.0}/src/uxarray_mcp/domain/mesh.py

@@ -47,17 +47,22 @@ def load_dataset(grid_path: str, data_path: str) -> Any:
         Loaded dataset object.
     """
     import uxarray as ux
+    import xarray as xr
 
-    # HEALPix is a special case (usually grid-only, but we support it if matched)
+    # HEALPix and GIS grids don't round-trip through ux.open_dataset() as a
+    # "grid file" the way a real UGRID/MPAS/SCRIP file does: grid.to_xarray()
+    # returns a minimal representation (e.g. HEALPix has no node coordinates)
+    # that the generic UGRID reader rejects. Attach the data directly to the
+    # already-loaded Grid object instead.
     if grid_path.lower().startswith("healpix"):
         parts = grid_path.split(":")
         zoom = int(parts[1]) if len(parts) > 1 else 1
         grid = ux.Grid.from_healpix(zoom=zoom)
-        return ux.open_dataset(grid.to_xarray(), data_path)
+        return ux.UxDataset(xr.open_dataset(data_path), uxgrid=grid)
 
     ext = os.path.splitext(grid_path.lower())[1]
     if ext in [".shp", ".geojson"]:
         grid = ux.Grid.from_file(grid_path, backend="geopandas")
-        return ux.open_dataset(grid.to_xarray(), data_path)
+        return ux.UxDataset(xr.open_dataset(data_path), uxgrid=grid)
 
     return ux.open_dataset(grid_path, data_path)