@barivia/barsom-mcp 0.7.6 → 0.7.12

package/README.md

@@ -1,10 +1,12 @@
 # @barivia/barsom-mcp
 
-MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. **`guide_barsom_workflow`** is the canonical bootstrap: it returns how the proxy works (env, tool map, async polling, training modes) and the step-by-step SOP. Core tools are `datasets`, `jobs` (`train_map`, `train_siom_map`, `train_floop_siom`; `train_floop_chain` is deprecated), `results`, and `inference`. **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer` / `explore_map`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results.
+MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. **`guide_barsom_workflow`** is the canonical bootstrap: it fetches **`GET /v1/docs/workflow`** (authenticated) and returns tier-scoped text — proxy model, tool map, async rules, training modes allowed for your key, and step-by-step SOP. If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `jobs` (`train_map`, `train_siom_map`, `train_floop_siom` where entitled; `train_floop_chain` is deprecated), `results`, and `inference`. **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer` / `explore_map`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results.
 
 ## Installation
 
-No install step needed. MCP clients run it via `npx`:
+Published on the **public npm registry** as **`@barivia/barsom-mcp`**. No GitHub token or scoped `.npmrc` is required for installs.
+
+MCP clients typically run it with **`npx`** (downloads on first use):
 
 ```json
 {
@@ -21,7 +23,11 @@ No install step needed. MCP clients run it via `npx`:
 }
 ```
 
-This is the standard pattern for MCP servers distributed as npm packages (same as `firecrawl-mcp`, `@paypal/mcp`, etc.).
+**Verify:** `npm view @barivia/barsom-mcp version`
+
+**Also available:** hosted HTTP MCP at **`https://mcp.barivia.se/mcp`** (same API key; no npm) for clients that support remote MCP.
+
+**Future:** A **private npm org** scoped package is an option later (paid npm teams/orgs; users authenticate with npm, usually simpler than GitHub Packages for pure npm consumers).
 
 ## Environment Variables
 
