@jagilber-org/index-server 1.22.0

package/dist/server/multiInstanceStartup.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startMultiInstanceMode = startMultiInstanceMode;
+const registry_1 = require("./registry");
+const LeaderElection_js_1 = require("../dashboard/server/LeaderElection.js");
+const HttpTransport_js_1 = require("../dashboard/server/HttpTransport.js");
+const ThinClient_js_1 = require("../dashboard/server/ThinClient.js");
+/**
+ * Start multi-instance leader or follower behavior when enabled by runtime config.
+ * Preserves the existing leader election and follower proxy flow from the server entrypoint.
+ */
+async function startMultiInstanceMode(dashboardHost, runtime) {
+    const instanceMode = runtime.server.instanceMode;
+    if (instanceMode !== 'leader' && instanceMode !== 'auto') {
+        if (instanceMode !== 'standalone') {
+            process.stderr.write(`[startup] Instance mode=${instanceMode} (follower mode requires thin-client entry point)\n`);
+        }
+        return;
+    }
+    try {
+        const stateDir = runtime.dashboard.admin.stateDir;
+        const leaderPort = runtime.server.leaderPort;
+        const leaderHost = dashboardHost || '127.0.0.1';
+        const election = new LeaderElection_js_1.LeaderElection({
+            stateDir,
+            port: leaderPort,
+            host: leaderHost,
+            heartbeatIntervalMs: runtime.server.heartbeatIntervalMs,
+            staleThresholdMs: runtime.server.staleThresholdMs,
+        });
+        const role = election.start();
+        process.stderr.write(`[startup] Instance mode=${instanceMode} elected=${role} pid=${process.pid}\n`);
+        if (role === 'leader') {
+            const express = (await import('express')).default;
+            const mcpApp = express();
+            mcpApp.use('/mcp', (0, HttpTransport_js_1.createMcpTransportRoutes)());
+            const transportLocation = `${leaderHost}:${leaderPort}/mcp`;
+            const mcpServer = mcpApp.listen(leaderPort, leaderHost, () => {
+                process.stderr.write(`[startup] MCP HTTP transport listening on ${transportLocation}\n`);
+                process.stderr.write(`[startup] Thin clients can connect via INDEX_SERVER_STATE_DIR=${stateDir}\n`);
+            });
+            mcpServer.on('error', (err) => {
+                process.stderr.write(`[startup] MCP HTTP transport failed: ${err.message}\n`);
+                if (err.code === 'EADDRINUSE') {
+                    process.stderr.write(`[startup] Port ${leaderPort} is already in use. Check INDEX_SERVER_LEADER_PORT or other services on this port.\n`);
+                    process.stderr.write(`[startup] Releasing leader lock and continuing as standalone.\n`);
+                    election.stop();
+                }
+                else {
+                    election.stop();
+                }
+            });
+            process.on('exit', () => {
+                election.stop();
+                try {
+                    mcpServer.close();
+                }
+                catch { /* ignore */ }
+            });
+            return;
+        }
+        process.stderr.write(`[startup] Running as follower -- leader at pid=${election.leaderInfo?.pid} port=${election.leaderInfo?.port}\n`);
+        const thinClient = new ThinClient_js_1.ThinClient({ stateDir });
+        const leaderUrl = thinClient.discoverLeader();
+        process.stderr.write(`[startup] Follower proxy target: ${leaderUrl ?? 'pending discovery'}\n`);
+        (0, registry_1.installHandlerProxy)(async (tool, params) => {
+            const response = await thinClient.sendRpc(tool, params);
+            if (response.error) {
+                throw new Error(`Leader error [${response.error.code}]: ${response.error.message}`);
+            }
+            return response.result;
+        });
+        process.stderr.write(`[startup] Handler proxy installed -- all tool calls forwarded to leader\n`);
+        election.on('leader-lost', () => {
+            process.stderr.write(`[startup] Leader lost -- attempting promotion\n`);
+        });
+        election.on('promoted', () => {
+            process.stderr.write(`[startup] Promoted to leader -- starting HTTP transport before removing proxy\n`);
+            (async () => {
+                try {
+                    const express = (await import('express')).default;
+                    const mcpApp = express();
+                    mcpApp.use('/mcp', (0, HttpTransport_js_1.createMcpTransportRoutes)());
+                    const transportLocation = `${leaderHost}:${leaderPort}/mcp`;
+                    const mcpServer = mcpApp.listen(leaderPort, leaderHost, () => {
+                        (0, registry_1.installHandlerProxy)(null);
+                        process.stderr.write(`[startup] MCP HTTP transport listening on ${transportLocation}\n`);
+                        process.stderr.write(`[startup] Handler proxy removed -- serving requests locally\n`);
+                    });
+                    mcpServer.on('error', (err) => {
+                        process.stderr.write(`[startup] Post-promotion HTTP transport failed: ${err.message}\n`);
+                        if (err.code === 'EADDRINUSE') {
+                            process.stderr.write(`[startup] Port ${leaderPort} in use after promotion -- retrying in 2s\n`);
+                            setTimeout(() => {
+                                try {
+                                    mcpServer.close();
+                                    mcpApp.listen(leaderPort, leaderHost, () => {
+                                        (0, registry_1.installHandlerProxy)(null);
+                                        process.stderr.write(`[startup] MCP HTTP transport listening on retry\n`);
+                                    });
+                                }
+                                catch (retryErr) {
+                                    process.stderr.write(`[startup] Port retry failed: ${retryErr}\n`);
+                                    election.stop();
+                                }
+                            }, 2000);
+                        }
+                        else {
+                            election.stop();
+                        }
+                    });
+                    process.on('exit', () => {
+                        try {
+                            mcpServer.close();
+                        }
+                        catch { /* ignore */ }
+                    });
+                }
+                catch (e) {
+                    process.stderr.write(`[startup] Post-promotion HTTP setup failed: ${e}\n`);
+                }
+            })();
+        });
+        process.on('exit', () => {
+            election.stop();
+            thinClient.stop();
+        });
+    }
+    catch (e) {
+        process.stderr.write(`[startup] Leader election failed: ${e}\n`);
+    }
+}

