Simplify MCP tool surface

CHANGELOG.md

@@ -49,6 +49,11 @@ under their entry.
 - Apache 2.0 LICENSE.
 
 ### Changed
+- Reduced the public MCP surface to front-door tools (`run_analysis`,
+  `plot_dataset`, `diagnose_endpoint`, `manage_session`, `get_status`,
+  `get_result`, workflows, and discovery) while keeping low-level
+  implementation functions available as Python APIs. Slash commands now point
+  at workflows/front doors instead of individual implementation tools.
 - Collapsed the `*_hpc` tool surface. The unified tools
   (`inspect_mesh`, `inspect_variable`, `calculate_area`, plotting tools,
   etc.) accept `use_remote: bool` and `endpoint: str | None`; there are

README.md

@@ -98,49 +98,32 @@ endpoints are not shadowed by an empty user config.
 7. [docs/chrysalis.md](docs/chrysalis.md) if you are on Argonne Chrysalis
 6. [docs/workflows.md](docs/workflows.md) for sequential remote workflows
 
-## Main Tools
-
-Analysis:
-
-- `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
-
-Stateful workflows:
-
-- `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`
-
-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`
-
-HPC diagnostics:
-
-- `get_execution_mode` / `set_execution_mode`
-- `endpoint_status`
-- `validate_hpc_setup`
-- `probe_path_access`
-
-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.
+## MCP Front-Door Tools
+
+The MCP surface is intentionally small. Low-level UXarray functions are still
+available as Python APIs inside `uxarray_mcp.tools`, but MCP clients see
+intent-shaped tools:
+
+- `get_capabilities` — discover topology, variables, applicable operations,
+  and next steps.
+- `analyze_dataset` — deterministic first-look pipeline: inspect, validate,
+  area, zonal mean, and plots where possible.
+- `run_analysis` — one-operation dispatcher for inspection, validation,
+  area/zonal statistics, subsetting, vector calculus, comparison, remapping,
+  temporal/ensemble summaries, and export.
+- `plot_dataset` — mesh, geographic mesh, variable, or zonal-mean plots.
+- `diagnose_endpoint` and `probe_path_access` — endpoint status, setup
+  validation, and exact path readability checks.
+- `run_workflow`, `resume_workflow`, `get_status`, `get_result`, and
+  `manage_session` — persisted sessions, workflows, operation status, and
+  result handles.
+
+`analyze_dataset`, `run_analysis`, `plot_dataset`, and `probe_path_access`
+accept ``use_remote: bool`` and ``endpoint: str | None`` where remote execution
+applies. 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.
 
 Full parameter and return details live in [docs/tools.md](docs/tools.md).
 
@@ -165,7 +148,7 @@ Remote execution has three separate layers:
 
 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.
+`diagnose_endpoint(action="validate")` before real remote jobs.
 
 ## Configuration
 

docs/architecture.html

@@ -204,7 +204,7 @@ <h1>UXarray MCP Server — Architecture Diagram</h1>
   <rect x="387" y="76" width="306" height="74" rx="8" fill="#091c35" stroke="#1f6feb" stroke-width="2"/>
   <text x="540" y="96"  text-anchor="middle" font-size="15" font-weight="700" fill="#58a6ff" font-family="Inter,sans-serif">Receive tool call</text>
   <line x1="400" y1="103" x2="682" y2="103" stroke="#112238" stroke-width="1"/>
-  <text x="540" y="121" text-anchor="middle" font-size="13"   fill="#8b949e" font-family="Inter,sans-serif">run_scientific_agent(path)</text>
+  <text x="540" y="121" text-anchor="middle" font-size="13"   fill="#8b949e" font-family="Inter,sans-serif">analyze_dataset(path)</text>
   <text x="540" y="139" text-anchor="middle" font-size="11.5" fill="#484f58" font-family="Inter,sans-serif">Remote execution selected per call</text>
 
   <!-- Agent: Begin analysis -->
