@barivia/barsom-mcp 0.17.1 → 0.18.1

package/README.md

@@ -43,7 +43,7 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 | `BARIVIA_API_URL` | No | `https://api.barivia.se` | API base URL |
 | `BARIVIA_WORKSPACE_ROOT` | No | `process.cwd()` or `PWD` | Directory for relative `file_path` and `save_to_disk`. In Cursor MCP, `process.cwd()` is often the MCP install dir — add `BARIVIA_WORKSPACE_ROOT` to your MCP config `env` with your project path (e.g. `/home/user/myproject`). Absolute paths and `file://` URIs work without it. |
 | `BARIVIA_FETCH_TIMEOUT_MS` | No | `60000` | Per-request HTTP timeout (ms) to the API. Increase (e.g. `120000`) on slow networks or when the API does long-running work. Large dataset uploads use a separate longer timeout internally, and `datasets(analyze)` runs asynchronously (auto-polled) so it is not bound by this. A timeout is not auto-retried (re-firing slow work would only multiply load / risk duplicates). |
-| `BARIVIA_VIZ_PORT` | No | OS-assigned | When the client has no MCP Apps support, the proxy may start a local viz server on `127.0.0.1`; set a fixed port if you need stable bookmark URLs. |
+| `BARIVIA_VIZ_PORT` | No | OS-assigned | When the client has no MCP Apps support, the proxy may start a local viz server on `127.0.0.1`. The port is **assigned per MCP session and changes when the proxy restarts**, so standalone `…/viz/…` URLs from a previous session go stale (the page then can't reach `/api/*` and shows a "stale session — re-run the tool" message). Set a fixed port for stable bookmark URLs. Diagnostic: `GET http://127.0.0.1:<port>/api/health?job_id=<id>` reports the port, API reachability, and the job's status. |
 | `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | No | `1` (enabled) | File uploads are constrained to the MCP workspace root by default. Set to `0` or `false` to allow absolute paths anywhere on the machine (high trust). **Changed in v0.x:** previously defaulted to off; now on for security. If uploads fail with "paths outside the workspace are disabled", either set `BARIVIA_WORKSPACE_ROOT` to cover your data directory, or opt out with `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0`. |
 
 Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` / `BARSOM_WORKSPACE_ROOT` are also accepted as fallbacks.
@@ -228,6 +228,8 @@ MCP Client (Cursor/Claude) ←stdio→ @barivia/barsom-mcp ←HTTPS→ api.bariv
 | `Path must be within the workspace` / upload can’t find file | Set `BARIVIA_WORKSPACE_ROOT` to your project directory, or use an absolute path / `file:///...` URI. |
 | Job stuck “running” | Poll `jobs(action=status)` every 10–15s; large grids or FLooP-SIOM can take several minutes—not an MCP error. Staged datasets enqueue **`prepare_training_matrix`** (or impute prepare) first — train submit returns `prepare_job_id`; MCP auto-polls prepare when present. CFD mesh submit may return `prepare_job_id` for **`cfd_prepare`** (barmesh auto-polls). |
 | `429` | Rate limit—wait and retry. |
+| Standalone `…/viz/…` page stuck at "running 0%" or "Loading…" | The link is stale: the viz port is assigned per MCP session and changes when the proxy restarts. Re-run `training_monitor` / `results_explorer` for a fresh URL, or set `BARIVIA_VIZ_PORT` for a persistent port. Confirm with `GET /api/health?job_id=<id>`. |
+| Embedded results explorer: switching figures shows nothing | Fixed in `0.18.0` — earlier versions pointed embedded figures at a localhost URL the webview can't load. Update the package; the embedded view now lazy-loads figures over the MCP App bridge. |
 | Malformed MCP / client errors | Ensure nothing writes to **stdout** except MCP JSON-RPC (the proxy logs API traffic to **stderr** only). |
 
 ## Development

package/dist/shared.js

@@ -26,7 +26,7 @@ export const RETRYABLE_STATUS = new Set([502, 503, 504]);
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.17.1";
+export const CLIENT_VERSION = "0.18.1";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -289,7 +289,8 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
         if (err instanceof Error && (err.message.includes("escapes") || err.message.includes("regular file"))) {
             throw err;
         }
-        throw new Error(`File not accessible. For relative paths, set BARIVIA_WORKSPACE_ROOT in your MCP config. Or use an absolute path or file:// URI.`);
+        throw new Error(`File not accessible. Easiest fix: pass an ABSOLUTE path (e.g. "/home/you/project/data.csv" or ` +
+            `"C:\\\\Users\\\\you\\\\data.csv") or a file:// URI. For relative paths, set BARIVIA_WORKSPACE_ROOT in your MCP config.`);
     }
 }
 /** User-visible API error line (includes request id for support). Exported for tests. */