@@ -30,15 +36,21 @@ This is the standard pattern for MCP servers distributed as npm packages (same a
 | `BARIVIA_API_KEY` | Yes | -- | API key (starts with `bv_`) |
 | `BARIVIA_API_URL` | No | `https://api.barivia.se` | API base URL |
 | `BARIVIA_WORKSPACE_ROOT` | No | `process.cwd()` or `PWD` | Directory for relative `file_path` and `save_to_disk`. In Cursor MCP, `process.cwd()` is often the MCP install dir — add `BARIVIA_WORKSPACE_ROOT` to your MCP config `env` with your project path (e.g. `/home/user/myproject`). Absolute paths and `file://` URIs work without it. |
+| `BARIVIA_FETCH_TIMEOUT_MS` | No | `30000` | Per-request HTTP timeout (ms) to the API. Increase (e.g. `120000`) on slow networks or when the API does long-running work. Large dataset uploads use a separate longer timeout internally. |
+| `BARIVIA_VIZ_PORT` | No | OS-assigned | When the client has no MCP Apps support, the proxy may start a local viz server on `127.0.0.1`; set a fixed port if you need stable bookmark URLs. |
 
 Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` / `BARSOM_WORKSPACE_ROOT` are also accepted as fallbacks.
 
+**Supported stack:** Node **18+** (see `engines` in `package.json`). Built with `@modelcontextprotocol/sdk` **^1.x** — if a major MCP client upgrade breaks tools, check SDK release notes alongside this package version.
+
+**Local viz fallback:** If the IDE does not advertise MCP Apps, the proxy starts an HTTP server bound to **127.0.0.1** only (not exposed to the LAN). It serves built-in HTML for training prep / monitor / results explorer and proxies read-only API calls with your existing API key. Responses may include `http://127.0.0.1:<port>/viz/...` links. Browser `Access-Control-Allow-Origin: *` applies only to that localhost origin so the embedded pages can load data.
+
 ## Tools (14 registrations)
 
 All multi-action tools follow the `datasets` pattern: a required `action` enum routes to the correct operation.
 
 ### `guide_barsom_workflow`
-Call at the **start of mapping work** (or when the user asks what the MCP can do). Returns **proxy and capabilities** (stdio → REST, `BARIVIA_*` env, tool map, async contract, SOM vs SIOM vs FLooP-SIOM, optional MCP Apps) and the **Workflow (SOP)**. No parameters.
+Call at the **start of mapping work** (or when the user asks what the MCP can do). Loads full orientation from the API (`GET /v1/docs/workflow`); content reflects **your plan** (`allowed_job_types`). No parameters. **`training_guidance`** uses `GET /v1/training/config` with the same entitlement filtering.
 
 ### `datasets(action)`
 
@@ -112,7 +124,7 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 | `explore_map` | Legacy alias of `results_explorer` |
 | `_fetch_figure` | Internal helper for Results Explorer (single figure as image) |
 
-When the client does not advertise MCP Apps support, the proxy starts **`viz-server`** on `127.0.0.1` and tool responses can include `http://localhost:PORT/viz/...` links.
+When the client does not advertise MCP Apps support, the proxy starts **`viz-server`** on **`127.0.0.1`** (localhost-only). Tool responses can include `http://127.0.0.1:PORT/viz/...` links. See **Local viz fallback** under Environment Variables.
 
 ### `send_feedback`
 Submit feedback or feature requests (max 1400 characters, ~190 words).
@@ -138,6 +150,17 @@ The proxy implements the MCP stdio transport locally and translates tool calls i
 MCP Client (Cursor/Claude) ←stdio→ @barivia/barsom-mcp ←HTTPS→ api.barivia.se
 ```
 
+## Troubleshooting
+
+| Symptom | What to check |
+|--------|----------------|
+| `401` / invalid key | `BARIVIA_API_KEY` in MCP config; regenerate or verify at [barivia.se](https://barivia.se). Error text includes a **request id** for support. |
+| Request timed out | Raise `BARIVIA_FETCH_TIMEOUT_MS` (e.g. `120000`). Large uploads already use an extended timeout. |
+| `Path must be within the workspace` / upload can’t find file | Set `BARIVIA_WORKSPACE_ROOT` to your project directory, or use an absolute path / `file:///...` URI. |
+| Job stuck “running” | Poll `jobs(action=status)` every 10–15s; large grids or FLooP-SIOM can take several minutes—not an MCP error. |
+| `429` | Rate limit—wait and retry. |
+| Malformed MCP / client errors | Ensure nothing writes to **stdout** except MCP JSON-RPC (the proxy logs API traffic to **stderr** only). |
+
 ## Development
 
 ```bash
@@ -155,22 +178,24 @@ BARIVIA_API_URL=http://localhost:8080 BARIVIA_API_KEY=bv_test_key npm run dev
 
 ## Publishing
 
-Published to npm via GitHub Actions on tag `mcp-proxy-v*`:
+The npm tarball is **runtime-only**: minified `dist/**/*.js`, the three embedded view HTML files, plus `package.json` and `README.md`. It does **not** include TypeScript source, `.map`, `.d.ts`, tests, or `src/`. CI runs `build:publish` (clean `dist`, compile without source maps, views, minify entrypoint) via `prepublishOnly`.
+
+Published to **registry.npmjs.org** via GitHub Actions when you push tag `mcp-proxy-v*` (version in `package.json` must match the tag, e.g. tag `mcp-proxy-v0.7.10` for version `0.7.10`):
 
 ```bash
-git tag mcp-proxy-v0.1.0
-git push origin mcp-proxy-v0.1.0
+git tag mcp-proxy-v0.7.10
+git push origin mcp-proxy-v0.7.10
 ```
 
-Requires `NPM_TOKEN` secret in GitHub repository settings.
+The repository needs a **`NPM_TOKEN`** secret (npm automation/publish token with access to the `@barivia` scope).
 
 ### Checking local vs published
 
-From the platform root, compare the current build to the published npm package (same version in `package.json`):
+From the platform root:
 
 ```bash
 cd barivia-platform
 bash scripts/check-mcp-proxy-publish.sh
 ```
 
-Exit 0 = local matches published. Exit 1 = local differs (bump version and publish to update `npx`). Use `VERBOSE=1` for a full file diff.
+Compares local `build:publish` output to the tarball on **public npm**. Exit 0 = match; exit 1 = diff. `VERBOSE=1` for a full `dist/` diff.

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as a,registerAppResource as i,RESOURCE_MIME_TYPE as r}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as s,apiCall as c,apiRawCall as l,loadViewHtml as p,setVizPort as d,setClientSupportsMcpApps as m}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as g,JOBS_DESCRIPTION_BASE as f}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as y}from"./tools/account.js";import{registerInferenceTool as w}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as k}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as O}from"./tools/training_monitor.js";s||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const P=new e({name:"analytics-engine",version:"0.7.6",instructions:"# Barivia Mapping Analytics Engine\n\nYou have access to a mapping (Self-Organizing Map) analytics platform that projects high-dimensional data onto a 2D grid, revealing clusters, gradients, and anomalies.\n\n## Typical workflow\n\n1. **Upload** → `datasets(action=upload)` — ingest a CSV\n2. **Preview** → `datasets(action=preview)` — inspect columns, detect cyclics/datetimes; add derived columns with `datasets(action=add_expression)` if needed\n3. **Train** → choose one:\n   - `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM\n   - `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization\n   - `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM (default topology=free / CHL; optional topology=chain)\n   Returns a job_id; poll `jobs(action=status, job_id=...)` until completed\n4. **Analyze** → `results(action=get)` — view metrics and figures (grid-map or FLooP-specific; no separate analyze tool)\n5. **Compare / Export / Inference** → `jobs(action=compare)`, `results(download)`, `inference` (predict/enrich/compare/report)\n\nFor **proxy model, full tool map, async rules, training modes, and optional MCP App UIs**, call `guide_barsom_workflow` first—it is the ground-truth bootstrap (this section stays short on purpose).\n\n## Tool categories\n\n| Category | Tools |\n|----------|-------|\n| Data management | `datasets` (upload/preview/list/subset/delete/add_expression) |\n| Jobs & training | `jobs` (train_map/train_siom_map/train_floop_siom/status/list/compare/cancel/delete/batch_predict; deprecated alias train_floop_chain) |\n| Results | `results` (get/recolor/download/export/transition_flow) |\n| Inference & export | `inference` (predict/enrich/compare/report/project_columns) |\n| Account | `account` (status/request_compute/compute_status/release_compute/history/add_funds) |\n| Utility | `guide_barsom_workflow`, `training_guidance`, `training_prep`, `results_explorer`, `training_monitor`, `send_feedback` |\n\n## Optional rich UI (MCP Apps)\n\n**None of these are required** to train, poll, or read results—`jobs` + `results` + text output are enough. **Recommended** for learning: `training_prep` (preparation), `results_explorer` (postprocessing). **Optional:** `training_monitor(job_id)` for visual progress; `jobs(action=status)` is sufficient without it.\n\n## Async job pattern\n\nMost operations are async. Every tool that submits a job either:\n- **Auto-polls** (results(recolor/transition_flow), inference) — waits up to the action-specific timeout then returns or gives a job_id for manual polling\n- **Returns immediately** (jobs(action=train_map/train_siom_map/train_floop_siom)) — always requires manual `jobs(action=status, job_id=...)` polling (`train_floop_chain` is a deprecated alias for `train_floop_siom`)\n\n**Do not tell the user a job failed because it is still running.** If a tool returns a job_id, poll `jobs(action=status)` every 10–15 seconds. Grid-map training takes 30s–10min depending on grid size and dataset; FLooP-SIOM jobs can also take several minutes for larger `max_nodes` or `thorough` runs.\nFor FLooP-SIOM, `max_nodes` is a total node budget, not a grid side length. If omitted, the backend uses a dataset-size heuristic; reduce `max_nodes` before increasing `effort` when coverage looks collapsed.\n\n## Credit and cost\n\nJobs consume compute credits. Inference jobs are priced the same as projection jobs. Check `account(action=status)` to see the remaining balance and queue depth before starting large jobs.\n\n## Key constraints\n\n- For parameter guidance (grid, epochs, presets, when to use standard SOM vs SIOM vs FLooP-SIOM), use `training_guidance` or `prepare_training` — do not guess.\n- Column names are case-sensitive; always match exactly what `datasets(action=preview)` returns\n- Uploads may include text/categorical columns, but the default training path is still numeric/cyclic/temporal. If a categorical column truly matters, use explicit `categorical_features` for simple baseline encoding.\n- `predict` input must match the model's supported inference contract. Numeric/batch predict expects the training feature set; single-row stateless inference can also accept raw categorical strings for baseline `categorical_features` models."});i(P,b,b,{mimeType:r},async()=>{const e=await p("results-explorer");return{contents:[{uri:b,mimeType:r,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),i(P,k,k,{mimeType:r},async()=>{const e=await p("training-prep");return{contents:[{uri:k,mimeType:r,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),i(P,O,O,{mimeType:r},async()=>{const e=await p("training-monitor");return{contents:[{uri:O,mimeType:r,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),h(P),I(P),M(P),j(P),u(P),g(P,f),_(P),y(P),w(P),v(P),x(P),P.prompt("info","Overview of the Barivia Mapping MCP: capabilities, workflow, tools, analysis types, and tips. Use when the user asks what this MCP can do, how to get started, or what the process is.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Inform the user using this overview:","","**What it is:** Barivia MCP connects you to a mapping analytics engine that learns a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.","","**Orientation:** Call `guide_barsom_workflow` first for proxy model, full tool list, async rules, training modes, and optional MCP App UIs (defer long-form detail there).","","**Core workflow:**","0. **Prepare** — CSV with header; no NaNs in used columns; numeric and datetime columns are the default training path; raw categoricals can stay in the CSV but should usually be excluded unless you explicitly use simple `categorical_features` encoding","1. **Upload** — `datasets(action=upload)` with a CSV file path or inline data","2. **Preview** — `datasets(action=preview)` to inspect columns, stats, and detect cyclic/datetime fields","3. **Prepare** — use the `prepare_training` prompt for a guided checklist (column selection, transforms, cyclic encoding, feature weights, grid sizing)","4. **Train** — choose one: `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM, `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization, or `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM (default topology=free / CHL; optional topology=chain). Use `preset=quick|standard|refined|high_res` for standard or SIOM map defaults","5. **Monitor** — `jobs(action=status, job_id=...)` every 10–15s until complete (required path). Optional: `training_monitor(job_id=...)` for a visual panel—not required.","6. **View and interpret** — `results(action=get)` returns metrics and figures. Grid-map jobs show U-matrix, component planes, and clusters; FLooP-SIOM jobs show structure/coverage, occupation/profile views, and metrics. Optional: `results_explorer(job_id=...)` for interactive browsing; `results(action=get)` alone is enough.","7. **Feedback** — Ask the user if they'd like to submit feedback via `send_feedback` based on their experience.","8. **Iterate** — `results(action=recolor)` to change colormap, `jobs(action=compare)` to compare hyperparameters, `inference(action=project_columns)` to overlay dataset columns onto the map","","All visualizations and metrics come from `results(action=get)`; use figures=all or export_type=... for more.","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `datasets(action=add_expression)` — create computed columns from expressions (ratios, differences, etc.)","- `inference(action=project_columns)` — overlay one or more dataset columns onto a trained map (component planes)","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, hsv, twilight, etc.) can be set at training or changed later via results(action=recolor).","","**Key tools:** datasets, jobs (train_map/train_siom_map/train_floop_siom/status/list/...), results, inference (predict/enrich/compare/project_columns/report), account, guide_barsom_workflow, training_guidance, training_prep, results_explorer, training_monitor.","","**Optional rich UI:** `training_prep` and `results_explorer` are recommended for prep and postprocessing; `training_monitor` is optional. None are required—`jobs` + `results` complete the workflow.","","**Tips:**","- For the full step-by-step SOP and capabilities text, use the `guide_barsom_workflow` tool","- Always `datasets(action=preview)` before training to understand your data","- Use `account(action=status)` to check GPU availability, queue depth, and plan limits before large jobs","- Start with `preset=quick` for fast iteration, then `refined` for publication quality","- For time-series data, consider `transition_flow` after training","","Keep the reply scannable with headers and bullet points."].join("\n")}}]})),P.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling jobs(action=train_map), jobs(action=train_siom_map), or jobs(action=train_floop_siom). Walks through data inspection, column selection, transforms, cyclic/temporal features, weighting, subsetting, and grid sizing.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{let t=`Please run datasets(action=preview, dataset_id="${e}") to inspect columns, then datasets(action=analyze, dataset_id="${e}") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id="${e}", ...) for a standard fixed-grid SOM, jobs(action=train_siom_map, dataset_id="${e}", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id="${e}", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).`;try{const o=await c("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}});const C=new t;(async function(){try{const e=await n(c,l,p);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=P.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=a(t);m(!!o?.mimeTypes?.includes(r))},await P.connect(C)})().catch(console.error);
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as a,registerAppResource as i,RESOURCE_MIME_TYPE as r}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as s,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as d,setClientSupportsMcpApps as m}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as f,JOBS_DESCRIPTION_BASE as g}from"./tools/jobs.js";import{registerResultsTool as h}from"./tools/results.js";import{registerExploreMapTool as _,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as y}from"./tools/account.js";import{registerInferenceTool as w}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as k}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as P}from"./tools/training_monitor.js";s||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const O=new e({name:"analytics-engine",version:"0.7.10",instructions:"# Barivia Mapping Analytics Engine\n\nYou have access to a mapping (Self-Organizing Map) analytics platform that projects high-dimensional data onto a 2D grid, revealing clusters, gradients, and anomalies.\n\n## Typical workflow\n\n1. **Upload** → `datasets(action=upload)` — ingest a CSV\n2. **Preview** → `datasets(action=preview)` — inspect columns, detect cyclics/datetimes; add derived columns with `datasets(action=add_expression)` if needed\n3. **Train** → choose one:\n   - `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM\n   - `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization\n   - `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM when the plan includes all_algorithms (Premium or Enterprise; default topology=free / CHL; optional topology=chain)\n   Returns a job_id; poll `jobs(action=status, job_id=...)` until completed\n4. **Analyze** → `results(action=get)` — view metrics and figures (grid-map or FLooP-specific; no separate analyze tool)\n5. **Compare / Export / Inference** → `jobs(action=compare)`, `results(download)`, `inference` (predict/enrich/compare/report)\n\nFor **proxy model, full tool map, async rules, training modes (tier-scoped), and optional MCP App UIs**, call `guide_barsom_workflow` first—it loads the ground-truth bootstrap from the API (`GET /v1/docs/workflow`; this section stays short on purpose).\n\n## Tool categories\n\n| Category | Tools |\n|----------|-------|\n| Data management | `datasets` (upload/preview/list/subset/delete/add_expression) |\n| Jobs & training | `jobs` (train_map/train_siom_map/train_floop_siom/status/list/compare/cancel/delete/batch_predict; deprecated alias train_floop_chain) |\n| Results | `results` (get/recolor/download/export/transition_flow) |\n| Inference & export | `inference` (predict/enrich/compare/report/project_columns) |\n| Account | `account` (status/request_compute/compute_status/release_compute/history/add_funds) |\n| Utility | `guide_barsom_workflow`, `training_guidance`, `training_prep`, `results_explorer`, `training_monitor`, `send_feedback` |\n\n## Optional rich UI (MCP Apps)\n\n**None of these are required** to train, poll, or read results—`jobs` + `results` + text output are enough. **Recommended** for learning: `training_prep` (preparation), `results_explorer` (postprocessing). **Optional:** `training_monitor(job_id)` for visual progress; `jobs(action=status)` is sufficient without it.\n\n## Async job pattern\n\nMost operations are async. Every tool that submits a job either:\n- **Auto-polls** (results(recolor/transition_flow), inference) — waits up to the action-specific timeout then returns or gives a job_id for manual polling\n- **Returns immediately** (jobs(action=train_map/train_siom_map/train_floop_siom)) — always requires manual `jobs(action=status, job_id=...)` polling (`train_floop_chain` is a deprecated alias for `train_floop_siom`)\n\n**Do not tell the user a job failed because it is still running.** If a tool returns a job_id, poll `jobs(action=status)` every 10–15 seconds. Grid-map training takes 30s–10min depending on grid size and dataset; FLooP-SIOM jobs can also take several minutes for larger `max_nodes` or `thorough` runs.\nFor FLooP-SIOM, `max_nodes` is a total node budget, not a grid side length. If omitted, the backend uses a dataset-size heuristic; reduce `max_nodes` before increasing `effort` when coverage looks collapsed.\n\n## Credit and cost\n\nJobs consume compute credits. Inference jobs are priced the same as projection jobs. Check `account(action=status)` to see the remaining balance and queue depth before starting large jobs.\n\n## Key constraints\n\n- For parameter guidance (grid, epochs, presets, when to use standard SOM vs SIOM vs FLooP-SIOM), use `training_guidance` or `prepare_training` — do not guess.\n- Column names are case-sensitive; always match exactly what `datasets(action=preview)` returns\n- Uploads may include text/categorical columns, but the default training path is still numeric/cyclic/temporal. If a categorical column truly matters, use explicit `categorical_features` for simple baseline encoding.\n- `predict` input must match the model's supported inference contract. Numeric/batch predict expects the training feature set; single-row stateless inference can also accept raw categorical strings for baseline `categorical_features` models."});i(O,b,b,{mimeType:r},async()=>{const e=await p("results-explorer");return{contents:[{uri:b,mimeType:r,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),i(O,k,k,{mimeType:r},async()=>{const e=await p("training-prep");return{contents:[{uri:k,mimeType:r,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),i(O,P,P,{mimeType:r},async()=>{const e=await p("training-monitor");return{contents:[{uri:P,mimeType:r,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),_(O),I(O),M(O),j(O),u(O),f(O,g),h(O),y(O),w(O),v(O),x(O),O.prompt("info","Overview of the Barivia Mapping MCP: capabilities, workflow, tools, analysis types, and tips. Use when the user asks what this MCP can do, how to get started, or what the process is.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Inform the user using this overview:","","**What it is:** Barivia MCP connects you to a mapping analytics engine that learns a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.","","**Orientation:** Call `guide_barsom_workflow` first for proxy model, full tool list, async rules, training modes, and optional MCP App UIs (defer long-form detail there).","","**Core workflow:**","0. **Prepare** — CSV with header; no NaNs in used columns; numeric and datetime columns are the default training path; raw categoricals can stay in the CSV but should usually be excluded unless you explicitly use simple `categorical_features` encoding","1. **Upload** — `datasets(action=upload)` with a CSV file path or inline data","2. **Preview** — `datasets(action=preview)` to inspect columns, stats, and detect cyclic/datetime fields","3. **Prepare** — use the `prepare_training` prompt for a guided checklist (column selection, transforms, cyclic encoding, feature weights, grid sizing)","4. **Train** — choose one: `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM, `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization, or `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM only on Premium / Enterprise (`all_algorithms`; default topology=free / CHL; optional topology=chain). Use `preset=quick|standard|refined|high_res` for standard or SIOM map defaults","5. **Monitor** — `jobs(action=status, job_id=...)` every 10–15s until complete (required path). Optional: `training_monitor(job_id=...)` for a visual panel—not required.","6. **View and interpret** — `results(action=get)` returns metrics and figures. Grid-map jobs show U-matrix, component planes, and clusters; FLooP-SIOM jobs show structure/coverage, occupation/profile views, and metrics. Optional: `results_explorer(job_id=...)` for interactive browsing; `results(action=get)` alone is enough.","7. **Feedback** — Ask the user if they'd like to submit feedback via `send_feedback` based on their experience.","8. **Iterate** — `results(action=recolor)` to change colormap, `jobs(action=compare)` to compare hyperparameters, `inference(action=project_columns)` to overlay dataset columns onto the map","","All visualizations and metrics come from `results(action=get)`; use figures=all or export_type=... for more.","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `datasets(action=add_expression)` — create computed columns from expressions (ratios, differences, etc.)","- `inference(action=project_columns)` — overlay one or more dataset columns onto a trained map (component planes)","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, hsv, twilight, etc.) can be set at training or changed later via results(action=recolor).","","**Key tools:** datasets, jobs (train_map/train_siom_map/train_floop_siom/status/list/...), results, inference (predict/enrich/compare/project_columns/report), account, guide_barsom_workflow, training_guidance, training_prep, results_explorer, training_monitor.","","**Optional rich UI:** `training_prep` and `results_explorer` are recommended for prep and postprocessing; `training_monitor` is optional. None are required—`jobs` + `results` complete the workflow.","","**Tips:**","- For the full step-by-step SOP and capabilities text (from the API, scoped to your plan), use the `guide_barsom_workflow` tool","- Always `datasets(action=preview)` before training to understand your data","- Use `account(action=status)` to check GPU availability, queue depth, and plan limits before large jobs","- Start with `preset=quick` for fast iteration, then `refined` for publication quality","- For time-series data, consider `transition_flow` after training","","Keep the reply scannable with headers and bullet points."].join("\n")}}]})),O.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling jobs(action=train_map), jobs(action=train_siom_map), or jobs(action=train_floop_siom) when entitled. Walks through data inspection, column selection, transforms, cyclic/temporal features, weighting, subsetting, and grid sizing.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{let t=`Please run datasets(action=preview, dataset_id="${e}") to inspect columns, then datasets(action=analyze, dataset_id="${e}") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id="${e}", ...) for a standard fixed-grid SOM, jobs(action=train_siom_map, dataset_id="${e}", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id="${e}", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).`;try{const o=await l("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}});const C=new t;(async function(){try{const e=await n(l,c,p);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=O.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=a(t);m(!!o?.mimeTypes?.includes(r))},await O.connect(C)})().catch(console.error);

package/dist/shared.js

@@ -14,6 +14,12 @@ 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]);
+/** User-facing links; keep aligned with barivia.se / api.barivia.se. */
+export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
+/** Poll window for datasets(add_expression) / derive jobs (server-side work can exceed 30s). */
+export const POLL_DERIVE_MAX_MS = 120_000;
+/** Large CSV uploads may exceed default FETCH_TIMEOUT_MS. */
+export const UPLOAD_DATASET_TIMEOUT_MS = 180_000;
 // ---------------------------------------------------------------------------
 // Shared state (mutable)
 // ---------------------------------------------------------------------------
@@ -149,10 +155,50 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
         throw new Error(`File not accessible. For relative paths, set BARIVIA_WORKSPACE_ROOT in your MCP config. Or use an absolute path or file:// URI.`);
     }
 }
-// ---------------------------------------------------------------------------
-// API helpers
-// ---------------------------------------------------------------------------
-export async function apiCall(method, path, body, extraHeaders) {
+/** User-visible API error line (includes request id for support). Exported for tests. */
+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 for this operation (plan or permissions).${accountHint}`
+                : status === 402
+                    ? ` Credits or subscription may be insufficient — see ${PUBLIC_SITE_ORIGIN}.`
+                    : 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
+                                ? " Rate limit exceeded — wait a moment and retry."
+                                : 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;
+}
+/**
+ * @param requestTimeoutMs Optional per-request timeout (default `BARIVIA_FETCH_TIMEOUT_MS`).
+ */
+export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs) {
     const url = `${API_URL}${path}`;
     const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
     const requestId = Math.random().toString(36).slice(2, 10);
@@ -167,6 +213,7 @@ export async function apiCall(method, path, body, extraHeaders) {
         serializedBody =
             contentType === "application/json" ? JSON.stringify(body) : String(body);
     }
+    const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     const t0 = Date.now();
     console.error(`${new Date().toISOString()} API -> ${method} ${path} rid=${requestId}`);
     let lastError;
@@ -176,7 +223,7 @@ export async function apiCall(method, path, body, extraHeaders) {
                 method,
                 headers,
                 body: serializedBody,
-            });
+            }, effectiveTimeout);
             const text = await resp.text();
             if (!resp.ok) {
                 if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
@@ -184,23 +231,7 @@ export async function apiCall(method, path, body, extraHeaders) {
                     continue;
                 }
                 console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
-                const errBody = (() => { try {
-                    return JSON.parse(text);
-                }
-                catch {
-                    return null;
-                } })();
-                const detail = errBody?.error ?? text;
-                const hint = resp.status === 400 ? " Check parameter types and required fields."
-                    : resp.status === 401 ? " Check BARIVIA_API_KEY in your environment or regenerate at https://barivia.com/dashboard."
-                        : resp.status === 404 ? " The resource may not exist or may have been deleted."
-                            : resp.status === 409 ? " The job may not be in the expected state."
-                                : resp.status === 429 ? " Rate limit exceeded — wait a moment and retry."
-                                    : "";
-                const code = errBody?.error_code ? ` (error_code: ${errBody.error_code})` : "";
-                const err = new Error(`${detail}${code}${hint}`);
-                err.httpStatus = resp.status;
-                throw err;
+                throwApiError(resp.status, text, requestId);
             }
             console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
             return JSON.parse(text);
@@ -211,27 +242,38 @@ export async function apiCall(method, path, body, extraHeaders) {
                 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 in your MCP env (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(path) {
+export async function apiRawCall(path, requestTimeoutMs) {
     const url = `${API_URL}${path}`;
+    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}` },
-            });
+                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;
                 }
-                throw new Error(`Request failed with status ${resp.status}`);
+                const text = await resp.text();
+                throwApiError(resp.status, text, requestId);
             }
             const arrayBuf = await resp.arrayBuffer();
             return {
@@ -245,6 +287,11 @@ export async function apiRawCall(path) {
                 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 large images. (request id: ${requestId})`);
+            }
             throw err;
         }
     }
@@ -286,25 +333,34 @@ export async function pollUntilComplete(jobId, maxWaitMs = 30_000, intervalMs =
     }
     return { status: "timeout" };
 }
-/** Fetch training guidance from API (used by training_guidance tool). Domain knowledge returned when asked; valid license required. */
+function formatGuidanceScopeSuffix(config) {
+    const scope = config?.guidance_scope;
+    const ajt = scope?.allowed_job_types;
+    if (Array.isArray(ajt) && ajt.length > 0) {
+        return "\n\n(Your plan allows these training job types: " + ajt.map(String).join(", ") + ")";
+    }
+    return "";
+}
+/** Fetch training guidance from API (used by training_guidance tool). Domain knowledge returned when asked; valid license required. Hints are filtered by plan (allowed_job_types). */
 export async function fetchTrainingGuidanceFromApi() {
     try {
         const config = (await apiCall("GET", "/v1/training/config"));
+        const scopeSuffix = formatGuidanceScopeSuffix(config);
         const presetDesc = config?.preset_descriptions;
         const presetBlock = Array.isArray(presetDesc) && presetDesc.length > 0
             ? "Presets: " + presetDesc.join(" | ") + "\n\n"
             : "";
         const hints = config?.training_hints;
         if (Array.isArray(hints) && hints.length > 0) {
-            return presetBlock + "Parameter guidance (from API):\n- " + hints.join("\n- ");
+            return presetBlock + "Parameter guidance (from API):\n- " + hints.join("\n- ") + scopeSuffix;
         }
         const pg = config?.parameter_guidance;
         if (pg && typeof pg === "object") {
             const lines = Object.entries(pg).map(([k, v]) => `${k}: ${v}`);
-            return presetBlock + "Parameter guidance (from API):\n- " + lines.join("\n- ");
+            return presetBlock + "Parameter guidance (from API):\n- " + lines.join("\n- ") + scopeSuffix;
         }
         if (presetBlock)
-            return presetBlock + "No additional parameter guidance in config.";
+            return presetBlock + "No additional parameter guidance in config." + scopeSuffix;
     }
     catch (e) {
         if (e?.httpStatus === 401 || e?.httpStatus === 403)
@@ -313,6 +369,25 @@ export async function fetchTrainingGuidanceFromApi() {
     }
     return "No parameter guidance available.";
 }
+/**
+ * Full MCP workflow + bootstrap text from API (tier-scoped). Null on network/parse failure (caller may show offline stub).
+ * Re-throws 401/403 so the MCP host surfaces auth errors.
+ */
+export async function fetchWorkflowGuideFromApi() {
+    try {
+        const data = (await apiCall("GET", "/v1/docs/workflow"));
+        const md = data?.workflow_markdown;
+        if (typeof md === "string" && md.trim().length > 0) {
+            return md.trim();
+        }
+        return null;
+    }
+    catch (e) {
+        if (e?.httpStatus === 401 || e?.httpStatus === 403)
+            throw e;
+        return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Image helpers
 // ---------------------------------------------------------------------------
@@ -509,4 +584,3 @@ export async function loadViewHtml(viewName) {
     }
     return null;
 }
-//# sourceMappingURL=shared.js.map

package/dist/tools/account.js

@@ -163,4 +163,3 @@ bash scripts/manage-credits.sh add <org_id> <amount_usd>` }]
         };
     });
 }
