nuwax-mcp-stdio-proxy 1.4.6 → 1.4.8

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
@@ -156,38 +157,45 @@ 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: 0, // No heartbeat for stdio — child process close/error events handle detection
             });
             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);
             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;

package/dist/detect.d.ts

@@ -1,14 +1,20 @@
 /**
  * Protocol auto-detection — determine whether a URL serves Streamable HTTP or SSE
+ *
+ * Aligned with workspace/mcp-proxy (Rust) detection logic:
+ * - Only probe Streamable HTTP (POST initialize)
+ * - Default to SSE if probe fails
  */
 /**
  * Detect the MCP transport protocol of a remote URL.
  *
- * Strategy:
- * 1. Try Streamable HTTP first: send a JSON-RPC initialize POST.
- *    If the server responds with 200 and JSON, it's streamable-http.
- *    Then clean up the orphan session via DELETE.
- * 2. If that fails, try SSE: send a GET and check for text/event-stream content-type.
- * 3. Default to 'stream' (Streamable HTTP) if both probes fail.
+ * Strategy (matches Rust mcp-proxy):
+ * 1. Send a JSON-RPC initialize POST to probe for Streamable HTTP.
+ * 2. Check 4 criteria — any match means streamable-http:
+ *    a. Response has `mcp-session-id` header
+ *    b. Content-Type is `text/event-stream` with 2xx status
+ *    c. Response body is valid JSON-RPC 2.0
+ *    d. Status is 406 Not Acceptable
+ * 3. If probe fails or no criteria match → default to SSE.
  */
 export declare function detectProtocol(url: string, headers?: Record<string, string>): Promise<'sse' | 'stream'>;

package/dist/detect.js

