@yarkivaev/scada 2.3.84 → 2.3.86

package/README.md

@@ -4,6 +4,25 @@ Generic industrial monitoring domain, state persistence, and HTTP APIs (`@yarkiv
 
 This package is plant-agnostic: it defines `plant` → `shop` → `machine` hierarchy, timeline and alerts, sensor read ports, STOMP ingest pipelines, and PostgreSQL/ClickHouse adapters. Plant-specific routes, sensors, HMI strings, and tag taxonomies live in downstream plant packages.
 
+`analyticsMcp` is a stateless Streamable HTTP MCP server. The plant package supplies a `namespaceTree` (path, kind, silence, source topic) and read ports. Tools address nodes by path. `query_postgres` is registered only when a standby query port is supplied. Each call writes one JSON line to the injected journal. `GET /metrics` exposes call counts and in-flight reads.
+
+```javascript
+import { analyticsMcp, namespaceTree } from '@yarkivaev/scada';
+
+const mcp = analyticsMcp({
+  tree: namespaceTree(nodes),
+  tokens: { secret: 'analyst' },
+  journal(line) { process.stdout.write(line); },
+  ports: {
+    measurements, segments, operations, alerts, state, samples, cursor, queryClickhouse
+  },
+  extend(server) { /* plant tools, resources, prompts */ }
+});
+await mcp.listen(0, '127.0.0.1');
+```
+
+`ports.queryPostgres` registers `query_postgres`. `extend(server)` may add plant tools. `POST /mcp` requires `Authorization: Bearer`.
+
 Repository: `https://github.com/yarkivaev/scada`
 
 ## Install
@@ -113,6 +132,7 @@ Main entry (`import { … } from '@yarkivaev/scada'`):
 | `stompTimeline`, `stompAlerts`, `userDecisions` | STOMP messaging |
 | `machineOwners`, `ownerTimeline`, `httpTimeline`, `httpOperations` | Owner-routed timeline and operations write (local or edge HTTP) |
 | `mqttMetrics`, `modbusMqtt`, `activityTracking`, `amqpMetricsIngest` | Ingest pipelines |
+| `analyticsMcp`, `namespaceTree`, `coverageSpans`, `sqlGuard` | Analytics MCP, path index, coverage spans, read-only SQL guard |
 
 Subpath exports:
 

package/index.js

@@ -86,3 +86,7 @@ export { default as siteSync } from './src/application/sync/siteSync.js';
 export { default as siteSyncSites } from './src/application/sync/siteSyncSites.js';
 export { default as siteSyncTargets } from './src/application/sync/siteSyncTargets.js';
 export { default as siteSyncBind } from './src/application/sync/siteSyncBind.js';
+export { default as namespaceTree } from './src/domain/namespace/namespaceTree.js';
+export { default as coverageSpans } from './src/domain/span/coverageSpans.js';
+export { default as sqlGuard } from './src/domain/sql/sqlGuard.js';
+export { default as analyticsMcp } from './src/application/mcp/analyticsMcp.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.84",
+  "version": "2.3.86",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",
@@ -28,11 +28,13 @@
   },
   "dependencies": {
     "@clickhouse/client": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.24.3",
     "@yarkivaev/simple-server": "1.0.2",
     "@yarkivaev/source-to-sink": "1.3.7",
     "amqplib": "^0.10.9",
     "pg": "^8.0.0",
-    "stompit": "^1.0.0"
+    "stompit": "^1.0.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/application/mcp/analyticsMcp.js

@@ -0,0 +1,376 @@
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import mcpMetrics from './mcpMetrics.js';
+import observe from './mcpObserve.js';
+import registerCoverage from './mcpCoverage.js';
+import registerQueries from './mcpQuery.js';
+import registerReads from './mcpReads.js';
+import registerResources from './mcpResources.js';
+
+const load = createRequire(import.meta.url);
+const pkg = load('../../../package.json');
+
+/**
+ * Throws when a required bundle part is absent.
+ *
+ * @param {boolean} ok - whether the part is present
+ * @param {string} message - error context
+ * @returns {void}
+ *
+ * @example
+ *   assertPart(true, 'Analytics ports are missing');
+ */
+function assertPart(ok, message) {
+    if (ok) {
+        return;
+    }
+    throw new Error(message);
+}
+
+/**
+ * Requires the read ports that named tools always register.
+ *
+ * @param {object} ports - read ports
+ * @returns {void}
+ *
+ * @example
+ *   assertPorts(ports);
+ */
+function assertPorts(ports) {
+    const names = [
+        'alerts', 'cursor', 'measurements', 'operations',
+        'queryClickhouse', 'samples', 'segments', 'state'
+    ];
+    for (const name of names) {
+        assertPart(typeof ports[name] === 'function', `Analytics port is missing: ${name}`);
+    }
+}
+
+/**
+ * Requires the namespace, journal, tokens, and ports.
+ *
+ * @param {object} bundle - analyticsMcp bundle
+ * @returns {void}
+ *
+ * @example
+ *   assertBundle(bundle);
+ */
+function assertBundle(bundle) {
+    const treeOk = Boolean(bundle && bundle.tree && typeof bundle.tree.resolve === 'function');
+    assertPart(treeOk, 'Analytics namespace tree is missing');
+    assertPart(Boolean(bundle && typeof bundle.journal === 'function'), 'Analytics journal writer is missing');
+    assertPart(Boolean(bundle && bundle.tokens), 'Analytics bearer map is missing');
+    assertPart(Boolean(bundle && bundle.ports), 'Analytics ports are missing');
+    assertPorts(bundle.ports);
+}
+
+/**
+ * Server name and package version for the MCP handshake.
+ *
+ * @returns {{name: string, version: string}} implementation
+ *
+ * @example
+ *   serverInfo().name;
+ */
+function serverInfo() {
+    return { name: 'analytics', version: pkg.version };
+}
+
+/**
+ * Lets a plant package register tools on the same server.
+ *
+ * @param {object} server - McpServer
+ * @param {object} bundle - analyticsMcp bundle
+ * @returns {void}
+ *
+ * @example
+ *   extendServer(server, bundle);
+ */
+function extendServer(server, bundle) {
+    if (typeof bundle.extend === 'function') {
+        bundle.extend(server);
+    }
+}
+
+/**
+ * Builds one stateless server for a single HTTP request.
+ *
+ * @param {object} bundle - analyticsMcp bundle
+ * @param {object} metrics - prometheus counters
+ * @param {string} caller - bearer caller name
+ * @returns {object} McpServer
+ *
+ * @example
+ *   openServer(bundle, metrics, 'analyst');
+ */
+function openServer(bundle, metrics, caller) {
+    const server = new McpServer(serverInfo());
+    observe(server, { caller, journal: bundle.journal, metrics });
+    registerReads(server, bundle.ports, bundle.tree);
+    registerCoverage(server, bundle.ports, bundle.tree);
+    registerQueries(server, bundle.ports);
+    registerResources(server, bundle.tree);
+    extendServer(server, bundle);
+    return server;
+}
+
+/**
+ * Resolves a bearer token to a caller name.
+ *
+ * @param {import('node:http').IncomingMessage} req - request
+ * @param {object} tokens - token to caller name
+ * @returns {string} caller name or an empty string
+ *
+ * @example
+ *   callerName(req, { secret: 'analyst' });
+ */
+function callerName(req, tokens) {
+    const header = req.headers.authorization;
+    if (typeof header !== 'string') {
+        return '';
+    }
+    const matched = /^Bearer\s+(?<token>\S+)$/iu.exec(header);
+    if (!matched || !Object.hasOwn(tokens, matched.groups.token)) {
+        return '';
+    }
+    const name = tokens[matched.groups.token];
+    if (typeof name === 'string' && name.length > 0) {
+        return name;
+    }
+    return '';
+}
+
+/**
+ * Closes a one-request transport after the HTTP response finishes.
+ *
+ * The SDK writes the JSON body after handleRequest returns, so the transport
+ * stays open until the response closes.
+ *
+ * @param {object} transport - StreamableHTTPServerTransport
+ * @param {object} server - McpServer
+ * @returns {Function} release
+ *
+ * @example
+ *   const release = releaser(transport, server);
+ */
+function releaser(transport, server) {
+    let settled = false;
+    return function release() {
+        if (settled) {
+            return Promise.resolve();
+        }
+        settled = true;
+        return Promise.all([transport.close(), server.close()]).then(() => {
+            return undefined;
+        }, () => {
+            return undefined;
+        });
+    };
+}
+
+/**
+ * Handles one MCP POST on a fresh stateless transport.
+ *
+ * @param {import('node:http').IncomingMessage} req - request
+ * @param {import('node:http').ServerResponse} res - response
+ * @param {object} bundle - analyticsMcp bundle
+ * @param {object} metrics - prometheus counters
+ * @param {string} caller - bearer caller name
+ * @returns {Promise<void>}
+ *
+ * @example
+ *   dispatch(req, res, bundle, metrics, 'analyst');
+ */
+async function dispatch(req, res, bundle, metrics, caller) {
+    const server = openServer(bundle, metrics, caller);
+    const transport = new StreamableHTTPServerTransport({
+        enableJsonResponse: true,
+        sessionIdGenerator: undefined
+    });
+    const done = releaser(transport, server);
+    res.on('close', () => {
+        done();
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    } catch (err) {
+        await done();
+        throw err;
+    }
+}
+
+/**
+ * Authorizes a POST /mcp request and then hands it to the SDK.
+ *
+ * @param {import('node:http').IncomingMessage} req - request
+ * @param {import('node:http').ServerResponse} res - response
+ * @param {object} bundle - analyticsMcp bundle
+ * @param {object} metrics - prometheus counters
+ * @returns {Promise<void>}
+ *
+ * @example
+ *   postMcp(req, res, bundle, metrics);
+ */
+async function postMcp(req, res, bundle, metrics) {
+    const name = callerName(req, bundle.tokens);
+    if (name.length === 0) {
+        res.writeHead(401).end();
+        return;
+    }
+    await dispatch(req, res, bundle, metrics, name);
+}
+
+/**
+ * Writes the Prometheus scrape body.
+ *
+ * @param {import('node:http').ServerResponse} res - response
+ * @param {object} metrics - prometheus counters
+ * @returns {void}
+ *
+ * @example
+ *   writeMetrics(res, metrics);
+ */
+function writeMetrics(res, metrics) {
+    res.writeHead(200, { 'content-type': 'text/plain; version=0.0.4; charset=utf-8' });
+    res.end(metrics.text());
+}
+
+/**
+ * Routes /metrics and /mcp.
+ *
+ * @param {import('node:http').IncomingMessage} req - request
+ * @param {import('node:http').ServerResponse} res - response
+ * @param {object} bundle - analyticsMcp bundle
+ * @param {object} metrics - prometheus counters
+ * @returns {Promise<void>}
+ *
+ * @example
+ *   route(req, res, bundle, metrics);
+ */
+function route(req, res, bundle, metrics) {
+    if (req.method === 'GET' && req.url === '/metrics') {
+        writeMetrics(res, metrics);
+        return Promise.resolve();
+    }
+    if (req.method === 'POST' && req.url === '/mcp') {
+        return postMcp(req, res, bundle, metrics);
+    }
+    res.writeHead(404).end();
+    return Promise.resolve();
+}
+
+/**
+ * Answers a failed request without copying the error text.
+ *
+ * @param {import('node:http').ServerResponse} res - response
+ * @returns {void}
+ *
+ * @example
+ *   fail(res);
+ */
+function fail(res) {
+    if (res.headersSent) {
+        return;
+    }
+    res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('MCP request failed');
+}
+
+/**
+ * Forwards a request and hides handler failures.
+ *
+ * @param {import('node:http').IncomingMessage} req - request
+ * @param {import('node:http').ServerResponse} res - response
+ * @param {object} bundle - analyticsMcp bundle
+ * @param {object} metrics - prometheus counters
+ * @returns {void}
+ *
+ * @example
+ *   onRequest(req, res, bundle, metrics);
+ */
+function onRequest(req, res, bundle, metrics) {
+    route(req, res, bundle, metrics).catch(() => {
+        fail(res);
+    });
+}
+
+/**
+ * Starts listening and resolves the bound address.
+ *
+ * @param {import('node:http').Server} server - HTTP server
+ * @param {number} port - port, or 0 for an ephemeral port
+ * @param {string} host - bind address
+ * @returns {Promise<object>} address
+ *
+ * @example
+ *   listen(server, 0, '127.0.0.1');
+ */
+function listen(server, port, host) {
+    const chosen = typeof port === 'number' ? port : 0;
+    const iface = typeof host === 'string' ? host : '127.0.0.1';
+    return new Promise((resolve, reject) => {
+        function failBind(err) {
+            reject(err);
+        }
+        server.once('error', failBind);
+        server.listen(chosen, iface, () => {
+            server.removeListener('error', failBind);
+            resolve(server.address());
+        });
+    });
+}
+
+/**
+ * Closes the HTTP server.
+ *
+ * @param {import('node:http').Server} server - HTTP server
+ * @returns {Promise<void>}
+ *
+ * @example
+ *   shut(server);
+ */
+function shut(server) {
+    return new Promise((resolve, reject) => {
+        server.close((err) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+
+/**
+ * Stateless Streamable HTTP MCP for plant analytics.
+ *
+ * The plant package supplies a namespaceTree, read ports, a bearer map, and a
+ * journal writer. query_postgres is registered only when ports.queryPostgres
+ * is a function. extend(server) may register more tools. POST /mcp speaks MCP.
+ * GET /metrics is Prometheus text.
+ *
+ * @param {object} bundle - tree, tokens, journal, ports, optional extend
+ * @returns {object} listen and close
+ *
+ * @example
+ *   const mcp = analyticsMcp({ tree, tokens, journal, ports });
+ *   await mcp.listen(0, '127.0.0.1');
+ */
+export default function analyticsMcp(bundle) {
+    assertBundle(bundle);
+    const metrics = mcpMetrics();
+    const server = http.createServer((req, res) => {
+        onRequest(req, res, bundle, metrics);
+    });
+    return Object.freeze({
+        close() {
+            return shut(server);
+        },
+        listen(port, host) {
+            return listen(server, port, host);
+        }
+    });
+}

package/src/application/mcp/mcpCoverage.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import coverageSpans from '../../domain/span/coverageSpans.js';
+import { toolText } from './mcpText.js';
+
+/**
+ * Unwraps an ingest cursor object to its instant.
+ *
+ * @param {Date|number|string|object} value - cursor
+ * @returns {Date|number|string} instant
+ *
+ * @example
+ *   cursorAt({ at: '2024-11-02T03:04:05.137Z' });
+ */
+function cursorAt(value) {
+    if (value && typeof value === 'object' && !(value instanceof Date) && Object.hasOwn(value, 'at')) {
+        return value.at;
+    }
+    return value;
+}
+
+/**
+ * Builds capped coverage spans for one path.
+ *
+ * @param {string} path - namespace path
+ * @param {object} args - from and to
+ * @param {object} ports - samples and cursor
+ * @param {object} tree - namespaceTree
+ * @returns {Promise<object>} path spans
+ *
+ * @example
+ *   coverOne('site/metric', { from: 'a', to: 'b' }, ports, tree);
+ */
+async function coverOne(path, args, ports, tree) {
+    const node = tree.resolve(path);
+    const samples = await ports.samples({ from: args.from, path, to: args.to });
+    const cursor = await ports.cursor({ path });
+    const spans = coverageSpans(
+        samples,
+        args.from,
+        args.to,
+        node.silenceSeconds * 1000,
+        cursorAt(cursor)
+    );
+    return {
+        path,
+        spans: spans.slice(0, 200),
+        truncated: spans.length > 200
+    };
+}
+
+/**
+ * Reads present, absent, and unknown spans for each path.
+ *
+ * @param {object} args - paths, from, to
+ * @param {object} ports - samples and cursor
+ * @param {object} tree - namespaceTree
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   runCoverage({ paths: ['site'], from: 'a', to: 'b' }, ports, tree);
+ */
+async function runCoverage(args, ports, tree) {
+    const jobs = args.paths.map((path) => {
+        return coverOne(path, args, ports, tree);
+    });
+    const paths = await Promise.all(jobs);
+    const truncated = paths.some((item) => {
+        return item.truncated === true;
+    });
+    return toolText({ paths, truncated });
+}
+
+/**
+ * Registers the coverage tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerCoverage(server, ports, tree);
+ */
+export default function registerCoverage(server, ports, tree) {
+    server.registerTool('coverage', {
+        description: 'Present, absent, and unknown spans for metric paths',
+        inputSchema: {
+            from: z.string(),
+            paths: z.array(z.string()),
+            to: z.string()
+        }
+    }, (args) => {
+        return runCoverage(args, ports, tree);
+    });
+}

package/src/application/mcp/mcpJournal.js

@@ -0,0 +1,102 @@
+import sqlShape from '../../domain/sql/sqlShape.js';
+
+/**
+ * Caps a journal string.
+ *
+ * @param {string} text - raw text
+ * @returns {string} at most 512 characters
+ *
+ * @example
+ *   cap('SELECT 1');
+ */
+function cap(text) {
+    if (text.length > 512) {
+        return text.slice(0, 512);
+    }
+    return text;
+}
+
+/**
+ * Reads SQL from a query tool call.
+ *
+ * @param {string} name - tool or resource name
+ * @param {object} [args] - tool arguments
+ * @returns {string} SQL or an empty string
+ *
+ * @example
+ *   sqlText('query_clickhouse', { sql: 'SELECT 1' });
+ */
+function sqlText(name, args) {
+    if (name !== 'query_clickhouse' && name !== 'query_postgres') {
+        return '';
+    }
+    if (args && typeof args.sql === 'string') {
+        return args.sql;
+    }
+    return '';
+}
+
+/**
+ * Builds the common journal fields.
+ *
+ * @param {object} ctx - caller and writers
+ * @param {string} name - tool or resource name
+ * @param {string} status - ok or error
+ * @param {number} durationMs - elapsed milliseconds
+ * @returns {object} journal record
+ *
+ * @example
+ *   base({ caller: 'analyst' }, 'state', 'ok', 4);
+ */
+function base(ctx, name, status, durationMs) {
+    return {
+        caller: ctx.caller,
+        durationMs,
+        name,
+        status,
+        ts: new Date().toISOString()
+    };
+}
+
+/**
+ * Adds capped SQL text and a collapsed shape for query tools.
+ *
+ * @param {object} record - journal record
+ * @param {string} name - tool or resource name
+ * @param {object} [args] - tool arguments
+ * @returns {object} record
+ *
+ * @example
+ *   withSql({ name: 'state' }, 'state');
+ */
+function withSql(record, name, args) {
+    const sql = sqlText(name, args);
+    if (sql.length === 0) {
+        return record;
+    }
+    return {
+        ...record,
+        shape: cap(sqlShape(sql)),
+        sql: cap(sql)
+    };
+}
+
+/**
+ * Writes one JSON line and counts the call.
+ *
+ * @param {object} ctx - caller, journal, metrics
+ * @param {string} name - tool or resource name
+ * @param {string} status - ok or error
+ * @param {number} started - epoch milliseconds
+ * @param {object} [args] - tool arguments
+ * @returns {void}
+ *
+ * @example
+ *   note({ caller: 'analyst', journal() {}, metrics: { mark() {} } }, 'state', 'ok', Date.now());
+ */
+export default function note(ctx, name, status, started, args) {
+    const durationMs = Date.now() - started;
+    const record = base(ctx, name, status, durationMs);
+    ctx.metrics.mark(name, status);
+    ctx.journal(`${JSON.stringify(withSql(record, name, args))}\n`);
+}

package/src/application/mcp/mcpMetrics.js

@@ -0,0 +1,69 @@
+/**
+ * Escapes a Prometheus label value.
+ *
+ * @param {string} value - raw label
+ * @returns {string} escaped label
+ *
+ * @example
+ *   escapeLabel('query_clickhouse');
+ */
+function escapeLabel(value) {
+    return String(value).replace(/\\/gu, '\\\\').replace(/"/gu, '\\"').replace(/\n/gu, '\\n');
+}
+
+/**
+ * Renders counters and gauges as Prometheus text.
+ *
+ * @param {Map<string, number>} calls - tool and status counts
+ * @param {object} inflight - counts by engine
+ * @returns {string} exposition
+ *
+ * @example
+ *   render(new Map(), { clickhouse: 0, plant: 0, postgres: 0 });
+ */
+function render(calls, inflight) {
+    const lines = ['# TYPE mcp_calls_total counter'];
+    for (const [key, count] of calls) {
+        const parts = key.split('\u0000');
+        lines.push(`mcp_calls_total{tool="${escapeLabel(parts[0])}",status="${escapeLabel(parts[1])}"} ${count}`);
+    }
+    lines.push('# TYPE mcp_inflight gauge');
+    lines.push(`mcp_inflight{engine="clickhouse"} ${inflight.clickhouse}`);
+    lines.push(`mcp_inflight{engine="plant"} ${inflight.plant}`);
+    lines.push(`mcp_inflight{engine="postgres"} ${inflight.postgres}`);
+    return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Prometheus text for analytics MCP calls.
+ *
+ * Labels are tool and status on the counter, and engine on the in-flight gauge.
+ * Caller, machine, and SQL are not labels.
+ *
+ * @returns {object} begin, end, mark, and text
+ *
+ * @example
+ *   const metrics = mcpMetrics();
+ *   metrics.mark('state', 'ok');
+ *   metrics.text();
+ */
+export default function mcpMetrics() {
+    const calls = new Map();
+    const inflight = { clickhouse: 0, plant: 0, postgres: 0 };
+    return Object.freeze({
+        begin(engine) {
+            inflight[engine] += 1;
+        },
+        end(engine) {
+            inflight[engine] -= 1;
+        },
+        mark(tool, status) {
+            const key = `${tool}\u0000${status}`;
+            const count = calls.get(key) || 0;
+            calls.set(key, count + 1);
+        },
+        text() {
+            return render(calls, inflight);
+        }
+    });
+}