package/dist/server/registry.d.ts

@@ -0,0 +1,44 @@
+export type Handler<TParams = unknown> = (params: TParams) => Promise<unknown> | unknown;
+interface MetricRecord {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+/**
+ * Register a tool handler in the in-process registry, wrapping it with metrics,
+ * audit logging, correlation IDs, and optional proxy forwarding.
+ * @param name - Tool name used to route incoming requests
+ * @param fn - Handler function; may return a plain value or a Promise
+ */
+export declare function registerHandler<TParams = unknown>(name: string, fn: Handler<TParams>): void;
+/**
+ * Look up a registered (wrapped) handler by name.
+ * @param name - Tool name to look up
+ * @returns The wrapped handler, or `undefined` if not registered
+ */
+export declare function getHandler(name: string): Handler<unknown>;
+/**
+ * Return the raw (unwrapped) handler that always executes locally,
+ * bypassing any installed proxy. Used by HttpTransport so the leader
+ * never accidentally routes its own handler calls through a proxy.
+ * @param name - Tool name to look up
+ * @returns The raw unwrapped handler, or `undefined` if not registered
+ */
+export declare function getLocalHandler(name: string): Handler<unknown>;
+export declare function installHandlerProxy(fn: ((tool: string, params: unknown) => Promise<unknown>) | null): void;
+/**
+ * Return the currently installed proxy function, or `null` if no proxy is active.
+ * @returns The proxy function, or `null`
+ */
+export declare function getHandlerProxy(): ((tool: string, params: unknown) => Promise<unknown>) | null;
+/**
+ * Return a sorted list of all registered tool method names.
+ * @returns Array of method name strings in alphabetical order
+ */
+export declare function listRegisteredMethods(): string[];
+/**
+ * Return the raw per-tool metrics record map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by tool name
+ */
+export declare function getMetricsRaw(): Record<string, MetricRecord>;
+export {};

package/dist/server/registry.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHandler = registerHandler;
+exports.getHandler = getHandler;
+exports.getLocalHandler = getLocalHandler;
+exports.installHandlerProxy = installHandlerProxy;
+exports.getHandlerProxy = getHandlerProxy;
+exports.listRegisteredMethods = listRegisteredMethods;
+exports.getMetricsRaw = getMetricsRaw;
+// Lightweight in-process tool registry used exclusively by the SDK server path.
+// Replaces the prior custom JSON-RPC transport layer.
+const logger_1 = require("../services/logger");
+const responseEnvelope_1 = require("../services/responseEnvelope");
+const auditLog_1 = require("../services/auditLog");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// Dashboard metrics integration: bridge per-tool execution to global MetricsCollector
+// so the admin panel performance & tool counters reflect live activity. Previously the
+// dashboard showed zeros because recordToolCall was never invoked along the runtime path.
+const MetricsCollector_js_1 = require("../dashboard/server/MetricsCollector.js");
+const handlers = {};
+// Raw (unwrapped) handlers that always execute locally - never go through proxy.
+// Used by HttpTransport so the leader always runs handlers locally even when
+// a proxy is installed in this process (e.g., same-process test scenarios).
+const localHandlers = {};
+const metrics = {};
+function recordMetric(name, ms) {
+    let rec = metrics[name];
+    if (!rec) {
+        rec = { count: 0, totalMs: 0, maxMs: 0 };
+        metrics[name] = rec;
+    }
+    rec.count++;
+    rec.totalMs += ms;
+    if (ms > rec.maxMs)
+        rec.maxMs = ms;
+}
+/**
+ * Register a tool handler in the in-process registry, wrapping it with metrics,
+ * audit logging, correlation IDs, and optional proxy forwarding.
+ * @param name - Tool name used to route incoming requests
+ * @param fn - Handler function; may return a plain value or a Promise
+ */
+function registerHandler(name, fn) {
+    // Always log tool lifecycle events (previously gated by INDEX_SERVER_LOG_TOOLS)
+    // Lazily resolve singleton (avoid throwing if dashboard disabled – metrics collector module
+    // still exports a singleton even when dashboard not started).
+    const collector = (() => { try {
+        return (0, MetricsCollector_js_1.getMetricsCollector)();
+    }
+    catch {
+        return null;
+    } })();
+    const wrapped = async (params) => {
+        const corr = (0, logger_1.newCorrelationId)();
+        // If a proxy is installed (follower mode), forward to leader instead of running locally
+        if (proxyFn) {
+            try {
+                (0, logger_1.log)('INFO', `[registry] → ${name} (proxy)`, { tool: name, correlationId: corr });
+            }
+            catch { /* ignore */ }
+            const startNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+            try {
+                const result = await proxyFn(name, params);
+                const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+                const ms = Number(endNs - startNs) / 1_000_000;
+                recordMetric(name, ms);
+                try {
+                    collector?.recordToolCall(name, true, ms);
+                }
+                catch { /* ignore */ }
+                try {
+                    (0, logger_1.log)('INFO', `[registry] ← ${name} (proxy)`, { tool: name, correlationId: corr, ms });
+                }
+                catch { /* ignore */ }
+                return result;
+            }
+            catch (e) {
+                const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+                const ms = Number(endNs - startNs) / 1_000_000;
+                recordMetric(name, ms);
+                try {
+                    collector?.recordToolCall(name, false, ms, 'proxy_error');
+                }
+                catch { /* ignore */ }
+                try {
+                    (0, logger_1.log)('ERROR', `[registry] Tool proxy error: ${name}`, { tool: name, correlationId: corr, detail: e instanceof Error ? e.stack : String(e) });
+                }
+                catch { /* ignore */ }
+                throw e;
+            }
+        }
+        const startNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+        const timingEnabled = process.env.INDEX_SERVER_ADD_TIMING === '1' || (0, runtimeConfig_1.getRuntimeConfig)().mutation.dispatcherTiming;
+        let phaseMarks;
+        if (timingEnabled) {
+            phaseMarks = [{ p: 'start', t: Date.now() }];
+        }
+        try {
+            (0, logger_1.log)('INFO', `[registry] → ${name}`, { tool: name, correlationId: corr });
+        }
+        catch { /* logging should not break */ }
+        let success = false;
+        let errorType;
+        try {
+            const result = await (0, auditLog_1.runWithCorrelation)(corr, () => Promise.resolve(fn(params)));
+            if (timingEnabled && phaseMarks) {
+                phaseMarks.push({ p: 'afterFn', t: Date.now() });
+            }
+            success = true;
+            const wrappedResp = (0, responseEnvelope_1.wrapResponse)(result);
+            if (timingEnabled) {
+                try {
+                    const endTs = Date.now();
+                    phaseMarks.push({ p: 'endPreWrap', t: endTs });
+                    const phases = phaseMarks;
+                    wrappedResp.__timing = { tool: name, phases };
+                }
+                catch { /* ignore timing embed errors */ }
+            }
+            return wrappedResp;
+        }
+        catch (e) {
+            try {
+                (0, logger_1.log)('ERROR', `[registry] Tool error: ${name}`, { tool: name, correlationId: corr, detail: e instanceof Error ? e.stack : String(e) });
+            }
+            catch { /* ignore */ }
+            // Best-effort classification for dashboard error breakdown
+            try {
+                const errObj = e;
+                // Narrow progressively without casting to any to satisfy eslint no-explicit-any rule.
+                if (typeof errObj === 'object' && errObj !== null) {
+                    const maybeCode = errObj.code;
+                    if (Number.isSafeInteger(maybeCode)) {
+                        errorType = `code_${maybeCode}`;
+                    }
+                    else {
+                        const maybeData = errObj.data;
+                        if (typeof maybeData === 'object' && maybeData !== null && typeof maybeData.reason === 'string') {
+                            errorType = String(maybeData.reason);
+                        }
+                        else if (typeof errObj.reason === 'string') {
+                            errorType = String(errObj.reason);
+                        }
+                        else {
+                            errorType = 'error';
+                        }
+                    }
+                }
+                else {
+                    errorType = 'error';
+                }
+            }
+            catch { /* ignore classification errors */ }
+            throw e;
+        }
+        finally {
+            const endNs = typeof process.hrtime === 'function' ? process.hrtime.bigint() : BigInt(Date.now()) * 1000000n;
+            const ms = Number(endNs - startNs) / 1_000_000;
+            recordMetric(name, ms);
+            if (timingEnabled && phaseMarks) {
+                try {
+                    phaseMarks.push({ p: 'finally', t: Date.now() });
+                }
+                catch { /* ignore */ }
+            }
+            // Feed global dashboard metrics (safe no-op if collector absent). This enables:
+            //  - requestsPerMinute (rolling window)
+            //  - successRate / errorRate
+            //  - per-tool call counts & avg response time
+            try {
+                collector?.recordToolCall(name, success, ms, success ? undefined : errorType);
+            }
+            catch { /* never block tool path */ }
+            try {
+                (0, auditLog_1.logToolAudit)(name, success, ms, corr, success ? undefined : errorType);
+            }
+            catch { /* never block tool path */ }
+            try {
+                (0, logger_1.log)('INFO', `[registry] ← ${name}`, { tool: name, correlationId: corr, ms });
+            }
+            catch { /* ignore */ }
+        }
+    };
+    handlers[name] = wrapped;
+    localHandlers[name] = fn;
+}
+/**
+ * Look up a registered (wrapped) handler by name.
+ * @param name - Tool name to look up
+ * @returns The wrapped handler, or `undefined` if not registered
+ */
+function getHandler(name) {
+    return handlers[name];
+}
+/**
+ * Return the raw (unwrapped) handler that always executes locally,
+ * bypassing any installed proxy. Used by HttpTransport so the leader
+ * never accidentally routes its own handler calls through a proxy.
+ * @param name - Tool name to look up
+ * @returns The raw unwrapped handler, or `undefined` if not registered
+ */
+function getLocalHandler(name) {
+    return localHandlers[name];
+}
+/**
+ * Install a proxy function that intercepts all handler calls.
+ * Used by follower instances to forward tool calls to the leader.
+ * The proxy receives (toolName, params) and returns the result.
+ * Pass null to remove the proxy (e.g., on promotion to leader).
+ * @param fn - Proxy function to install, or `null` to remove the current proxy
+ */
+let proxyFn = null;
+function installHandlerProxy(fn) {
+    proxyFn = fn;
+}
+/**
+ * Return the currently installed proxy function, or `null` if no proxy is active.
+ * @returns The proxy function, or `null`
+ */
+function getHandlerProxy() {
+    return proxyFn;
+}
+/**
+ * Return a sorted list of all registered tool method names.
+ * @returns Array of method name strings in alphabetical order
+ */
+function listRegisteredMethods() {
+    return Object.keys(handlers).sort();
+}
+/**
+ * Return the raw per-tool metrics record map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by tool name
+ */
+function getMetricsRaw() {
+    return metrics;
+}

package/dist/server/sdkServer.d.ts

@@ -0,0 +1,8 @@
+import '../services/toolHandlers';
+/**
+ * Create and configure an MCP SDK server instance with the full tool registry.
+ * @param ServerClass - The MCP SDK Server constructor (loaded dynamically to avoid ESM/CJS conflicts)
+ * @returns Configured SDK server instance with all tool handlers registered
+ */
+export declare function createSdkServer(ServerClass: any): any;
+export declare function startSdkServer(): Promise<void>;