@barivia/barmesh-mcp 0.4.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ form on a shared self-organizing map (SOM)**:
   each mesh to a volume-weighted fingerprint, and computes **symmetric KL** and
   **Wasserstein-1 (EMD)** distances stepwise and against a reference mesh, with publication
   figures and an advisory convergence reading. The SOM features are preprocessed by the
-  same staged pipeline as barsom training, so any dataset (small or large, CSV/gzip/Parquet)
+  same staged pipeline as barsom training, so any dataset (small or large, CSV/gzip)
   is handled out-of-core by default; optional `transforms`, `normalize`,
   `normalization_methods`, and `row_range` give the same preprocessing controls. Submit
   enqueues **`prepare_training_matrix`** on worker-io when the dataset is staged; the proxy
@@ -52,13 +52,31 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 |------|---------|
 | `barmesh_guide_workflow` | Workflow + tool map (tier-scoped). Call first. |
 | `barmesh_prepare_mesh_data` | Recipe for the combined per-cell CSV. |
-| `barmesh_datasets` | Upload / preview / list the mesh CSV. |
+| `barmesh_datasets` | Upload / preview / list / get / subset / delete the mesh CSV. |
 | `barmesh_mesh_convergence` | SOM fingerprint distances (async job). |
 | `barmesh_richardson` | Richardson/GCI on scalar QoIs (async job). |
-| `barmesh_jobs` | Poll job status / list jobs (auto-polls CFD prepare + finalize when applicable). |
-| `barmesh_results` | Distances, convergence reading, and figures. |
+| `barmesh_jobs` | Poll job status / list jobs (auto-polls CFD prepare + finalize when applicable). Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
+| `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines a single `combined.png` overview by default; `action=render` produces publication PDFs on demand. |
+| `barmesh_results_explorer` | Interactive MCP App (or standalone localhost page) to browse the distances, convergence reading, and every figure after a job completes. |
 | `barmesh_send_feedback` | Send a short note or bug report to the Barivia team. |
 
+### Figures and progress (0.5.0)
+
+- **Combined overview:** every completed `mesh_convergence` job produces a single
+  `combined.png` (coarse vs reference volume fingerprint, KL-vs-reference, EMD-vs-reference)
+  as the headline artifact, alongside per-panel PNG previews.
+- **PDFs on demand:** publication vector PDFs are NOT generated by default. Render them
+  after completion with `barmesh_results(action=render, format=pdf)`, then download each
+  with `barmesh_results(action=image, filename="KL_ref.pdf")`. This avoids generating
+  ~2× the artifacts (and storage/finalize cost) on every run.
+- **Adaptive layout:** the stepwise volume panels use a single row for small studies and
+  auto-wrap into a near-square grid for many meshes; figures are not cavity-specific.
+- **Live progress:** `barmesh_jobs(action=status)` exposes phase, epoch/total, elapsed,
+  ETA, and quantization error during the SOM training (barsom parity).
+- **Results explorer:** `barmesh_results_explorer(job_id)` opens an interactive figure
+  browser. It embeds as an MCP App in supporting hosts (Claude, VS Code, etc.) and falls
+  back to a standalone `localhost` page otherwise (set `BARIVIA_VIZ_PORT` for a stable port).
+
 ### Migration notes
 
 - **`send_feedback` → `barmesh_send_feedback` (0.3.0):** the feedback tool was renamed so it no longer collides with the `@barivia/barsom-mcp` tool of the same name when both servers are enabled in one client. Update any direct call sites; the behavior is unchanged.
@@ -69,6 +87,12 @@ One combined CSV: one row per cell, a mesh-label column (`mesh_id`), the physica
 you choose as `feature_columns` (e.g. `p`, `U_mag`, `k`, `log_epsilon`, `T`), and a
 cell-volume column (`V`). Use `barmesh_prepare_mesh_data` for the full recipe.
 
+**Upload formats:** `.csv`, `.tsv`, `.csv.gz`, or `.tsv.gz`. For large per-cell tables
+(≥64 MB), prefer `.csv.gz` — uploads stream directly to object storage with presigned PUT.
+Use `barmesh_datasets(action=get, dataset_id=...)` to check staging status after upload;
+`barmesh_datasets(action=subset, sample_n=...)` to downsample huge tables server-side.
+Parquet staging is supported by the API but not yet exposed as an MCP upload format.
+
 ## Environment variables
 
 | Variable | Default | Purpose |
@@ -78,3 +102,4 @@ cell-volume column (`V`). Use `barmesh_prepare_mesh_data` for the full recipe.
 | `BARIVIA_FETCH_TIMEOUT_MS` | `60000` | Per-request timeout (raise for large uploads). |
 | `BARIVIA_WORKSPACE_ROOT` | workspace/cwd | Root for resolving relative `file_path` uploads. |
 | `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | `1` | Restrict uploads to the workspace; set `0` to allow absolute paths. |