-//# sourceMappingURL=account.js.map

package/dist/tools/datasets.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs/promises";
 import { z } from "zod";
-import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, } from "../shared.js";
 export function registerDatasetsTool(server) {
     server.tool("datasets", `Manage datasets: upload, preview, list, subset, add_expression, or delete.
 
@@ -110,7 +110,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const data = (await apiCall("POST", "/v1/datasets", body, {
                 "X-Dataset-Name": name,
                 "Content-Type": "text/csv",
-            }));
+            }, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null)
                 data.suggested_next_step = `Suggested next step: datasets(action=preview, dataset_id=${id}) to inspect columns before training.`;
@@ -284,7 +284,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 body.options = options;
             const data = (await apiCall("POST", `/v1/datasets/${dataset_id}/derive`, body));
             const deriveJobId = data.id;
-            const poll = await pollUntilComplete(deriveJobId);
+            const poll = await pollUntilComplete(deriveJobId, POLL_DERIVE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${deriveJobId}`));
                 const summary = (results.summary ?? {});
@@ -341,4 +341,3 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
         throw new Error("Invalid action");
     });
 }
-//# sourceMappingURL=datasets.js.map

package/dist/tools/explore_map.js

@@ -194,4 +194,3 @@ export function registerExploreMapTool(server) {
         }
     });
 }
