nuwax-mcp-stdio-proxy 1.3.1 → 1.4.0

package/dist/bridge.d.ts

@@ -32,8 +32,13 @@ export declare class PersistentMcpBridge {
     constructor(logger?: BridgeLogger);
     /**
      * Start bridge: spawn child processes for each persistent server and create HTTP server
+     *
+     * @param servers - Map of server ID to stdio config
+     * @param options - Optional settings (e.g. port to listen on)
      */
-    start(servers: Record<string, StdioServerEntry>): Promise<void>;
+    start(servers: Record<string, StdioServerEntry>, options?: {
+        port?: number;
+    }): Promise<void>;
     /**
      * Stop bridge: close HTTP, kill all child processes
      */

package/dist/bridge.js

@@ -40,8 +40,11 @@ export class PersistentMcpBridge {
     }
     /**
      * Start bridge: spawn child processes for each persistent server and create HTTP server
+     *
+     * @param servers - Map of server ID to stdio config
+     * @param options - Optional settings (e.g. port to listen on)
      */
-    async start(servers) {
+    async start(servers, options) {
         if (this.running) {
             this.log.warn(`${LOG_TAG} Already running, stopping first`);
             await this.stop();
@@ -52,7 +55,7 @@ export class PersistentMcpBridge {
             await this.startServer(id, config);
         }
         // 2. Start HTTP server
-        await this.startHttpServer();
+        await this.startHttpServer(options?.port);
         this.running = true;
         // 3. Start periodic session cleanup
         this.sessionCleanupTimer = setInterval(() => this.cleanupStaleSessions(), SESSION_CLEANUP_INTERVAL_MS);
@@ -246,7 +249,7 @@ export class PersistentMcpBridge {
         entry.transport = null;
     }
     // ==================== Internal: HTTP Server ====================
-    async startHttpServer() {
+    async startHttpServer(listenPort) {
         return new Promise((resolve, reject) => {
             const server = http.createServer((req, res) => {
                 this.handleHttpRequest(req, res).catch((e) => {
@@ -257,8 +260,8 @@ export class PersistentMcpBridge {
                     }
                 });
             });
-            // Listen on random port
-            server.listen(0, '127.0.0.1', () => {
+            // Listen on specified port or random port (0)
+            server.listen(listenPort ?? 0, '127.0.0.1', () => {
                 const addr = server.address();
                 if (addr && typeof addr === 'object') {
                     this.port = addr.port;

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Package constants — injected at build time by esbuild define (see build.mjs)
+ *
+ * Falls back to static values when running via tsc in development.
+ */
+export declare const PKG_NAME: string;
+export declare const PKG_VERSION: string;

package/dist/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Package constants — injected at build time by esbuild define (see build.mjs)
+ *
+ * Falls back to static values when running via tsc in development.
+ */
+export const PKG_NAME = process.env.__MCP_PROXY_PKG_NAME__ || 'nuwax-mcp-stdio-proxy';
+export const PKG_VERSION = process.env.__MCP_PROXY_PKG_VERSION__ || '0.0.0-dev';

package/dist/detect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Protocol auto-detection — determine whether a URL serves Streamable HTTP or SSE
+ */
+/**
+ * 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.
+ */
+export declare function detectProtocol(url: string, headers?: Record<string, string>): Promise<'sse' | 'stream'>;

package/dist/detect.js

@@ -0,0 +1,95 @@
+/**
+ * Protocol auto-detection — determine whether a URL serves Streamable HTTP or SSE
+ */
+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.
+ */
+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',
+            Accept: 'application/json, text/event-stream',
+            ...headers,
+        };
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10_000);
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: reqHeaders,
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'nuwax-mcp-detect', version: '1.0.0' },
+                },
+            }),
+            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
+            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}`);
+            controller.abort();
+            return 'sse';
+        }
+        clearTimeout(timeout);
+        await res.text().catch(() => { });
+    }
+    catch {
+        // SSE probe failed
+    }
+    // 3. Default to streamable-http
+    logWarn(`Could not auto-detect protocol for ${url}, defaulting to streamable-http`);
+    return 'stream';
+}

package/dist/filter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool filtering — whitelist/blacklist tools by name
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export interface ToolFilter {
+    allowTools?: Set<string>;
+    denyTools?: Set<string>;
+}
+/**
+ * Filter tools by allow/deny lists.
+ * - If allowTools is set, only tools in the set are returned.
+ * - If denyTools is set, tools in the set are excluded.
+ * - If both are set, allowTools takes precedence.
+ * - If neither is set, all tools are returned unchanged.
+ */
+export declare function filterTools(tools: Tool[], filter: ToolFilter): Tool[];

package/dist/filter.js

@@ -0,0 +1,19 @@
+/**
+ * Tool filtering — whitelist/blacklist tools by name
+ */
+/**
+ * Filter tools by allow/deny lists.
+ * - If allowTools is set, only tools in the set are returned.
+ * - If denyTools is set, tools in the set are excluded.
+ * - If both are set, allowTools takes precedence.
+ * - If neither is set, all tools are returned unchanged.
+ */
+export function filterTools(tools, filter) {
+    if (filter.allowTools && filter.allowTools.size > 0) {
+        return tools.filter((t) => filter.allowTools.has(t.name));
+    }
+    if (filter.denyTools && filter.denyTools.size > 0) {
+        return tools.filter((t) => !filter.denyTools.has(t.name));
+    }
+    return tools;
+}

package/dist/index.d.ts

@@ -1,22 +1,19 @@
 /**
- * nuwax-mcp-stdio-proxy
+ * nuwax-mcp-stdio-proxy — CLI entry point
  *
- * A pure TypeScript stdio MCP proxy that aggregates multiple MCP servers
- * into a single MCP server endpoint. Supports two upstream transport types:
+ * A pure TypeScript MCP proxy with three operating modes:
  *
- * - **stdio**: Spawns child MCP server processes (StdioClientTransport)
- * - **bridge**: Connects to persistent MCP Bridge servers via StreamableHTTP (StreamableHTTPClientTransport)
+ * 1. **Default (stdio aggregation)**: Aggregates multiple MCP servers
+ *    (stdio + streamable-http + SSE) into a single stdio endpoint.
+ *    Usage: nuwax-mcp-stdio-proxy --config '{"mcpServers":{...}}'
  *
- * Usage:
- *   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
- *   }}'
+ * 2. **convert**: Connects to a single remote MCP service and exposes via stdio.
+ *    Usage: nuwax-mcp-stdio-proxy convert [URL] [OPTIONS]
  *
- * Architecture:
- *   Agent Engine (stdin/stdout)  ←→  This Proxy (StdioServerTransport)
- *                                         ├→ Child MCP Server A (StdioClientTransport)
- *                                         ├→ Bridge MCP Server B (StreamableHTTPClientTransport)
- *                                         └→ ...
+ * 3. **proxy**: Starts PersistentMcpBridge as a Streamable HTTP server.
+ *    Usage: nuwax-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'
+ *
+ * This file handles CLI argument parsing and routes to the appropriate mode.
+ * Mode implementations live in modes/*.ts.
  */
 export {};