+| `BARIVIA_VIZ_PORT` | ephemeral | Fixed localhost port for the `barmesh_results_explorer` standalone page (otherwise OS-assigned per session). |

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as s}from"@modelcontextprotocol/sdk/server/stdio.js";import{API_KEY as r,CLIENT_VERSION as n}from"./shared.js";import{registerGuideTool as o}from"./tools/guide.js";import{registerDatasetsTool as t}from"./tools/datasets.js";import{registerCfdTools as a}from"./tools/cfd.js";import{registerJobsTool as i}from"./tools/jobs.js";import{registerResultsTool as c}from"./tools/results.js";import{registerFeedbackTool as m}from"./tools/feedback.js";r||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const r=new e({name:"barmesh",version:n},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_jobs(action=status) — poll every 10-20s, for minutes if needed.\n6. barmesh_results(action=get) — distances, convergence reading, and figures.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(r),t(r),a(r),i(r),c(r),m(r);const l=new s;await r.connect(l),console.error(`barmesh-mcp ${n} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as o,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as t}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as p}from"./shared.js";import{registerGuideTool as h}from"./tools/guide.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerCfdTools as f}from"./tools/cfd.js";import{registerJobsTool as b}from"./tools/jobs.js";import{registerResultsTool as v}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as _}from"./tools/barmesh_results_explorer.js";import{registerFeedbackTool as g}from"./tools/feedback.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const i=new e({name:"barmesh",version:a},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_jobs(action=status) — poll every 10-20s, for minutes if needed.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,_,_,{mimeType:n},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:_,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),h(i),y(i),u(i),f(i),b(i),v(i),g(i);try{const e=await t(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const w=i.server;w.oninitialized=()=>{const e=w.getClientCapabilities(),r=s(e);p(!!r?.mimeTypes?.includes(n))};const j=new r;await i.connect(j),console.error(`barmesh-mcp ${a} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});

package/dist/job_status_format.js