@@ -253,17 +253,17 @@ <h1>UXarray MCP Server — Architecture Diagram</h1>
 
   <!-- INSPECT BOXES  y=320–406 (86px) -->
 
-  <!-- Local: inspect_mesh() -->
+  <!-- Local: run_analysis(operation="inspect_mesh") -->
   <rect x="1107" y="320" width="306" height="86" rx="8" fill="#091c09" stroke="#2ea043" stroke-width="2"/>
-  <text x="1260" y="342" text-anchor="middle" font-size="15" font-weight="700" fill="#56d364" font-family="Inter,sans-serif">inspect_mesh( )</text>
+  <text x="1260" y="342" text-anchor="middle" font-size="15" font-weight="700" fill="#56d364" font-family="Inter,sans-serif">run_analysis(inspect_mesh)</text>
   <line x1="1120" y1="350" x2="1402" y2="350" stroke="#0f2010" stroke-width="1"/>
   <text x="1260" y="367" text-anchor="middle" font-size="13"   fill="#8b949e" font-family="Inter,sans-serif">domain/mesh.py → ux.open_grid()</text>
   <text x="1260" y="383" text-anchor="middle" font-size="11.5" fill="#8b949e" font-family="Inter,sans-serif">MPAS · UGRID · SCRIP · HEALPix</text>
   <text x="1260" y="398" text-anchor="middle" font-size="11"   fill="#2ea043" font-family="Inter,sans-serif" font-style="italic">→ n_face · n_node · n_edge · format</text>
 
-  <!-- HPC: inspect_mesh(..., use_remote=True) -->
+  <!-- HPC: run_analysis(operation="inspect_mesh", use_remote=True) -->
   <rect x="1467" y="320" width="306" height="86" rx="8" fill="#180e00" stroke="#d29922" stroke-width="2"/>
-  <text x="1620" y="342" text-anchor="middle" font-size="15" font-weight="700" fill="#e3b341" font-family="Inter,sans-serif">inspect_mesh(use_remote)</text>
+  <text x="1620" y="342" text-anchor="middle" font-size="15" font-weight="700" fill="#e3b341" font-family="Inter,sans-serif">run_analysis(remote)</text>
   <line x1="1480" y1="350" x2="1762" y2="350" stroke="#201400" stroke-width="1"/>
   <text x="1620" y="362" text-anchor="middle" font-size="11.5" fill="#39d0d0" font-family="Inter,sans-serif" font-style="italic">✓ _endpoint_is_ready( ) pre-flight</text>
   <text x="1620" y="377" text-anchor="middle" font-size="13"   fill="#8b949e" font-family="Inter,sans-serif">remote/compute_functions.py</text>
@@ -432,7 +432,7 @@ <h1>UXarray MCP Server — Architecture Diagram</h1>
 
   <!-- Stats strip -->
   <div class="stats-strip">
-    <div class="stat"><div class="v" style="color:#58a6ff">13</div><div class="l">MCP Tools (max)</div></div>
+    <div class="stat"><div class="v" style="color:#58a6ff">11</div><div class="l">MCP Front Doors</div></div>
     <div class="stat"><div class="v" style="color:#bc8cff">5</div><div class="l">Architecture Layers</div></div>
     <div class="stat"><div class="v" style="color:#56d364">142</div><div class="l">Tests Passing</div></div>
     <div class="stat"><div class="v" style="color:#e3b341">4</div><div class="l">Domain Modules</div></div>
@@ -449,34 +449,32 @@ <h1>UXarray MCP Server — Architecture Diagram</h1>
     <strong style="color:#e3b341">Orange boxes</strong> = dispatched to a named HPC endpoint via Globus Compute — the file never leaves the cluster.
     <strong style="color:#39d0d0">Teal dashed boxes</strong> = steps that only activate under certain conditions (data_path provided, remote mode requested).
     <strong style="color:#f85149">Red dashed</strong> inside HPC boxes = automatic local fallback when the endpoint is unreachable.
