@barivia/barmesh-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Barivia AB. All rights reserved.
+
+This software and associated documentation files (the "Software") are
+proprietary to Barivia AB. The Software is licensed, not sold.
+
+Without prior written permission from Barivia AB, you may not copy, modify,
+merge, publish, distribute, sublicense, sell, or create derivative works
+from the Software, except to the extent necessary to install and execute it
+for your own use in connection with Barivia services under a separate
+agreement with Barivia AB.
+
+For licensing inquiries, contact Barivia AB.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED.

package/README.md

@@ -0,0 +1,68 @@
+# @barivia/barmesh-mcp
+
+MCP proxy for **SOM-based CFD mesh-convergence** and **Richardson/GCI** analysis on the
+Barivia cloud API. It connects any MCP client (Cursor, Claude Desktop, etc.) to the same
+Barivia backend as `@barivia/barsom-mcp`, using the same API key and licensing.
+
+## What it does
+
+Given a mesh-refinement study (several meshes of the same CFD case at increasing
+resolution), barmesh compares the meshes by the **volume-weighted distribution their cells
+form on a shared self-organizing map (SOM)**:
+
+- **`barmesh_mesh_convergence`** — trains one SOM on all meshes (joint-normalized), projects
+  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.
+- **`barmesh_richardson`** — classical three-level Richardson extrapolation / Grid
+  Convergence Index (GCI) on scalar quantities of interest.
+
+These complement, and do not replace, conventional numerical uncertainty analysis.
+
+## Install / configure
+
+```json
+{
+  "mcpServers": {
+    "barmesh": {
+      "command": "npx",
+      "args": ["-y", "@barivia/barmesh-mcp"],
+      "env": {
+        "BARIVIA_API_KEY": "bv_live_xxxx",
+        "BARIVIA_API_URL": "https://api.barivia.se"
+      }
+    }
+  }
+}
+```
+
+Access to the analysis tools requires the **`cfd`** entitlement on your API key; otherwise
+the analysis calls return HTTP 403. Contact Barivia to enable it.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `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_mesh_convergence` | SOM fingerprint distances (async job). |
+| `barmesh_richardson` | Richardson/GCI on scalar QoIs (async job). |
+| `barmesh_jobs` | Poll job status / list jobs. |
+| `barmesh_results` | Distances, convergence reading, and figures. |
+
+## Data format (mesh_convergence)
+
+One combined CSV: one row per cell, a mesh-label column (`mesh_id`), the physical channels
+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.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `BARIVIA_API_KEY` | (required) | Your Barivia API key. |
+| `BARIVIA_API_URL` | `https://api.barivia.se` | API base URL. |
+| `BARIVIA_FETCH_TIMEOUT_MS` | `30000` | 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. |

package/dist/audit.js

@@ -0,0 +1,92 @@
+/**
+ * MCP tool audit wrapper — tool name, action, latency, outcome; no secrets.
+ */
+import { logAudit } from "./logger.js";
+const AUDIT_PARAM_KEYS = new Set([
+    "action",
+    "preset",
+    "backend",
+    "emd_method",
+    "reference_mesh",
+    "job_id",
+    "dataset_id",
+    "figures",
+]);
+function scrubParams(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (!AUDIT_PARAM_KEYS.has(k))
+            continue;
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function extractIds(result) {
+    const ids = {};
+    if (result === null || typeof result !== "object")
+        return ids;
+    try {
+        const text = JSON.stringify(result);
+        const jobMatch = text.match(/"(?:job_id|id)"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (jobMatch)
+            ids.job_id = jobMatch[1];
+        const dsMatch = text.match(/"dataset_id"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (dsMatch)
+            ids.dataset_id = dsMatch[1];
+    }
+    catch {
+        /* ignore */
+    }
+    return ids;
+}
+function errorCodeFrom(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.httpStatus !== undefined)
+            return `http_${e.httpStatus}`;
+        const m = e.message ?? "";
+        const codeMatch = m.match(/error_code:\s*(\w+)/);
+        if (codeMatch)
+            return codeMatch[1];
+    }
+    return undefined;
+}
+export async function runMcpToolAudit(tool, action, args, handler) {
+    const t0 = Date.now();
+    const params = scrubParams(args);
+    try {
+        const result = await handler();
+        const ids = extractIds(result);
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "ok",
+            ...ids,
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        return result;
+    }
+    catch (err) {
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "error",
+            error_code: errorCodeFrom(err),
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        throw err;
+    }
+}
+export function registerAuditedTool(server, name, description, schema, handler) {
+    server.tool(name, description, schema, (async (args) => {
+        const rec = args;
+        const action = typeof rec.action === "string" && rec.action.length > 0 ? rec.action : "default";
+        return runMcpToolAudit(name, action, rec, () => handler(args));
+    }));
+}

package/dist/index.js

@@ -0,0 +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 n,CLIENT_VERSION as r}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";n||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const n=new e({name:"barmesh",version:r},{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(n),t(n),a(n),i(n),c(n);const m=new s;await n.connect(m),console.error(`barmesh-mcp ${r} 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/logger.js

