nuwax-mcp-stdio-proxy 1.4.5 → 1.4.7

package/README.md

@@ -1,37 +1,64 @@
 # nuwax-mcp-stdio-proxy
 
-TypeScript stdio MCP proxy — aggregates multiple MCP servers into a single stdio endpoint. Supports **stdio** (spawn child processes) and **bridge** (Streamable HTTP to a persistent MCP bridge).
+一个纯 TypeScript 编写的 MCP (Model Context Protocol) 代理工具，为 MCP Server 提供高级聚合、协议转换以及生命周期管理功能。
 
-## Requirements
+它的设计初衷，是为了解决将 MCP Server 集成到大型应用或 Agent OS 平台时遇到的“启动时序竞争”及“应用退出后产生僵尸进程”等痛点问题。
+
+## 环境要求
 
 - **Node.js** >= 22.0.0
 
-## Usage
+## 运行模式
+
+该代理工具具备三种截然不同的工作模式：
+
+### 1. Stdio 聚合模式 (默认)
+
+将多个基于不同协议上游 MCP Server 聚合成单个面向下游的 `stdio` 节点。
 
 ```bash
 nuwax-mcp-stdio-proxy --config '{"mcpServers":{...}}'
 ```
 
-The proxy reads JSON from `--config` and runs as a stdio MCP server. Upstream servers can be:
+配置中可以混合配置 `stdio` (子进程) 和 `bridge` (HTTP 连接) 类型的上游服务器。代理会统一将它们聚合并向客户端暴露唯一的一个 `stdio` MCP 交互接口。
 
-- **stdio**: `{ "command", "args?", "env?" }` — proxy spawns a child process and talks MCP over stdin/stdout.
-- **bridge**: `{ "url" }` — proxy connects via HTTP (Streamable HTTP) to a long-lived MCP bridge (e.g. Electron app’s PersistentMcpBridge).
+### 2. 协议转换模式 (`convert`)
 
-## Config format
+将单个远程的 SSE 或 Streamable HTTP MCP Server 代理转化为本地的 `stdio` MCP Server。适用于仅支持 `stdio` 接入的客户端应用。
 
-| Entry type | Shape | Description |
-|------------|--------|-------------|
-| **stdio** | `{ "command": string, "args"?: string[], "env"?: Record<string, string> }` | Spawn subprocess; MCP over stdio. |
-| **bridge** | `{ "url": string }` | Connect to MCP over HTTP (e.g. `http://127.0.0.1:PORT/mcp/<serverId>`). |
+```bash
+nuwax-mcp-stdio-proxy convert http://example.com/mcp/sse --protocol sse
+```
 
-Example:
+### 3. 持久化 HTTP 桥接模式 (`proxy`)
+
+作为 Streamable HTTP Server 启动 `PersistentMcpBridge`。该模式会预先构建并管理标准的 `stdio` 子进程，进而将它们通过高速、可秒连的 HTTP 接口暴露给下游使用。
+
+```bash
+nuwax-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'
+```
+
+## 配置文件格式
+
+在使用默认聚合模式或 `proxy` 模式时，使用如下结构的 JSON 配置：
+
+| 节点类型   | 配置结构                                                                   | 描述                                                                    |
+| ---------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **stdio**  | `{ "command": string, "args"?: string[], "env"?: Record<string, string> }` | 创建子进程；通过 stdio 进行 MCP 通信。                                  |
+| **bridge** | `{ "url": string }`                                                        | 通过 HTTP 建立 MCP 连接 (例如 `http://127.0.0.1:PORT/mcp/<serverId>`)。 |
+
+**配置示例：**
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/path/to/allowed"
+      ]
     },
     "chrome-devtools": {
       "url": "http://127.0.0.1:57278/mcp/chrome-devtools"
@@ -40,31 +67,27 @@ Example:
 }
 ```
 
-- `filesystem` → stdio (child process).
-- `chrome-devtools` → bridge (HTTP to a persistent bridge).
-
-## Architecture
+## 架构简图
 
 ```
-Agent / ACP engine (stdin/stdout)
+Agent / ACP 引擎客户端 (stdin/stdout)
         ↕
