@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. 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.

These complement, and do not replace, conventional numerical uncertainty analysis.

Install / configure

{
  "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 (or all_plus_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 / 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 / block until terminal (action=monitor) / list jobs. Auto-polls CFD prepare + finalize when applicable. Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. | | barmesh_training_monitor | Alias for barmesh_jobs(action=monitor) — server-side poll with throttled snapshots until terminal (preferred after submit). | | barmesh_results | Distances, convergence reading, and figures. action=get inlines headline PNGs; action=download saves artifacts to disk; action=render produces publication PDFs on demand. | | barmesh_results_explorer | Interactive MCP App with a figure dropdown above the plot (or standalone localhost page) to browse every figure after a job completes. | | barmesh_send_feedback | Send a short note or bug report to the Barivia team. |

Figures and progress (0.5.2)

• Combined overview (combined.png): barsom-style grid of all component planes on the trained SOM — the primary headline artifact. A separate overview_distances.png holds the KL/EMD diagnostic mosaic (all four distance panels). plot_vol_all_meshes.png shows volume fingerprints for every mesh in mesh_order.
• Learning curve: every job produces learning_curve.png (QE by epoch) for training quality inspection; listed in the results explorer dropdown.
• PDFs on demand: publication vector PDFs are NOT generated by default. Render them after completion with barmesh_results(action=render, format=pdf), then download with barmesh_results(action=download, folder=...) or action=image.
• Headless download: barmesh_results(action=download, folder=..., include_json=true) writes PNGs, summary.json, and text/CSV artifacts to a per-job subfolder (barsom parity).
• Explorer UX: figure <select> above the plot (no scrolling past metrics to switch figures). PNG previews inline; PDF/SVG offered for download when rendered.
• Uploads: large CSVs use presigned PUT with explicit Content-Length; .csv.gz / .tsv.gz accepted. Pin @barivia/[email protected] (clear ~/.npm/_npx if stale).
• Live progress: barmesh_training_monitor(job_id) or barmesh_jobs(action=monitor) block server-side with compact snapshots (phase, epoch, QE, panel/map TE, ETA, ordering_errors tail) until terminal or block_until_sec (default 900). Waits for cfd_finalize by default. One-shot: barmesh_jobs(action=status).

Migration notes

• Fixed-panel live TE (0.6.3 / barsom 0.20.4): mid-training TE uses a fixed evaluation panel (te_panel_size; te_inner_samples alias). Curves stay on panel TE; monitors show Panel TE and Map TE separately — no snap-to-map on the curve tail.
• barmesh_training_monitor (0.5.3): server-side blocking monitor with throttled snapshots — preferred after job submit instead of manual barmesh_jobs(status) loops. Equivalent to barmesh_jobs(action=monitor).
• send_feedback → barmesh_send_feedback (0.3.0): the feedback tool was renamed so it no longer collides with the @barivia/barsom-mcp tool of the same name when both servers are enabled in one client. Update any direct call sites; the behavior is unchanged.

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.

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 | |----------|---------|---------| | BARIVIA_API_KEY | (required) | Your Barivia API key. | | BARIVIA_API_URL | https://api.barivia.se | API base URL. | | BARIVIA_FETCH_TIMEOUT_MS | 60000 | Per-request timeout (raise for large uploads). | | BARIVIA_WORKSPACE_ROOT | workspace/cwd | Root for resolving relative file_path uploads. | | BARIVIA_ENFORCE_WORKSPACE_SANDBOX | 1 | Restrict uploads to the workspace; set 0 to allow absolute paths. | | BARIVIA_VIZ_PORT | ephemeral | Fixed localhost port for the barmesh_results_explorer standalone page (otherwise OS-assigned per session). |