@yarkivaev/scada 2.3.84 → 2.3.86

package/src/application/mcp/mcpObserve.js

@@ -0,0 +1,168 @@
+import note from './mcpJournal.js';
+
+/**
+ * Maps a tool name to the engine gauge label.
+ *
+ * @param {string} name - tool name
+ * @returns {string} clickhouse, postgres, or plant
+ *
+ * @example
+ *   engineOf('query_clickhouse');
+ */
+function engineOf(name) {
+    if (name === 'query_clickhouse') {
+        return 'clickhouse';
+    }
+    if (name === 'query_postgres') {
+        return 'postgres';
+    }
+    return 'plant';
+}
+
+/**
+ * Reads ok or error from a tool result.
+ *
+ * @param {object} result - tool result
+ * @returns {string} status
+ *
+ * @example
+ *   statusOf({ isError: true });
+ */
+function statusOf(result) {
+    if (result && result.isError === true) {
+        return 'error';
+    }
+    return 'ok';
+}
+
+/**
+ * Runs a callback and keeps the status and any thrown error.
+ *
+ * @param {Function} cb - tool or resource callback
+ * @param {object} args - first callback argument
+ * @param {object} extra - SDK extra
+ * @returns {Promise<object>} outcome
+ *
+ * @example
+ *   invoke(() => ({ content: [] }), {}, {});
+ */
+async function invoke(cb, args, extra) {
+    try {
+        const result = await cb(args, extra);
+        return { result, status: statusOf(result) };
+    } catch (err) {
+        return { err, status: 'error' };
+    }
+}
+
+/**
+ * Returns the callback result or rethrows its error.
+ *
+ * @param {object} outcome - invoke outcome
+ * @returns {object} result
+ *
+ * @example
+ *   settle({ result: { content: [] }, status: 'ok' });
+ */
+function settle(outcome) {
+    if (outcome.err) {
+        throw outcome.err;
+    }
+    return outcome.result;
+}
+
+/**
+ * Times one tool call, counts it, and tracks the engine gauge.
+ *
+ * @param {string} name - tool name
+ * @param {object} args - tool arguments
+ * @param {object} extra - SDK extra
+ * @param {Function} cb - tool callback
+ * @param {object} ctx - journal context
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   trackedTool('state', {}, {}, () => ({ content: [] }), ctx);
+ */
+async function trackedTool(name, args, extra, cb, ctx) {
+    const engine = engineOf(name);
+    const started = Date.now();
+    ctx.metrics.begin(engine);
+    const outcome = await invoke(cb, args, extra);
+    ctx.metrics.end(engine);
+    note(ctx, name, outcome.status, started, args);
+    return settle(outcome);
+}
+
+/**
+ * Times one resource read.
+ *
+ * @param {string} uri - resource URI
+ * @param {object} target - SDK uri argument
+ * @param {object} extra - SDK extra
+ * @param {Function} cb - read callback
+ * @param {object} ctx - journal context
+ * @returns {Promise<object>} resource result
+ *
+ * @example
+ *   trackedRead('plant://topology', new URL('plant://topology'), {}, () => ({}), ctx);
+ */
+async function trackedRead(uri, target, extra, cb, ctx) {
+    const started = Date.now();
+    const outcome = await invoke(cb, target, extra);
+    note(ctx, String(uri), outcome.status, started);
+    return settle(outcome);
+}
+
+/**
+ * Wraps registerTool so every tools/call is journaled.
+ *
+ * @param {Function} registerTool - McpServer.registerTool
+ * @param {object} ctx - journal context
+ * @returns {Function} wrapped register
+ *
+ * @example
+ *   wrapTool(server.registerTool, ctx);
+ */
+function wrapTool(registerTool, ctx) {
+    return function wrap(name, config, cb) {
+        return registerTool(name, config, (args, extra) => {
+            return trackedTool(name, args, extra, cb, ctx);
+        });
+    };
+}
+
+/**
+ * Wraps registerResource so every resources/read is journaled.
+ *
+ * @param {Function} registerResource - McpServer.registerResource
+ * @param {object} ctx - journal context
+ * @returns {Function} wrapped register
+ *
+ * @example
+ *   wrapResource(server.registerResource, ctx);
+ */
+function wrapResource(registerResource, ctx) {
+    return function wrap(name, uri, config, cb) {
+        return registerResource(name, uri, config, (target, extra) => {
+            return trackedRead(uri, target, extra, cb, ctx);
+        });
+    };
+}
+
+/**
+ * Journals later tool and resource registrations on this server.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ctx - caller, journal, metrics
+ * @returns {void}
+ *
+ * @example
+ *   observe(server, { caller: 'analyst', journal() {}, metrics });
+ */
+export default function observe(server, ctx) {
+    const registerResource = server.registerResource.bind(server);
+    const registerTool = server.registerTool.bind(server);
+    server.registerResource = wrapResource(registerResource, ctx);
+    server.registerTool = wrapTool(registerTool, ctx);
+}