@@ -0,0 +1,34 @@
+/**
+ * Structured stderr logging for the barmesh MCP proxy (Docker json-file friendly).
+ */
+const SERVICE_NAME = process.env.BARIVIA_SERVICE_NAME ?? "barmesh-mcp";
+const LOG_FORMAT = (process.env.BARIVIA_LOG_FORMAT ?? "text").toLowerCase();
+function emit(fields) {
+    const level = fields.level ?? "info";
+    const payload = {
+        ts: new Date().toISOString(),
+        level,
+        service: SERVICE_NAME,
+        ...fields,
+    };
+    delete payload.level;
+    if (LOG_FORMAT === "json") {
+        console.error(JSON.stringify(payload));
+        return;
+    }
+    const parts = [`${payload.ts} ${level.toUpperCase().padEnd(5)} ${fields.msg}`];
+    for (const [k, v] of Object.entries(payload)) {
+        if (k === "ts" || k === "msg" || k === "service")
+            continue;
+        if (v !== undefined && v !== null && v !== "") {
+            parts.push(`${k}=${String(v)}`);
+        }
+    }
+    console.error(parts.join(" | "));
+}
+export function logInfo(msg, fields = {}) {
+    emit({ ...fields, level: "info", msg });
+}
+export function logAudit(fields) {
+    emit({ ...fields, event: "mcp_tool_call", level: "info", msg: "mcp_tool_call" });
+}

package/dist/shared.js