-  nuwax-mcp-stdio-proxy (StdioServerTransport)
-        ├→ stdio upstream  → child process (StdioClientTransport)
-        └→ bridge upstream → StreamableHTTPClientTransport → PersistentMcpBridge HTTP
+  nuwax-mcp-stdio-proxy (Stdio 模式)
+        ├→ [stdio 上游]  → Spawn 启动子进程 (StdioClientTransport)
+        └→ [bridge 上游] → StreamableHTTPClientTransport → 连接 PersistentMcpBridge HTTP
 ```
 
-- **Downstream**: one stdio MCP server; the agent talks to the proxy over stdin/stdout.
-- **Upstream**: multiple backends — some are child processes (stdio), some are HTTP bridge endpoints. Tools from all upstreams are aggregated and exposed as one tool list.
+通过引入 `proxy` 模式开启 `PersistentMcpBridge`，上层的应用可以剥离 MCP Server 的原本子进程生命周期，从而避免启动初期的时序竞争条件，同时能够更加可靠、整洁地在退出时销毁无用进程。
 
-## Scripts
+## 开发指令
 
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Compile TypeScript to `dist/`. |
-| `npm run test` | Run tests (Vitest). |
-| `npm run test:run` | Run tests once (no watch). |
-| `npm run test:coverage` | Run tests with coverage. |
+| 指令                    | 描述                                                         |
+| ----------------------- | ------------------------------------------------------------ |
+| `npm run build`         | 编译 TypeScript 输出到 `dist/` 目录。                        |
+| `npm run test`          | 运行测试 (Vitest)。                                          |
+| `npm run test:run`      | 单次运行所有的单元与集成测试 (无监控交互)。                  |
+| `npm run test:coverage` | 运行测试并生成详细的覆盖率统计报告 (存于 `coverage/` 目录)。 |
 
-## License
+## 许可证
 
 MIT

package/dist/bridge.js

@@ -20,7 +20,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { CustomStdioClientTransport } from './customStdio.js';
-const LOG_TAG = '[PersistentMcpBridge]';
+import { ResilientTransportWrapper } from './resilient.js';
+const LOG_TAG = '[McpProxy] [PersistentMcpBridge]';
 const BASE_RESTART_COOLDOWN_MS = 5_000;
 const MAX_RESTART_ATTEMPTS = 5;
 const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10 MB
@@ -49,17 +50,36 @@ export class PersistentMcpBridge {
             this.log.warn(`${LOG_TAG} Already running, stopping first`);
             await this.stop();
         }
-        this.log.info(`${LOG_TAG} Starting with ${Object.keys(servers).length} persistent servers`);
-        // 1. Spawn each persistent server + create MCP Client
-        for (const [id, config] of Object.entries(servers)) {
-            await this.startServer(id, config);
+        const serverCount = Object.keys(servers).length;
+        this.log.info(`${LOG_TAG} Starting with ${serverCount} persistent servers (parallel)`);
+        // 1. 并行启动 HTTP server 和所有 MCP server 子进程。
+        //    两者完全独立：HTTP server 在请求时才查询 this.servers，
+        //    startServer 会在异步 spawnAndConnect 前先同步写入 this.servers，
+        //    所以 HTTP server 收到第一个请求时所有 entry 都已注册。
+        //
+        //    提前保存 serverPromises 引用：若 startHttpServer 抛出，在 catch 中先
+        //    await Promise.allSettled(serverPromises) 等所有 spawnAndConnect 跑完
+        //    （保证 entry.client / entry.transport 已赋值），再调用 stopServer，
+        //    才能可靠关闭子进程，防止孤儿进程残留。
+        const serverPromises = Object.entries(servers).map(([id, config]) => this.startServer(id, config));
+        try {
+            await Promise.all([
+                this.startHttpServer(options?.port),
+                ...serverPromises,
+            ]);
+        }
+        catch (e) {
+            this.log.error(`${LOG_TAG} 启动失败，清理已 spawn 的子进程:`, e);
+            // 等待所有 spawnAndConnect 完成，确保 entry.client/transport 已赋值后再清理
+            await Promise.allSettled(serverPromises);
+            await Promise.all(Array.from(this.servers.keys()).map((id) => this.stopServer(id)));
+            this.servers.clear();
+            throw e;
         }
-        // 2. Start HTTP server
-        await this.startHttpServer(options?.port);
         this.running = true;
-        // 3. Start periodic session cleanup
+        // 2. Start periodic session cleanup
         this.sessionCleanupTimer = setInterval(() => this.cleanupStaleSessions(), SESSION_CLEANUP_INTERVAL_MS);
-        this.log.info(`${LOG_TAG} Bridge ready on port ${this.port}`);
+        this.log.info(`${LOG_TAG} Bridge ready on port ${this.port} (${serverCount} servers)`);
     }
     /**
      * Stop bridge: close HTTP, kill all child processes
@@ -72,15 +92,16 @@ export class PersistentMcpBridge {
             clearInterval(this.sessionCleanupTimer);
             this.sessionCleanupTimer = null;
         }
-        // Close all HTTP sessions
-        for (const [key, session] of this.httpSessions) {
+        // 并行关闭所有 HTTP sessions（各 session transport 独立，无顺序依赖）。
+        // 内层 async 函数自行 catch 错误后不再 throw，Promise.all 足够，不需要 allSettled。
+        await Promise.all(Array.from(this.httpSessions.entries()).map(async ([key, session]) => {
             try {
                 await session.transport.close();
             }
             catch (e) {
                 this.log.warn(`${LOG_TAG} Error closing HTTP session ${key}:`, e);
             }
-        }
+        }));
         this.httpSessions.clear();
         // Close HTTP server
         if (this.httpServer) {
@@ -90,10 +111,8 @@ export class PersistentMcpBridge {
             this.httpServer = null;
             this.port = 0;
         }
-        // Stop all persistent servers
-        for (const [id] of this.servers) {
-            await this.stopServer(id);
-        }
+        // 并行关闭所有 MCP server 子进程（各自独立，无顺序依赖）
+        await Promise.all(Array.from(this.servers.keys()).map((id) => this.stopServer(id)));
         this.servers.clear();
         this.log.info(`${LOG_TAG} Stopped`);
     }
@@ -138,38 +157,50 @@ export class PersistentMcpBridge {
     async spawnAndConnect(id, entry) {
         try {
             this.log.info(`${LOG_TAG} Spawning server "${id}": ${entry.config.command} ${(entry.config.args || []).join(' ')}`);
-            // Create MCP Client + CustomStdioClientTransport (handles spawn internally)
-            const transport = new CustomStdioClientTransport({
-                command: entry.config.command,
-                args: entry.config.args || [],
-                env: entry.config.env,
-                stderr: 'pipe',
+            // Create MCP Client + ResilientTransportWrapper
+            const wrapper = new ResilientTransportWrapper({
+                name: id,
+                logger: this.log,
+                connectParams: async () => {
+                    const t = new CustomStdioClientTransport({
+                        command: entry.config.command,
+                        args: entry.config.args || [],
+                        env: entry.config.env,
+                        stderr: 'pipe',
+                    });
+                    if (t.stderr) {
+                        t.stderr.on('data', (chunk) => {
+                            const text = chunk.toString().trim();
+                            if (text)
+                                this.log.info(`${LOG_TAG} [${id}:stderr] ${text}`);
+                        });
+                    }
+                    return t;
+                },
+                pingIntervalMs: entry.config.pingIntervalMs,
+                pingTimeoutMs: entry.config.pingTimeoutMs,
             });
             const client = new Client({ name: 'nuwax-persistent-bridge', version: '1.0.0' }, { capabilities: {} });
             // Handle transport close → auto restart
-            transport.onclose = () => {
+            wrapper.onclose = () => {
                 this.log.warn(`${LOG_TAG} Server "${id}" transport closed`);
                 entry.healthy = false;
                 if (this.running && !entry.restarting) {
                     this.scheduleRestart(id, entry);
                 }
             };
-            transport.onerror = (err) => {
+            wrapper.onerror = (err) => {
                 this.log.error(`${LOG_TAG} Server "${id}" transport error:`, err.message);
             };
             // Connect client to transport (this starts the subprocess)
-            await client.connect(transport);
+            await wrapper.start();
+            await client.connect(wrapper);
+            // Enable heartbeat monitoring AFTER the MCP initialize handshake
+            // completes — sending pings before initialize causes "Server not
+            // initialized" errors from the MCP server.
+            wrapper.enableHeartbeat();
             entry.client = client;
-            entry.transport = transport;
-            // Pipe stderr for debugging
-            const stderrStream = transport.stderr;
-            if (stderrStream) {
-                stderrStream.on('data', (chunk) => {
-                    const text = chunk.toString().trim();
-                    if (text)
-                        this.log.info(`${LOG_TAG} [${id}:stderr] ${text}`);
-                });
-            }
+            entry.transport = wrapper;
             // List tools (cached)
             const result = await client.listTools();
             entry.tools = result.tools;