package/src/application/mcp/mcpQuery.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import sqlGuard from '../../domain/sql/sqlGuard.js';
+import { capRows, toolText } from './mcpText.js';
+
+/**
+ * Guards SQL, runs the port, and caps rows.
+ *
+ * @param {string} sql - statement
+ * @param {string} engine - clickhouse or postgres
+ * @param {Function} query - port
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   runQuery('SELECT 1', 'postgres', () => []);
+ */
+async function runQuery(sql, engine, query) {
+    const guarded = sqlGuard(sql, engine);
+    const rows = await query(guarded);
+    return toolText(capRows(rows));
+}
+
+/**
+ * Registers read-only ClickHouse SQL.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @returns {void}
+ *
+ * @example
+ *   registerClickhouse(server, ports);
+ */
+function registerClickhouse(server, ports) {
+    server.registerTool('query_clickhouse', {
+        description: 'Read-only ClickHouse SQL with a ts predicate',
+        inputSchema: {
+            sql: z.string()
+        }
+    }, (args) => {
+        return runQuery(args.sql, 'clickhouse', ports.queryClickhouse);
+    });
+}
+
+/**
+ * Registers read-only Postgres SQL when a standby port exists.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @returns {void}
+ *
+ * @example
+ *   registerPostgres(server, ports);
+ */
+function registerPostgres(server, ports) {
+    if (typeof ports.queryPostgres !== 'function') {
+        return;
+    }
+    server.registerTool('query_postgres', {
+        description: 'Read-only Postgres SQL',
+        inputSchema: {
+            sql: z.string()
+        }
+    }, (args) => {
+        return runQuery(args.sql, 'postgres', ports.queryPostgres);
+    });
+}
+
+/**
+ * Registers SQL tools. Postgres is omitted without a standby port.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @returns {void}
+ *
+ * @example
+ *   registerQueries(server, ports);
+ */
+export default function registerQueries(server, ports) {
+    registerClickhouse(server, ports);
+    registerPostgres(server, ports);
+}

