@barivia/barsom-mcp 0.10.2 → 0.10.3

package/dist/audit.js

@@ -0,0 +1,118 @@
+/**
+ * MCP tool audit wrapper — tool name, action, latency, outcome; no secrets.
+ */
+import { logAudit } from "./logger.js";
+/** Keys safe to include in audit param summaries (no paths, keys, or bodies). */
+const AUDIT_PARAM_KEYS = new Set([
+    "action",
+    "job_type",
+    "model",
+    "preset",
+    "backend",
+    "output_format",
+    "figures",
+    "job_id",
+    "dataset_id",
+    "compare",
+    "topology",
+    "viz_mode",
+]);
+function scrubParams(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (!AUDIT_PARAM_KEYS.has(k))
+            continue;
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function extractIds(result) {
+    const ids = {};
+    if (result === null || typeof result !== "object")
+        return ids;
+    const r = result;
+    if (typeof r.job_id === "string")
+        ids.job_id = r.job_id;
+    if (typeof r.id === "string" && !ids.job_id)
+        ids.job_id = r.id;
+    if (typeof r.dataset_id === "string")
+        ids.dataset_id = r.dataset_id;
+    const sc = r.structuredContent;
+    if (sc && typeof sc === "object") {
+        const s = sc;
+        if (typeof s.jobId === "string")
+            ids.job_id = s.jobId;
+        if (typeof s.datasetId === "string")
+            ids.dataset_id = s.datasetId;
+    }
+    try {
+        const text = JSON.stringify(result);
+        const jobMatch = text.match(/"job_id"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (jobMatch && !ids.job_id)
+            ids.job_id = jobMatch[1];
+        const dsMatch = text.match(/"dataset_id"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (dsMatch && !ids.dataset_id)
+            ids.dataset_id = dsMatch[1];
+    }
+    catch {
+        /* ignore */
+    }
+    return ids;
+}
+function errorCodeFrom(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.httpStatus !== undefined)
+            return `http_${e.httpStatus}`;
+        const m = e.message ?? "";
+        const codeMatch = m.match(/error_code:\s*(\w+)/);
+        if (codeMatch)
+            return codeMatch[1];
+    }
+    return undefined;
+}
+/**
+ * Run a tool handler with structured audit logging.
+ */
+export async function runMcpToolAudit(tool, action, args, handler) {
+    const t0 = Date.now();
+    const params = scrubParams(args);
+    try {
+        const result = await handler();
+        const ids = extractIds(result);
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "ok",
+            ...ids,
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        return result;
+    }
+    catch (err) {
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "error",
+            error_code: errorCodeFrom(err),
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        throw err;
+    }
+}
+/**
+ * Register an MCP tool with structured audit logging on each invocation.
+ */
+export function registerAuditedTool(server, name, description, schema, handler) {
+    server.tool(name, description, schema, (async (args) => {
+        const rec = args;
+        const action = typeof rec.action === "string" && rec.action.length > 0 ? rec.action : "default";
+        return runMcpToolAudit(name, action, rec, () => handler(args));
+    }));
+}

package/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * Structured stdout/stderr logging for the MCP proxy (Docker json-file friendly).
+ */
+const SERVICE_NAME = process.env.BARIVIA_SERVICE_NAME ?? process.env.BARSOM_SERVICE_NAME ?? "mcp-proxy";
+const LOG_FORMAT = (process.env.BARIVIA_LOG_FORMAT ?? process.env.BARSOM_LOG_FORMAT ?? "text").toLowerCase();
+function emit(fields) {
+    const level = fields.level ?? "info";
+    const payload = {
+        ts: new Date().toISOString(),
+        level,
+        service: SERVICE_NAME,
+        ...fields,
+    };
+    delete payload.level;
+    if (LOG_FORMAT === "json") {
+        console.error(JSON.stringify(payload));
+        return;
+    }
+    const parts = [`${payload.ts} ${level.toUpperCase().padEnd(5)} ${fields.msg}`];
+    for (const [k, v] of Object.entries(payload)) {
+        if (k === "ts" || k === "msg" || k === "service")
+            continue;
+        if (v !== undefined && v !== null && v !== "") {
+            parts.push(`${k}=${String(v)}`);
+        }
+    }
+    console.error(parts.join(" | "));
+}
+export function logInfo(msg, fields = {}) {
+    emit({ ...fields, level: "info", msg });
+}
+export function logWarn(msg, fields = {}) {
+    emit({ ...fields, level: "warn", msg });
+}
+export function logError(msg, fields = {}) {
+    emit({ ...fields, level: "error", msg });
+}
+export function logAudit(fields) {
+    emit({ ...fields, event: "mcp_tool_call", level: "info", msg: "mcp_tool_call" });
+}

package/dist/shared.js

@@ -4,6 +4,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { logInfo } from "./logger.js";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -19,7 +20,7 @@ export const RETRYABLE_STATUS = new Set([502, 503, 504]);
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.10.2";
+export const CLIENT_VERSION = "0.10.3";
 /** 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). */
@@ -277,7 +278,7 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
     }
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     const t0 = Date.now();
-    console.error(`${new Date().toISOString()} API -> ${method} ${path} rid=${requestId}`);
+    logInfo("API request", { rid: requestId, method, path });
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
@@ -292,10 +293,19 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
                     await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
                     continue;
                 }