-//# sourceMappingURL=explore_map.js.map

package/dist/tools/feedback.js

@@ -27,4 +27,3 @@ export function registerFeedbackTool(server) {
         }
     });
 }
-//# sourceMappingURL=feedback.js.map

package/dist/tools/guide_barsom.js

@@ -1,76 +1,19 @@
-const BOOTSTRAP = `## Proxy and capabilities
+import { fetchWorkflowGuideFromApi } from "../shared.js";
+/** Minimal orientation when the API is unreachable; full SOP lives on GET /v1/docs/workflow. */
+const OFFLINE_STUB = `## Offline / API unavailable
 
-**What this MCP is:** A local stdio server that forwards tool calls to the Barivia REST API. Configure \`BARIVIA_API_KEY\` and \`BARIVIA_API_URL\` in the client; there is no direct DB or object storage access from the MCP process.
+Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
 
-**Tool map (high level):**
-- \`datasets\` — upload, preview, list, subset, delete, add_expression
-- \`jobs\` — \`train_map\`, \`train_siom_map\`, \`train_floop_siom\` (and deprecated alias \`train_floop_chain\`), plus \`status\`, \`list\`, \`compare\`, \`cancel\`, \`delete\`, \`batch_predict\`, \`run_baseline_study\`
-- \`results\` — get, recolor, download, export, transition_flow
-- \`inference\` — predict, enrich, compare, report, project_columns
-- \`account\` — status, compute credits, history
-- \`training_guidance\` — API-served parameter hints (grid, epochs, presets, SIOM/FLooP knobs)
-- \`training_prep\`, \`results_explorer\`, \`training_monitor\` — **optional** rich UIs (see below)
-- \`send_feedback\`, \`guide_barsom_workflow\` (this tool)
+**Core tools:** \`datasets\`, \`jobs\` (train_map, train_siom_map, train_floop_siom where entitled), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
 
-**Async contract:** Training submits return \`job_id\` immediately. Poll \`jobs(action=status, job_id=...)\` every **10–15s**. “Still running” is not failure; allow several minutes for larger grids or FLooP-SIOM (\`max_nodes\` is a node budget, not a grid side).
-
-**Training modes (when to use which):**
-- **Standard SOM** — \`jobs(action=train_map)\`: fixed hex/grid map.
-- **SIOM** — \`jobs(action=train_siom_map)\`: same grid flow with coverage regularization.
-- **FLooP-SIOM** — \`jobs(action=train_floop_siom)\`: growing manifold; default \`topology=free\` (CHL); optional \`topology=chain\`.
-
-**MCP Apps (optional rich UI):** **Not required** for any outcome—the same work completes with \`jobs\`, \`results\`, and thread text alone. **Recommended** for clarity: **preparation** → \`training_prep\`; **postprocessing / exploration** → \`results_explorer\` after completion. **Monitoring** → \`training_monitor(job_id)\` is optional polish (charts); \`jobs(action=status)\` is sufficient. If the host has no MCP Apps, ignore these or use standalone URLs from tool responses when offered.
-
-**Where to go next:** Parameter presets and field-level hints → \`training_guidance\` or the \`prepare_training\` prompt. Full step order → **Workflow (SOP)** below.
-
----
-
-## Workflow (SOP)
-
-`;
-const SOP = `Step 1: Upload Data
-- Use \`datasets(action=upload)\` with \`file_path\` to your CSV (server reads from workspace root; token-efficient). Use \`csv_data\` only for small inline pastes.
-- BEFORE UPLOADING: Clean the dataset to remove NaNs or malformed data.
-- Capture the \`dataset_id\` returned.
-
-Step 2: Preview & Preprocess
-- Use \`datasets(action=preview)\` to inspect columns, ranges, and types.
-- Check for skewed columns requiring 'log' or 'sqrt' transforms.
-- Check for cyclical or temporal features (hours, days) requiring \`cyclic_features\` or \`temporal_features\` during training.
-- Raw categorical/text columns usually stay out of the first map. If one really matters, use explicit baseline \`categorical_features\` encoding rather than assuming advanced categorical embeddings.
-- *(Optional UI)* \`training_prep(dataset_id=...)\` helps review variables, transforms, and hyperparameters before submit—not required if you train directly with \`jobs\`.
-
-Step 3: Train the map
-- Choose one: \`jobs(action=train_map, dataset_id=...)\`, \`jobs(action=train_siom_map, dataset_id=...)\`, or \`jobs(action=train_floop_siom, dataset_id=...)\`.
-- Carefully select columns to include (start with 5–10).
-- Assign \`feature_weights\` when some numeric or encoded features should matter more than others.
-- Wait for the returned \`job_id\`.
-- For projection and inference, use the same job_id from train_som (or the new job_id returned by recolor/project when applicable).
-- *(Optional UI)* After submit, \`training_monitor(job_id=...)\` can show progress visually; **\`jobs(action=status)\` alone is enough** to know when training finished.
-
-Step 4: Wait for Completion (ASYNC POLLING)
-- Use \`jobs(action=status, job_id=...)\` every 10–15 seconds.
-- Wait until status is "completed". DO NOT assume failure before 3 minutes (or longer for large grids).
-- If it fails, read the error message and adjust parameters (e.g., reduce grid size, fix column names).
-
-Step 5: Analyze and Export
-- Once completed, use \`results(action=get, job_id=...)\` to get the map, metrics (QE, TE, Silhouette, etc.), and figures (U-matrix, component planes, clusters, hit histogram). There is no separate \`analyze\` tool — all visualizations and metrics come from \`results(action=get)\`.
-- *(Optional UI)* \`results_explorer(job_id=...)\` is especially useful to browse figures and metrics interactively; **\`results(action=get)\` is sufficient** without it.
-Step 5b (optional): Use \`jobs(action=compare, job_ids=[id1, id2, ...])\` to compare multiple train_map runs (QE, TE, explained variance, silhouette) before committing to one.
-
-What you can do at each step:
-- After upload: datasets(preview), datasets(subset), datasets(add_expression), datasets(delete).
-- After training completes: results(get/download/export), results(recolor), results(transition_flow), jobs(compare), inference(predict/enrich/compare/project_columns/report).`;
+**Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {
-    server.tool("guide_barsom_workflow", `Ground-truth orientation for this MCP: (A) how the proxy works, tool categories, async training rules, training modes, and optional MCP App UIs; (B) the step-by-step mapping SOP. Call at the **start of mapping work** or when the user asks what the integration can do. For field-level training parameters only, use training_guidance or prepare_training.`, {}, async () => {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: BOOTSTRAP + SOP,
-                },
-            ],
-        };
+    server.tool("guide_barsom_workflow", "Ground-truth orientation for this MCP: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online (tier-scoped to allowed_job_types). Call at the start of mapping work. Offline: returns a short stub. For field-level training parameters, use training_guidance or prepare_training.", {}, async () => {
+        const md = await fetchWorkflowGuideFromApi();
+        if (md) {
+            const text = "Source: Barivia API (`GET /v1/docs/workflow`). Text below is scoped to your API key / plan.\n\n" + md;
+            return { content: [{ type: "text", text }] };
+        }
+        return { content: [{ type: "text", text: OFFLINE_STUB }] };
     });
 }
