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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uxarray-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: MCP server for analyzing unstructured meshes with UXarray
 Keywords: uxarray,mcp,unstructured grids,scientific computing,globus compute
 Author: Rajeev Jain, Dayan Abdulla
@@ -212,257 +212,231 @@ 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: fastmcp>=3.4.0
+Requires-Dist: toolregistry-server[mcp]>=0.4.0
 Requires-Dist: holoviews>=1.19.0
 Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: uxarray>=2025.12.0
+Requires-Dist: uxarray>=2026.6.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-Python: >=3.11
+Requires-Dist: toolregistry-server[openapi]>=0.4.0 ; extra == 'openapi'
+Requires-Python: >=3.12, <3.13
 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
 Provides-Extra: docs
 Provides-Extra: hpc
+Provides-Extra: openapi
 Description-Content-Type: text/markdown
 
 # UXarray MCP Server
 
-An MCP server that exposes [UXarray](https://uxarray.readthedocs.io/) tools to
-AI clients such as Claude. It supports:
+An MCP server that lets an AI assistant (Claude Code, Claude Desktop, Cursor,
+or any MCP client) analyze unstructured climate meshes with
+[UXarray](https://uxarray.readthedocs.io/) — locally on your machine, or
+remotely on an HPC system you have access to.
 
-- local execution for normal mesh analysis
-- optional remote execution on HPC systems through Globus Compute
-- diagnostics and provenance for scientific workflows
+```text
+┌─────────────┐  stdio  ┌──────────────┐                    ┌─────────────────┐
+│  AI client  │ ◀─────▶ │ uxarray-mcp  │ ◀── Globus ──────▶ │  HPC endpoint   │
+│  (Claude…)  │   pipe  │ (your laptop)│    Compute (opt)   │ (Slurm/PBS node)│
+└─────────────┘         └──────────────┘                    └─────────────────┘
+```
 
-## How it runs
+> **What the AI can do.** Open meshes and datasets, compute area / zonal mean
+> / vorticity / divergence, subset, remap, plot, and run multi-step workflows.
+> All as natural-language prompts.
 
-The server runs as a subprocess of the MCP client (Claude Code, Claude Desktop,
-or any FastMCP transport) and dispatches tool calls either locally or to a
-configured Globus Compute endpoint on an HPC cluster. Same MCP tool, same
-schema — `use_remote: bool` on every tool decides which path runs.
+> **Local by default; HPC is opt-in.** Everything runs on your machine unless
+> you configure a [Globus Compute](https://www.globus.org/compute) endpoint.
+> The remote option only becomes available once such an endpoint exists —
+> running one requires an account and allocation on that HPC system, though a
+> shared/service-account endpoint can let authorized users submit without their
+> own login.
 
-**Local mode** — analysis on your machine, files on your disk:
+> **⚠️ What the AI can access.** Any file you (or your HPC account) can read.
+> Any compute the configured endpoint can submit. Outputs are written to your
+> disk. **See [SECURITY.md](SECURITY.md) before connecting any remote endpoint.**
 
-```
- ┌────────────────┐         ┌─────────────────────────────┐
- │  Claude Code   │  stdio  │  uv run python -m           │      reads
- │  / Desktop     │ ◀─────▶ │  uxarray_mcp                │ ───▶  local
- │                │  pipe   │  (subprocess on your box)   │       mesh files
- └────────────────┘         └─────────────────────────────┘
-```
+---
 
-**HPC mode** — analysis on facility hardware, files stay on facility storage:
+## Pick your path
 
-```
- ┌────────────────┐  stdio  ┌─────────────────────────┐  Globus  ┌─────────────────────────┐
- │  Claude Code   │ ◀─────▶ │  uxarray_mcp on laptop  │ ◀──────▶ │  Worker on HPC endpoint │      reads
- │  / Desktop     │  pipe   │  (dispatches when       │  Compute │  (uxarray reads file    │ ───▶ facility
- │                │         │   use_remote=True)      │  RPC     │   from facility GPFS)   │      mesh files
- └────────────────┘         └─────────────────────────┘          └─────────────────────────┘      (never copied)
-```
+You are most likely one of:
+
+1. **Local user** — laptop only, no HPC. → [Local install](#local-install).
+2. **HPC user, endpoint already exists** — someone at your lab gave you a
+   Globus Compute endpoint UUID. → [Local install](#local-install), then
+   [docs/remote-hpc.md](docs/remote-hpc.md).
+3. **HPC user, your own personal endpoint** — you have a Globus identity and
+   shell access to an HPC machine, and want to stand up an endpoint just for
+   yourself. → [Local install](#local-install), then
+   [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md#solo-personal-endpoint-quickstart).
+4. **Group / shared endpoint operator** — you're standing one up for a team,
+   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.
+
+---
+
+## Local install
+
+Five steps. Each is one command unless noted.
 
-The dispatcher falls back to local execution if a remote call is requested
-but the endpoint is missing or unhealthy.
+### Step 1 — Install the package
 
-## Install
+Pick one. `uv` is the easiest; `pip` works too.
 
 ```bash
-# Stable user path (after the package is published)
-uv tool install uxarray-mcp
-uxarray-mcp setup
-uxarray-mcp install-claude --print-only   # prints the Claude Desktop block
+# Recommended
+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
 ```
 
+> **Why `--python 3.12`?** The server uses Globus Compute to submit work to
+> HPC endpoints, and Globus Compute's serializer is fragile across Python
+> minor versions — a 3.13 submitter against a 3.12 endpoint worker raises
+> `WorkerLost` on non-trivial payloads. HPC sites broadly ship 3.12 conda
+> stacks today, so we pin the install to match. Tracking removal of this pin
+> at [globus/globus-compute#2139](https://github.com/globus/globus-compute/issues/2139).
+> `uv` downloads 3.12 automatically if your system doesn't have it.
+
+### Step 2 — Write a starter config
+
 ```bash
-# Stable user path with HPC support
-uv tool install "uxarray-mcp[hpc]"
 uxarray-mcp setup
-uxarray-mcp endpoints add improv <your-endpoint-uuid> --set-default
-uxarray-mcp doctor --endpoint improv --timeout-seconds 180
 ```
 
+Creates `~/.config/uxarray-mcp/config.yaml` with sensible defaults. Local mode
+needs nothing more.
+
+### Step 3 — Connect your AI client
+
+**Claude Desktop**
+
 ```bash
-# Developer / contributor path, and best path when using repo scripts/docs
-git clone https://github.com/UXARRAY/uxarray-mcp-server.git
-cd uxarray-mcp-server
-uv sync                 # core local install
-uv sync --extra hpc     # add Globus Compute deps
+uxarray-mcp install-claude        # merges the mcpServers block into your config
+# or
+uxarray-mcp install-claude --print-only   # prints the JSON to paste manually
 ```
 
+Restart Claude Desktop. The `uxarray` server should appear in Settings →
+Developer.
+
+**Claude Code**
+
 ```bash
-# User install directly from GitHub before a PyPI release exists
-uv tool install "git+https://github.com/UXARRAY/uxarray-mcp-server.git"
-uxarray-mcp setup
-uxarray-mcp endpoints add improv <your-endpoint-uuid>
-uxarray-mcp install-claude --print-only   # prints the Claude Desktop block
+claude mcp add uxarray --transport stdio -- uxarray-mcp serve
 ```
 
-The ``uxarray-mcp`` CLI exposes:
+Then `/mcp` in Claude Code; pick `uxarray`.
 
-| subcommand          | what it does                                             |
-| ------------------- | -------------------------------------------------------- |
-| ``serve``           | run the MCP server on stdio (Claude / FastMCP transport) |
-| ``setup``           | write a starter config to ``~/.config/uxarray-mcp/``     |
-| ``endpoints add``   | register a named Globus Compute endpoint                 |
-| ``endpoints list``  | show configured endpoints + discovery path               |
-| ``doctor``          | validate auth, endpoint health, optional remote probes   |
-| ``install-claude``  | print or merge the Claude Desktop ``mcpServers`` block   |
+**Cursor / other MCP clients**
 
-Config is discovered in this order: ``$UXARRAY_MCP_CONFIG`` →
-``~/.config/uxarray-mcp/config.yaml`` → ``./config.yaml`` (repo root).
+Add an MCP server entry pointing at `uxarray-mcp serve` over stdio. See your
+client's MCP docs.
 
-## Most Users Should Read These in Order
+### Step 4 — Sanity check
 
-1. [GETTING_STARTED.md](GETTING_STARTED.md) for the short setup path
-2. [docs/getting-started.md](docs/getting-started.md) for the full walkthrough
-3. [docs/globus-compute.md](docs/globus-compute.md) if you are new to Globus Compute
-4. [docs/hpc.md](docs/hpc.md) for generic cluster bring-up
-5. [docs/improv.md](docs/improv.md) if you are on Argonne Improv
-6. [docs/ucar.md](docs/ucar.md) if you are on NCAR Casper
-7. [docs/chrysalis.md](docs/chrysalis.md) if you are on Argonne Chrysalis
-6. [docs/workflows.md](docs/workflows.md) for sequential remote workflows
+```bash
+uxarray-mcp doctor
+```
 
-## Main Tools
+Should print `local execution: ok` and (if no endpoints configured) skip the
+remote checks.
 
-Analysis:
+### Step 5 — Ask the AI to do something
 
-- `inspect_mesh` — topology, format detection, face/node/edge counts
-- `inspect_variable` — variable metadata, location, and statistics
-- `calculate_area` — face area statistics
-- `calculate_zonal_mean` — latitude-band averaging (conservative or standard)
-- `validate_dataset` — NaN, Inf, and fill value checks
-- `run_scientific_agent` — autonomous Analyze → Plan → Execute → Verify pipeline
-- `subset_bbox` / `subset_polygon` / `extract_cross_section` — spatial queries and regional reductions
-- `calculate_gradient`, `calculate_curl`, `calculate_divergence`, `calculate_azimuthal_mean` — vector calculus and radial summaries
-- `compare_fields`, `calculate_bias`, `calculate_rmse`, `calculate_pattern_correlation` — same-grid comparison metrics
-- `remap_variable` / `regrid_dataset` — UXarray-backed remapping to a target grid
-- `calculate_temporal_mean`, `calculate_anomaly`, `calculate_ensemble_mean`, `calculate_ensemble_spread` — temporal and ensemble summaries
-- `export_to_netcdf`, `export_to_csv`, `write_result` — persist derived results to downstream formats
+In your client, try:
 
-Stateful workflows:
+> "Open `<path to a UGRID/MPAS/SCRIP grid file>` and plot the mesh."
 
-- `create_session`, `register_dataset`, `get_session_state`, `reset_session_state`
-- `run_workflow`, `resume_workflow`, `get_workflow_status`
-- `get_result_handle`, `get_operation_status`, `list_operations`
+That's it for local use.
 
-Visualization (returns inline PNG):
+---
 
-- `plot_mesh` — mesh wireframe
-- `plot_mesh_geo` — geographic mesh plot with boundary-aware rendering
-- `plot_variable` — face-centered variable as filled polygon map; supports `cmap`, `vmin`, `vmax`, `title`
-- `plot_zonal_mean` — latitude vs. value line chart; supports `line_color`, `title`
+## Going beyond your laptop
 
-HPC diagnostics:
+If you have an HPC account at a national lab or university cluster with
+[Globus Compute](https://www.globus.org/compute) available:
 
-- `get_execution_mode` / `set_execution_mode`
-- `endpoint_status`
-- `validate_hpc_setup`
-- `probe_path_access`
+| You want to … | Read this |
+|---|---|
+| Connect to an endpoint someone else set up | **[docs/remote-hpc.md](docs/remote-hpc.md)** |
+| Stand up your own endpoint | **[docs/operating-an-endpoint.md](docs/operating-an-endpoint.md)** |
+| Understand the security model first | **[SECURITY.md](SECURITY.md)** |
 
-All inspection, computation, and plotting tools accept ``use_remote: bool``
-and ``endpoint: str | None``. When ``use_remote=True`` the dispatcher submits
-to the configured (or named) Globus Compute endpoint and falls back to local
-execution if the endpoint is missing or unhealthy. There are no separate
-``*_hpc`` tool names on the MCP surface — the same tool runs locally or
-remotely based on the flag.
+Both paths assume you've finished local install above.
 
-Full parameter and return details live in [docs/tools.md](docs/tools.md).
+---
 
-## Helper Scripts
+## What the MCP exposes
 
-- `scripts/hpc_doctor.py`
-  First-pass CLI doctor for local auth, endpoint status, remote no-op
-  execution, and optional real-path probing.
-- `scripts/improv_endpoint.sh`
-  Writes Improv endpoint templates for single-host validation or PBS debug.
-- `scripts/agentic_hpc_loop.py`
-  Example submit/poll/branch workflow using Globus Compute futures directly.
+Intent-shaped tools, not raw UXarray bindings:
 
-## HPC in One Paragraph
+- `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.
 
-Remote execution has three separate layers:
+Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
+The dispatcher falls back to local if the endpoint is unhealthy.
 
-1. the local machine running this repository
-2. the endpoint running on the HPC machine
-3. the remote worker environment that must also have `uxarray`, `xarray`,
-   `netCDF4`, and `h5netcdf`
+Full schema: [docs/tools.md](docs/tools.md).
 
-Most confusing failures happen because only one or two of those layers are set
-up. Start with [docs/globus-compute.md](docs/globus-compute.md) and use
-`validate_hpc_setup()` before real remote jobs.
+---
 
-## Configuration
+## CLI reference
 
-Use the CLI for the common case:
+| Command | Purpose |
+|---|---|
+| `uxarray-mcp serve` | Run the MCP server (used by your AI client) |
+| `uxarray-mcp setup` | Write a starter config |
+| `uxarray-mcp endpoints add NAME UUID` | Register a Globus Compute endpoint |
+| `uxarray-mcp endpoints list` | Show configured endpoints |
+| `uxarray-mcp doctor` | Validate local + (optionally) remote setup |
+| `uxarray-mcp install-claude` | Merge or print the Claude Desktop config block |
 
-```bash
-uxarray-mcp setup
-uxarray-mcp endpoints add improv <your-endpoint-uuid> --path-prefix /lus/ --set-default
-```
+---
 
-This writes ``~/.config/uxarray-mcp/config.yaml`` with the canonical
-multi-endpoint schema. For dev clones, ``./config.yaml`` at the repo root
-still works (and is gitignored). The full schema:
-
-```yaml
-hpc:
-  default_endpoint: "ucar"
-  endpoints:
-    ucar:
-      endpoint_id: "your-ucar-endpoint-uuid"
-      path_prefixes: ["/glade/"]
-    improv:
-      endpoint_id: "your-improv-endpoint-uuid"
-      path_prefixes: ["/gpfs/fs1/", "/home/jain/"]
-  execution_mode: "auto"
-  timeout_seconds: 300
-```
+## Risks (read before relying on output)
 
-Remote tools accept `endpoint="ucar"` or `endpoint="improv"`; when omitted,
-the server routes by path prefix before falling back to `default_endpoint`.
+AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,
+sphere-radius scaling on derivatives), or run long jobs on your HPC
+allocation. uxarray-mcp does **not** guarantee correctness of agent-driven
+analysis. You are responsible for:
 
-## Development Checks
+- Verifying numerical results before publishing.
+- Reviewing what files the agent opens.
+- Monitoring HPC job submissions against your allocation.
 
-```bash
-uv run pre-commit run --all-files
-uv run pytest tests/ --ignore=tests/test_remote_agent.py
-uv sync --extra docs --dev
-uv run sphinx-build -b html docs docs/_build/html
-```
+For the security model (what the agent and the endpoint operator can access),
+see **[SECURITY.md](SECURITY.md)**.
 
-## Publishing
+---
 
-Releases follow the UXarray pattern: publish a GitHub Release from a version tag
-such as `v0.1.0`; the release workflow builds and publishes to PyPI with trusted
-publishing. Conda packages are handled through a separate conda-forge feedstock;
-`conda/recipe/meta.yaml` is a seed recipe for `uxarray-mcp-feedstock`.
+## Development
 
 ```bash
-uv build
-uv tool install dist/uxarray_mcp-*.whl --force
-uxarray-mcp --help
+uv sync --extra hpc --extra docs --dev
+uv run pre-commit run --all-files
+uv run pytest tests/ --ignore=tests/test_remote_agent.py
+uv run sphinx-build -b html docs docs/_build/html
 ```
 
-See [docs/release.md](docs/release.md) for the full PyPI and Conda workflow.
+Release process: [docs/release.md](docs/release.md).
 
-## Documentation Index
+## License
 
-- [GETTING_STARTED.md](GETTING_STARTED.md)
-- [docs/getting-started.md](docs/getting-started.md)
-- [docs/globus-compute.md](docs/globus-compute.md)
-- [docs/hpc.md](docs/hpc.md)
-- [docs/improv.md](docs/improv.md)
-- [docs/ucar.md](docs/ucar.md)
-- [docs/chrysalis.md](docs/chrysalis.md)
-- [docs/tools.md](docs/tools.md)
-- [docs/workflows.md](docs/workflows.md)
-- [docs/scientific-agent.md](docs/scientific-agent.md)
+See [LICENSE](LICENSE).

uxarray_mcp-0.1.2/README.md

@@ -0,0 +1,206 @@
+# UXarray MCP Server
+
+An MCP server that lets an AI assistant (Claude Code, Claude Desktop, Cursor,
+or any MCP client) analyze unstructured climate meshes with
+[UXarray](https://uxarray.readthedocs.io/) — locally on your machine, or
+remotely on an HPC system you have access to.
+
+```text
+┌─────────────┐  stdio  ┌──────────────┐                    ┌─────────────────┐
+│  AI client  │ ◀─────▶ │ uxarray-mcp  │ ◀── Globus ──────▶ │  HPC endpoint   │
+│  (Claude…)  │   pipe  │ (your laptop)│    Compute (opt)   │ (Slurm/PBS node)│
+└─────────────┘         └──────────────┘                    └─────────────────┘
+```
+
+> **What the AI can do.** Open meshes and datasets, compute area / zonal mean
+> / vorticity / divergence, subset, remap, plot, and run multi-step workflows.
+> All as natural-language prompts.
+
+> **Local by default; HPC is opt-in.** Everything runs on your machine unless
+> you configure a [Globus Compute](https://www.globus.org/compute) endpoint.
+> The remote option only becomes available once such an endpoint exists —
+> running one requires an account and allocation on that HPC system, though a
+> shared/service-account endpoint can let authorized users submit without their
+> own login.
+
+> **⚠️ What the AI can access.** Any file you (or your HPC account) can read.
+> Any compute the configured endpoint can submit. Outputs are written to your
+> disk. **See [SECURITY.md](SECURITY.md) before connecting any remote endpoint.**
+
+---
+
+## Pick your path
+
+You are most likely one of:
+
+1. **Local user** — laptop only, no HPC. → [Local install](#local-install).
+2. **HPC user, endpoint already exists** — someone at your lab gave you a
+   Globus Compute endpoint UUID. → [Local install](#local-install), then
+   [docs/remote-hpc.md](docs/remote-hpc.md).
+3. **HPC user, your own personal endpoint** — you have a Globus identity and
+   shell access to an HPC machine, and want to stand up an endpoint just for
+   yourself. → [Local install](#local-install), then
+   [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md#solo-personal-endpoint-quickstart).
+4. **Group / shared endpoint operator** — you're standing one up for a team,
+   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.
+
+---
+
+## Local install
+
+Five steps. Each is one command unless noted.
+
+### Step 1 — Install the package
+
+Pick one. `uv` is the easiest; `pip` works too.
+
+```bash
+# Recommended
+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
+```
+
+> **Why `--python 3.12`?** The server uses Globus Compute to submit work to
+> HPC endpoints, and Globus Compute's serializer is fragile across Python
+> minor versions — a 3.13 submitter against a 3.12 endpoint worker raises
+> `WorkerLost` on non-trivial payloads. HPC sites broadly ship 3.12 conda
+> stacks today, so we pin the install to match. Tracking removal of this pin
+> at [globus/globus-compute#2139](https://github.com/globus/globus-compute/issues/2139).
+> `uv` downloads 3.12 automatically if your system doesn't have it.
+
+### Step 2 — Write a starter config
+
+```bash
+uxarray-mcp setup
+```
+
+Creates `~/.config/uxarray-mcp/config.yaml` with sensible defaults. Local mode
+needs nothing more.
+
+### Step 3 — Connect your AI client
+
+**Claude Desktop**
+
+```bash
+uxarray-mcp install-claude        # merges the mcpServers block into your config
+# or
+uxarray-mcp install-claude --print-only   # prints the JSON to paste manually
+```
+
+Restart Claude Desktop. The `uxarray` server should appear in Settings →
+Developer.
+
+**Claude Code**
+
+```bash
+claude mcp add uxarray --transport stdio -- uxarray-mcp serve
+```
+
+Then `/mcp` in Claude Code; pick `uxarray`.
+
+**Cursor / other MCP clients**
+
+Add an MCP server entry pointing at `uxarray-mcp serve` over stdio. See your
+client's MCP docs.
+
+### Step 4 — Sanity check
+
+```bash
+uxarray-mcp doctor
+```
+
+Should print `local execution: ok` and (if no endpoints configured) skip the
+remote checks.
+
+### Step 5 — Ask the AI to do something
+
+In your client, try:
+
+> "Open `<path to a UGRID/MPAS/SCRIP grid file>` and plot the mesh."
+
+That's it for local use.
+
+---
+
+## Going beyond your laptop
+
+If you have an HPC account at a national lab or university cluster with
+[Globus Compute](https://www.globus.org/compute) available:
+
+| You want to … | Read this |
+|---|---|
+| Connect to an endpoint someone else set up | **[docs/remote-hpc.md](docs/remote-hpc.md)** |
+| Stand up your own endpoint | **[docs/operating-an-endpoint.md](docs/operating-an-endpoint.md)** |
+| Understand the security model first | **[SECURITY.md](SECURITY.md)** |
+
+Both paths assume you've finished local install above.
+
+---
+
+## What the MCP exposes
+
+Intent-shaped tools, not raw UXarray bindings:
+
+- `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).
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `uxarray-mcp serve` | Run the MCP server (used by your AI client) |
+| `uxarray-mcp setup` | Write a starter config |
+| `uxarray-mcp endpoints add NAME UUID` | Register a Globus Compute endpoint |
+| `uxarray-mcp endpoints list` | Show configured endpoints |
+| `uxarray-mcp doctor` | Validate local + (optionally) remote setup |
+| `uxarray-mcp install-claude` | Merge or print the Claude Desktop config block |
+
+---
+
+## Risks (read before relying on output)
+
+AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,
+sphere-radius scaling on derivatives), or run long jobs on your HPC
+allocation. uxarray-mcp does **not** guarantee correctness of agent-driven
+analysis. You are responsible for:
+
+- Verifying numerical results before publishing.
+- Reviewing what files the agent opens.
+- Monitoring HPC job submissions against your allocation.
+
+For the security model (what the agent and the endpoint operator can access),
+see **[SECURITY.md](SECURITY.md)**.
+
+---
+
+## Development
+
+```bash
+uv sync --extra hpc --extra docs --dev
+uv run pre-commit run --all-files
+uv run pytest tests/ --ignore=tests/test_remote_agent.py
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+Release process: [docs/release.md](docs/release.md).
+
+## License
+
+See [LICENSE](LICENSE).