@barivia/barsom-mcp 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @barivia/barsom-mcp
+
+MCP proxy for the Barivia Analytics Engine -- connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. 20 tools covering the full data analysis lifecycle: upload, preview, train, analyze, compare, and export.
+
+## Installation
+
+No install step needed. MCP clients run it via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "analytics-engine": {
+      "command": "npx",
+      "args": ["-y", "@barivia/barsom-mcp"],
+      "env": {
+        "BARIVIA_API_KEY": "bv_your_key",
+        "BARIVIA_API_URL": "https://api.barivia.se"
+      }
+    }
+  }
+}
+```
+
+This is the standard pattern for MCP servers distributed as npm packages (same as `firecrawl-mcp`, `@paypal/mcp`, etc.).
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `BARIVIA_API_KEY` | Yes | -- | API key (starts with `bv_`) |
+| `BARIVIA_API_URL` | No | `https://api.barivia.se` | API base URL |
+
+Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` are also accepted as fallbacks.
+
+## Tools (20)
+
+### Data Management
+
+| Tool | Description |
+|---|---|
+| `upload_dataset` | Upload CSV data for SOM analysis |
+| `list_datasets` | List uploaded datasets with row/column counts |
+| `preview_dataset` | Inspect columns, statistics, sample rows, detect datetime columns, suggest temporal features |
+| `delete_dataset` | Delete dataset and S3 artifacts |
+
+### Training Lifecycle
+
+| Tool | Description |
+|---|---|
+| `train_som` | Submit training job with full control: model type (SOM/RSOM/SOM-SOFT/RSOM-SOFT), grid size, epochs, learning rate curves, feature weights, cyclic encoding, temporal features |
+| `get_job_status` | Check training progress and estimated completion |
+| `cancel_job` | Cancel a pending or running job |
+| `list_jobs` | List all jobs with status, parameters, and timing |
+| `delete_job` | Delete job and all result artifacts |
+
+### Results & Export
+
+| Tool | Description |
+|---|---|
+| `get_results` | Download results with inline images and quality metrics |
+| `get_training_log` | Per-epoch learning curves (QE residuals) for diagnostics |
+| `get_weights` | Export raw SOM weight matrix and normalization parameters |
+| `get_node_data` | Per-node hit counts and feature-value distributions |
+
+### Analysis (9 types via `analyze`)
+
+| Type | Description |
+|---|---|
+| `u_matrix` | Distance matrix heatmap showing cluster boundaries |
+| `component_planes` | Per-feature spatial distribution across the SOM |
+| `bmu_hits` | Hit histogram showing data density |
+| `clusters` | Automated cluster quality assessment |
+| `feature_importance` | Feature ranking by variance contribution |
+| `feature_correlation` | Inter-feature correlation analysis |
+| `transition_flow` | Temporal trajectory analysis with quiver plots |
+| `local_density` | Node neighborhood density analysis |
+| `feature_gradient` | Spatial gradient magnitude across the SOM |
+
+### Advanced Analysis
+
+| Tool | Description |
+|---|---|
+| `compare_runs` | Side-by-side metric comparison across training runs |
+| `project_variable` | Project a derived variable onto a trained SOM |
+| `transition_flow` | Dedicated temporal flow analysis |
+| `quality_report` | Extended quality metrics (trustworthiness, neighborhood preservation) |
+
+### System
+
+| Tool | Description |
+|---|---|
+| `system_info` | Runtime environment, CPU cores, worker topology, queue state |
+| `configure_resources` | Set worker threads, replica count, max concurrency |
+
+## How It Works
+
+The proxy implements the MCP stdio transport locally and translates tool calls into REST API requests to the Barivia backend. Results are returned as rich MCP content with text summaries, inline base64 images, and resource links.
+
+```
+MCP Client (Cursor/Claude) ←stdio→ @barivia/barsom-mcp ←HTTPS→ api.barivia.se
+```
+
+## Development
+
+```bash
+cd apps/mcp-proxy
+npm install
+npm run dev      # Run with tsx (hot reload)
+npm run build    # Compile to dist/
+```
+
+For local development against a local API stack:
+
+```bash
+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*`:
+
+```bash
+git tag mcp-proxy-v0.1.0
+git push origin mcp-proxy-v0.1.0
+```
+
+Requires `NPM_TOKEN` secret in GitHub repository settings.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * @barivia/barsom-mcp
+ *
+ * Thin MCP proxy: implements stdio MCP locally and forwards every tool call
+ * to the Barivia cloud REST API. Users configure BARIVIA_API_KEY and
+ * BARIVIA_API_URL as environment variables.
+ *
+ * Usage (in MCP client config, e.g. Cursor / Claude Desktop):
+ *
+ *   {
+ *     "mcpServers": {
+ *       "analytics-engine": {
+ *         "command": "npx",
+ *         "args": ["-y", "@barivia/barsom-mcp"],
+ *         "env": {
+ *           "BARIVIA_API_KEY": "bv_live_xxxx",
+ *           "BARIVIA_API_URL": "https://api.barivia.se"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG"}