-//# sourceMappingURL=guide_barsom.js.map

package/dist/tools/inference.js

@@ -211,4 +211,3 @@ action=report: Returns a report manifest for the given job_id (job must be compl
         };
     });
 }
-//# sourceMappingURL=inference.js.map

package/dist/tools/jobs.js

@@ -9,7 +9,7 @@ export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs.
 | compare | Picking the best training run from a set of completed jobs |
 | train_map | Submitting a new map training job — returns job_id for polling |
 | train_siom_map | Submitting a self-interacting map training job — same map flow with SIOM coverage control |
-| train_floop_siom | Submitting a FLooP-SIOM job (growing manifold; default topology=free / CHL) |
+| train_floop_siom | Submitting a FLooP-SIOM job (growing manifold; default topology=free / CHL) — requires Premium or Enterprise plan (all_algorithms) |
 | train_floop_chain | Deprecated alias for train_floop_siom — same behavior; prefer train_floop_siom |
 | cancel | Stopping a running or pending job to free the worker |
 | delete | Permanently removing a job and all its S3 result files |
@@ -36,7 +36,7 @@ action=train_map / train_siom_map: Submits a grid-map training job. Returns job_
   normalize: "auto" (default) = scale only non-cyclic features; "all" = scale every feature. Use "auto" when using cyclic_features.
   categorical_features: optional baseline categorical support using explicit weighted one-hot encoding. Provide the raw column name, allowed categories, and a weight. Advanced categorical embeddings are intentionally outside this default tool surface.
   train_siom_map only: siom_feature_geometry l2 (default) | mixed | auto — torus distance on cyclic (cos,sin) pairs when mixed or auto with cyclic encodings. siom_qe_backend cpu|cuda|auto and siom_qe_batch_size align siom_qe with training geometry when mixed.