package/dist/tools/datasets.js

@@ -278,8 +278,10 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     stat = await fs.stat(resolved);
                 }
                 catch {
-                    throw new Error(`File not accessible at resolved path. file_path is relative to workspace root. ` +
-                        `Set BARIVIA_WORKSPACE_ROOT in your MCP config env if needed (current: ${await getWorkspaceRootAsync(server)}).`);
+                    throw new Error(`File not accessible at resolved path. Easiest fix: pass an ABSOLUTE path ` +
+                        `(e.g. "/home/you/project/data.csv" or "C:\\\\Users\\\\you\\\\data.csv") or a file:// URI. ` +
+                        `Relative paths resolve against the MCP workspace root (current: ${await getWorkspaceRootAsync(server)}); ` +
+                        `set BARIVIA_WORKSPACE_ROOT in your MCP config env to your project directory to use them.`);
                 }
                 if (stat.size > HARD_MAX_BYTES) {
                     const gzipHint = isGzipInput ? "" : ` ${GZIP_UPLOAD_HINT}`;

package/dist/tools/explore_map.js

@@ -26,7 +26,12 @@ function buildAvailableFigures(jobId, summary) {
     const files = (summary.files ?? []).filter((file) => /\.(png|pdf|svg)$/i.test(file));
     const fallback = getResultsImagesToFetch(jobType, summary, "default", false);
     const figureFiles = files.length > 0 ? files : fallback;
-    const port = getVizPort();
+    // NOTE: this payload feeds the *embedded* MCP App view, which runs in a
+    // sandboxed webview that cannot load a localhost http asset. So we never set
+    // a `url` here — the App lazy-loads each raster as base64 through the
+    // `_fetch_figure` server-tool bridge (the default figure also arrives as a
+    // base64 image via the tool result). The standalone browser page builds its
+    // own relative-URL payload separately (see views/results-explorer/app.ts).
     return figureFiles.map((filename) => {
         const base = filename.replace(/\.(png|pdf|svg)$/i, "");
         const featureName = base.startsWith("component_")
@@ -40,7 +45,6 @@ function buildAvailableFigures(jobId, summary) {
             kind: base.startsWith("component_") ? "component" : base === "combined" ? "summary" : "diagnostic",
             featureName,
             caption: getCaptionForImage(filename) || (!isRaster ? "This figure is available for download, but it is not inline-displayable in this first iteration." : undefined),
-            url: port && isRaster ? `http://localhost:${port}/api/results/${jobId}/image/${filename}` : undefined,
         };
     });
 }
@@ -96,7 +100,7 @@ function buildMetrics(summary) {
         { label: "Features", value: features },
     ];
 }
