nuwax-mcp-stdio-proxy 1.4.6 → 1.4.7

package/dist/resilient.js

@@ -0,0 +1,297 @@
+/**
+ * Resilient Transport Wrapper for MCP
+ *
+ * Provides heartbeat monitoring, automatic reconnection, and request queueing
+ * for MCP transports (HTTP, SSE, Stdio).
+ */
+import { logInfo, logWarn, logError } from './logger.js';
+const DEFAULT_OPTIONS = {
+    pingIntervalMs: 20000,
+    maxConsecutiveFailures: 3,
+    pingTimeoutMs: 5000,
+    reconnectDelayMs: 3000,
+    maxQueueSize: 100,
+    name: 'remote',
+};
+/** Default logger that delegates to logger.js (stderr) */
+const defaultLogger = {
+    info: (...args) => logInfo(args.map(String).join(' ')),
+    warn: (...args) => logWarn(args.map(String).join(' ')),
+    error: (...args) => logError(args.map(String).join(' ')),
+};
+export class ResilientTransportWrapper {
+    options;
+    log;
+    activeTransport = null;
+    mcpClient = null;
+    heartbeatTimer = null;
+    consecutiveFailures = 0;
+    state = 'connecting';
+    // Handlers required by the Transport interface
+    onclose;
+    onerror;
+    onmessage;
+    // Queue for messages sent while reconnecting
+    messageQueue = [];
+    // Pending ping requests awaiting a response
+    pendingPings = new Map();
+    constructor(options) {
+        this.log = options.logger ?? defaultLogger;
+        this.options = { ...DEFAULT_OPTIONS, logger: this.log, ...options };
+    }
+    /**
+     * Initializes the transport and connects to the backend
+     *
+     * This method is idempotent - if the transport is already connected or
+     * connecting, subsequent calls will return immediately without creating
+     * duplicate connections. This is important because MCP SDK's client.connect()
+     * internally calls transport.start(), and we also call it explicitly in bridge.ts.
+     */
+    async start() {
+        // Idempotent check: if already connected or connecting, return early
+        if (this.state === 'connected' || this.state === 'connecting') {
+            return;
+        }
+        this.state = 'connecting';
+        await this.performConnect(true);
+    }
+    /**
+     * Enable heartbeat monitoring. Call this AFTER the MCP client has
+     * completed its initialize handshake (client.connect()), otherwise
+     * the server will reject ping requests with "Server not initialized".
+     */
+    enableHeartbeat() {
+        this.startHeartbeat();
+    }
+    async performConnect(initial = false) {
+        try {
+            this.activeTransport = await this.options.connectParams();
+            // Inherit the handlers from this wrapper
+            this.bindInnerTransport(this.activeTransport);
+            await this.activeTransport.start();
+            this.state = 'connected';
+            this.consecutiveFailures = 0;
+            this.log.info(`[McpProxy] [ResilientTransport:${this.options.name}] Connected via ${this.activeTransport.constructor.name}`);
+            // Flush any queued messages
+            this.flushQueue();
+            // Only start heartbeat on reconnects — initial connections need
+            // the caller to invoke enableHeartbeat() after client.connect()
+            // completes the MCP initialize handshake. Sending pings before
+            // initialize causes "Server not initialized" errors.
+            if (!initial) {
+                this.startHeartbeat();
+            }
+        }
+        catch (err) {
+            this.log.error(`[McpProxy] [ResilientTransport:${this.options.name}] Connect failed: ${err}`);
+            if (initial) {
+                this.state = 'closed';
+                throw err;
+            }
+            this.triggerReconnect(); // Retry connection
+        }
+    }
+    bindInnerTransport(transport) {
+        transport.onclose = () => {
+            // If the inner transport closes but we are not intentionally closed
+            if (this.state !== 'closed') {
+                this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] Inner transport closed unexpectedly. Reconnecting...`);
+                this.triggerReconnect();
+            }
+        };
+        transport.onerror = (error) => {
+            // If it throws ENOENT or similar before we even catch it, we might be here.
+            if (this.state !== 'closed') {
+                this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] Inner transport error: ${error.message}`);
+                if (this.state === 'connecting') {
+                    if (this.onerror)
+                        this.onerror(error);
+                    return;
+                }
+                this.triggerReconnect();
+            }
+        };
+        transport.onmessage = (message) => {
+            // Intercept our own ping responses here (both success and error responses)
+            if ('id' in message && typeof message.id === 'string' && message.id.startsWith('respl-ping-')) {
+                const resolve = this.pendingPings.get(message.id);
+                if (resolve) {
+                    // Any response (even error like "Method not found") means server is alive
+                    resolve(true);
+                    this.pendingPings.delete(message.id);
+                }
+                return; // Don't forward ping responses to downstream
+            }
+            if (this.onmessage) {
+                this.onmessage(message);
+            }
+        };
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        if (this.options.pingIntervalMs <= 0)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            this.checkHealth();
+        }, this.options.pingIntervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /** Track consecutive ping timeouts (no response at all, not even an error) */
+    consecutivePingTimeouts = 0;
+    /** If server doesn't support ping, auto-disable heartbeat after maxConsecutiveFailures timeouts */
+    pingDisabled = false;
+    async checkHealth() {
+        if (this.state !== 'connected' || !this.activeTransport)
+            return;
+        if (this.pingDisabled)
+            return;
+        try {
+            // Send raw ping JSON-RPC
+            const pingId = `respl-ping-${Date.now()}`;
+            const responsePromise = new Promise((resolve) => {
+                this.pendingPings.set(pingId, resolve);
+                setTimeout(() => {
+                    if (this.pendingPings.has(pingId)) {
+                        this.pendingPings.delete(pingId);
+                        resolve(false); // Timeout
+                    }
+                }, this.options.pingTimeoutMs);
+            });
+            // Try to send ping — if send() throws, the transport itself is broken
+            let sendFailed = false;
+            try {
+                this.log.info(`[McpProxy] [ResilientTransport:${this.options.name}] 💓 Sending heartbeat ping (id: ${pingId})`);
+                await this.activeTransport.send({
+                    jsonrpc: '2.0',
+                    id: pingId,
+                    method: 'ping',
+                });
+            }
+            catch (sendErr) {
+                sendFailed = true;
+                throw sendErr; // Transport broken, treat as real failure
+            }
+            const success = await responsePromise;
+            if (!success) {
+                // Ping was sent successfully but timed out — server might not support ping
+                this.consecutivePingTimeouts++;
+                if (this.consecutivePingTimeouts >= this.options.maxConsecutiveFailures) {
+                    // Server consistently never responds to ping — it probably doesn't support
+                    // the ping method. Auto-disable heartbeat instead of reconnecting, since
+                    // the transport is likely healthy (sends succeed, no errors from transport).
+                    this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] Server does not respond to ping. Disabling heartbeat monitoring.`);
+                    this.pingDisabled = true;
+                    this.stopHeartbeat();
+                    return;
+                }
+                // Still count as a failure for logging, but don't reconnect yet
+                this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] Ping timeout (${this.consecutivePingTimeouts}/${this.options.maxConsecutiveFailures})`);
+                return;
+            }
+            // Got a response — server is alive
+            this.log.info(`[McpProxy] [ResilientTransport:${this.options.name}] 💖 Heartbeat successful (id: ${pingId})`);
+            this.consecutiveFailures = 0;
+            this.consecutivePingTimeouts = 0;
+        }
+        catch (err) {
+            this.consecutiveFailures++;
+            this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] 💔 Heartbeat error (attempt ${this.consecutiveFailures}/${this.options.maxConsecutiveFailures}): ${err}`);
+            if (this.consecutiveFailures >= this.options.maxConsecutiveFailures) {
+                this.log.error(`[McpProxy] [ResilientTransport:${this.options.name}] Max consecutive heartbeat failures reached. Force reconnecting.`);
+                this.triggerReconnect();
+            }
+        }
+    }
+    triggerReconnect() {
+        if (this.state === 'reconnecting' || this.state === 'closed')
+            return;
+        this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] 🔄 Triggering reconnect (previous state: ${this.state})`);
+        this.state = 'reconnecting';
+        this.stopHeartbeat();
+        // Clean up old transport
+        if (this.activeTransport) {
+            // Avoid triggering our own onclose
+            this.activeTransport.onclose = undefined;
+            this.activeTransport.onerror = undefined;
+            try {
+                this.activeTransport.close();
+            }
+            catch { /* ignore */ }
+            this.activeTransport = null;
+        }
+        setTimeout(() => {
+            this.performConnect();
+        }, this.options.reconnectDelayMs);
+    }
+    async flushQueue() {
+        if (!this.activeTransport || this.state !== 'connected')
+            return;
+        if (this.messageQueue.length > 0) {
+            this.log.info(`[McpProxy] [ResilientTransport:${this.options.name}] Flushing ${this.messageQueue.length} queued requests...`);
+        }
+        const queueToFlush = [...this.messageQueue];
+        this.messageQueue = [];
+        for (let i = 0; i < queueToFlush.length; i++) {
+            const msg = queueToFlush[i];
+            try {
+                await this.activeTransport.send(msg);
+            }
+            catch (e) {
+                this.log.error(`[McpProxy] [ResilientTransport:${this.options.name}] Error flushing queue: ${e}`);
+                // If sending fails, put this message and remaining ones back at the front of the queue
+                const failedAndRemaining = queueToFlush.slice(i);
+                this.messageQueue = [...failedAndRemaining, ...this.messageQueue];
+                this.triggerReconnect();
+                break; // Stop flushing until reconnected
+            }
+        }
+    }
+    // --- Transport Interface Methods ---
+    async send(message) {
+        if (this.state === 'closed') {
+            throw new Error('Transport is closed');
+        }
+        if (this.state === 'reconnecting' || this.state === 'connecting') {
+            // Queue the message
+            if (this.messageQueue.length >= this.options.maxQueueSize) {
+                this.log.warn(`[McpProxy] [ResilientTransport:${this.options.name}] Message queue full, dropping oldest request.`);
+                this.messageQueue.shift(); // Drop oldest
+            }
+            this.messageQueue.push(message);
+            return;
+        }
+        if (!this.activeTransport) {
+            throw new Error('No active transport to send message');
+        }
+        try {
+            await this.activeTransport.send(message);
+        }
+        catch (err) {
+            // Queue it and reconnect
+            this.messageQueue.push(message);
+            this.triggerReconnect();
+        }
+    }
+    async close() {
+        if (this.state === 'closed')
+            return;
+        this.state = 'closed';
+        this.stopHeartbeat();
+        this.messageQueue = [];
+        if (this.activeTransport) {
+            // Prevent bubble up closure
+            this.activeTransport.onclose = undefined;
+            this.activeTransport.onerror = undefined;
+            await this.activeTransport.close();
+            this.activeTransport = null;
+        }
+        if (this.onclose) {
+            this.onclose();
+        }
+    }
+}