-action=train_floop_siom (preferred) or train_floop_chain (deprecated alias): Submits FLooP-SIOM — a growing node-budget manifold instead of a fixed hex grid. Default topology is free (CHL dynamic graph); topology=chain is optional for a strict 1D linked-list backbone.
+action=train_floop_siom (preferred) or train_floop_chain (deprecated alias): Submits FLooP-SIOM — a growing node-budget manifold instead of a fixed hex grid. **Only if the API key’s plan includes all_algorithms** (Premium or Enterprise); otherwise the API returns a clear upgrade message. Default topology is free (CHL dynamic graph); topology=chain is optional for a strict 1D linked-list backbone.
   Key params: topology (default free), max_nodes, effort, gamma, siom_decay.
   max_nodes is a total node budget, not a grid width or area. If omitted, the backend uses a dataset-size heuristic (roughly 2*sqrt(n_samples), capped for stability).
   effort controls passes only: quick≈15, standard≈30, thorough≈60. If coverage collapses, reduce max_nodes before increasing effort.
@@ -512,4 +512,3 @@ export function registerJobsTool(server, description) {
         throw new Error("Invalid action");
     });
 }
-//# sourceMappingURL=jobs.js.map

package/dist/tools/results.js

@@ -596,4 +596,3 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
         throw new Error("Invalid action");
     });
 }
