@yarkivaev/scada 2.3.85 → 2.3.87

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

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