@@ -0,0 +1,89 @@
+/**
+ * Format barmesh_jobs(status) text from GET /v1/jobs/:id (barsom parity).
+ * Surfaces phase, elapsed, ETA, and epoch N/M during the SOM training of a
+ * cfd_mesh_convergence job, plus CFD finalize (figure render) sub-status.
+ */
+function formatElapsedPart(data, status) {
+    const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
+        ? Number(data.wall_elapsed_sec)
+        : null;
+    const kernel = data.kernel_elapsed_sec != null && !Number.isNaN(Number(data.kernel_elapsed_sec))
+        ? Number(data.kernel_elapsed_sec)
+        : data.training_elapsed_sec != null && !Number.isNaN(Number(data.training_elapsed_sec))
+            ? Number(data.training_elapsed_sec)
+            : null;
+    if (wall != null && wall >= 0) {
+        const wallR = Math.round(wall);
+        if (status === "completed" && kernel != null && kernel >= 0 && Math.abs(wallR - Math.round(kernel)) >= 2) {
+            return `elapsed: ${wallR}s (kernel training: ${Math.round(kernel)}s)`;
+        }
+        return `elapsed: ${wallR}s`;
+    }
+    if (kernel != null && kernel >= 0) {
+        return `elapsed: ${Math.round(kernel)}s`;
+    }
+    const startedAt = data.started_at != null ? String(data.started_at) : null;
+    if (startedAt) {
+        const startedMs = Date.parse(startedAt);
+        if (!Number.isNaN(startedMs)) {
+            const elapsedSec = Math.max(0, Math.round((Date.now() - startedMs) / 1000));
+            return `elapsed: ${elapsedSec}s`;
+        }
+    }
+    return null;
+}
+export function formatJobStatusText(job_id, data) {
+    const status = String(data.status ?? "unknown");
+    const progress = (data.progress ?? 0) * 100;
+    const label = data.label != null && data.label !== "" ? String(data.label) : null;
+    const jobDesc = label ? `Job ${label} (id: ${job_id})` : `Job ${job_id}`;
+    const parts = [`${jobDesc}: ${status} (${progress.toFixed(1)}%)`];
+    const attempt = data.attempt != null ? Number(data.attempt) : null;
+    if (attempt != null && attempt > 1) {
+        parts.push(`attempt ${attempt} (job was requeued after worker timeout — not stuck from scratch)`);
+    }
+    const phase = data.progress_phase != null && String(data.progress_phase) !== ""
+        ? String(data.progress_phase)
+        : null;
+    if (status === "running") {
+        parts.push(phase ? `phase: ${phase}` : `phase: preprocessing (download/parse before first tick)`);
+    }
+    const startedAt = data.started_at != null ? String(data.started_at) : null;
+    if (startedAt)
+        parts.push(`started_at: ${startedAt}`);
+    const elapsedPart = formatElapsedPart(data, status);
+    if (elapsedPart)
+        parts.push(elapsedPart);
+    if (status === "running") {
+        const etaSec = data.training_eta_sec != null ? Number(data.training_eta_sec) : null;
+        if (etaSec != null && etaSec > 0)
+            parts.push(`ETA ~${Math.round(etaSec)}s`);
+        const epoch = data.epoch != null ? Number(data.epoch) : null;
+        const totalEpochs = data.total_epochs != null ? Number(data.total_epochs) : null;
+        if (epoch != null && totalEpochs != null && totalEpochs > 0)
+            parts.push(`epoch ${epoch}/${totalEpochs}`);
+        const qe = data.quantization_error != null ? Number(data.quantization_error) : null;
+        if (qe != null && !Number.isNaN(qe))
+            parts.push(`QE ${qe.toFixed(4)}`);
+    }
+    if (status === "running" && progress < 5 && !phase) {
+        parts.push("Advisory: still in early preprocessing — epoch counter starts after ingest completes.");
+    }
+    if (status === "completed") {
+        const finalizeId = data.finalize_job_id != null && String(data.finalize_job_id) !== "" ? String(data.finalize_job_id) : null;
+        if (finalizeId) {
+            parts.push(`Compute done; cfd_finalize still rendering figures (finalize_job_id=${finalizeId}). Poll barmesh_jobs(action=status) again to auto-wait before barmesh_results(action=get).`);
+        }
+        else {
+            parts.push(`Results ready. Use barmesh_results(action=get, job_id="${job_id}") for distances and figures, or barmesh_results_explorer(job_id="${job_id}") to browse interactively.`);
+        }
+    }
+    else if (status === "failed") {
+        const failureStage = data.failure_stage != null && String(data.failure_stage) !== "" ? ` [${data.failure_stage}]` : "";
+        parts.push(`Error${failureStage}: ${data.error ?? "unknown"}`);
+    }
+    else if (status === "cancelled") {
+        parts.push(`Cancelled. Poll again to confirm; dataset and partial worker state are unchanged.`);
+    }
+    return parts.join(" | ");
+}

package/dist/shared.js

@@ -4,10 +4,12 @@
  * remains a thin HTTPS client to the same Barivia API (no domain logic here).
  */
 import fs from "node:fs/promises";
-import { createReadStream } from "node:fs";
+import { createReadStream, createWriteStream } from "node:fs";
 import { createGzip } from "node:zlib";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { logInfo } from "./logger.js";
@@ -20,7 +22,7 @@ export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ??
 export const MAX_RETRIES = 2;
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.4.0";
+export const CLIENT_VERSION = "0.5.0";
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Large per-cell CSV uploads may exceed the default fetch timeout. */
 export const UPLOAD_DATASET_TIMEOUT_MS = 180_000;
