nuwax-mcp-stdio-proxy 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -2,17 +2,22 @@
 /**
  * nuwax-mcp-stdio-proxy
  *
- * A pure TypeScript stdio MCP proxy that aggregates multiple child MCP servers
- * into a single MCP server endpoint. Eliminates HTTP/port management and
- * avoids Windows console popup issues when invoked via Node.js directly.
+ * A pure TypeScript stdio MCP proxy that aggregates multiple MCP servers
+ * into a single MCP server endpoint. Supports two upstream transport types:
+ *
+ * - **stdio**: Spawns child MCP server processes (StdioClientTransport)
+ * - **bridge**: Connects to persistent MCP Bridge servers via StreamableHTTP (StreamableHTTPClientTransport)
  *
  * Usage:
- *   nuwax-mcp-stdio-proxy --config '{"mcpServers":{"name":{"command":"...","args":["..."]}}}'
+ *   nuwax-mcp-stdio-proxy --config '{"mcpServers":{
+ *     "local":  {"command":"npx","args":["-y","some-mcp"]},
+ *     "remote": {"url":"http://127.0.0.1:8080/mcp/name"}  // bridge to persistent server
+ *   }}'
  *
  * Architecture:
  *   Agent Engine (stdin/stdout)  ←→  This Proxy (StdioServerTransport)
  *                                         ├→ Child MCP Server A (StdioClientTransport)
- *                                         ├→ Child MCP Server B (StdioClientTransport)
+ *                                         ├→ Bridge MCP Server B (StreamableHTTPClientTransport)
  *                                         └→ ...
  */
 export {};

package/dist/index.js

@@ -2,32 +2,31 @@
 /**
  * nuwax-mcp-stdio-proxy
  *
- * A pure TypeScript stdio MCP proxy that aggregates multiple child MCP servers
- * into a single MCP server endpoint. Eliminates HTTP/port management and
- * avoids Windows console popup issues when invoked via Node.js directly.
+ * A pure TypeScript stdio MCP proxy that aggregates multiple MCP servers
+ * into a single MCP server endpoint. Supports two upstream transport types:
+ *
+ * - **stdio**: Spawns child MCP server processes (StdioClientTransport)
+ * - **bridge**: Connects to persistent MCP Bridge servers via StreamableHTTP (StreamableHTTPClientTransport)
  *
  * Usage:
- *   nuwax-mcp-stdio-proxy --config '{"mcpServers":{"name":{"command":"...","args":["..."]}}}'
+ *   nuwax-mcp-stdio-proxy --config '{"mcpServers":{
+ *     "local":  {"command":"npx","args":["-y","some-mcp"]},
+ *     "remote": {"url":"http://127.0.0.1:8080/mcp/name"}  // bridge to persistent server
+ *   }}'
  *
  * Architecture:
  *   Agent Engine (stdin/stdout)  ←→  This Proxy (StdioServerTransport)
  *                                         ├→ Child MCP Server A (StdioClientTransport)
- *                                         ├→ Child MCP Server B (StdioClientTransport)
+ *                                         ├→ Bridge MCP Server B (StreamableHTTPClientTransport)
  *                                         └→ ...
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-// ========== Logging (stderr only — stdout is MCP JSON-RPC channel) ==========
-function log(level, msg) {
-    process.stderr.write(`[nuwax-mcp-proxy] ${level}: ${msg}\n`);
-}
-const logInfo = (msg) => log('INFO', msg);
-const logWarn = (msg) => log('WARN', msg);
-const logError = (msg) => log('ERROR', msg);
-// ========== CLI Argument Parsing ==========
+import { isHttpEntry } from './types.js';
+import { logInfo, logWarn, logError } from './logger.js';
+import { buildBaseEnv, connectStdio, connectBridge } from './transport.js';
+// ========== CLI ==========
 function parseConfig() {
     const args = process.argv.slice(2);
     const idx = args.indexOf('--config');
@@ -48,20 +47,6 @@ function parseConfig() {
         process.exit(1);
     }
 }
-// ========== Build Clean Environment for Child Processes ==========
-function buildBaseEnv() {
-    const env = {};
-    // Copy current process.env, filtering out undefined values
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value !== undefined) {
-            env[key] = value;
-        }
-    }
-    // Remove ELECTRON_RUN_AS_NODE — child MCP servers should run normally,
-    // not as Electron Node.js instances
-    delete env.ELECTRON_RUN_AS_NODE;
-    return env;
-}
 // ========== Main ==========
 async function main() {
     const config = parseConfig();
@@ -70,38 +55,22 @@ async function main() {
         logError('No MCP servers configured in mcpServers');
         process.exit(1);
     }
-    logInfo(`Starting proxy with ${entries.length} child server(s): ${entries.map(([id]) => id).join(', ')}`);
-    // ---- Phase 1: Connect to all child MCP servers ----
-    // Build base env once — per-server env is merged on top
+    logInfo(`Starting proxy with ${entries.length} server(s): ${entries.map(([id]) => id).join(', ')}`);
+    // ---- Phase 1: Connect to all MCP servers (stdio + bridge) ----
     const baseEnv = buildBaseEnv();
     const clients = new Map();
+    const cleanups = new Map();
     const toolToClient = new Map();
     const toolToServer = new Map();
     const toolsByName = new Map();
     for (const [id, entry] of entries) {
-        let transport = null;
         try {
-            logInfo(`Connecting to "${id}": ${entry.command} ${(entry.args || []).join(' ')}`);
-            transport = new StdioClientTransport({
-                command: entry.command,
-                args: entry.args || [],
-                env: { ...baseEnv, ...(entry.env || {}) },
-                // stderr defaults to 'pipe' in the SDK; child errors captured via transport.stderr
-            });
-            // Attach stderr listener BEFORE connect to catch early child errors
-            // (SDK returns a PassThrough stream immediately for this purpose)
-            if (transport.stderr) {
-                transport.stderr.on('data', (chunk) => {
-                    const text = chunk.toString().trim();
-                    if (text) {
-                        process.stderr.write(`[child:${id}] ${text}\n`);
-                    }
-                });
-            }
-            const client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
-            await client.connect(transport);
+            const { client, cleanup } = isHttpEntry(entry)
+                ? await connectBridge(id, entry)
+                : await connectStdio(id, entry, baseEnv);
             clients.set(id, client);
-            // Discover tools from this child server (handle pagination)
+            cleanups.set(id, cleanup);
+            // Discover tools (handle pagination)
             const allServerTools = [];
             let cursor;
             do {
@@ -121,29 +90,20 @@ async function main() {
         }
         catch (e) {
             logError(`Failed to connect to server "${id}": ${e}`);
-            // Clean up transport to prevent child process leak
-            if (transport) {
-                try {
-                    await transport.close();
-                }
-                catch { /* ignore */ }
-            }
             // Continue with remaining servers — partial startup is acceptable
         }
     }
     if (clients.size === 0) {
-        logError('Failed to connect to any child MCP server');
+        logError('Failed to connect to any MCP server');
         process.exit(1);
     }
     const aggregatedTools = Array.from(toolsByName.values());
     logInfo(`Aggregated ${aggregatedTools.length} unique tool(s) from ${clients.size} server(s)`);
     // ---- Phase 2: Create the aggregating MCP server ----
     const server = new Server({ name: 'nuwax-mcp-stdio-proxy', version: '1.0.0' }, { capabilities: { tools: {} } });
