@barivia/barmesh-mcp 0.3.1 → 0.4.1

package/README.md

@@ -13,10 +13,14 @@ 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. Submit enqueues **`cfd_prepare`** on worker-io
-  when needed; the proxy auto-polls `prepare_job_id` before the mesh job runs. Default
-  **`defer_figures=true`** → **`cfd_finalize`** on worker-io; **`barmesh_jobs(status)`** auto-polls
-  **`finalize_job_id`** when figures are deferred.
+  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)
+  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
+  auto-polls `prepare_job_id` before the mesh job runs. Default **`defer_figures=true`** →
+  **`cfd_finalize`** on worker-io; **`barmesh_jobs(status)`** auto-polls **`finalize_job_id`**
+  when figures are deferred.
 - **`barmesh_richardson`** — classical three-level Richardson extrapolation / Grid
   Convergence Index (GCI) on scalar quantities of interest.
 
@@ -48,7 +52,7 @@ 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). |
@@ -65,6 +69,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 |

package/dist/cfd_prepare.js

@@ -1,6 +1,8 @@
 import { pollUntilComplete } from "./shared.js";
 /**
- * When the API enqueues cfd_prepare for mesh-convergence, poll it before the mesh job runs.
+ * Mesh-convergence on a staged dataset enqueues a preprocessing job
+ * (prepare_training_matrix) first; the submit response carries its id as
+ * `prepare_job_id`. Poll it to completion before the mesh job runs.
  */
 export async function pollCfdPrepareIfPresent(data, label, timeoutMs = 600_000) {
     const prepareJobId = data.prepare_job_id;
@@ -8,10 +10,10 @@ export async function pollCfdPrepareIfPresent(data, label, timeoutMs = 600_000)
         return null;
     const poll = await pollUntilComplete(prepareJobId, timeoutMs);
     if (poll.status === "failed") {
-        throw new Error(`${label}: cfd_prepare job ${prepareJobId} failed: ${poll.error ?? "unknown error"}`);
+        throw new Error(`${label}: data preparation job ${prepareJobId} failed: ${poll.error ?? "unknown error"}`);
     }
     if (poll.status !== "completed") {
-        throw new Error(`${label}: cfd_prepare job ${prepareJobId} did not complete (status=${poll.status})`);
+        throw new Error(`${label}: data preparation job ${prepareJobId} did not complete (status=${poll.status})`);
     }
     return prepareJobId;
 }

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.3.1";
+export const CLIENT_VERSION = "0.4.1";
 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,27 +42,56 @@ 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(() => { });
     }
 }
 // ---------------------------------------------------------------------------

package/dist/tools/cfd.js

@@ -27,6 +27,10 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         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)"),
+        transforms: z.record(z.enum(["log", "log1p", "log10", "sqrt", "square", "abs", "invert", "none"])).optional().describe("Per-feature transform applied before normalization (e.g. log1p to compress k/epsilon/omega). Same preprocessing engine as barsom training."),
+        normalize: z.union([z.enum(["all", "auto", "mad", "sigmoidal", "sepd"]), z.array(z.string())]).optional().describe("Normalization mode for SOM features (default auto = joint z-score of non-cyclic features). Use mad for heavy-tailed channels."),
+        normalization_methods: z.record(z.enum(["zscore", "mad", "sigmoidal", "sepd", "none"])).optional().describe("Per-feature normalization override; keys must be in feature_columns."),
+        row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional().describe("1-based inclusive [start, end] row slice applied during preprocessing (and to mesh labels / cell volumes)."),
         label: z.string().optional().describe("Optional job label"),
     }, async (args) => {
         const { dataset_id, label, ...rest } = args;

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/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.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barmesh-mcp",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
   "keywords": [
     "mcp",