@jagilber-org/index-server 1.22.0

package/dist/server/sdkServer.js

@@ -0,0 +1,299 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSdkServer = createSdkServer;
+exports.startSdkServer = startSdkServer;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * SDK-based MCP server bootstrap (dynamic require variant to work under CommonJS build).
+ * Uses the published dist/ subpath exports without relying on TS ESM moduleResolution.
+ *
+ * Orchestrates server creation and startup, delegating handshake/protocol logic to
+ * handshakeManager.ts and transport/dispatcher setup to transportFactory.ts.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const toolRegistry_1 = require("../services/toolRegistry");
+require("../services/toolHandlers");
+const registry_1 = require("./registry");
+const zod_1 = require("zod");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const handshakeManager_1 = require("./handshakeManager");
+const transportFactory_1 = require("./transportFactory");
+// ESM dynamic import used below for SDK modules.
+// We'll lazy-load ESM exports via dynamic import when starting.
+let StdioServerTransport;
+/**
+ * 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
+ */
+function createSdkServer(ServerClass) {
+    // Derive version from package.json (no artificial suffix so clients see real semantic version)
+    let version = '0.0.0';
+    const pkgCandidates = [
+        path_1.default.join(process.cwd(), 'package.json'),
+        path_1.default.join(__dirname, '..', '..', 'package.json'), // dist/server/../.. = repo root
+        path_1.default.join(__dirname, '..', 'package.json'), // fallback
+    ];
+    for (const pkgPath of pkgCandidates) {
+        try {
+            if (fs_1.default.existsSync(pkgPath)) {
+                const raw = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+                if (raw.version) {
+                    version = raw.version;
+                    break;
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
+    const server = new ServerClass({ name: 'index', version }, { capabilities: { tools: { listChanged: true } } });
+    server.__declaredVersion = version;
+    // Never emit tools/list_changed before ready. Wrap sendToolListChanged to enforce ordering.
+    try {
+        const origSendToolListChanged = server.sendToolListChanged?.bind(server);
+        if (origSendToolListChanged && !server.__listPatched) {
+            server.__listPatched = true;
+            server.sendToolListChanged = (...a) => {
+                if (!server.__readyNotified) {
+                    server.__pendingListChanged = true;
+                    (0, handshakeManager_1.record)('buffer_list_changed_pre_ready');
+                    return;
+                }
+                return origSendToolListChanged(...a);
+            };
+        }
+    }
+    catch { /* ignore */ }
+    // Track ready notification + whether initialize was seen (ordering guarantee)
+    server.__readyNotified = false;
+    server.__sawInitializeRequest = false;
+    server.__initResponseSent = false;
+    // Single fallback watchdog if ready somehow suppressed.
+    if ((0, handshakeManager_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                if (server.__sawInitializeRequest && !server.__readyNotified) {
+                    (0, handshakeManager_1.record)('watchdog_emit_ready');
+                    (0, handshakeManager_1.emitReadyGlobal)(server, 'watchdog');
+                }
+            }
+            catch { /* ignore */ }
+        }, 250).unref?.();
+    }
+    const requestSchema = (methodName) => zod_1.z.object({
+        jsonrpc: zod_1.z.literal('2.0'),
+        id: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+        method: zod_1.z.literal(methodName),
+        params: zod_1.z.any().optional()
+    });
+    // Explicit initialize handler – guarantees deterministic initialize response
+    // followed by exactly one server/ready notification.
+    server.setRequestHandler(requestSchema('initialize'), async (req) => {
+        try {
+            server.__sawInitializeRequest = true;
+            (0, handshakeManager_1.record)('initialize_received', { requestedProtocol: req?.params?.protocolVersion });
+            const requested = req?.params?.protocolVersion;
+            const negotiated = (0, handshakeManager_1.negotiateProtocolVersion)(requested);
+            const versionDeclared = server.__declaredVersion || server.version || '0.0.0';
+            const result = {
+                protocolVersion: negotiated,
+                serverInfo: { name: 'index', version: versionDeclared },
+                capabilities: { tools: { listChanged: true } },
+                instructions: 'Use initialize -> tools/list -> tools/call { name, arguments }. Health: tools/call health_check. Metrics: tools/call metrics_snapshot. Ping: ping.'
+            };
+            (0, handshakeManager_1.initFrameLog)('handler_return', { negotiated });
+            return result;
+        }
+        catch {
+            return { protocolVersion: handshakeManager_1.SUPPORTED_PROTOCOL_VERSIONS[0], serverInfo: { name: 'index', version: '0.0.0' }, capabilities: { tools: { listChanged: true } }, instructions: 'init fallback' };
+        }
+    });
+    // Legacy internal _oninitialize patch (will not trigger because we intercept initialize directly)
+    const originalInitInner = server._oninitialize?.bind(server);
+    if (originalInitInner && !server.__initPatched) {
+        server.__initPatched = true;
+        server._oninitialize = async function (request) {
+            const result = await originalInitInner(request);
+            try {
+                const negotiated = (0, handshakeManager_1.negotiateProtocolVersion)(request?.params?.protocolVersion);
+                result.protocolVersion = negotiated;
+                if (result && typeof result === 'object' && !('instructions' in result)) {
+                    result.instructions = 'Use initialize -> tools/list -> tools/call { name, arguments }. Health: tools/call health_check. Metrics: tools/call metrics_snapshot. Ping: ping.';
+                }
+                this.__sawInitializeRequest = true;
+            }
+            catch { /* ignore */ }
+            return result;
+        };
+    }
+    server.setRequestHandler(requestSchema('tools/list'), async () => {
+        (0, handshakeManager_1.record)('tools_list_request', { afterReady: !!server.__readyNotified, sawInit: !!server.__sawInitializeRequest });
+        const registry = (0, toolRegistry_1.getToolRegistry)();
+        return { tools: registry.map(r => ({ name: r.name, description: r.description, inputSchema: r.inputSchema })) };
+    });
+    // Raw handler for tools/call (MCP style) - returns content array
+    server.setRequestHandler(requestSchema('tools/call'), async (req) => {
+        const p = req?.params ?? {};
+        const name = p.name ?? '';
+        const args = p.arguments || {};
+        if (name === 'health_check')
+            (0, handshakeManager_1.record)('tools_call_health');
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write(`[rpc] call method=tools/call tool=${name} id=${req?.id ?? 'n/a'}\n`);
+        }
+        catch { /* ignore */ }
+        const handler = (0, registry_1.getHandler)(name);
+        if (!handler) {
+            throw { code: -32601, message: `Unknown tool: ${name}`, data: { message: `Unknown tool: ${name}`, method: name } };
+        }
+        try {
+            const result = await Promise.resolve(handler(args));
+            try {
+                if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${Buffer.byteLength(JSON.stringify(result), 'utf8')}\n`);
+            }
+            catch { /* ignore */ }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            const code = e?.code;
+            const sem = e?.__semantic === true;
+            if (Number.isSafeInteger(code)) {
+                try {
+                    if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                        process.stderr.write(`[rpc] tool_error_passthru tool=${name} code=${code} semantic=${sem ? '1' : '0'} msg=${e?.message || ''}\n`);
+                }
+                catch { /* ignore */ }
+                throw e;
+            }
+            const msg = e instanceof Error ? e.message : String(e);
+            try {
+                if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msg.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
+            }
+            catch { /* ignore */ }
+            throw { code: -32603, message: 'Tool execution failed', data: { message: msg, method: name } };
+        }
+    });
+    // Lightweight ping handler (simple reachability / latency measurement)
+    server.setRequestHandler(requestSchema('ping'), async () => {
+        if (server.__sawInitializeRequest && server.__initResponseSent && !server.__readyNotified) {
+            (0, handshakeManager_1.emitReadyGlobal)(server, 'ping-trigger');
+        }
+        return { timestamp: new Date().toISOString(), uptimeMs: Math.round(process.uptime() * 1000) };
+    });
+    return server;
+}
+// Diagnostic accessor tool registered via dynamic side-effect (safe: tiny + read-only)
+try {
+    global.__MCP_HANDSHAKE_TRACE_TOOL__ = true;
+}
+catch { /* ignore */ }
+async function startSdkServer() {
+    // Lazy dynamic import once (first-call path)
+    if (!StdioServerTransport) {
+        let modServer, modStdio;
+        try {
+            modServer = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/index.js');
+            modStdio = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/stdio.js');
+        }
+        catch (e) {
+            try {
+                process.stderr.write(`[startup] sdk_dynamic_import_failed ${(e instanceof Error) ? e.message : String(e)}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            StdioServerTransport = modStdio?.StdioServerTransport;
+        }
+        catch { /* ignore */ }
+        let server;
+        try {
+            if (modServer?.Server)
+                server = createSdkServer(modServer.Server);
+        }
+        catch (e) {
+            try {
+                process.stderr.write(`[startup] sdk_server_create_failed ${(e instanceof Error) ? e.message : String(e)}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        await (0, transportFactory_1.setupStdoutDiagnostics)();
+        (0, handshakeManager_1.setupStdinSniffer)(server);
+        if (!StdioServerTransport || !server) {
+            throw new Error('MCP SDK transport unavailable (removed fallback)');
+        }
+        (0, transportFactory_1.setupDispatcherOverride)(server);
+        const logDiag = (0, runtimeConfig_1.getRuntimeConfig)().logging.diagnostics;
+        if (logDiag) {
+            try {
+                process.stderr.write(`[transport-init] creating StdioServerTransport\n`);
+            }
+            catch { /* ignore */ }
+        }
+        const transport = new StdioServerTransport();
+        if (logDiag) {
+            try {
+                process.stderr.write(`[transport-init] connecting transport to server\n`);
+            }
+            catch { /* ignore */ }
+        }
+        await server.connect(transport);
+        if (logDiag) {
+            try {
+                const stdinReadable = process.stdin.readable;
+                const stdinListenerCount = process.stdin.listenerCount('data');
+                process.stderr.write(`[transport-init] transport connected stdin.readable=${stdinReadable} stdin.dataListeners=${stdinListenerCount}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        (0, transportFactory_1.setupKeepalive)();
+        (0, handshakeManager_1.setupSafetyFallbacks)(server);
+        (0, transportFactory_1.wrapTransportSend)(server, transport);
+        return;
+    }
+    // Secondary path: StdioServerTransport already loaded
+    const modServer = await (0, transportFactory_1.dynamicImport)('@modelcontextprotocol/sdk/server/index.js');
+    const server = createSdkServer(modServer.Server);
+    const logDiag2 = (0, runtimeConfig_1.getRuntimeConfig)().logging.diagnostics;
+    if (logDiag2) {
+        try {
+            process.stderr.write(`[transport-init] (secondary) creating StdioServerTransport\n`);
+        }
+        catch { /* ignore */ }
+    }
+    const transport = new StdioServerTransport();
+    if (logDiag2) {
+        try {
+            process.stderr.write(`[transport-init] (secondary) connecting transport to server\n`);
+        }
+        catch { /* ignore */ }
+    }
+    await server.connect(transport);
+    if (logDiag2) {
+        try {
+            const stdinReadable = process.stdin.readable;
+            const stdinListenerCount = process.stdin.listenerCount('data');
+            process.stderr.write(`[transport-init] (secondary) transport connected stdin.readable=${stdinReadable} stdin.dataListeners=${stdinListenerCount}\n`);
+        }
+        catch { /* ignore */ }
+    }
+    (0, transportFactory_1.setupKeepalive)('secondary');
+    // Safety fallback timer (mirrors dynamic path) for missed ready emission
+    if ((0, handshakeManager_1.isHandshakeFallbacksEnabled)()) {
+        setTimeout(() => {
+            try {
+                if (server.__sawInitializeRequest && !server.__readyNotified) {
+                    (0, handshakeManager_1.handshakeLog)('safety_timeout_emit_attempt', { label: 'safety-timeout-100ms-secondary', sawInit: true, initRespSent: !!server.__initResponseSent });
+                    (0, handshakeManager_1.emitReadyGlobal)(server, 'safety-timeout-100ms-secondary');
+                }
+            }
+            catch { /* ignore */ }
+        }, 100).unref?.();
+    }
+}

package/dist/server/shutdownGuard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shutdown Guard — Consolidates all process exit handling into a single
+ * re-entrance-guarded shutdown path.
+ *
+ * Fixes: GitHub Issue #36 — Multiple process.exit() race in shutdown paths
+ *
+ * Instead of SIGINT/SIGTERM/uncaughtException each independently calling
+ * process.exit(), all paths funnel through initiateShutdown() which:
+ * 1. Sets a guard flag to prevent re-entrance
+ * 2. Runs all registered cleanup handlers (with error isolation)
+ * 3. Returns the appropriate exit code
+ */
+export interface ShutdownGuard {
+    /**
+     * Register a named cleanup handler to run during shutdown.
+     * @param name - Unique identifier for this cleanup handler
+     * @param handler - Function to invoke during shutdown; errors are caught and logged
+     */
+    registerCleanup(name: string, handler: () => void): void;
+    /**
+     * Remove a previously registered cleanup handler.
+     * @param name - Identifier of the handler to remove
+     */
+    deregisterCleanup(name: string): void;
+    /**
+     * Initiate shutdown — only executes cleanup once (re-entrant calls return early).
+     * @param reason - Reason string; `'uncaughtException'` maps to exit code 1, all others to 0
+     * @returns The process exit code that callers should pass to `process.exit()`
+     */
+    initiateShutdown(reason: string): number;
+    /**
+     * Check if shutdown has been initiated.
+     * @returns `true` once {@link initiateShutdown} has been called
+     */
+    isShuttingDown(): boolean;
+}
+/**
+ * Create a new shutdown guard that consolidates all process exit paths into a single re-entrance-safe flow.
+ * @returns A {@link ShutdownGuard} instance with `registerCleanup`, `deregisterCleanup`, `initiateShutdown`, and `isShuttingDown` methods
+ */
+export declare function createShutdownGuard(): ShutdownGuard;

package/dist/server/shutdownGuard.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Shutdown Guard — Consolidates all process exit handling into a single
+ * re-entrance-guarded shutdown path.
+ *
+ * Fixes: GitHub Issue #36 — Multiple process.exit() race in shutdown paths
+ *
+ * Instead of SIGINT/SIGTERM/uncaughtException each independently calling
+ * process.exit(), all paths funnel through initiateShutdown() which:
+ * 1. Sets a guard flag to prevent re-entrance
+ * 2. Runs all registered cleanup handlers (with error isolation)
+ * 3. Returns the appropriate exit code
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShutdownGuard = createShutdownGuard;
+/**
+ * Create a new shutdown guard that consolidates all process exit paths into a single re-entrance-safe flow.
+ * @returns A {@link ShutdownGuard} instance with `registerCleanup`, `deregisterCleanup`, `initiateShutdown`, and `isShuttingDown` methods
+ */
+function createShutdownGuard() {
+    let shuttingDown = false;
+    const cleanupHandlers = new Map();
+    return {
+        registerCleanup(name, handler) {
+            cleanupHandlers.set(name, handler);
+        },
+        deregisterCleanup(name) {
+            cleanupHandlers.delete(name);
+        },
+        initiateShutdown(reason) {
+            const exitCode = reason === 'uncaughtException' ? 1 : 0;
+            if (shuttingDown)
+                return exitCode;
+            shuttingDown = true;
+            for (const [name, handler] of cleanupHandlers) {
+                try {
+                    handler();
+                }
+                catch (err) {
+                    try {
+                        process.stderr.write(`[shutdown] cleanup handler "${name}" failed: ${err}\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            return exitCode;
+        },
+        isShuttingDown() {
+            return shuttingDown;
+        }
+    };
+}

package/dist/server/startupDiagnostics.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeConfig } from '../config/runtimeConfig';
+export declare function emitStartupDiagnostics(runtime: RuntimeConfig, bufferEnabled: boolean, earlyInitChunks: Buffer[]): Promise<void>;

package/dist/server/startupDiagnostics.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitStartupDiagnostics = emitStartupDiagnostics;
+const registry_1 = require("./registry");
+const indexContext_1 = require("../services/indexContext");
+async function emitStartupDiagnostics(runtime, bufferEnabled, earlyInitChunks) {
+    if (runtime.logging.verbose || runtime.logging.diagnostics) {
+        try {
+            const methods = (0, registry_1.listRegisteredMethods)();
+            const idx = (0, indexContext_1.getIndexState)();
+            const mutation = runtime.mutationEnabled;
+            const dirDiag = (0, indexContext_1.diagnoseInstructionsDir)();
+            process.stderr.write(`[startup] toolsRegistered=${methods.length} mutationEnabled=${mutation} indexCount=${idx.list.length} indexHash=${idx.hash} instructionsDir="${dirDiag.dir}" exists=${dirDiag.exists} writable=${dirDiag.writable}${dirDiag.error ? ` dirError=${dirDiag.error.replace(/\s+/g, ' ')}` : ''}\n`);
+            try {
+                const { summarizeTraceEnv } = await import('../services/tracing.js');
+                const sum = summarizeTraceEnv();
+                process.stderr.write(`[startup] trace level=${sum.level} session=${sum.session} file=${sum.file || 'none'} categories=${sum.categories ? sum.categories.join(',') : '*'} maxFileSize=${sum.maxFileSize || 0} rotationIndex=${sum.rotationIndex}\n`);
+            }
+            catch { /* ignore */ }
+        }
+        catch (e) {
+            process.stderr.write(`[startup] diagnostics_error ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    if (bufferEnabled && runtime.logging.diagnostics) {
+        try {
+            const totalBytes = earlyInitChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+            const hasContentLength = earlyInitChunks.some(chunk => chunk.toString('utf8').includes('Content-Length'));
+            process.stderr.write(`[handshake-buffer] pre-start buffered=${earlyInitChunks.length} totalBytes=${totalBytes} hasContentLength=${hasContentLength}\n`);
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/server/thin-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Index Server - Thin Client Entry Point
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Lightweight stdio-to-HTTP bridge for MCP hosts.
+ * Instead of loading the full index and handler registry, this process
+ * reads JSON-RPC frames from stdin and forwards them to the leader server
+ * over HTTP.
+ *
+ * Usage:
+ *   node dist/server/thin-client.js
+ *
+ * Environment:
+ *   INDEX_SERVER_STATE_DIR    - State directory to discover leader (default: ./data/state)
+ *   INDEX_SERVER_LEADER_URL   - Explicit leader URL (e.g., http://127.0.0.1:9090/mcp)
+ *
+ * The thin client auto-discovers the leader from the lock file in INDEX_SERVER_STATE_DIR,
+ * or connects to INDEX_SERVER_LEADER_URL if provided. On leader failover, it re-discovers
+ * and reconnects automatically.
+ */
+export {};

package/dist/server/thin-client.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Index Server - Thin Client Entry Point
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Lightweight stdio-to-HTTP bridge for MCP hosts.
+ * Instead of loading the full index and handler registry, this process
+ * reads JSON-RPC frames from stdin and forwards them to the leader server
+ * over HTTP.
+ *
+ * Usage:
+ *   node dist/server/thin-client.js
+ *
+ * Environment:
+ *   INDEX_SERVER_STATE_DIR    - State directory to discover leader (default: ./data/state)
+ *   INDEX_SERVER_LEADER_URL   - Explicit leader URL (e.g., http://127.0.0.1:9090/mcp)
+ *
+ * The thin client auto-discovers the leader from the lock file in INDEX_SERVER_STATE_DIR,
+ * or connects to INDEX_SERVER_LEADER_URL if provided. On leader failover, it re-discovers
+ * and reconnects automatically.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const ThinClient_js_1 = require("../dashboard/server/ThinClient.js");
+const stateDir = process.env.INDEX_SERVER_STATE_DIR || path_1.default.join(process.cwd(), 'data', 'state');
+const leaderUrl = process.env.INDEX_SERVER_LEADER_URL || undefined;
+const client = new ThinClient_js_1.ThinClient({
+    leaderUrl,
+    stateDir,
+    maxRetries: 5,
+    retryDelayMs: 500,
+});
+process.stderr.write(`[thin-client] Starting stdio bridge (pid=${process.pid})\n`);
+process.stderr.write(`[thin-client] State dir: ${stateDir}\n`);
+if (leaderUrl) {
+    process.stderr.write(`[thin-client] Explicit leader URL: ${leaderUrl}\n`);
+}
+else {
+    const discovered = client.discoverLeader();
+    process.stderr.write(`[thin-client] Discovered leader: ${discovered || '(none yet — will retry on first request)'}\n`);
+}
+// Read JSON-RPC frames from stdin (Content-Length delimited or newline-delimited)
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    // Try Content-Length framing first (standard MCP protocol)
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const headerMatch = buffer.match(/^Content-Length:\s*(\d+)\r?\n\r?\n/);
+        if (headerMatch) {
+            const contentLength = parseInt(headerMatch[1], 10);
+            const headerEnd = headerMatch[0].length;
+            if (buffer.length >= headerEnd + contentLength) {
+                const frame = buffer.slice(headerEnd, headerEnd + contentLength);
+                buffer = buffer.slice(headerEnd + contentLength);
+                handleFrame(frame);
+                continue;
+            }
+            break; // Wait for more data
+        }
+        // Fallback: newline-delimited JSON
+        const newlineIdx = buffer.indexOf('\n');
+        if (newlineIdx >= 0) {
+            const line = buffer.slice(0, newlineIdx).trim();
+            buffer = buffer.slice(newlineIdx + 1);
+            if (line.length > 0 && line.startsWith('{')) {
+                handleFrame(line);
+            }
+            continue;
+        }
+        break; // Wait for more data
+    }
+});
+async function handleFrame(frame) {
+    try {
+        const response = await client.processFrame(frame);
+        const responseBytes = Buffer.from(response, 'utf8');
+        process.stdout.write(`Content-Length: ${responseBytes.length}\r\n\r\n`);
+        process.stdout.write(responseBytes);
+    }
+    catch (err) {
+        const errorResponse = JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },
+            id: null,
+        });
+        const errorBytes = Buffer.from(errorResponse, 'utf8');
+        process.stdout.write(`Content-Length: ${errorBytes.length}\r\n\r\n`);
+        process.stdout.write(errorBytes);
+    }
+}
+process.stdin.on('end', () => {
+    process.stderr.write('[thin-client] stdin closed, shutting down\n');
+    client.stop();
+    process.exit(0);
+});
+process.on('SIGINT', () => {
+    process.stderr.write('[thin-client] SIGINT received, shutting down\n');
+    client.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    process.stderr.write('[thin-client] SIGTERM received, shutting down\n');
+    client.stop();
+    process.exit(0);
+});

package/dist/server/transport.d.ts

@@ -0,0 +1,41 @@
+export type Handler<TParams = unknown> = (params: TParams) => Promise<unknown> | unknown;
+interface MetricRecord {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+/** Return the in-memory per-method metrics map (count, totalMs, maxMs).
+ * @returns Reference to the live metrics map keyed by method name
+ */
+export declare function getMetrics(): Record<string, MetricRecord>;
+/**
+ * Register a method handler in the stdio transport's handler table.
+ * Unlike the SDK registry, this does not add wrapping (metrics, audit, etc.).
+ * @param method - JSON-RPC method name
+ * @param handler - Handler function invoked with the parsed params
+ */
+export declare function registerHandler<TParams = unknown>(method: string, handler: Handler<TParams>): void;
+/**
+ * Return a sorted list of all registered method names in the stdio transport.
+ * @returns Array of method name strings in alphabetical order
+ */
+export declare function listRegisteredMethods(): string[];
+/**
+ * Look up a registered handler by method name.
+ * @param method - JSON-RPC method name to look up
+ * @returns The handler function, or `undefined` if not registered
+ */
+export declare function getHandler(method: string): Handler | undefined;
+export interface TransportOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Start the stdio JSON-RPC 2.0 transport, reading requests from stdin and writing responses to stdout.
+ * Registers built-in handlers for `initialize`, `notifications/initialized`, `shutdown`, and `exit`.
+ * @param opts - Optional stream overrides (input, output, stderr) and environment; defaults to process streams
+ */
+export declare function startTransport(opts?: TransportOptions): void;
+export {};