@@ -40,30 +42,83 @@ export async function streamFileSha256(srcPath) {
         s.on("error", reject);
     });
 }
-/** Stream a local file through gzip directly to a presigned PUT URL (e.g. R2). */
-export async function putPresignedStream(url, srcPath, contentType, timeoutMs = PRESIGNED_PUT_TIMEOUT_MS) {
-    const gz = createReadStream(srcPath).pipe(createGzip());
-    const webStream = Readable.toWeb(gz);
+/** Turn a raw S3/R2 presigned-PUT error into a clean, actionable message. */
+function presignedPutError(status, bodyText) {
+    const snippet = bodyText.slice(0, 200);
+    if (status === 411 || /MissingContentLength/i.test(bodyText)) {
+        return new Error("Upload rejected by storage: the Content-Length header was missing. " +
+            "This is a client bug — please update @barivia/barmesh-mcp to the latest version.");
+    }
+    if (status === 413 || /EntityTooLarge|entity is too large/i.test(bodyText)) {
+        return new Error("Upload rejected by storage: file exceeds the maximum upload size.");
+    }
+    if (status === 403) {
+        return new Error("Upload rejected by storage: the presigned URL expired or was invalid; retry barmesh_datasets(action=upload).");
+    }
+    return new Error(`Presigned upload failed: HTTP ${status} ${snippet}`);
+}
+/**
+ * Stream a local file directly to a presigned PUT URL (e.g. R2), gzip-compressing
+ * on the way unless the source is already gzipped. Never materializes the payload
+ * in process memory: when compression is needed we gzip to a temp file first, then
+ * PUT that file with an explicit Content-Length.
+ */
+export async function putPresignedStream(url, srcPath, contentType, timeoutMs = PRESIGNED_PUT_TIMEOUT_MS, alreadyGzipped = false) {
+    let putPath = srcPath;
+    let tempPath;
+    if (!alreadyGzipped) {
+        tempPath = path.join(os.tmpdir(), `barmesh-upload-${randomUUID()}.csv.gz`);
+        await pipeline(createReadStream(srcPath), createGzip(), createWriteStream(tempPath));
+        putPath = tempPath;
+    }
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
+        const contentLength = (await fs.stat(putPath)).size;
+        const webStream = Readable.toWeb(createReadStream(putPath));
         const resp = await fetch(url, {
             method: "PUT",
             body: webStream,
-            headers: { "Content-Type": contentType },
+            headers: { "Content-Type": contentType, "Content-Length": String(contentLength) },
             duplex: "half",
             signal: controller.signal,
         });
         if (!resp.ok) {
             const t = await resp.text().catch(() => "");
-            throw new Error(`Presigned upload failed: HTTP ${resp.status} ${t.slice(0, 200)}`);
+            throw presignedPutError(resp.status, t);
         }
     }
     finally {
         clearTimeout(timer);
+        if (tempPath)
+            await fs.rm(tempPath, { force: true }).catch(() => { });
     }
 }
 // ---------------------------------------------------------------------------