@@ -0,0 +1,317 @@
+/**
+ * Shared config, fetch helpers, sandbox path resolution, API client, and image
+ * helpers for the barmesh MCP proxy. Adapted from @barivia/barsom-mcp; the proxy
+ * remains a thin HTTPS client to the same Barivia API (no domain logic here).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { logInfo } from "./logger.js";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+export const API_URL = process.env.BARIVIA_API_URL ?? process.env.BARSOM_API_URL ?? "https://api.barivia.se";
+export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY ?? "";
+export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "30000", 10);
+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.1.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;
+// ---------------------------------------------------------------------------
+// Fetch helpers
+// ---------------------------------------------------------------------------
+export function isTransientError(err, status) {
+    if (status !== undefined && RETRYABLE_STATUS.has(status))
+        return true;
+    if (err instanceof DOMException && err.name === "AbortError")
+        return true;
+    if (err instanceof TypeError)
+        return true;
+    return false;
+}
+export async function fetchWithTimeout(url, init, timeoutMs = FETCH_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------------------------------------------------------------------
+// Path / sandbox helpers
+// ---------------------------------------------------------------------------
+export function getSandboxRoot() {
+    const raw = process.env.BARIVIA_WORKSPACE_ROOT ?? process.env.BARSOM_WORKSPACE_ROOT;
+    if (raw)
+        return path.resolve(process.cwd(), raw);
+    const workspaceFolder = process.env.CURSOR_WORKSPACE_FOLDER ?? process.env.WORKSPACE_FOLDER;
+    if (workspaceFolder)
+        return path.resolve(workspaceFolder);
+    const pwd = process.env.PWD;
+    if (pwd && path.isAbsolute(pwd))
+        return pwd;
+    return process.cwd();
+}
+export async function getWorkspaceRootAsync(mcpServer) {
+    try {
+        const result = await mcpServer.server.listRoots();
+        const roots = result?.roots ?? [];
+        const fileRoot = roots.find((r) => r.uri.startsWith("file://"));
+        if (fileRoot)
+            return fileURLToPath(fileRoot.uri);
+    }
+    catch {
+        /* client may not support roots/list */
+    }
+    return getSandboxRoot();
+}
+function enforceWorkspaceSandboxUpload() {
+    const v = process.env.BARIVIA_ENFORCE_WORKSPACE_SANDBOX ?? "1";
+    if (v === "0" || v.toLowerCase() === "false")
+        return false;
+    return true;
+}
+/**
+ * Resolve file_path for dataset upload. Rejects "..", enforces workspace sandbox
+ * by default (set BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0 to allow absolute paths).
+ */
+export async function resolveFilePathForUpload(filePath, mcpServer) {
+    const trimmed = filePath.trim();
+    if (trimmed.includes(".."))
+        throw new Error("Path traversal ('..') is not allowed.");
+    const checkUnder = async (p) => {
+        const root = await getWorkspaceRootAsync(mcpServer);
+        const real = await fs.realpath(p);
+        const realRoot = await fs.realpath(root);
+        if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+            throw new Error(`Path outside the workspace is disabled (BARIVIA_ENFORCE_WORKSPACE_SANDBOX). Workspace root: ${realRoot}`);
+        }
+        const stat = await fs.stat(real);
+        if (!stat.isFile())
+            throw new Error("Path must be a regular file, not a directory.");
+        return real;
+    };
+    if (trimmed.startsWith("file://")) {
+        const url = new URL(trimmed);
+        if (url.protocol !== "file:" || (url.hostname && url.hostname !== "localhost")) {
+            throw new Error("Only local file:// URIs are allowed (no remote hosts).");
+        }
+        const p = fileURLToPath(trimmed);
+        return enforceWorkspaceSandboxUpload() ? checkUnder(p) : p;
+    }
+    if (path.isAbsolute(trimmed)) {
+        return enforceWorkspaceSandboxUpload() ? checkUnder(trimmed) : trimmed;
+    }
+    const root = await getWorkspaceRootAsync(mcpServer);
+    const resolved = path.resolve(root, trimmed);
+    return checkUnder(resolved);
+}
+export function formatApiErrorMessage(status, bodyText, requestId) {
+    let parsed = null;
+    try {
+        const j = JSON.parse(bodyText);
+        if (j && typeof j === "object")
+            parsed = j;
+    }
+    catch {
+        /* ignore */
+    }
+    const detail = (parsed?.error != null && String(parsed.error)) ||
+        (bodyText.trim() ? bodyText.trim() : `HTTP ${status}`);
+    const code = parsed?.error_code != null ? ` (error_code: ${parsed.error_code})` : "";
+    const accountHint = ` Regenerate or verify your key via ${PUBLIC_SITE_ORIGIN} if needed.`;
+    const hint = status === 400
+        ? " Check parameter types and required fields."
+        : status === 401
+            ? ` Check BARIVIA_API_KEY in your MCP config.${accountHint}`
+            : status === 403
+                ? ` Access denied (your plan may not include the CFD mesh-convergence tools).${accountHint}`
+                : status === 404
+                    ? " The resource may not exist or may have been deleted."
+                    : status === 409
+                        ? " The job may not be in the expected state."
+                        : status === 429
+                            ? " Plan limit or rate limit — read the error above; delete unused datasets or wait and retry."
+                            : status === 502
+                                ? " Object storage error from API — retry later."
+                                : status === 503
+                                    ? " API or database temporarily unavailable — retry later."
+                                    : status >= 500
+                                        ? " Server error — retry later."
+                                        : "";
+    const rid = ` (request id: ${requestId} — include if contacting support)`;
+    return `${detail}${code}${hint}${rid}`;
+}
+function throwApiError(status, bodyText, requestId) {
+    const err = new Error(formatApiErrorMessage(status, bodyText, requestId));
+    err.httpStatus = status;
+    throw err;
+}
+export async function apiCall(method, pathPart, body, extraHeaders, requestTimeoutMs) {
+    const url = `${API_URL}${pathPart}`;
+    const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
+    const requestId = Math.random().toString(36).slice(2, 10);
+    const headers = {
+        Authorization: `Bearer ${API_KEY}`,
+        "Content-Type": contentType,
+        "X-Request-ID": requestId,
+        "X-Barmesh-Client-Version": CLIENT_VERSION,
+        ...extraHeaders,
+    };
+    let serializedBody;
+    if (body !== undefined) {
+        if (body instanceof Uint8Array) {
+            serializedBody = body;
+        }
+        else {
+            serializedBody = contentType === "application/json" ? JSON.stringify(body) : String(body);
+        }
+    }
+    const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
+    const t0 = Date.now();
+    logInfo("API request", { rid: requestId, action: method, path: pathPart });
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const resp = await fetchWithTimeout(url, { method, headers, body: serializedBody }, effectiveTimeout);
+            const text = await resp.text();
+            if (!resp.ok) {
+                if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
+                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    continue;
+                }
+                logInfo("API response", { rid: requestId, outcome: "error", duration_ms: Date.now() - t0, error_code: `http_${resp.status}` });
+                throwApiError(resp.status, text, requestId);
+            }
+            logInfo("API response", { rid: requestId, outcome: "ok", duration_ms: Date.now() - t0 });
+            return JSON.parse(text);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < MAX_RETRIES && isTransientError(err)) {
+                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                continue;
+            }
+            if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
+                throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (e.g. 120000) for slow or large requests. (request id: ${requestId})`);
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+/** Fetch raw bytes from the API (for image downloads). */
+export async function apiRawCall(pathPart, requestTimeoutMs) {
+    const url = `${API_URL}${pathPart}`;
+    const requestId = Math.random().toString(36).slice(2, 10);
+    const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const resp = await fetchWithTimeout(url, { method: "GET", headers: { Authorization: `Bearer ${API_KEY}`, "X-Request-ID": requestId } }, effectiveTimeout);
+            if (!resp.ok) {
+                if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
+                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    continue;
+                }
+                const text = await resp.text();
+                throwApiError(resp.status, text, requestId);
+            }
+            const arrayBuf = await resp.arrayBuffer();
+            return {
+                data: Buffer.from(arrayBuf),
+                contentType: resp.headers.get("content-type") ?? "application/octet-stream",
+            };
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < MAX_RETRIES && isTransientError(err)) {
+                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+// ---------------------------------------------------------------------------
+// Result helpers
+// ---------------------------------------------------------------------------
+export function textResult(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+export async function pollUntilComplete(jobId, maxWaitMs = 30_000, intervalMs = 2000) {
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
+        const status = data.status;
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            return {
+                status,
+                result_ref: data.result_ref,
+                error: data.error,
+            };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return { status: "timeout" };
+}
+// ---------------------------------------------------------------------------
+// Image helpers
+// ---------------------------------------------------------------------------
+export function mimeForFilename(fname) {
+    if (fname.endsWith(".pdf"))
+        return "application/pdf";
+    if (fname.endsWith(".svg"))
+        return "image/svg+xml";
+    return "image/png";
+}
+/** Per-image caption for multimodal LLM context (what to look for). */
+export function getCaptionForImage(filename) {
+    const base = filename.replace(/\.(png|pdf|svg)$/i, "");
+    if (base === "KL_ref")
+        return "KL divergence to the reference mesh: steel blue is from the reference, coral is to the reference. Lower and converging toward the finest mesh indicates sufficiency.";
+    if (base === "KL_stepwise")
+        return "Stepwise KL between consecutive meshes (coarsening blue, refinement red on the right axis). Shrinking on the finest steps indicates a plateau.";
+    if (base === "EMD_ref")
+        return "Wasserstein-1 (EMD) distance from each mesh to the reference. A monotone decrease toward the finest mesh indicates field-level convergence.";
+    if (base === "EMD_stepwise")
+        return "Stepwise EMD between consecutive meshes. Small, plateauing values on the finest pairs indicate the fingerprint has stopped changing.";
+    if (base === "plot_vol_coarse_fine")
+        return "Volume-weighted SOM fingerprints P_vol for the coarsest and reference meshes (shared color scale).";
+    if (base.startsWith("plot_vol_steps") || base.startsWith("plot_vol_seven_steps"))
+        return "Stepwise change in the volume fingerprint between consecutive meshes; diverging-then-shrinking patterns trace where refinement still moves mass.";
+    if (base.startsWith("plot_"))
+        return `Component plane for ${base.replace(/^plot_/, "")} on the trained SOM.`;
+    return "";
+}
+export async function tryAttachImage(content, jobId, filename) {
+    if (filename.endsWith(".pdf") || filename.endsWith(".svg")) {
+        content.push({
+            type: "text",
+            text: `${filename} is ready (vector PDF — not inlineable). Use barmesh_results(action=image, job_id="${jobId}", filename="${filename}") to download it.`,
+        });
+        return;
+    }
+    const caption = getCaptionForImage(filename);
+    if (caption)
+        content.push({ type: "text", text: `${filename}: ${caption}` });
+    try {
+        const { data: imgBuf } = await apiRawCall(`/v1/results/${jobId}/image/${filename}`);
+        content.push({
+            type: "image",
+            data: imgBuf.toString("base64"),
+            mimeType: mimeForFilename(filename),
+            annotations: { audience: ["user"], priority: 0.8 },
+        });
+    }
+    catch {
+        content.push({ type: "text", text: `(${filename} not available for inline display)` });
+    }
+}

package/dist/tools/cfd.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, textResult } from "../shared.js";
+export function registerCfdTools(server) {
+    registerAuditedTool(server, "barmesh_mesh_convergence", `Run SOM-based mesh-convergence analysis on an uploaded combined per-cell CSV.
+
+What it does (one call): joint-normalizes all meshes, trains one SOM on a stratified pooled subsample, projects each mesh to a volume-weighted fingerprint, and computes symmetric KL and Wasserstein-1 (EMD) distances stepwise and against a reference mesh, plus publication figures and an advisory convergence reading.
+
+BEST FOR: A mesh-refinement study where you want a field-level (not just scalar) view of whether the mesh has converged.
+NOT FOR: Single scalar quantities of interest — use barmesh_richardson for classical GCI.
+ASYNC: This is a queued job. It returns a job id immediately. Then poll barmesh_jobs(action=status) every 10-20s; datacenter-scale grids plus EMD can take a few minutes — keep polling. On completion call barmesh_results(action=get).
+COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time.`, {
+        action: z.enum(["submit"]).optional().describe("submit: enqueue the analysis (default)"),
+        dataset_id: z.string().describe("Dataset ID from barmesh_datasets(upload)"),
+        feature_columns: z.array(z.string()).describe("Per-cell numeric feature columns to train the SOM on (e.g. [\"p\",\"U_mag\",\"k\",\"log_epsilon\"])"),
+        preset: z.enum(["generic", "cavity", "pitz", "datacenter"]).optional().describe("Hyperparameter preset; defaults to generic. cavity/pitz/datacenter reproduce the published settings."),
+        mesh_column: z.string().optional().describe("Column with the mesh label (default mesh_id)"),
+        volume_column: z.string().optional().describe("Cell-volume column for fingerprint weights (default V; equal weights if absent)"),
+        reference_mesh: z.string().optional().describe("Mesh label used as reference (default: the mesh with the most cells = finest)"),
+        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count)"),
+        grid: z.array(z.number().int()).optional().describe("SOM grid [rows, cols] (overrides preset)"),
+        epochs: z.array(z.number().int()).optional().describe("[ordering, convergence] epochs (overrides preset)"),
+        batch_size: z.number().int().optional().describe("SOM batch size (overrides preset)"),
+        sigma_f: z.number().optional().describe("Final ordering neighborhood width (overrides preset)"),
+        backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().describe("Compute backend (default auto / preset)"),
+        stratify_scale: z.number().optional().describe("[0,1] per-mesh training-row cap; 1 uses all cells (default 1)"),
+        emd_method: z.enum(["exact", "sinkhorn"]).optional().describe("EMD solver: exact LP (default) or sinkhorn (fast approximation for large grids)"),
+        component_planes_physical: z.boolean().optional().describe("Physical-scale component-plane colorbars (default true)"),
+        figures: z.boolean().optional().describe("Generate publication figures (default true)"),
+        label: z.string().optional().describe("Optional job label"),
+    }, async (args) => {
+        const { action, dataset_id, label, ...rest } = args;
+        void action;
+        const params = {};
+        for (const [k, v] of Object.entries(rest)) {
+            if (v !== undefined && v !== null)
+                params[k] = v;
+        }
+        const body = { dataset_id, params };
+        if (typeof label === "string" && label.length > 0)
+            body.label = label;
+        const data = (await apiCall("POST", "/v1/cfd/mesh-convergence", body));
+        const id = data.id;
+        if (id != null)
+            data.suggested_next_step = `Poll barmesh_jobs(action=status, job_id=${id}); on completion call barmesh_results(action=get, job_id=${id}).`;
+        return textResult(data);
+    });
+    registerAuditedTool(server, "barmesh_richardson", `Run classical Richardson extrapolation / Grid Convergence Index (GCI) on scalar quantities of interest.
+
+What it does: from a small CSV with one row per mesh (a mesh label, a representative cell size h or a cell count, and one or more QoI columns), slides the three-level Celik (2008) GCI over consecutive mesh triplets (finest first) and reports the observed order p, the extrapolated value, and the fine-grid GCI per triplet per QoI.
+
+BEST FOR: Scalar benchmarks (reattachment length, centerline values, probe readings) where a classical asymptotic-convergence check is expected.
+NOT FOR: High-dimensional field comparison — use barmesh_mesh_convergence (complementary).
+ASYNC: queued job; poll barmesh_jobs(action=status), then barmesh_results(action=get).
+COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV.`, {
+        action: z.enum(["submit"]).optional().describe("submit: enqueue the GCI job (default)"),
+        dataset_id: z.string().describe("Dataset ID (one row per mesh)"),
+        qoi_columns: z.array(z.string()).describe("Scalar QoI column names to extrapolate"),
+        mesh_column: z.string().optional().describe("Mesh label column (default mesh_id)"),
+        h_column: z.string().optional().describe("Representative cell-size column (provide this or n_cells_column)"),
+        n_cells_column: z.string().optional().describe("Cell-count column; h is derived as n_cells^(-1/dimension)"),
+        dimension: z.number().int().optional().describe("Spatial dimension d for deriving h from cell count (default 3)"),
+        safety_factor: z.number().optional().describe("GCI safety factor Fs (default 1.25, Roache)"),
+        label: z.string().optional().describe("Optional job label"),
+    }, async (args) => {
+        const { action, dataset_id, label, ...rest } = args;
+        void action;
+        const params = {};
+        for (const [k, v] of Object.entries(rest)) {
+            if (v !== undefined && v !== null)
+                params[k] = v;
+        }
+        const body = { dataset_id, params };
+        if (typeof label === "string" && label.length > 0)
+            body.label = label;
+        const data = (await apiCall("POST", "/v1/cfd/richardson", body));
+        const id = data.id;
+        if (id != null)
+            data.suggested_next_step = `Poll barmesh_jobs(action=status, job_id=${id}); on completion call barmesh_results(action=get, job_id=${id}).`;
+        return textResult(data);
+    });
+}

package/dist/tools/datasets.js

@@ -0,0 +1,64 @@
+import { gzipSync } from "node:zlib";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, resolveFilePathForUpload, textResult, UPLOAD_DATASET_TIMEOUT_MS, } from "../shared.js";
+export function registerDatasetsTool(server) {
+    registerAuditedTool(server, "barmesh_datasets", `Upload, preview, or list the combined per-cell mesh CSV used for convergence analysis.
+
+| Action | Use when |
+|--------|----------|
+| upload | You have prepared a combined per-cell CSV (mesh_id + feature columns + cell volume V). Do this first. |
+| preview | After upload — verify the mesh column, feature columns, and volume column are present and numeric. |
+| list | Find dataset IDs for analysis. |
+
+BEST FOR: One combined CSV holding all meshes of a refinement study (one row per cell, a mesh label column, the physical channels, and a cell-volume column).
+NOT FOR: Raw OpenFOAM case directories — extract a per-cell CSV first (see barmesh_prepare_mesh_data).
+COMMON MISTAKES: omitting the cell-volume column (defaults to equal weights, which weakens the fingerprint); inconsistent feature columns across meshes.
+ESCALATION: If preview shows a feature column as non-numeric, fix the extraction and re-upload.`, {
+        action: z.enum(["upload", "preview", "list"]).describe("upload: add the combined CSV; preview: inspect columns; list: see datasets"),
+        name: z.string().optional().describe("Dataset name (required for upload)"),
+        file_path: z.string().optional().describe("Path to the combined CSV (PREFERRED): absolute, file:// URI, or relative to the workspace root"),
+        csv_data: z.string().optional().describe("Inline CSV string for small pastes only (<10KB). Prefer file_path."),
+        dataset_id: z.string().optional().describe("Dataset ID (required for preview)"),
+        n_rows: z.number().int().optional().default(5).describe("Sample rows to return (preview only)"),
+    }, async (args) => {
+        const { action, name, file_path, csv_data, dataset_id, n_rows } = args;
+        if (action === "upload") {
+            if (!name)
+                throw new Error("barmesh_datasets(upload) requires name.");
+            let body;
+            if (file_path && file_path.length > 0) {
+                const resolved = await resolveFilePathForUpload(file_path, server);
+                body = await fs.readFile(resolved, "utf-8");
+            }
+            else if (csv_data && csv_data.length > 0) {
+                body = csv_data;
+            }
+            else {
+                throw new Error("barmesh_datasets(upload) requires file_path or csv_data. Prefer file_path.");
+            }
+            const GZIP_THRESHOLD = 1024 * 1024;
+            const uploadHeaders = { "X-Dataset-Name": name, "Content-Type": "text/csv" };
+            let uploadBody = body;
+            if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
+                uploadBody = gzipSync(Buffer.from(body, "utf-8"));
+                uploadHeaders["Content-Encoding"] = "gzip";
+            }
+            const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
+            const id = data.id ?? data.dataset_id;
+            if (id != null)
+                data.suggested_next_step = `Next: barmesh_datasets(action=preview, dataset_id=${id}) to verify the mesh, feature, and volume columns.`;
+            return textResult(data);
+        }
+        if (action === "preview") {
+            if (!dataset_id)
+                throw new Error("barmesh_datasets(preview) requires dataset_id.");
+            const data = await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=${n_rows ?? 5}`);
+            return textResult(data);
+        }
+        // list
+        const data = await apiCall("GET", "/v1/datasets");
+        return textResult(data);
+    });
+}