package/src/application/mcp/mcpReads.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { capMeasurements, capRows, toolText } from './mcpText.js';
+
+/**
+ * Loads rows for one namespace path and caps them.
+ *
+ * @param {object} tree - namespaceTree
+ * @param {string} path - namespace path
+ * @param {Function} load - port call
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   loadRows(tree, 'site', () => []);
+ */
+async function loadRows(tree, path, load) {
+    tree.resolve(path);
+    const rows = await load();
+    return toolText(capRows(rows));
+}
+
+/**
+ * Adds age and live or stale from the node silence threshold.
+ *
+ * @param {object} raw - state port payload
+ * @param {number} silenceSeconds - liveness seconds
+ * @returns {object} state payload
+ *
+ * @example
+ *   fresh({ found: false }, 60);
+ */
+function fresh(raw, silenceSeconds) {
+    if (raw && raw.found === true && typeof raw.time === 'string') {
+        const ageMs = Date.now() - Date.parse(raw.time);
+        const freshness = ageMs <= silenceSeconds * 1000 ? 'live' : 'stale';
+        return { ...raw, ageMs, freshness };
+    }
+    return raw;
+}
+
+/**
+ * Reads metric points for namespace paths.
+ *
+ * @param {object} args - paths, from, to, step, mode
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   runMeasurements({ paths: ['site'], from: 'a', to: 'b', step: 60 }, ports, tree);
+ */
+async function runMeasurements(args, ports, tree) {
+    for (const path of args.paths) {
+        tree.resolve(path);
+    }
+    const raw = await ports.measurements(args);
+    return toolText(capMeasurements(raw, args.step));
+}
+
+/**
+ * Reads the latest values under a path.
+ *
+ * @param {object} args - path
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   runState({ path: 'site' }, ports, tree);
+ */
+async function runState(args, ports, tree) {
+    const node = tree.resolve(args.path);
+    const raw = await ports.state(args);
+    return toolText(fresh(raw, node.silenceSeconds));
+}
+
+/**
+ * Registers the measurements tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerMeasurements(server, ports, tree);
+ */
+function registerMeasurements(server, ports, tree) {
+    server.registerTool('measurements', {
+        description: 'Metric points for namespace paths over an interval',
+        inputSchema: {
+            from: z.string(),
+            mode: z.string().optional(),
+            paths: z.array(z.string()),
+            step: z.number(),
+            to: z.string()
+        }
+    }, (args) => {
+        return runMeasurements(args, ports, tree);
+    });
+}
+
+/**
+ * Registers the segments tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerSegments(server, ports, tree);
+ */
+function registerSegments(server, ports, tree) {
+    server.registerTool('segments', {
+        description: 'Timeline segments for a namespace path',
+        inputSchema: {
+            from: z.string(),
+            kinds: z.array(z.string()).optional(),
+            path: z.string(),
+            to: z.string()
+        }
+    }, (args) => {
+        return loadRows(tree, args.path, () => {
+            return ports.segments(args);
+        });
+    });
+}
+
+/**
+ * Registers the operations tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerOperations(server, ports, tree);
+ */
+function registerOperations(server, ports, tree) {
+    server.registerTool('operations', {
+        description: 'Operation rows for a namespace path and an opaque kind',
+        inputSchema: {
+            from: z.string(),
+            kind: z.string(),
+            path: z.string(),
+            to: z.string()
+        }
+    }, (args) => {
+        return loadRows(tree, args.path, () => {
+            return ports.operations(args);
+        });
+    });
+}
+
+/**
+ * Registers the alerts tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerAlerts(server, ports, tree);
+ */
+function registerAlerts(server, ports, tree) {
+    server.registerTool('alerts', {
+        description: 'Alert rows for a namespace path',
+        inputSchema: {
+            from: z.string(),
+            path: z.string(),
+            to: z.string()
+        }
+    }, (args) => {
+        return loadRows(tree, args.path, () => {
+            return ports.alerts(args);
+        });
+    });
+}
+
+/**
+ * Registers the state tool.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerState(server, ports, tree);
+ */
+function registerState(server, ports, tree) {
+    server.registerTool('state', {
+        description: 'Latest readings under a namespace path',
+        inputSchema: {
+            path: z.string()
+        }
+    }, (args) => {
+        return runState(args, ports, tree);
+    });
+}
+
+/**
+ * Registers measurement, segment, operation, alert, and state tools.
+ *
+ * @param {object} server - McpServer
+ * @param {object} ports - read ports
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerReads(server, ports, tree);
+ */
+export default function registerReads(server, ports, tree) {
+    registerMeasurements(server, ports, tree);
+    registerSegments(server, ports, tree);
+    registerOperations(server, ports, tree);
+    registerAlerts(server, ports, tree);
+    registerState(server, ports, tree);
+}

package/src/application/mcp/mcpResources.js

