@barivia/barmesh-mcp 0.4.0 → 0.5.0

package/dist/tools/datasets.js

@@ -4,54 +4,140 @@ import { z } from "zod";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, } from "../shared.js";
+import { GZIP_UPLOAD_HINT } from "../upload_hints.js";
+/**
+ * Normalize a nullable string field from the API. Returns "" for absent values,
+ * empty strings, and the literal SQL/serialization sentinels "missing"/"null".
+ */
+function cleanNullable(v) {
+    if (v == null)
+        return "";
+    const s = String(v).trim();
+    return s === "" || s.toLowerCase() === "missing" || s.toLowerCase() === "null" ? "" : s;
+}
 export function registerDatasetsTool(server) {
-    registerAuditedTool(server, "barmesh_datasets", `Upload, preview, or list the combined per-cell mesh CSV used for convergence analysis.
+    registerAuditedTool(server, "barmesh_datasets", `Upload, preview, list, get, subset, or delete the combined per-cell mesh CSV used for convergence analysis.
+
+Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~64 MB, prefer .csv.gz (often 2–3× smaller); large uploads use presigned direct-to-storage PUT and accept gzip bodies.
 
 | 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. |
+| get | Fetch one dataset by id — status, staging fields, ingest_error (use after upload or when staging is slow). |
 | list | Find dataset IDs for analysis. |
+| subset | Shrink a huge per-cell table server-side (row_range, filters, or sample_n). |
+| delete | Remove a dataset permanently. |
+
+action=upload: PREFER file_path — server reads from workspace root (token-efficient). Accepts .csv, .tsv, .csv.gz, .tsv.gz. Use csv_data only for small inline pastes (<10KB). If plain CSV exceeds the 5 GB upload cap, gzip it first (.csv.gz).
 
 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"),
+        action: z
+            .enum(["upload", "preview", "list", "get", "subset", "delete"])
+            .describe("upload: add CSV or .csv.gz; preview: inspect columns; list: see all datasets; get: fetch one dataset metadata (status/staging); subset: create filtered subset; delete: remove dataset"),
+        name: z.string().optional().describe("Dataset name (required for upload and subset)"),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Path to local CSV or .csv.gz (PREFERRED): absolute path, file:// URI, or path relative to the workspace root. NOTE: relative paths resolve against the MCP workspace root — in Cursor/IDE clients that root is often the MCP install dir, not your project, so set BARIVIA_WORKSPACE_ROOT in the MCP config env (or pass an absolute path) if a relative path is 'not accessible'. Use .csv.gz for large mesh tables."),
         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)"),
+        dataset_id: z.string().optional().describe("Dataset ID (required for preview, get, subset, and delete)"),
         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;
+        row_range: z
+            .tuple([z.number().int(), z.number().int()])
+            .optional()
+            .describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),
+        filters: z.preprocess((v) => {
+            if (v === undefined || v === null)
+                return v;
+            if (Array.isArray(v))
+                return v;
+            if (typeof v === "object" && v !== null && "column" in v)
+                return [v];
+            return v;
+        }, z
+            .array(z.object({
+            column: z.string(),
+            op: z.enum(["eq", "ne", "in", "gt", "lt", "gte", "lte", "between"]),
+            value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
+        }))
+            .optional()
+            .describe("For subset: filter conditions (AND logic). Single object or array.")),
+        filter: z
+            .object({
+            column: z.string(),
+            op: z.enum(["eq", "ne", "in", "gt", "lt", "gte", "lte", "between"]),
+            value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
+        })
+            .optional()
+            .describe("Deprecated — use filters instead. Single filter condition."),
+        sample_n: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("action=subset: keep a random N-row sample (seeded, row order preserved). Use to shrink a huge table server-side."),
+        sample_seed: z
+            .number()
+            .int()
+            .optional()
+            .describe("action=subset: RNG seed for sample_n (default 42)."),
+    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, sample_n, sample_seed, }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("barmesh_datasets(upload) requires name.");
             let body;
             if (file_path && file_path.length > 0) {
-                // Preflight: warm plan/limits and reject over-limit uploads before reading the file.
                 await apiCall("GET", "/v1/system/info");
                 const resolved = await resolveFilePathForUpload(file_path, server);
-                const ext = path.extname(resolved).toLowerCase();
-                if (ext !== ".csv" && ext !== ".tsv") {
-                    throw new Error("Only .csv and .tsv files can be uploaded as datasets.");
+                const lower = resolved.toLowerCase();
+                const isGzipInput = lower.endsWith(".gz");
+                const baseExt = path.extname(isGzipInput ? lower.slice(0, -3) : lower);
+                if (baseExt !== ".csv" && baseExt !== ".tsv") {
+                    throw new Error("Only .csv, .tsv, .csv.gz, or .tsv.gz files can be uploaded as datasets.");
                 }
                 const HARD_MAX_BYTES = 5 * 1024 * 1024 * 1024; // 5 GB
-                const stat = await fs.stat(resolved);
+                let stat;
+                try {
+                    stat = await fs.stat(resolved);
+                }
+                catch {
+                    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) {
-                    throw new Error(`File too large (${(stat.size / 1024 / 1024 / 1024).toFixed(2)} GB). Maximum upload size is 5 GB.`);
+                    const gzipHint = isGzipInput ? "" : ` ${GZIP_UPLOAD_HINT}`;
+                    throw new Error(`File too large (${(stat.size / 1024 / 1024 / 1024).toFixed(2)} GB). Maximum upload size is 5 GB.${gzipHint}`);
                 }
                 if (stat.size >= LARGE_UPLOAD_BYTES) {
                     const idem = await streamFileSha256(resolved);
-                    const init = (await apiCall("POST", "/v1/datasets/upload-url", { name, size_bytes: stat.size }, { "Idempotency-Key": idem }));
+                    let init;
+                    try {
+                        init = (await apiCall("POST", "/v1/datasets/upload-url", { name, size_bytes: stat.size }, { "Idempotency-Key": idem }));
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        if (msg.includes("dataset_too_large") && !isGzipInput) {
+                            throw new Error(`${msg} ${GZIP_UPLOAD_HINT}`);
+                        }
+                        throw e;
+                    }
                     const datasetId = (init.dataset_id ?? init.id);
-                    if (init.idempotent_replay) {
-                        return textResult({ id: datasetId, status: init.status, idempotent_replay: true,
-                            suggested_next_step: `barmesh_datasets(action=preview, dataset_id=${datasetId})` });
+                    if (init.idempotent_replay && !init.upload_url) {
+                        return textResult({
+                            id: datasetId,
+                            status: init.status,
+                            idempotent_replay: true,
+                            suggested_next_step: `barmesh_datasets(action=preview, dataset_id=${datasetId})`,
+                        });
                     }
-                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? "application/octet-stream", PRESIGNED_PUT_TIMEOUT_MS);
+                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? "application/octet-stream", PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
                     const fin = (await apiCall("POST", `/v1/datasets/${datasetId}/finalize`, {}));
                     const jobId = (fin.id ?? fin.job_id);
                     const poll = await pollUntilComplete(jobId, POLL_STAGE_MAX_MS);
@@ -59,10 +145,28 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                         return textResult({ id: datasetId, status: "failed", error: poll.error ?? "staging failed" });
                     }
                     const ready = poll.status === "completed";
-                    return textResult({ id: datasetId, status: ready ? "ready" : "staging", job_id: jobId,
+                    return textResult({
+                        id: datasetId,
+                        status: ready ? "ready" : "staging",
+                        job_id: jobId,
                         suggested_next_step: ready
-                            ? `barmesh_datasets(action=preview, dataset_id=${datasetId})`
-                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}").` });
+                            ? `barmesh_datasets(action=preview, dataset_id=${datasetId}) to verify mesh, feature, and volume columns.`
+                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}") then barmesh_datasets(action=preview, dataset_id=${datasetId}).`,
+                    });
+                }
+                if (isGzipInput) {
+                    const gzBytes = await fs.readFile(resolved);
+                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
+                        "X-Dataset-Name": name,
+                        "Content-Type": "text/csv",
+                        "Content-Encoding": "gzip",
+                        "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
+                    }, UPLOAD_DATASET_TIMEOUT_MS));
+                    const gid = data.id ?? data.dataset_id;
+                    if (gid != null) {
+                        data.suggested_next_step = `Next: barmesh_datasets(action=preview, dataset_id=${gid}) to verify the mesh, feature, and volume columns.`;
+                    }
+                    return textResult(data);
                 }
                 body = await fs.readFile(resolved, "utf-8");
             }