+// MCP App view state (results explorer)
+// ---------------------------------------------------------------------------
+let _vizPort = 0;
+let _clientSupportsMcpApps = false;
+export function getVizPort() {
+    return _vizPort;
+}
+export function setVizPort(port) {
+    _vizPort = port;
+}
+export function getClientSupportsMcpApps() {
+    return _clientSupportsMcpApps;
+}
+export function setClientSupportsMcpApps(value) {
+    _clientSupportsMcpApps = value;
+}
+/** Tool result carrying both a structured payload (for the MCP App view) and text/image content. */
+export function structuredTextResult(structuredContent, text, content) {
+    return {
+        structuredContent,
+        content: content ?? [{ type: "text", text: text ?? JSON.stringify(structuredContent, null, 2) }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Fetch helpers
 // ---------------------------------------------------------------------------
 export function isTransientError(err, status) {
@@ -339,6 +394,26 @@ export function getCaptionForImage(filename) {
         return `Component plane for ${base.replace(/^plot_/, "")} on the trained SOM.`;
     return "";
 }
+// ---------------------------------------------------------------------------
+// View loading (bundled single-file HTML for the results explorer MCP App)
+// ---------------------------------------------------------------------------
+const BASE_DIR = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+export async function loadViewHtml(viewName) {
+    const candidates = [
+        path.join(BASE_DIR, "views", "src", "views", viewName, "index.html"),
+        path.join(BASE_DIR, "views", viewName, "index.html"),
+        path.join(BASE_DIR, "..", "dist", "views", "src", "views", viewName, "index.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            return await fs.readFile(p, "utf-8");
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 export async function tryAttachImage(content, jobId, filename) {
     if (filename.endsWith(".pdf") || filename.endsWith(".svg")) {
         content.push({

package/dist/tools/barmesh_results_explorer.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
+import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
+export const RESULTS_EXPLORER_URI = "ui://barmesh/results-explorer";
+function labelForFigure(filename) {
+    const base = filename.replace(/\.(png|pdf|svg)$/i, "");
+    if (base === "combined")
+        return "Combined overview";
+    if (base === "KL_ref")
+        return "KL divergence vs reference";
+    if (base === "KL_stepwise")
+        return "KL divergence stepwise";
+    if (base === "EMD_ref")
+        return "Wasserstein (EMD) vs reference";
+    if (base === "EMD_stepwise")
+        return "Wasserstein (EMD) stepwise";
+    if (base === "plot_vol_coarse_fine")
+        return "Volume fingerprint: coarse vs reference";
+    if (base.startsWith("plot_vol_"))
+        return "Volume fingerprint: stepwise";
+    if (base.startsWith("plot_"))
+        return `Component plane: ${base.replace(/^plot_/, "").replace(/_/g, " ")}`;
+    return base.replace(/_/g, " ");
+}
+function figureKind(base) {
+    if (base === "combined")
+        return "summary";
+    if (base.startsWith("plot_") && !base.startsWith("plot_vol_"))
+        return "component";
+    return "diagnostic";
+}
+function buildMetrics(summary) {
+    const grid = summary.grid ?? [];
+    const qe = summary.quantization_error != null ? Number(summary.quantization_error).toFixed(4) : "N/A";
+    const te = summary.topographic_error != null ? Number(summary.topographic_error).toFixed(4) : "N/A";
+    const meshes = summary.meshes ?? [];
+    return [
+        { label: "Grid", value: grid.length >= 2 ? `${grid[0]}×${grid[1]}` : "N/A" },
+        { label: "Preset", value: String(summary.preset ?? "generic") },
+        { label: "Reference", value: String(summary.reference_mesh ?? "N/A") },
+        { label: "Meshes", value: String(meshes.length || "N/A") },
+        { label: "QE", value: qe },
+        { label: "TE", value: te },
+        { label: "EMD method", value: String(summary.emd_method ?? "exact") },
+    ];
+}
+function buildHighlights(summary) {
+    const out = [];
+    const convergence = summary.convergence;
+    const emd = convergence?.emd;
+    const skl = convergence?.skl;
+    if (emd) {
+        const plateau = emd.plateau === true ? "plateauing" : "not yet plateauing";
+        const mono = emd.monotonic_decrease === true ? "monotonic decrease" : "non-monotonic";
+        out.push(`EMD vs reference: ${mono}, ${plateau}.`);
+    }
+    if (skl) {
+        const plateau = skl.plateau === true ? "plateauing" : "not yet plateauing";
+        out.push(`Symmetric KL vs reference: ${plateau}.`);
+    }
+    out.push("Advisory: SOM distances complement, not replace, numerical uncertainty analysis (Richardson/GCI).");
+    return out;
+}
+export function buildPayload(jobId, data) {
+    const summary = (data.summary ?? {});
+    const files = (summary.files ?? []).filter((f) => /\.(png|pdf|svg)$/i.test(f));
+    // Embedded view: never set `url` (sandboxed iframe cannot load localhost) — figures
+    // lazy-load as base64 through the _barmesh_fetch_figure bridge tool.
+    const figures = files.map((filename) => {
+        const base = filename.replace(/\.(png|pdf|svg)$/i, "");
+        const isRaster = /\.(png|jpe?g|gif|webp)$/i.test(filename);
+        return {
+            key: base,
+            label: labelForFigure(filename),
+            filename,
+            kind: figureKind(base),
+            caption: getCaptionForImage(filename) ||
+                (!isRaster ? "Vector figure — available for download, not inline-displayable." : undefined),
+        };
+    });
+    const port = getVizPort();
+    return {
+        type: "barmesh-results-explorer",
+        jobId,
+        title: "Mesh Convergence Results",
+        subtitle: String(data.label ?? ""),
+        metrics: buildMetrics(summary),
+        highlights: buildHighlights(summary),
+        availableFigures: figures,
+        defaultFigureKey: figures.find((f) => f.key === "combined")?.key ??
+            figures.find((f) => f.key === "KL_ref")?.key ??
+            figures[0]?.key,
+        standaloneUrl: port
+            ? `http://localhost:${port}/viz/barmesh-results-explorer?mode=standalone&job_id=${jobId}`
+            : undefined,
+    };
+}
+async function handleResultsExplorer(job_id) {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const payload = buildPayload(job_id, data);
+    const content = [
+        {
+            type: "text",
+            text: [
+                `Mesh convergence results explorer ready for job ${job_id}.`,
+                payload.subtitle ? `Label: ${payload.subtitle}` : "",
+                payload.highlights[0] ?? "",
+            ]
+                .filter(Boolean)
+                .join("\n"),
+        },
+    ];
+    const defaultFigure = payload.availableFigures.find((f) => f.key === payload.defaultFigureKey);
+    if (defaultFigure) {
+        await tryAttachImage(content, job_id, defaultFigure.filename);
+    }
+    if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
+        content.push({
+            type: "text",
+            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
+                `AGENT: surface this to the user as a clickable markdown link in your reply. ` +
+                `This localhost port is assigned per MCP session and changes if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
+        });
+    }
+    return structuredTextResult(payload, undefined, content);
+}
+export function registerResultsExplorerTool(server) {
+    const toolConfig = {
+        title: "Mesh Convergence Results Explorer",
+        description: "PREFERRED way to browse a completed mesh_convergence job after a first barmesh_results(get) glance. Interactive explorer of the distances, convergence reading, and every figure (combined overview, KL/EMD vs reference and stepwise, volume fingerprints, component planes). Embeds as an MCP App or falls back to a standalone localhost page. barmesh_results(action=get) remains the headless/metrics path.",
+        inputSchema: {
+            job_id: z.string().describe("Job ID of a completed cfd_mesh_convergence job"),
+        },
+        _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
+    };
+    registerAppTool(server, "barmesh_results_explorer", toolConfig, async (args) => runMcpToolAudit("barmesh_results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
+    // MUST stay a registered tool: the explorer App view lazy-loads non-default raster
+    // figures through the App bridge (mcpApp.callServerTool), which can only reach
+    // registered server tools. Agents must not call it directly from chat.
+    registerAuditedTool(server, "_barmesh_fetch_figure", "[INTERNAL — host / MCP App only; agents MUST NOT call this.] The Mesh Convergence Results Explorer view uses it to lazy-load one raster figure as base64. From chat, use barmesh_results(action=get) or barmesh_results_explorer instead.", {
+        job_id: z.string(),
+        filename: z.string(),
+    }, async ({ job_id, filename }) => {
+        const safeFilename = filename.replace(/[^a-zA-Z0-9._-]/g, "");
+        const mime = mimeForFilename(safeFilename);
+        if (safeFilename.endsWith(".pdf") || safeFilename.endsWith(".svg")) {
+            return { content: [{ type: "text", text: `${safeFilename} is a vector format and cannot be displayed inline.` }] };
+        }
+        try {
+            const { data: imgBuf } = await apiRawCall(`/v1/results/${job_id}/image/${safeFilename}`);
+            return { content: [{ type: "image", data: imgBuf.toString("base64"), mimeType: mime }] };
+        }
+        catch {
+            return { content: [{ type: "text", text: `Failed to fetch ${safeFilename}.` }] };
+        }
+    });
+}