package/dist/tools/guide.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, textResult } from "../shared.js";
+const OFFLINE_GUIDE = `barmesh: CFD mesh-convergence on the Barivia API.
+Two tracks: barmesh_mesh_convergence (SOM fingerprint distances) and barmesh_richardson (classical GCI).
+Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_jobs(status) -> barmesh_results(get).
+(API unreachable; this is the offline summary. Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
+export function registerGuideTool(server) {
+    registerAuditedTool(server, "barmesh_guide_workflow", `Get the barmesh CFD mesh-convergence workflow and tool map from the API (tier-scoped).
+
+BEST FOR: First call in a session — orients you on the two tracks (SOM fingerprint distances and Richardson/GCI), the upload->submit->poll->results flow, and what your plan allows.
+NOT FOR: Step-by-step mesh-data preparation — use barmesh_prepare_mesh_data for that.
+ESCALATION: If the response says your plan does not include CFD tools, the analysis tools will return 403; contact Barivia to enable the cfd entitlement.`, { action: z.enum(["get"]).optional().describe("get: fetch the workflow guide (default)") }, async () => {
+        try {
+            const data = (await apiCall("GET", "/v1/cfd/guide"));
+            return textResult({
+                guide: data.guide,
+                entitled: data.entitled,
+                allowed_job_types: data.allowed_job_types,
+            });
+        }
+        catch (e) {
+            if (e?.httpStatus === 401 || e?.httpStatus === 403)
+                throw e;
+            return textResult(OFFLINE_GUIDE);
+        }
+    });
+    registerAuditedTool(server, "barmesh_prepare_mesh_data", `Get the step-by-step recipe for turning a mesh-refinement study into ONE combined per-cell CSV for SOM convergence analysis.
+
+BEST FOR: Before barmesh_datasets(upload) — tells you which physical channels to extract, how to label meshes (mesh_id), the cell-volume column (V), and how to pick the reference mesh.
+NOT FOR: Submitting jobs — after preparing the CSV, use barmesh_datasets(upload) then barmesh_mesh_convergence.
+COMMON MISTAKES: forgetting the per-cell cell-volume column; using different channels across meshes; not log-compressing turbulence quantities (k, epsilon, omega).`, { action: z.enum(["get"]).optional().describe("get: fetch the mesh-prep recipe (default)") }, async () => {
+        const data = (await apiCall("GET", "/v1/cfd/prep"));
+        return textResult({ recipe: data.recipe, entitled: data.entitled });
+    });
+}

package/dist/tools/jobs.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, textResult } from "../shared.js";
+export function registerJobsTool(server) {
+    registerAuditedTool(server, "barmesh_jobs", `Check job status or list jobs.
+
+BEST FOR: Polling a submitted barmesh_mesh_convergence or barmesh_richardson job until status is completed/failed.
+ASYNC PROTOCOL: Poll action=status every 10-20s. Keep polling for several minutes — datacenter-scale grids plus EMD are slow; do not give up after one poll. When status=completed, call barmesh_results(action=get, job_id=...).
+ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
+        action: z.enum(["status", "list"]).describe("status: check one job; list: recent jobs"),
+        job_id: z.string().optional().describe("Job ID (required for status)"),
+    }, async (args) => {
+        const { action, job_id } = args;
+        if (action === "status") {
+            if (!job_id)
+                throw new Error("barmesh_jobs(status) requires job_id.");
+            const data = await apiCall("GET", `/v1/jobs/${job_id}`);
+            return textResult(data);
+        }
+        const data = await apiCall("GET", "/v1/jobs");
+        return textResult(data);
+    });
+}