@@ -0,0 +1,106 @@
+/**
+ * Parent path of a node, or an empty string at the root.
+ *
+ * @param {string} path - namespace path
+ * @returns {string} parent path
+ *
+ * @example
+ *   parentOf('site/shop');
+ */
+function parentOf(path) {
+    const cut = path.lastIndexOf('/');
+    if (cut < 0) {
+        return '';
+    }
+    return path.slice(0, cut);
+}
+
+/**
+ * Topology resource body without source topics.
+ *
+ * @param {object} tree - namespaceTree
+ * @returns {Array<object>} nodes
+ *
+ * @example
+ *   topology(tree);
+ */
+function topology(tree) {
+    return tree.list().map((node) => {
+        return {
+            kind: node.kind,
+            liveness: node.silenceSeconds,
+            parent: parentOf(node.path),
+            path: node.path,
+            title: node.title
+        };
+    });
+}
+
+/**
+ * Binding resource body: path, source topic, and unit.
+ *
+ * @param {object} tree - namespaceTree
+ * @returns {Array<object>} bindings
+ *
+ * @example
+ *   bindings(tree);
+ */
+function bindings(tree) {
+    return tree.list().filter((node) => {
+        return typeof node.source === 'string';
+    }).map((node) => {
+        return {
+            path: node.path,
+            topic: node.source,
+            unit: typeof node.unit === 'string' ? node.unit : ''
+        };
+    });
+}
+
+/**
+ * JSON resource contents for one URI.
+ *
+ * @param {string} uri - resource URI
+ * @param {object} payload - JSON body
+ * @returns {object} read result
+ *
+ * @example
+ *   body('plant://topology', []);
+ */
+function body(uri, payload) {
+    return {
+        contents: [{
+            mimeType: 'application/json',
+            text: JSON.stringify(payload),
+            uri
+        }]
+    };
+}
+
+/**
+ * Registers plant topology and source bindings.
+ *
+ * Topology has paths, kinds, titles, and liveness. Bindings map a path to a
+ * topic and a unit. Gateway topics are not part of topology.
+ *
+ * @param {object} server - McpServer
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerResources(server, tree);
+ */
+export default function registerResources(server, tree) {
+    server.registerResource('topology', 'plant://topology', {
+        description: 'Paths, kinds, titles, and liveness',
+        mimeType: 'application/json'
+    }, () => {
+        return body('plant://topology', topology(tree));
+    });
+    server.registerResource('bindings', 'plant://bindings', {
+        description: 'Source topic and unit for each bound path',
+        mimeType: 'application/json'
+    }, () => {
+        return body('plant://bindings', bindings(tree));
+    });
+}

package/src/application/mcp/mcpText.js

@@ -0,0 +1,106 @@
+/**
+ * Caps a row list at the analytics response limit.
+ *
+ * @param {Array} rows - port rows
+ * @returns {{rows: Array, truncated: boolean}} capped rows
+ *
+ * @example
+ *   capRows([{ id: 1 }]);
+ */
+export function capRows(rows) {
+    const list = Array.isArray(rows) ? rows : [];
+    return {
+        rows: list.slice(0, 200),
+        truncated: list.length > 200
+    };
+}
+
+/**
+ * Wraps a payload as MCP text content.
+ *
+ * @param {object} payload - JSON payload
+ * @returns {object} tool result
+ *
+ * @example
+ *   toolText({ rows: [] });
+ */
+export function toolText(payload) {
+    return {
+        content: [{
+            text: JSON.stringify(payload),
+            type: 'text'
+        }]
+    };
+}
+
+/**
+ * Reads a point list from an array or a points field.
+ *
+ * @param {Array|object} raw - port payload
+ * @returns {Array} points
+ *
+ * @example
+ *   readPoints({ points: [1] });
+ */
+function readPoints(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && Array.isArray(raw.points)) {
+        return raw.points;
+    }
+    return [];
+}
+
+/**
+ * Reads the step the port actually used.
+ *
+ * @param {Array|object} raw - port payload
+ * @param {number} step - requested step seconds
+ * @returns {number} step seconds
+ *
+ * @example
+ *   readStep({ points: [], step: 30 }, 15);
+ */
+function readStep(raw, step) {
+    if (raw && typeof raw.step === 'number') {
+        return raw.step;
+    }
+    return step;
+}
+
+/**
+ * Keeps a truncated flag supplied by the port.
+ *
+ * @param {Array|object} raw - port payload
+ * @returns {boolean} whether the port already truncated
+ *
+ * @example
+ *   flagged({ truncated: true });
+ */
+function flagged(raw) {
+    if (raw && raw.truncated === true) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Caps measurement points at 200 and reports the step.
+ *
+ * @param {Array|object} raw - port payload
+ * @param {number} step - requested step seconds
+ * @returns {object} points, step, truncated
+ *
+ * @example
+ *   capMeasurements([{ v: 1 }], 15);
+ */
+export function capMeasurements(raw, step) {
+    const points = readPoints(raw);
+    const truncated = points.length > 200 || flagged(raw);
+    return {
+        points: points.slice(0, 200),
+        step: readStep(raw, step),
+        truncated
+    };
+}