@@ -1,20 +1,25 @@
 /**
  * Protocol auto-detection — determine whether a URL serves Streamable HTTP or SSE
+ *
+ * Aligned with workspace/mcp-proxy (Rust) detection logic:
+ * - Only probe Streamable HTTP (POST initialize)
+ * - Default to SSE if probe fails
  */
 import { logInfo, logWarn } from './logger.js';
 /**
  * Detect the MCP transport protocol of a remote URL.
  *
- * Strategy:
- * 1. Try Streamable HTTP first: send a JSON-RPC initialize POST.
- *    If the server responds with 200 and JSON, it's streamable-http.
- *    Then clean up the orphan session via DELETE.
- * 2. If that fails, try SSE: send a GET and check for text/event-stream content-type.
- * 3. Default to 'stream' (Streamable HTTP) if both probes fail.
+ * Strategy (matches Rust mcp-proxy):
+ * 1. Send a JSON-RPC initialize POST to probe for Streamable HTTP.
+ * 2. Check 4 criteria — any match means streamable-http:
+ *    a. Response has `mcp-session-id` header
+ *    b. Content-Type is `text/event-stream` with 2xx status
+ *    c. Response body is valid JSON-RPC 2.0
+ *    d. Status is 406 Not Acceptable
+ * 3. If probe fails or no criteria match → default to SSE.
  */
 export async function detectProtocol(url, headers) {
     logInfo(`Auto-detecting protocol for ${url}...`);
-    // 1. Try Streamable HTTP — POST a JSON-RPC initialize request
     try {
         const reqHeaders = {
             'Content-Type': 'application/json',
@@ -22,7 +27,7 @@ export async function detectProtocol(url, headers) {
             ...headers,
         };
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 10_000);
+        const timeout = setTimeout(() => controller.abort(), 5_000);
         const res = await fetch(url, {
             method: 'POST',
             headers: reqHeaders,
@@ -39,57 +44,61 @@ export async function detectProtocol(url, headers) {
             signal: controller.signal,
         });
         clearTimeout(timeout);
-        const ct = res.headers.get('content-type') || '';
-        if (res.ok && (ct.includes('application/json') || ct.includes('text/event-stream'))) {
-            logInfo(`Detected streamable-http protocol for ${url}`);
-            // Consume body to avoid socket hang
+        // Check 1: mcp-session-id header (definitive Streamable HTTP marker)
+        if (res.headers.get('mcp-session-id')) {
+            logInfo(`Detected streamable-http protocol for ${url} (mcp-session-id header)`);
+            cleanupSession(url, res.headers.get('mcp-session-id'), headers);
             await res.text().catch(() => { });
-            // Clean up orphan session — fire-and-forget DELETE so the server
-            // can discard the half-initialized session we created during probing.
-            // Not awaited: cleanup is best-effort and must not block detection.
-            const sessionId = res.headers.get('mcp-session-id');
-            if (sessionId) {
-                fetch(url, {
-                    method: 'DELETE',
-                    headers: { 'mcp-session-id': sessionId, ...headers },
-                    signal: AbortSignal.timeout(5_000),
-                }).catch(() => { });
-            }
             return 'stream';
         }
-        await res.text().catch(() => { });
-    }
-    catch {
-        // Streamable HTTP probe failed, try SSE
-    }
-    // 2. Try SSE — GET and check for event-stream
-    try {
-        const reqHeaders = {
-            Accept: 'text/event-stream',
-            ...headers,
-        };
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 10_000);
-        const res = await fetch(url, {
-            method: 'GET',
-            headers: reqHeaders,
-            signal: controller.signal,
-        });
         const ct = res.headers.get('content-type') || '';
-        if (ct.includes('text/event-stream')) {
-            // Detected SSE — abort the stream before clearing the timeout
-            clearTimeout(timeout);
-            logInfo(`Detected SSE protocol for ${url}`);
+        // Check 2: text/event-stream content-type with success status
+        if (ct.includes('text/event-stream') && res.ok) {
+            logInfo(`Detected streamable-http protocol for ${url} (event-stream response)`);
+            cleanupSession(url, res.headers.get('mcp-session-id'), headers);
+            // Abort the stream to free the connection
             controller.abort();
-            return 'sse';
+            return 'stream';
+        }
+        // Read body for JSON-RPC check
+        let bodyText = '';
+        try {
+            bodyText = await res.text();
+        }
+        catch { /* ignore */ }
+        // Check 3: valid JSON-RPC 2.0 response
+        try {
+            const json = JSON.parse(bodyText);
+            if (json && json.jsonrpc === '2.0') {
+                logInfo(`Detected streamable-http protocol for ${url} (JSON-RPC 2.0 response)`);
+                cleanupSession(url, res.headers.get('mcp-session-id'), headers);
+                return 'stream';
+            }
+        }
+        catch { /* not JSON */ }
+        // Check 4: 406 Not Acceptable (may indicate Streamable HTTP)
+        if (res.status === 406) {
+            logInfo(`Detected streamable-http protocol for ${url} (406 Not Acceptable)`);
+            return 'stream';
         }
-        clearTimeout(timeout);
-        await res.text().catch(() => { });
     }
     catch {
-        // SSE probe failed
+        // Probe failed (timeout, connection refused, etc.)
     }
-    // 3. Default to streamable-http
-    logWarn(`Could not auto-detect protocol for ${url}, defaulting to streamable-http`);
-    return 'stream';
+    // Default to SSE (matches Rust mcp-proxy behavior)
+    logWarn(`Could not detect streamable-http for ${url}, defaulting to SSE`);
+    return 'sse';
+}
+/**
+ * Clean up orphan session — fire-and-forget DELETE so the server
+ * can discard the half-initialized session we created during probing.
+ */
+function cleanupSession(url, sessionId, headers) {
+    if (!sessionId)
+        return;
+    fetch(url, {
+        method: 'DELETE',
+        headers: { 'mcp-session-id': sessionId, ...headers },
+        signal: AbortSignal.timeout(5_000),
+    }).catch(() => { });
 }