-                console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
+                logInfo("API response", {
+                    rid: requestId,
+                    outcome: "error",
+                    duration_ms: Date.now() - t0,
+                    error_code: `http_${resp.status}`,
+                });
                 throwApiError(resp.status, text, requestId);
             }
-            console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
+            logInfo("API response", {
+                rid: requestId,
+                outcome: "ok",
+                duration_ms: Date.now() - t0,
+            });
             return JSON.parse(text);
         }
         catch (err) {

package/dist/tools/account.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall } from "../shared.js";
 export function registerAccountTool(server) {
-    server.tool("account", `Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.
 
 | Action | Use when |
 |--------|----------|

package/dist/tools/datasets.js

@@ -2,9 +2,10 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { gzipSync } from "node:zlib";
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.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.
+    registerAuditedTool(server, "datasets", `Manage datasets: upload, preview, list, subset, add_expression, or delete.
 
 | Action | Use when |
 |--------|----------|

package/dist/tools/explore_map.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, getResultsImagesToFetch, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 export const RESULTS_EXPLORER_URI = "ui://barsom/results-explorer";
 export const MAP_EXPLORER_URI = RESULTS_EXPLORER_URI;
@@ -164,13 +165,13 @@ export function registerExploreMapTool(server) {
         },
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
-    registerAppTool(server, "results_explorer", toolConfig, async ({ job_id }) => handleResultsExplorer(job_id));
+    registerAppTool(server, "results_explorer", toolConfig, async (args) => runMcpToolAudit("results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
     registerAppTool(server, "explore_map", {
         ...toolConfig,
         title: "Results Explorer",
         description: `${toolConfig.description} Deprecated alias for results_explorer — migrate configs to results_explorer.`,
-    }, async ({ job_id }) => handleResultsExplorer(job_id));
-    server.tool("_fetch_figure", "Host / MCP App use only — do NOT invoke from agent chat. Results Explorer calls this to load one raster figure as base64; agents should use results(action=get) or results_explorer instead.", {
+    }, async (args) => runMcpToolAudit("explore_map", "default", args, () => handleResultsExplorer(String(args.job_id))));
+    registerAuditedTool(server, "_fetch_figure", "Host / MCP App use only — do NOT invoke from agent chat. Results Explorer calls this to load one raster figure as base64; agents should use results(action=get) or results_explorer instead.", {
         job_id: z.string(),
         filename: z.string(),
     }, async ({ job_id, filename }) => {

package/dist/tools/feedback.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, API_URL, fetchWithTimeout, textResult } from "../shared.js";
 export function registerFeedbackTool(server) {
-    server.tool("send_feedback", `Send feedback or feature requests to Barivia developers (max 1400 characters, ~190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.`, { feedback: z.string().max(1400).describe("Feedback text (max 1400 characters)") }, async ({ feedback }) => {
+    registerAuditedTool(server, "send_feedback", `Send feedback or feature requests to Barivia developers (max 1400 characters, ~190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.`, { feedback: z.string().max(1400).describe("Feedback text (max 1400 characters)") }, async ({ feedback }) => {
         try {
             const data = await apiCall("POST", "/v1/feedback", { feedback });
             return textResult(data);

package/dist/tools/guide_barsom.js

@@ -1,3 +1,4 @@
+import { registerAuditedTool } from "../audit.js";
 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
@@ -8,7 +9,7 @@ Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guid
 
 **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", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt or training_prep.", {}, async () => {
+    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt or training_prep.", {}, async () => {
         const md = await fetchWorkflowGuideFromApi();
         if (md) {
             const text = "Plan-scoped workflow (from Barivia API). Text below reflects your API key / plan.\n\n" + md;

package/dist/tools/inference.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, pollUntilComplete, tryAttachImage } from "../shared.js";
 const PREDICT_PREVIEW_ROW_CAP = 10;
 /** One line per scored row when worker embedded `predictions_preview` (n_rows ≤ cap). Exported for tests. */
@@ -30,7 +31,7 @@ export function formatPredictPreviewLines(summary) {
     return lines;
 }
 export function registerInferenceTool(server) {
-    server.tool("inference", `Use a trained map as a persistent inference artifact — score data, annotate the source CSV, compare datasets, project columns, or generate a report manifest.
+    registerAuditedTool(server, "inference", `Use a trained map as a persistent inference artifact — score data, annotate the source CSV, compare datasets, project columns, or generate a report manifest.
 
 | Action | Use when | Timing |
 |--------|----------|--------|

package/dist/tools/jobs.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs.
 
@@ -224,7 +225,7 @@ export function buildTrainMapParams(args, presets) {
     return { params, paramSummary, effectiveGrid };
 }
 export function registerJobsTool(server, description) {
-    server.tool("jobs", description, {
+    registerAuditedTool(server, "jobs", description, {
         action: z
             .enum(["status", "list", "compare", "cancel", "delete", "train_map", "train_impute", "train_siom_map", "train_floop_siom", "train_floop_chain", "batch_predict", "run_baseline_study"])
             .describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files; train_map: submit standard map training; train_siom_map: submit SIOM map training; train_floop_siom: submit FLooP-SIOM (preferred); train_floop_chain: deprecated alias for train_floop_siom; batch_predict: submit multiple predict jobs at once; run_baseline_study: auto-configure and train a baseline SOM"),

package/dist/tools/results.js

@@ -1,9 +1,10 @@
 import path from "node:path";
 import fs from "node:fs/promises";
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, getResultsImagesToFetch, getCaptionForImage, mimeForFilename, } from "../shared.js";
 export function registerResultsTool(server) {
-    server.tool("results", `Retrieve, recolor, download, export, or run temporal flow on a completed map job.
+    registerAuditedTool(server, "results", `Retrieve, recolor, download, export, or run temporal flow on a completed map job.
 
 | Action | Use when | Sync/Async |
 |--------|----------|------------|

package/dist/tools/training_guidance.js

@@ -1,6 +1,7 @@
+import { registerAuditedTool } from "../audit.js";
 import { fetchTrainingGuidanceFromApi } from "../shared.js";
 export function registerTrainingGuidanceTool(server) {
-    server.tool("training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints; training_prep = interactive UI + submit_prepared_training. For full orientation and SOP, call guide_barsom_workflow first. Optional UIs: training_prep, results_explorer—not required; jobs + results suffice.", {}, async () => {
+    registerAuditedTool(server, "training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints; training_prep = interactive UI + submit_prepared_training. For full orientation and SOP, call guide_barsom_workflow first. Optional UIs: training_prep, results_explorer—not required; jobs + results suffice.", {}, async () => {
         const text = await fetchTrainingGuidanceFromApi();
         return { content: [{ type: "text", text }] };
     });

package/dist/tools/training_monitor.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { runMcpToolAudit } from "../audit.js";
 import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
 export const TRAINING_MONITOR_URI = "ui://barsom/training-monitor";
 function buildStructuredContent(job_id, data) {
@@ -20,7 +21,8 @@ export function registerTrainingMonitorTool(server) {
             job_id: z.string().describe("Training job ID to monitor"),
         },
         _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
-    }, async ({ job_id }) => {
+    }, async (args) => runMcpToolAudit("training_monitor", "default", args, async () => {
+        const job_id = String(args.job_id);
         const data = (await apiCall("GET", `/v1/jobs/${job_id}`));
         const structuredContent = buildStructuredContent(job_id, data);
         const status = String(data.status ?? "unknown");
@@ -39,5 +41,5 @@ export function registerTrainingMonitorTool(server) {
             });
         }
         return structuredTextResult(structuredContent, text, content);
-    });
+    }));
 }

package/dist/tools/training_prep.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, fetchTrainingGuidanceFromApi, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
 import { buildTrainMapParams, fetchTrainingPresets, } from "./jobs.js";
 import { attachTrainingReviewPayload, consumeTrainingReview, getTrainingReview, storeTrainingReview, } from "./training_review_store.js";
@@ -324,11 +325,11 @@ export function registerTrainingPrepTools(server) {
         description: "Interactive training prep UI + guarded submit (submit_prepared_training). Prep ladder: prepare_training prompt = narrative checklist; training_guidance tool = JSON/presets; this tool = visual review. Opens inline review of variables, transforms, encodings, and hyperparameters.",
         inputSchema: trainPrepSchema,
         _meta: { ui: { resourceUri: TRAINING_PREP_URI } },
-    }, async ({ dataset_id, ...args }) => {
+    }, async ({ dataset_id, ...args }) => runMcpToolAudit("training_prep", "default", { dataset_id, ...args }, async () => {
         const payload = await buildTrainingPrepPayload(dataset_id, args);
         return structuredTextResult(payload, undefined, buildTrainingPrepContent(payload));
-    });
-    server.tool("submit_prepared_training", "Submit a previously reviewed training-prep configuration. Requires an unexpired review token and explicit confirmation.", {
+    }));
+    registerAuditedTool(server, "submit_prepared_training", "Submit a previously reviewed training-prep configuration. Requires an unexpired review token and explicit confirmation.", {
         review_token: z.string().describe("Review token returned inside training_prep structured content."),
         explicit_confirm: z.boolean().describe("Must be true to submit the reviewed training job."),
     }, async ({ review_token, explicit_confirm }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barsom-mcp",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "barSOM MCP proxy — connect any MCP client to the barSOM cloud API for Self-Organizing Map analytics",
   "keywords": [
     "mcp",