-//# sourceMappingURL=results.js.map

package/dist/tools/training_guidance.js

@@ -1,8 +1,7 @@
 import { fetchTrainingGuidanceFromApi } from "../shared.js";
 export function registerTrainingGuidanceTool(server) {
-    server.tool("training_guidance", "Returns parameter guidance for training jobs (grid, epochs, batch, model, periodic, SIOM/FLooP fields, categorical baselines). Domain knowledge is served from the API; requires valid API key. For full proxy orientation, tool map, async rules, and workflow SOP, call guide_barsom_workflow first. Optional visual workflows: training_prep (prep), results_explorer (postprocess)—not required; jobs + results are sufficient.", {}, async () => {
+    server.tool("training_guidance", "Returns parameter guidance for training jobs (grid, epochs, batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Domain knowledge is served from GET /v1/training/config and filtered to your allowed_job_types; requires valid API key. For full proxy orientation and SOP, call guide_barsom_workflow (loads GET /v1/docs/workflow). Optional visual workflows: training_prep (prep), results_explorer (postprocess)—not required; jobs + results are sufficient.", {}, async () => {
         const text = await fetchTrainingGuidanceFromApi();
         return { content: [{ type: "text", text }] };
     });
 }
-//# sourceMappingURL=training_guidance.js.map

package/dist/tools/training_monitor.js

@@ -41,4 +41,3 @@ export function registerTrainingMonitorTool(server) {
         return structuredTextResult(structuredContent, text, content);
     });
 }
-//# sourceMappingURL=training_monitor.js.map

package/dist/tools/training_prep.js

@@ -353,4 +353,3 @@ export function registerTrainingPrepTools(server) {
         }, `Training job submitted from reviewed prep. Job ID: ${jobId}\nPoll with jobs(action=status, job_id="${jobId}") until complete, then use results(action=get, job_id="${jobId}").`);
     });
 }
-//# sourceMappingURL=training_prep.js.map

package/dist/tools/training_review_store.js

@@ -51,4 +51,3 @@ export function consumeTrainingReview(reviewToken) {
     reviews.delete(reviewToken);
     return review;
 }
-//# sourceMappingURL=training_review_store.js.map

package/dist/viz-server.js

@@ -208,4 +208,3 @@ export function startVizServer(apiCall, apiRawCall, loadViewHtml) {
         server.on("error", reject);
     });
 }
-//# sourceMappingURL=viz-server.js.map