package/dist/tools/results.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, apiRawCall, textResult, tryAttachImage } from "../shared.js";
+const MESH_DEFAULT_FIGURES = ["KL_ref", "EMD_ref", "plot_vol_coarse_fine"];
+export function registerResultsTool(server) {
+    registerAuditedTool(server, "barmesh_results", `Fetch results of a completed CFD job: distances, convergence reading, and figures.
+
+| Action | Use when |
+|--------|----------|
+| get | Read the summary (distances per mesh, stepwise, convergence reading) and inline key figures. |
+| image | Download one figure by filename (e.g. KL_ref.pdf, EMD_stepwise.png). |
+
+BEST FOR: After barmesh_jobs(action=status) shows completed.
+FIGURES: For mesh_convergence, action=get inlines the headline panels (KL_ref, EMD_ref, volume coarse/fine) as PNGs with captions; pass figures="all" for every figure, "none" for metrics only, or a list of names. PDFs are publication vector copies — fetch with action=image.
+NOT FOR: Submitting jobs.`, {
+        action: z.enum(["get", "image"]).describe("get: summary + figures; image: download one figure file"),
+        job_id: z.string().describe("Job ID"),
+        filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.pdf)"),
+        figures: z
+            .union([z.enum(["default", "all", "none"]), z.array(z.string())])
+            .optional()
+            .describe("For action=get: which figures to inline (default headline panels; 'all'; 'none'; or a list of names)"),
+    }, async (args) => {
+        const { action, job_id, filename, figures } = args;
+        if (action === "image") {
+            if (!filename)
+                throw new Error("barmesh_results(image) requires filename.");
+            const { data, contentType } = await apiRawCall(`/v1/results/${job_id}/image/${filename}`);
+            if (contentType.startsWith("image/")) {
+                return {
+                    content: [
+                        { type: "text", text: `${filename} (${contentType})` },
+                        { type: "image", data: data.toString("base64"), mimeType: contentType, annotations: { audience: ["user"], priority: 0.8 } },
+                    ],
+                };
+            }
+            return textResult(`${filename} is ${contentType}; saved out-of-band. For vector PDFs, open the downloaded file directly.`);
+        }
+        const summary = (await apiCall("GET", `/v1/results/${job_id}`));
+        const content = [{ type: "text", text: JSON.stringify(summary, null, 2) }];
+        if (figures === "none")
+            return { content };
+        const allFiles = summary.files ?? [];
+        const imageFiles = allFiles.filter((f) => /\.png$/i.test(f));
+        let toFetch;
+        if (figures === "all") {
+            toFetch = imageFiles;
+        }
+        else if (Array.isArray(figures)) {
+            toFetch = figures
+                .map((key) => {
+                if (/\.(png|pdf|svg)$/i.test(key))
+                    return key;
+                const png = imageFiles.find((f) => f.replace(/\.png$/i, "") === key);
+                return png ?? null;
+            })
+                .filter((f) => f != null);
+        }
+        else {
+            // default headline panels (PNG) when present
+            toFetch = MESH_DEFAULT_FIGURES.map((b) => `${b}.png`).filter((f) => imageFiles.includes(f));
+        }
+        for (const f of toFetch) {
+            await tryAttachImage(content, job_id, f);
+        }
+        return { content };
+    });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@barivia/barmesh-mcp",
+  "version": "0.1.0",
+  "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
+  "keywords": [
+    "mcp",
+    "cfd",
+    "mesh-convergence",
+    "grid-convergence",
+    "richardson",
+    "gci",
+    "som",
+    "barivia"
+  ],
+  "license": "UNLICENSED",
+  "author": "Barivia AB",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/barestrand/barivia-platform.git",
+    "directory": "apps/barmesh-mcp"
+  },
+  "homepage": "https://github.com/barestrand/barivia-platform/tree/main/apps/barmesh-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/barestrand/barivia-platform/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "barmesh-mcp": "dist/index.js"
+  },
+  "files": [
+    "LICENSE",
+    "dist/**/*.js"
+  ],
+  "scripts": {
+    "minify": "terser dist/index.js -o dist/index.js -c -m --toplevel",
+    "build": "tsc && npm run minify",
+    "build:publish": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.publish.json && npm run minify",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --config vitest.config.ts",
+    "prepublishOnly": "npm run build:publish"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "terser": "^5.46.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}