-function buildPayload(jobId, data) {
+export function buildPayload(jobId, data) {
     const summary = (data.summary ?? {});
     const figures = buildAvailableFigures(jobId, summary);
     const grid = summary.grid ?? [];
@@ -117,9 +121,7 @@ function buildPayload(jobId, data) {
         metrics,
         highlights,
         availableFigures: figures,
-        defaultFigureKey: figures.find((figure) => figure.key === "combined" && figure.url)?.key
-            ?? figures.find((figure) => Boolean(figure.url))?.key
-            ?? figures.find((figure) => figure.key === "combined")?.key
+        defaultFigureKey: figures.find((figure) => figure.key === "combined")?.key
             ?? figures[0]?.key,
         standaloneUrl: port ? `http://localhost:${port}/viz/results-explorer?mode=standalone&job_id=${jobId}` : undefined,
     };
@@ -150,7 +152,9 @@ async function handleResultsExplorer(job_id) {
     if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
         content.push({
             type: "text",
-            text: `Interactive visualization: ${payload.standaloneUrl}\nOpen this URL in your browser for a richer results exploration experience.`,
+            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
+                `AGENT: surface this to the user as a clickable markdown link (e.g. "[Open results explorer](${payload.standaloneUrl})") in your reply — do not leave it buried in tool output. ` +
+                `This localhost port is assigned per MCP session and changes if the proxy restarts — if the page won't load, re-run results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT in your MCP env for a persistent port.`,
         });
     }
     return structuredTextResult(payload, undefined, content);

package/dist/tools/training_monitor.js

@@ -54,7 +54,7 @@ async function enrichWithTrainingLog(job_id, data) {
 export function registerTrainingMonitorTool(server) {
     registerAppTool(server, "training_monitor", {
         title: "Training Monitor",
-        description: "Optional embedded or standalone view of training progress for a job_id. When embedded in a client that supports MCP Apps, the panel auto-refreshes every 5s until the job completes: live QE/TE learning curves plus a per-epoch hit-distribution heatmap (sampled BMU counts across the map, showing where observations are landing as training proceeds). A standalone browser URL is also available. The same scalar fields are available via jobs(action=status)—not required to complete training or read results.",
+        description: "Optional embedded or standalone view of training progress for a job_id. When embedded in a client that supports MCP Apps, the panel auto-refreshes every 5s until the job completes: live QE/TE learning curves plus a per-epoch hit-distribution heatmap (sampled BMU counts across the map, showing where observations are landing as training proceeds). A standalone browser URL is also available — its localhost port is per MCP session and goes stale if the proxy restarts (set BARIVIA_VIZ_PORT for a persistent port; re-run this tool for a fresh link). The same scalar fields are available via jobs(action=status)—not required to complete training or read results.",
         inputSchema: {
             job_id: z.string().describe("Training job ID to monitor"),
             fetch_training_log: z
@@ -96,7 +96,9 @@ export function registerTrainingMonitorTool(server) {
         if (!getClientSupportsMcpApps() && standaloneUrl) {
             content.push({
                 type: "text",
-                text: `Open in browser: ${standaloneUrl}`,
+                text: `Live training monitor: [Open training monitor](${standaloneUrl})\n` +
+                    `AGENT: surface this to the user as a clickable markdown link (e.g. "[Open training monitor](${standaloneUrl})") in your reply — do not leave it buried in tool output. Re-post the link after the job completes so the user can return to the curves.\n` +
+                    `This localhost port is assigned per MCP session and changes if the proxy restarts — if the page stays at "running 0%" or stops updating, the link is stale: re-run training_monitor for a fresh URL, or set BARIVIA_VIZ_PORT in your MCP env for a persistent port. Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(job_id)}`,
             });
         }
         return structuredTextResult(structuredContent, text, content);

package/dist/tools/training_prep.js

@@ -481,7 +481,8 @@ function buildTrainingPrepContent(payload) {
     if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
         content.push({
             type: "text",
-            text: `Interactive review: ${payload.standaloneUrl}\nOpen this URL in your browser to review and submit the prepared job.`,
+            text: `Interactive training prep review: [Open training prep](${payload.standaloneUrl})\n` +
+                `AGENT: surface this to the user as a clickable markdown link (e.g. "[Open training prep](${payload.standaloneUrl})") in your reply — do not leave it buried in tool output. The user opens it to review and submit the prepared job.`,
         });
     }
     return content;