@@ -76,8 +180,6 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const uploadHeaders = {
                 "X-Dataset-Name": name,
                 "Content-Type": "text/csv",
-                // Deterministic key so a timed-out retry of the SAME upload reconciles to
-                // the original dataset server-side instead of creating a duplicate.
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
             let uploadBody = body;
@@ -87,8 +189,9 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             }
             const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
-            if (id != null)
+            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") {
@@ -97,8 +200,68 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             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);
+        if (action === "subset") {
+            if (!dataset_id)
+                throw new Error("barmesh_datasets(subset) requires dataset_id.");
+            if (!name)
+                throw new Error("barmesh_datasets(subset) requires name.");
+            const allFilters = filters ?? (filter ? [filter] : undefined);
+            if (row_range === undefined && allFilters === undefined && sample_n === undefined) {
+                throw new Error("barmesh_datasets(subset) requires at least one of row_range, filters, or sample_n.");
+            }
+            const body = { name };
+            if (row_range !== undefined)
+                body.row_range = row_range;
+            if (allFilters !== undefined)
+                body.filters = allFilters;
+            if (sample_n !== undefined)
+                body.sample_n = sample_n;
+            if (sample_seed !== undefined)
+                body.sample_seed = sample_seed;
+            const data = await apiCall("POST", `/v1/datasets/${dataset_id}/subset`, body);
+            return textResult(data);
+        }
+        if (action === "list") {
+            const data = (await apiCall("GET", "/v1/datasets"));
+            if (Array.isArray(data)) {
+                const lines = data.map((ds) => {
+                    const id = String(ds.id ?? "");
+                    const dsName = String(ds.name ?? "");
+                    const rows = ds.rows != null ? Number(ds.rows) : "?";
+                    const cols = ds.cols != null ? Number(ds.cols) : "?";
+                    const st = ds.status != null ? String(ds.status) : "ready";
+                    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+                    const ingestErr = cleanNullable(ds.ingest_error);
+                    const err = ingestErr ? ` | ingest_error=${ingestErr}` : "";
+                    return `${dsName} (${id}) — ${rows}×${cols}${statusBit}${err}`;
+                });
+                return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No datasets." }] };
+            }
+            return textResult(data);
+        }
+        if (action === "get") {
+            if (!dataset_id)
+                throw new Error("barmesh_datasets(get) requires dataset_id.");
+            const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
+            const lines = [
+                `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
+                `Status: ${ds.status ?? "ready"}`,
+                `Rows × cols: ${ds.rows ?? "?"} × ${ds.cols ?? "?"}`,
+                ds.size_bytes != null ? `Size: ${Number(ds.size_bytes).toLocaleString()} bytes` : "",
+                ds.staged_prefix != null ? `Staged prefix: ${String(ds.staged_prefix)}` : "",
+                ds.staged_version != null ? `Staged version: ${String(ds.staged_version)}` : "",
+                ds.stage_job_id != null ? `Stage job: ${String(ds.stage_job_id)} (poll barmesh_jobs(action=status))` : "",
+                cleanNullable(ds.ingest_error) ? `Ingest error: ${cleanNullable(ds.ingest_error)}` : "",
+                ds.created_at != null ? `Created: ${String(ds.created_at)}` : "",
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        if (action === "delete") {
+            if (!dataset_id)
+                throw new Error("barmesh_datasets(delete) requires dataset_id.");
+            const data = await apiCall("DELETE", `/v1/datasets/${dataset_id}`);
+            return textResult(data);
+        }
+        throw new Error("Invalid action");
     });
 }

package/dist/tools/jobs.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "../cfd_finalize.js";
+import { formatJobStatusText } from "../job_status_format.js";
 export function registerJobsTool(server) {
     registerAuditedTool(server, "barmesh_jobs", `Check job status or list jobs.
 
@@ -20,16 +21,10 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             if (status === "completed" && data.finalize_job_id) {
                 const { note } = await pollCfdFinalizeIfPresent(job_id, data);
                 data = await refreshJobAfterFinalize(job_id);
-                const lines = [
-                    `Job ${job_id}: ${String(data.status ?? "unknown")}`,
-                    data.label != null ? `Label: ${String(data.label)}` : null,
-                    data.progress != null ? `Progress: ${String(data.progress)}` : null,
-                    data.result_ref != null ? `Results: ${String(data.result_ref)}` : null,
-                    note,
-                ].filter(Boolean);
-                return textResult({ ...data, status_text: lines.join("\n") });
+                const statusText = note ? `${formatJobStatusText(job_id, data)}\n${note}` : formatJobStatusText(job_id, data);
+                return textResult({ ...data, status_text: statusText });
             }
-            return textResult(data);
+            return textResult({ ...data, status_text: formatJobStatusText(job_id, data) });
         }
         const data = await apiCall("GET", "/v1/jobs");
         return textResult(data);

package/dist/tools/results.js

@@ -1,27 +1,52 @@
 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"];
+import { apiCall, apiRawCall, textResult, tryAttachImage, pollUntilComplete, POLL_STAGE_MAX_MS } from "../shared.js";
+// Headline figures when present, best first: the combined overview (barsom parity),
+// then KL/EMD-vs-reference and the coarse/fine volume pair.
+const MESH_DEFAULT_FIGURES = ["combined", "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). |
+| image | Download one figure by filename (e.g. KL_ref.png, EMD_stepwise.pdf). |
+| render | Re-render the figures as publication PDFs (or SVG) on demand — PDFs are NOT generated by default. |
 
 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.
+FIGURES: Default job output is metrics + PNG previews, including a single combined.png overview. action=get inlines the combined headline plus KL_ref/EMD_ref/volume PNGs with captions; pass figures="all" for every PNG, "none" for metrics only, or a list of names.
+PDFs ON DEMAND: vector PDFs are not produced by default. Use action=render (format=pdf) once, then action=image to download each <name>.pdf. For an interactive browser use barmesh_results_explorer.
 NOT FOR: Submitting jobs.`, {
-        action: z.enum(["get", "image"]).describe("get: summary + figures; image: download one figure file"),
+        action: z.enum(["get", "image", "render"]).describe("get: summary + figures; image: download one figure file; render: re-render figures as PDF/SVG on demand"),
         job_id: z.string().describe("Job ID"),
-        filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.pdf)"),
+        filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.png or, after render, KL_ref.pdf)"),
+        format: z.enum(["pdf", "png", "svg"]).optional().describe("For action=render: output format to generate (default pdf). PNG previews already exist by default."),
         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;
+        const { action, job_id, filename, format, figures } = args;
+        if (action === "render") {
+            const fmt = format ?? "pdf";
+            const submit = (await apiCall("POST", "/v1/cfd/render", { job_id, format: fmt }));
+            const renderId = (submit.id ?? submit.job_id);
+            if (!renderId)
+                throw new Error("cfd render did not return a job id");
+            const poll = await pollUntilComplete(renderId, POLL_STAGE_MAX_MS);
+            if (poll.status === "failed") {
+                return textResult({ status: "failed", render_job_id: renderId, error: poll.error ?? "render failed" });
+            }
+            if (poll.status !== "completed") {
+                return textResult({ status: poll.status, render_job_id: renderId, note: `Still rendering; poll barmesh_jobs(action=status, job_id="${renderId}").` });
+            }
+            return textResult({
+                status: "completed",
+                render_job_id: renderId,
+                format: fmt,
+                suggested_next_step: `Figures rendered as ${fmt}. Download one with barmesh_results(action=image, job_id="${job_id}", filename="KL_ref.${fmt}"), or list filenames via barmesh_results(action=get, job_id="${job_id}").`,
+            });
+        }
         if (action === "image") {
             if (!filename)
                 throw new Error("barmesh_results(image) requires filename.");

package/dist/upload_hints.js

@@ -0,0 +1 @@
+export const GZIP_UPLOAD_HINT = "Try gzip: save as .csv.gz (often 2–3× smaller). The upload limit applies to the compressed file size on presigned/large uploads.";