@yarkivaev/scada 2.3.85 → 2.3.87

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`, `coverageCursor`, `sqlGuard` | Analytics MCP, path index, coverage spans, checkpoint-or-sample cursor, read-only SQL guard |
 
 Subpath exports:
 

package/index.js

@@ -86,3 +86,8 @@ 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 coverageCursor } from './src/application/mcp/coverageCursor.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.85",
+  "version": "2.3.87",
   "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/coverageCursor.js

@@ -0,0 +1,116 @@
+const EMPTY = '1970-01-01T00:00:00.000Z';
+
+/**
+ * Reads epoch milliseconds from a cursor value.
+ *
+ * @param {Date|number|string|object} value - instant or { at }
+ * @returns {number} epoch milliseconds, or NaN
+ *
+ * @example
+ *   instant({ at: '2024-11-02T03:04:05.137Z' });
+ */
+function instant(value) {
+    if (value && typeof value === 'object' && !(value instanceof Date) && Object.hasOwn(value, 'at')) {
+        return instant(value.at);
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (value === undefined || value === null || value === '') {
+        return Number.NaN;
+    }
+    return Date.parse(String(value));
+}
+
+/**
+ * Formats a covered instant, treating epoch and gaps as empty.
+ *
+ * @param {Date|number|string|object} value - instant
+ * @returns {string} ISO instant, or the empty cursor
+ *
+ * @example
+ *   covered('2024-11-02T03:04:05.137Z');
+ */
+function covered(value) {
+    const at = instant(value);
+    if (!Number.isFinite(at) || at <= 0) {
+        return EMPTY;
+    }
+    return new Date(at).toISOString();
+}
+
+/**
+ * Latest sample instant, or the empty cursor when none exist.
+ *
+ * @param {Array} samples - instants or objects with ts
+ * @returns {string} ISO instant
+ *
+ * @example
+ *   latest([{ ts: '2024-11-02T03:04:05.137Z' }]);
+ */
+function latest(samples) {
+    const rows = Array.isArray(samples) ? samples : [];
+    let mark = 0;
+    for (const sample of rows) {
+        const raw = sample && typeof sample === 'object' && Object.hasOwn(sample, 'ts')
+            ? sample.ts
+            : sample;
+        const at = instant(raw);
+        if (Number.isFinite(at) && at > mark) {
+            mark = at;
+        }
+    }
+    return mark > 0 ? new Date(mark).toISOString() : EMPTY;
+}
+
+/**
+ * Reads the newest ingest checkpoint for a machine.
+ *
+ * @param {object|undefined} pool - pg pool
+ * @param {string} machine - machine id
+ * @returns {Promise<string>} ISO instant, or the empty cursor
+ *
+ * @example
+ *   checkpoint(pool, 'machine1');
+ */
+async function checkpoint(pool, machine) {
+    if (!pool) {
+        return EMPTY;
+    }
+    const result = await pool.query(
+        'SELECT cursor_at FROM ingest_checkpoints WHERE machine = $1 ORDER BY cursor_at DESC LIMIT 1',
+        [machine]
+    );
+    if (result.rows.length === 0) {
+        return EMPTY;
+    }
+    return covered(result.rows[0].cursor_at);
+}
+
+/**
+ * Coverage cursor: ingest checkpoint, else latest metric instant.
+ *
+ * Central ingest does not write ingest_checkpoints. When that table is empty,
+ * the latest sample is the covered bound so coverageSpans can paint present
+ * and absent instead of the whole window unknown.
+ *
+ * @param {object|undefined} pool - pg pool
+ * @param {Function} samples - async (args) => sample list
+ * @returns {Function} cursor port ({ machine, path }) => ISO instant
+ *
+ * @example
+ *   coverageCursor(pool, ({ path }) => ports.samples({ path }))({ machine: 'm1' });
+ */
+export default function coverageCursor(pool, samples) {
+    return async function bound(args) {
+        const machine = args.machine || args.path;
+        const mark = await checkpoint(pool, machine);
+        if (instant(mark) > 0) {
+            return mark;
+        }
+        return latest(await samples(args));
+    };
+}

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);
+    });
+}