-    <strong>Unified registration:</strong> tools are registered once; remote execution is selected with <code>use_remote=True</code> and optional endpoint names.
+    <strong>Small public surface:</strong> MCP clients call front-door tools such as <code>run_analysis</code>, <code>plot_dataset</code>, and <code>diagnose_endpoint</code>; implementation functions stay behind those dispatchers.
   </div>
 
   <!-- Tool table -->
   <div class="card">
-    <div class="card-h">Representative MCP Tools &nbsp;<span style="font-weight:400;color:#6e7681;font-size:12px">— unified local / remote surface</span></div>
+    <div class="card-h">MCP Front-Door Tools &nbsp;<span style="font-weight:400;color:#6e7681;font-size:12px">— small public surface, rich internal capabilities</span></div>
     <table>
       <thead>
         <tr><th>#</th><th>Tool Name</th><th>Source File</th><th>Runs On</th><th>Domain Module</th><th>What It Does</th></tr>
       </thead>
       <tbody>
-        <tr><td>1</td><td><code>inspect_mesh</code></td><td><code>inspection.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>mesh.py</code></td><td>Load grid → n_face, n_node, n_edge, format, file_size_mb. Supports MPAS · UGRID · SCRIP · HEALPix and more.</td></tr>
-        <tr><td>2</td><td><code>inspect_variable</code></td><td><code>inspection.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>variable.py</code></td><td>Variable metadata: location (faces/nodes/edges), shape, dtype, min/max/mean, units, attrs.</td></tr>
-        <tr><td>3</td><td><code>calculate_area</code></td><td><code>inspection.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>area.py</code></td><td>Face area stats: total, mean, min, max, units, n_face via grid.face_areas.</td></tr>
-        <tr><td>4</td><td><code>calculate_zonal_mean</code></td><td><code>inspection.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>zonal.py</code></td><td>Latitude-band averaging of any face-centered variable. Optional conservative area-weighting.</td></tr>
-        <tr><td>5</td><td><code>validate_dataset</code></td><td><code>inspection.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>variable.py</code></td><td>Check NaN coverage, fill value consistency, dimension alignment. Result gates zonal_mean in the agent.</td></tr>
-        <tr><td>6</td><td><code>get_capabilities</code></td><td><code>capabilities.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>mesh.py · variable.py</code></td><td>Inspect topology + variables; return applicable tools and UXarray API methods with recommendations.</td></tr>
-        <tr><td>7</td><td><code>get_execution_mode</code></td><td><code>execution_control.py</code></td><td><span class="tag tl">LOCAL</span></td><td>—</td><td>Returns current execution mode (local / hpc / auto) and whether an HPC endpoint is configured.</td></tr>
-        <tr><td>8</td><td><code>set_execution_mode</code></td><td><code>execution_control.py</code></td><td><span class="tag tl">LOCAL</span></td><td>—</td><td>Switch execution mode from the Claude UI without editing config.yaml directly.</td></tr>
-        <tr><td>9</td><td><code>run_scientific_agent</code></td><td><code>scientific_agent.py</code></td><td><span class="tag ta">AUTO</span></td><td>All 4 modules</td><td>Autonomous 4-stage pipeline: Analyze → Plan → Execute → Verify. Validation-gated. Returns full reasoning trace + provenance + artifacts.</td></tr>
-        <tr><td>10</td><td><code>inspect_mesh</code></td><td><code>remote_tools.py</code></td><td><span class="tag th">HPC*</span></td><td><code>mesh.py</code> on HPC</td><td>Mesh inspection with <code>use_remote=True</code>. Pre-flight health check. Auto-fallback to local.</td></tr>
-        <tr><td>11</td><td><code>calculate_area</code></td><td><code>remote_tools.py</code></td><td><span class="tag th">HPC*</span></td><td><code>area.py</code> on HPC</td><td>Face area calculation with <code>use_remote=True</code>. Pre-flight health check. Auto-fallback to local.</td></tr>
-        <tr><td>12</td><td><code>inspect_variable</code></td><td><code>remote_tools.py</code></td><td><span class="tag th">HPC*</span></td><td><code>variable.py</code> on HPC</td><td>Variable inspection with <code>use_remote=True</code>. Pre-flight health check. Auto-fallback to local.</td></tr>
-        <tr><td>13</td><td><code>calculate_zonal_mean</code></td><td><code>remote_tools.py</code></td><td><span class="tag th">HPC*</span></td><td><code>zonal.py</code> on HPC</td><td>Zonal mean with <code>use_remote=True</code>. Pre-flight health check. Auto-fallback to local.</td></tr>
+        <tr><td>1</td><td><code>get_capabilities</code></td><td><code>capabilities.py</code></td><td><span class="tag tl">LOCAL</span></td><td><code>mesh.py · variable.py</code></td><td>Discover topology, variables, applicable operations, and next steps.</td></tr>
+        <tr><td>2</td><td><code>analyze_dataset</code></td><td><code>orchestration.py</code></td><td><span class="tag ta">AUTO</span></td><td>Core domains</td><td>Run first-look inspection, validation, area, zonal mean, and plots.</td></tr>
+        <tr><td>3</td><td><code>run_analysis</code></td><td><code>frontdoor.py</code></td><td><span class="tag ta">AUTO</span></td><td>All domains</td><td>Dispatch one named operation: inspect, subset, compare, remap, vector, temporal, ensemble, or export.</td></tr>
+        <tr><td>4</td><td><code>plot_dataset</code></td><td><code>frontdoor.py</code></td><td><span class="tag ta">AUTO</span></td><td><code>plotting.py</code></td><td>Render mesh, geographic mesh, variable, or zonal mean plots.</td></tr>
+        <tr><td>5</td><td><code>diagnose_endpoint</code></td><td><code>frontdoor.py</code></td><td><span class="tag ta">AUTO</span></td><td>—</td><td>Endpoint status, setup validation, and path-probe workflows.</td></tr>
+        <tr><td>6</td><td><code>probe_path_access</code></td><td><code>execution_control.py</code></td><td><span class="tag ta">AUTO</span></td><td>—</td><td>Direct path readability probe for cluster bring-up.</td></tr>
+        <tr><td>7</td><td><code>run_workflow</code></td><td><code>stateful.py</code></td><td><span class="tag ta">AUTO</span></td><td>Core domains</td><td>Run the canonical persisted workflow.</td></tr>
+        <tr><td>8</td><td><code>resume_workflow</code></td><td><code>stateful.py</code></td><td><span class="tag ta">AUTO</span></td><td>Core domains</td><td>Resume a persisted workflow.</td></tr>
+        <tr><td>9</td><td><code>get_status</code></td><td><code>frontdoor.py</code></td><td><span class="tag tl">LOCAL</span></td><td>—</td><td>Read workflow or operation status.</td></tr>
+        <tr><td>10</td><td><code>get_result</code></td><td><code>frontdoor.py</code></td><td><span class="tag tl">LOCAL</span></td><td>—</td><td>Inspect persisted result handles and artifacts.</td></tr>
+        <tr><td>11</td><td><code>manage_session</code></td><td><code>frontdoor.py</code></td><td><span class="tag tl">LOCAL</span></td><td>—</td><td>Create sessions, register datasets, inspect/reset state, and list operations.</td></tr>
       </tbody>
     </table>
     <div style="padding:10px 15px;font-size:11.5px;color:#6e7681;border-top:1px solid #21262d;">
-      * Remote execution is selected per call with <code>use_remote=True</code>. Endpoint readiness controls remote dispatch and fallback.
+      * Remote execution is selected per call with <code>use_remote=True</code> on front doors that support remote work. Endpoint readiness controls remote dispatch and fallback.
     </div>
   </div>