-    // tools/list → return all aggregated tools
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return { tools: aggregatedTools };
     });
-    // tools/call → route to the correct child server
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: toolArgs } = request.params;
         const client = toolToClient.get(name);
@@ -180,10 +140,18 @@ async function main() {
         for (const [id, client] of clients) {
             try {
                 await client.close();
-                logInfo(`Closed child client "${id}"`);
+                logInfo(`Closed client "${id}"`);
+            }
+            catch (e) {
+                logError(`Failed to close client "${id}": ${e}`);
+            }
+        }
+        for (const [id, cleanup] of cleanups) {
+            try {
+                await cleanup();
             }
             catch (e) {
-                logError(`Failed to close child client "${id}": ${e}`);
+                logError(`Failed cleanup for "${id}": ${e}`);
             }
         }
         try {

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Logging utilities — stderr only, stdout is the MCP JSON-RPC channel
+ */
+export declare function log(level: string, msg: string): void;
+export declare const logInfo: (msg: string) => void;
+export declare const logWarn: (msg: string) => void;
+export declare const logError: (msg: string) => void;

package/dist/logger.js

@@ -0,0 +1,9 @@
+/**
+ * Logging utilities — stderr only, stdout is the MCP JSON-RPC channel
+ */
+export function log(level, msg) {
+    process.stderr.write(`[nuwax-mcp-proxy] ${level}: ${msg}\n`);
+}
+export const logInfo = (msg) => log('INFO', msg);
+export const logWarn = (msg) => log('WARN', msg);
+export const logError = (msg) => log('ERROR', msg);

package/dist/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Transport layer — connect to upstream MCP servers via stdio or bridge (HTTP)
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { StdioServerEntry, BridgeServerEntry } from './types.js';
+export interface ConnectedClient {
+    client: Client;
+    cleanup: () => Promise<void>;
+}
+/**
+ * Build a clean env for child processes (strips ELECTRON_RUN_AS_NODE)
+ */
+export declare function buildBaseEnv(): Record<string, string>;
+/**
+ * Connect to a stdio MCP server (spawn child process)
+ */
+export declare function connectStdio(id: string, entry: StdioServerEntry, baseEnv: Record<string, string>): Promise<ConnectedClient>;
+/**
+ * Connect to a bridge MCP server (StreamableHTTP → PersistentMcpBridge)
+ *
+ * Bridge connections target long-lived MCP servers managed by PersistentMcpBridge
+ * in the Electron main process, accessed via HTTP endpoints.
+ */
+export declare function connectBridge(id: string, entry: BridgeServerEntry): Promise<ConnectedClient>;
+/** @deprecated Use connectBridge instead */
+export declare const connectHttp: typeof connectBridge;

package/dist/transport.js

@@ -0,0 +1,75 @@
+/**
+ * Transport layer — connect to upstream MCP servers via stdio or bridge (HTTP)
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { logInfo } from './logger.js';
+/**
+ * Build a clean env for child processes (strips ELECTRON_RUN_AS_NODE)
+ */
+export function buildBaseEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    // Child MCP servers should run normally, not as Electron Node.js instances
+    delete env.ELECTRON_RUN_AS_NODE;
+    return env;
+}
+/**
+ * Connect to a stdio MCP server (spawn child process)
+ */
+export async function connectStdio(id, entry, baseEnv) {
+    logInfo(`Connecting to "${id}" (stdio): ${entry.command} ${(entry.args || []).join(' ')}`);
+    const transport = new StdioClientTransport({
+        command: entry.command,
+        args: entry.args || [],
+        env: { ...baseEnv, ...(entry.env || {}) },
+    });
+    // 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 client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
+    await client.connect(transport);
+    return {
+        client,
+        cleanup: async () => {
+            try {
+                await transport.close();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+/**
+ * Connect to a bridge MCP server (StreamableHTTP → PersistentMcpBridge)
+ *
+ * Bridge connections target long-lived MCP servers managed by PersistentMcpBridge
+ * in the Electron main process, accessed via HTTP endpoints.
+ */
+export async function connectBridge(id, entry) {
+    logInfo(`Connecting to "${id}" (bridge): ${entry.url}`);
+    const transport = new StreamableHTTPClientTransport(new URL(entry.url));
+    const client = new Client({ name: `proxy-${id}`, version: '1.0.0' });
+    await client.connect(transport);
+    return {
+        client,
+        cleanup: async () => {
+            try {
+                await transport.close();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+/** @deprecated Use connectBridge instead */
+export const connectHttp = connectBridge;

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Types for MCP server configuration
+ */
+/** stdio 类型: spawn 子进程 */
+export interface StdioServerEntry {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Bridge 类型: 连接持久化 MCP Bridge (HTTP)
+ *
+ * 用于连接 PersistentMcpBridge 等长生命周期的 MCP server。
+ * Bridge server 通过 StreamableHTTPClientTransport 访问，
+ * 其生命周期独立于 proxy 进程。
+ */
+export interface BridgeServerEntry {
+    url: string;
+}
+/** @deprecated Use BridgeServerEntry instead */
+export type HttpServerEntry = BridgeServerEntry;
+export type McpServerEntry = StdioServerEntry | BridgeServerEntry;
+export declare function isBridgeEntry(entry: McpServerEntry): entry is BridgeServerEntry;
+/** @deprecated Use isBridgeEntry instead */
+export declare const isHttpEntry: typeof isBridgeEntry;
+export interface McpServersConfig {
+    mcpServers: Record<string, McpServerEntry>;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Types for MCP server configuration
+ */
+export function isBridgeEntry(entry) {
+    return 'url' in entry && typeof entry.url === 'string';
+}
+/** @deprecated Use isBridgeEntry instead */
+export const isHttpEntry = isBridgeEntry;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuwax-mcp-stdio-proxy",
-  "version": "1.0.0",
-  "description": "TypeScript stdio MCP proxy — aggregates multiple child MCP servers into one",
+  "version": "1.1.0",
+  "description": "TypeScript stdio MCP proxy — aggregates multiple MCP servers (stdio + bridge) into one",
   "type": "module",
   "bin": {
     "nuwax-mcp-stdio-proxy": "./dist/index.js"