@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. Default mesh_order sorts by ascending cell count and interleaves U/G (or similar) families when counts tie, so stepwise distances do not jump across topology families. The SOM features use the same staged pipeline as barsom training; optional transforms, normalize, normalization_methods, and row_range apply. Submit enqueues prepare_training_matrix on worker-io when staged; the proxy auto-polls prepare_job_id. Default defer_figures=true → cfd_finalize; barmesh_jobs(status) auto-polls finalize_job_id.
• barmesh_richardson — classical three-level Richardson extrapolation / Grid Convergence Index (GCI) on scalar quantities of interest. Prefer one topology family (all U or all G); mixed families return a topology_warning in the result summary.

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. barmesh_guide_workflow / barmesh_prepare_mesh_data also redact their API bodies to an upgrade stub when the key is not CFD-entitled (method/prep details are not returned). Contact Barivia to enable it.

Tools

| Tool | Purpose | |------|---------| | barmesh_guide_workflow | Workflow + tool map from the API (full text when CFD-entitled). Call first. | | barmesh_prepare_mesh_data | Mesh CSV recipe from the API (full text when CFD-entitled). | | 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 | Live MCP App (QE + panel TE) and/or headless monitor; always returns a standalone localhost URL + ui_delivery. | | 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; action=feature_divergences refreshes feature-plane KL/W1 (distinct from mesh SKL/EMD). | | barmesh_results_explorer | Interactive MCP App with a figure dropdown above the plot; always leads with a standalone localhost URL + ui_delivery. | | 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.
• Asymmetric mesh KL (KL_asymmetric.png): pairwise D_{KL}(P\\|Q) heatmap — above-diagonal coarse→fine, below-diagonal fine→coarse (meshes ordered coarse→fine). Distinct from feature-plane divergence_kl (component association).
• Live ΔKL in training monitor: panel SKL→ref mean/max curve (TE-panel sample) beside the hit-grid; SOM batch-step axis labels (not FLooP) for regular mesh_convergence jobs.
• 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

• Feature-plane divergences (0.8.1): Mesh jobs write divergence_kl (directed KL heatmap) / feature_divergences.json / weights.json (barsom-parallel). These measure association between SOM component planes — not mesh-vs-mesh fingerprint SKL/EMD (KL_ref, EMD_*). Refresh or add Wasserstein via barmesh_results(action=feature_divergences).
• UI delivery + mesh_order (0.7.3+ / 0.8.0 / 0.8.10+): App tools emit structured ui_delivery and always put the standalone viz URL first (hosts may advertise MCP Apps without mounting widgets). Env: BARIVIA_UI_DELIVERY (auto | apps | localhost | inline | text_only), BARIVIA_UI_PREFER_LOCALHOST=1 (opt-in localhost under auto), BARIVIA_VIZ_PORT. Default mesh_order interleaves U/G at tied cell counts; Richardson warns on mixed topology families.
• 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 | 17332 | Localhost port for standalone App pages. Defaults to 17332; override to pin. Busy port falls back to ephemeral. | | BARIVIA_UI_DELIVERY | auto | Client-capability override for App tools: auto | apps | localhost | inline | text_only. Responses always lead with a standalone localhost URL. | | BARIVIA_UI_PREFER_LOCALHOST | (off) | Set 1 to force localhost under auto even when the host advertises MCP Apps. |