package/dist/transport.d.ts

@@ -2,10 +2,12 @@
  * Transport layer — connect to upstream MCP servers via stdio, Streamable HTTP, or SSE
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { StdioServerEntry, StreamableServerEntry, SseServerEntry } from './types.js';
 export interface ConnectedClient {
     client: Client;
     cleanup: () => Promise<void>;
+    transport: Transport;
 }
 /**
  * Build a clean env for child processes (strips ELECTRON_RUN_AS_NODE)

package/dist/transport.js

@@ -6,6 +6,22 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { CustomStdioClientTransport } from './customStdio.js';
 import { logInfo } from './logger.js';
+import { ResilientTransportWrapper } from './resilient.js';
+/**
+ * Helper to wrap a promise with a timeout
+ */
+async function withTimeout(promise, ms, message) {
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(message)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
 /**
  * Build a clean env for child processes (strips ELECTRON_RUN_AS_NODE)
  */
@@ -38,28 +54,49 @@ export function buildRequestHeaders(entry) {
  */
 export async function connectStdio(id, entry, baseEnv) {
     logInfo(`Connecting to "${id}" (stdio): ${entry.command} ${(entry.args || []).join(' ')}`);
-    const transport = new CustomStdioClientTransport({
-        command: entry.command,
-        args: entry.args || [],
-        env: { ...baseEnv, ...(entry.env || {}) },
-        stderr: 'pipe',
-    });
-    // Attach stderr listener BEFORE connect to catch early child errors
-    if (transport.stderr) {
-        transport.stderr.on('data', (chunk) => {
-            const text = chunk.toString().trim();
-            if (text) {
-                process.stderr.write(`[child:${id}] ${text}\n`);
+    const wrapper = new ResilientTransportWrapper({
+        name: id,
+        connectParams: async () => {
+            const t = new CustomStdioClientTransport({
+                command: entry.command,
+                args: entry.args || [],
+                env: { ...baseEnv, ...(entry.env || {}) },
+                stderr: 'pipe',
+            });
+            if (t.stderr) {
+                t.stderr.on('data', (chunk) => {
+                    const text = chunk.toString().trim();
+                    if (text) {
+                        process.stderr.write(`[child:${id}] ${text}\n`);
+                    }
+                });
             }
-        });
-    }
+            return t;
+        },
+        pingIntervalMs: entry.pingIntervalMs,
+        pingTimeoutMs: entry.pingTimeoutMs,
+    });
     const client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
-    await client.connect(transport);
+    try {
+        await withTimeout((async () => {
+            await wrapper.start();
+            await client.connect(wrapper);
+            wrapper.enableHeartbeat(); // Start heartbeat AFTER MCP initialize completes
+        })(), 5000, `Connection initialization timed out after 5s`);
+    }
+    catch (err) {
+        try {
+            await wrapper.close();
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
     return {
         client,
+        transport: wrapper,
         cleanup: async () => {
             try {
-                await transport.close();
+                await wrapper.close();
             }
             catch { /* ignore */ }
         },
@@ -75,14 +112,35 @@ export async function connectStreamable(id, entry) {
     logInfo(`Connecting to "${id}" (streamable-http): ${entry.url}`);
     const headers = buildRequestHeaders(entry);
     const url = new URL(entry.url);
-    const transport = new StreamableHTTPClientTransport(url, headers ? { requestInit: { headers } } : undefined);
+    const wrapper = new ResilientTransportWrapper({
+        name: id,
+        connectParams: async () => {
+            return new StreamableHTTPClientTransport(url, headers ? { requestInit: { headers } } : undefined);
+        },
+        pingIntervalMs: entry.pingIntervalMs,
+        pingTimeoutMs: entry.pingTimeoutMs,
+    });
     const client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
-    await client.connect(transport);
+    try {
+        await withTimeout((async () => {
+            await wrapper.start();
+            await client.connect(wrapper);
+            wrapper.enableHeartbeat(); // Start heartbeat AFTER MCP initialize completes
+        })(), 5000, `Connection initialization timed out after 5s`);
+    }
+    catch (err) {
+        try {
+            await wrapper.close();
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
     return {
         client,
+        transport: wrapper,
         cleanup: async () => {
             try {
-                await transport.close();
+                await wrapper.close();
             }
             catch { /* ignore */ }
         },
@@ -98,14 +156,35 @@ export async function connectSse(id, entry) {
     logInfo(`Connecting to "${id}" (sse): ${entry.url}`);
     const headers = buildRequestHeaders(entry);
     const url = new URL(entry.url);
-    const transport = new SSEClientTransport(url, headers ? { requestInit: { headers } } : undefined);
+    const wrapper = new ResilientTransportWrapper({
+        name: id,
+        connectParams: async () => {
+            return new SSEClientTransport(url, headers ? { requestInit: { headers } } : undefined);
+        },
+        pingIntervalMs: entry.pingIntervalMs,
+        pingTimeoutMs: entry.pingTimeoutMs,
+    });
     const client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
-    await client.connect(transport);
+    try {
+        await withTimeout((async () => {
+            await wrapper.start();
+            await client.connect(wrapper);
+            wrapper.enableHeartbeat(); // Start heartbeat AFTER MCP initialize completes
+        })(), 5000, `Connection initialization timed out after 5s`);
+    }
+    catch (err) {
+        try {
+            await wrapper.close();
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
     return {
         client,
+        transport: wrapper,
         cleanup: async () => {
             try {
-                await transport.close();
+                await wrapper.close();
             }
             catch { /* ignore */ }
         },

package/dist/types.d.ts

@@ -10,6 +10,10 @@ export interface StdioServerEntry {
     allowTools?: string[];
     /** 工具黑名单（排除指定工具） */
     denyTools?: string[];
+    /** Heartbeat ping interval configuration (ms) */
+    pingIntervalMs?: number;
+    /** Heartbeat ping timeout configuration (ms) */
+    pingTimeoutMs?: number;
 }
 /**
  * Streamable HTTP 类型: 连接远程 MCP server (Streamable HTTP)
@@ -26,6 +30,10 @@ export interface StreamableServerEntry {
     allowTools?: string[];
     /** 工具黑名单（排除指定工具） */
     denyTools?: string[];
+    /** Heartbeat ping interval configuration (ms) */
+    pingIntervalMs?: number;
+    /** Heartbeat ping timeout configuration (ms) */
+    pingTimeoutMs?: number;
 }
 /**
  * SSE 类型: 连接远程 MCP server (Server-Sent Events)
@@ -41,6 +49,10 @@ export interface SseServerEntry {
     allowTools?: string[];
     /** 工具黑名单（排除指定工具） */
     denyTools?: string[];
+    /** Heartbeat ping interval configuration (ms) */
+    pingIntervalMs?: number;
+    /** Heartbeat ping timeout configuration (ms) */
+    pingTimeoutMs?: number;
 }
 export type McpServerEntry = StdioServerEntry | StreamableServerEntry | SseServerEntry;
 export declare function isSseEntry(entry: McpServerEntry): entry is SseServerEntry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuwax-mcp-stdio-proxy",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "TypeScript MCP proxy — aggregates multiple MCP servers (stdio + streamable-http + SSE) with convert & proxy modes",
   "type": "module",
   "bin": {
@@ -12,18 +12,20 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc && node build.mjs",
+    "build": "tsc && node scripts/build.mjs",
     "build:tsc": "tsc",
     "test": "npm run build:tsc && vitest",
     "test:run": "npm run build:tsc && vitest run",
     "test:coverage": "npm run build:tsc && vitest run --coverage",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "publish:non-latest": "npm publish --tag beta"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "esbuild": "^0.27.3",
     "typescript": "^5.7.0",
     "vitest": "^2.1.8"