@silver886/mcp-proxy 0.2.3 → 0.2.5

package/README.md

@@ -106,7 +106,8 @@ single-proxy, in line with MCP's one-server-one-client model.)
 2. Agent calls the `configure` tool. Proxy spawns a Node wrapper that owns
    a `cloudflared` quick tunnel pointing at a local pairing HTTP server.
    That HTTP server serves both the setup page (GET /) and the pairing API
-   (POST /pair/forward, POST /pair/complete) on the same origin.
+   (POST /pair/list-servers, POST /pair/discover, POST /pair/complete) on
+   the same origin.
 3. Wrapper prints the tunnel URL. Proxy mints a bearer token and emits a
    setup URL — `<tunnel>/#token=<token>`. Token rides in the URL fragment
    so it never appears in server access logs or Referer headers.

package/dist/host/agent.js

@@ -29,25 +29,63 @@ class HostAgent {
     boundPort;
     constructor(configPath, timeout, overrides) {
         const raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
-        this.config = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
         this.timeout = timeout;
         this.authToken = (0, node_crypto_1.randomBytes)(32).toString("base64url"); // 256-bit token
-        this.boundHost = overrides?.host ?? this.config.host ?? protocol_js_1.DEFAULT_HOST;
-        // port 0 = let the OS pick. Resolved to the real bound port in start().
-        this.boundPort = overrides?.port ?? this.config.port ?? protocol_js_1.DEFAULT_PORT;
-        // Reject server names that the proxy/page would silently drop later.
-        // Authoritative at config-load time so misnamed servers surface as a
-        // startup error instead of disappearing during discovery.
+        // Single boundary-time validation pass: server-name policy, per-entry
+        // shape, and top-level host/port. Documented defaults (args=[]) are
+        // installed by normalizeServerConfig so downstream consumers can trust
+        // the ServerConfig contract instead of re-checking shapes — without
+        // this, omitting `args` (legal per README) crashes McpSession deep
+        // inside `args.join(" ")`. All reasons are accumulated so a broken
+        // file surfaces a complete diff to fix in one error message rather
+        // than one-issue-per-restart.
         const invalid = [];
-        for (const name of Object.keys(this.config.servers)) {
-            const reason = (0, protocol_js_1.validateServerName)(name);
-            if (reason)
-                invalid.push(`  - "${name}": ${reason}`);
+        const servers = {};
+        if (!parsed.servers || typeof parsed.servers !== "object" || Array.isArray(parsed.servers)) {
+            invalid.push(`  - "servers": must be an object map of name to config`);
+        }
+        else {
+            const rawServers = parsed.servers;
+            if (Object.keys(rawServers).length === 0) {
+                invalid.push(`  - "servers": at least one server must be declared`);
+            }
+            for (const [name, entry] of Object.entries(rawServers)) {
+                const nameReason = (0, protocol_js_1.validateServerName)(name);
+                if (nameReason)
+                    invalid.push(`  - "${name}": ${nameReason}`);
+                const result = (0, protocol_js_1.normalizeServerConfig)(entry);
+                if (!result.ok) {
+                    for (const reason of result.reasons)
+                        invalid.push(`  - "${name}": ${reason}`);
+                }
+                else if (!nameReason) {
+                    servers[name] = result.config;
+                }
+            }
+        }
+        if (parsed.host !== undefined && typeof parsed.host !== "string") {
+            invalid.push(`  - "host": must be a string (default: ${protocol_js_1.DEFAULT_HOST})`);
+        }
+        if (parsed.port !== undefined
+            && (typeof parsed.port !== "number"
+                || !Number.isInteger(parsed.port)
+                || parsed.port < 0
+                || parsed.port > 65535)) {
+            invalid.push(`  - "port": must be an integer 0–65535 (default: ${protocol_js_1.DEFAULT_PORT})`);
         }
         if (invalid.length > 0) {
-            throw new Error(`Invalid server name(s) in ${configPath}:\n${invalid.join("\n")}\n` +
-                `Rename the entries in config.json so they match the policy.`);
+            throw new Error(`Invalid host config in ${configPath}:\n${invalid.join("\n")}\n` +
+                `Fix the entries in config.json so they match the documented schema.`);
         }
+        this.config = {
+            servers,
+            host: typeof parsed.host === "string" ? parsed.host : undefined,
+            port: typeof parsed.port === "number" ? parsed.port : undefined,
+        };
+        this.boundHost = overrides?.host ?? this.config.host ?? protocol_js_1.DEFAULT_HOST;
+        // port 0 = let the OS pick. Resolved to the real bound port in start().
+        this.boundPort = overrides?.port ?? this.config.port ?? protocol_js_1.DEFAULT_PORT;
     }
     get port() {
         return this.boundPort;
@@ -200,19 +238,28 @@ class HostAgent {
     async handleMcpPost(req, res, serverName, serverConfig) {
         const body = await (0, protocol_js_1.readBody)(req);
         const headerSessionId = req.headers["mcp-session-id"];
-        // Peek the JSON-RPC method without consuming the body. Only `initialize`
-        // may run without an existing session — anything else against an
-        // unknown id is stale (post-GC, post-restart) or wrong, and silently
-        // spawning a fresh uninitialized child for it would violate the MCP
-        // handshake.
-        let method;
+        // Parse once at the HTTP boundary. The host is the JSON-RPC endpoint
+        // from the proxy's perspective, so a malformed body must surface as a
+        // spec-compliant parse-error response with id:null — not get forwarded
+        // to the child as a notification. Without this gate the body falls
+        // through sendRequest's `id === undefined` branch (notification path),
+        // garbage hits stdin, the caller gets a misleading 202, and the
+        // child's parse-error reply arrives with id:null and is dropped as an
+        // orphan — guaranteeing a silent timeout on the proxy.
+        let parsedBody;
         try {
-            method = JSON.parse(body).method;
+            parsedBody = JSON.parse(body);
         }
         catch {
-            // Unparseable body falls through as non-initialize → 404 below.
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.PARSE_ERROR, undefined, null));
+            return;
         }
-        const isInitialize = method === "initialize";
+        // Only `initialize` may run without an existing session — anything
+        // else against an unknown id is stale (post-GC, post-restart) or
+        // wrong, and silently spawning a fresh uninitialized child for it
+        // would violate the MCP handshake.
+        const isInitialize = parsedBody.method === "initialize";
         let existing;
         if (headerSessionId) {
             existing = this.sessions.get(headerSessionId);

package/dist/proxy/core/constants.d.ts

@@ -6,6 +6,8 @@ export declare const UPSTREAM_REQUEST_TIMEOUT_MS = 120000;
 export declare const DISCOVERY_FETCH_TIMEOUT_MS = 15000;
 export declare const TOOL_FORWARD_TIMEOUT_MS: number;
 export declare const SESSION_DELETE_TIMEOUT_MS = 5000;
+export declare const PAIRING_HEADERS_TIMEOUT_MS = 30000;
+export declare const PAIRING_REQUEST_TIMEOUT_MS = 60000;
 export declare const SSE_BACKOFF_INITIAL_MS = 500;
 export declare const SSE_BACKOFF_MAX_MS = 10000;
 export declare const SSE_CONNECT_TIMEOUT_MS = 15000;

package/dist/proxy/core/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIGURE_PROMPT = exports.CONFIGURE_TOOL = exports.SSE_CONNECT_TIMEOUT_MS = exports.SSE_BACKOFF_MAX_MS = exports.SSE_BACKOFF_INITIAL_MS = exports.SESSION_DELETE_TIMEOUT_MS = exports.TOOL_FORWARD_TIMEOUT_MS = exports.DISCOVERY_FETCH_TIMEOUT_MS = exports.UPSTREAM_REQUEST_TIMEOUT_MS = exports.PAIRING_WINDOW_MS = exports.TUNNEL_STARTUP_TIMEOUT_MS = exports.TOOL_SEPARATOR = void 0;
+exports.CONFIGURE_PROMPT = exports.CONFIGURE_TOOL = exports.SSE_CONNECT_TIMEOUT_MS = exports.SSE_BACKOFF_MAX_MS = exports.SSE_BACKOFF_INITIAL_MS = exports.PAIRING_REQUEST_TIMEOUT_MS = exports.PAIRING_HEADERS_TIMEOUT_MS = exports.SESSION_DELETE_TIMEOUT_MS = exports.TOOL_FORWARD_TIMEOUT_MS = exports.DISCOVERY_FETCH_TIMEOUT_MS = exports.UPSTREAM_REQUEST_TIMEOUT_MS = exports.PAIRING_WINDOW_MS = exports.TUNNEL_STARTUP_TIMEOUT_MS = exports.TOOL_SEPARATOR = void 0;
 const protocol_js_1 = require("../../shared/protocol.js");
 exports.TOOL_SEPARATOR = protocol_js_1.TOOL_NAME_SEPARATOR;
 // Pairing-tunnel + bridging budgets.
@@ -15,6 +15,13 @@ exports.UPSTREAM_REQUEST_TIMEOUT_MS = 120_000; // server→client bridge
 exports.DISCOVERY_FETCH_TIMEOUT_MS = 15_000;
 exports.TOOL_FORWARD_TIMEOUT_MS = 5 * 60 * 1000;
 exports.SESSION_DELETE_TIMEOUT_MS = 5_000;
+// Pairing HTTP server per-request budgets. Pairing payloads are small JSON
+// blobs (host creds, selected servers/tools), so a slow header or body
+// phase is broken or hostile rather than legitimate. Bounding both prevents
+// a slow upload from outliving PAIRING_WINDOW_MS via Node's defaults
+// (headersTimeout 60s, requestTimeout 5min).
+exports.PAIRING_HEADERS_TIMEOUT_MS = 30_000;
+exports.PAIRING_REQUEST_TIMEOUT_MS = 60_000;
 exports.SSE_BACKOFF_INITIAL_MS = 500;
 exports.SSE_BACKOFF_MAX_MS = 10_000;
 // Bound the connect+headers phase only. A blackholed tunnel would otherwise

package/dist/proxy/discovery/client.js

@@ -13,6 +13,17 @@ exports.listHostServers = listHostServers;
 const protocol_js_1 = require("../../shared/protocol.js");
 const constants_js_1 = require("../core/constants.js");
 const fetch_timeout_js_1 = require("../core/fetch-timeout.js");
+// Discovery helpers. List calls (tools/prompts/resources/templates)
+// distinguish METHOD_NOT_FOUND ("feature absent" → []) from any other
+// failure (transport blip, JSON-RPC error, malformed body → throw). The
+// caller decides whether to preserve cached state, mark a per-capability
+// retry flag, or fail outright. Every fetch is wrapped in
+// DISCOVERY_FETCH_TIMEOUT_MS so a host that accepts the connection then
+// hangs can't pin the proxy.
+// JSON-RPC METHOD_NOT_FOUND — what an MCP server returns when it doesn't
+// support a capability. Treated as "feature absent" (empty list), distinct
+// from a transport blip which the strict variants surface as a throw.
+const METHOD_NOT_FOUND = -32601;
 async function initializeServer(targetUrl, baseHeaders, name, clientCapabilities, clientInfo) {
     const resp = await fetch(targetUrl, {
         method: "POST",
@@ -81,14 +92,13 @@ async function fetchTools(targetUrl, headers, name) {
         throw new Error(`tools/list returned malformed JSON: ${err.message}`);
     }
     const error = data.error;
-    if (error)
+    if (error) {
+        if (error.code === METHOD_NOT_FOUND)
+            return [];
         throw new Error(`tools/list error: ${error.message ?? JSON.stringify(error)}`);
+    }
     return extractListField(data, "tools/list", "tools");
 }
-// JSON-RPC METHOD_NOT_FOUND — what an MCP server returns when it doesn't
-// support a capability. Treated as "feature absent" (empty list), distinct
-// from a transport blip which the strict variants surface as a throw.
-const METHOD_NOT_FOUND = -32601;
 // Run a tools/prompts/resources-style list call against the upstream and
 // extract the list field. Throws on any transport, parse, or JSON-RPC
 // failure other than METHOD_NOT_FOUND, which collapses to []. Callers
@@ -148,12 +158,15 @@ class DiscoveryError extends Error {
 }
 exports.DiscoveryError = DiscoveryError;
 // Single source of truth for the per-server MCP handshake: initialize →
-// notifications/initialized → tools/list (required) → prompts / resources /
-// templates (each optional, recorded as pending on failure). Used by both
-// the runtime discovery path and the pairing-mediated discovery endpoint
-// so the browser sees the same capability set the proxy will see at
-// runtime — including using the real MCP client's capabilities/clientInfo
-// rather than synthetic browser values.
+// notifications/initialized → tools / prompts / resources / templates
+// (each optional — METHOD_NOT_FOUND collapses to [], other failures on
+// prompts/resources/templates are recorded as pending; tools failures
+// other than METHOD_NOT_FOUND are still fatal because tools/list is the
+// canonical "is this server alive" probe). Used by both the runtime
+// discovery path and the pairing-mediated discovery endpoint so the
+// browser sees the same capability set the proxy will see at runtime —
+// including using the real MCP client's capabilities/clientInfo rather
+// than synthetic browser values.
 async function discoverServerCapabilities(targetUrl, baseHeaders, name, clientCapabilities, clientInfo, log) {
     let sessionId;
     try {

package/dist/proxy/pairing/controller.d.ts

@@ -8,12 +8,15 @@ export declare class PairingController {
     private readonly log;
     private readonly sendNotification;
     private pairing;
+    private configureInflight;
     constructor(state: ProxyState, runner: DiscoveryRunner, bridge: UpstreamBridge, log: (line: string) => void, sendNotification: (method: string) => void);
     handleConfigure(): Promise<string>;
+    private doConfigure;
     teardownPairing(): void;
     private validateHostCreds;
     private handleListServers;
     private handleDiscover;
     private handleComplete;
+    private notifyAllListsChanged;
     closeAllSessions(): Promise<void>;
 }

package/dist/proxy/pairing/controller.js

@@ -22,6 +22,13 @@ class PairingController {
     log;
     sendNotification;
     pairing = null;
+    // Single-flight gate for handleConfigure. Without it, two `configure`
+    // calls landing in the same event-loop window both observe `this.pairing`
+    // as null, both spawn an HTTP server + cloudflared subprocess, and the
+    // second's assignment to `this.pairing` orphans the first. The orphan's
+    // expiryTimer would then later call teardownPairing() and tear down the
+    // wrong (active) pairing, killing a working setup mid-session.
+    configureInflight = null;
     constructor(state, runner, bridge, log, sendNotification) {
         this.state = state;
         this.runner = runner;
@@ -29,7 +36,15 @@ class PairingController {
         this.log = log;
         this.sendNotification = sendNotification;
     }
-    async handleConfigure() {
+    handleConfigure() {
+        if (this.configureInflight)
+            return this.configureInflight;
+        this.configureInflight = this.doConfigure().finally(() => {
+            this.configureInflight = null;
+        });
+        return this.configureInflight;
+    }
+    async doConfigure() {
         this.teardownPairing();
         const bearer = (0, node_crypto_1.randomBytes)(32).toString("base64url");
         const http = new http_js_1.PairingHttpServer(bearer, {
@@ -257,6 +272,22 @@ class PairingController {
                     missing.push(`${host.config.id} (no servers)`);
             }
         }
+        // selectedTools entries are validated structurally by validatePairingConfig,
+        // but their existence on the wire can only be checked after discovery has
+        // populated state.toolRoute. The browser path can't produce stale entries
+        // (the UI builds selectedTools from the just-discovered set), but a direct
+        // caller of /pair/complete can — and getFilteredTools silently drops any
+        // entry whose key isn't in toolRoute, leaving the proxy paired-but-empty
+        // for tools with no error surfaced. Treat stale entries the same as
+        // missing servers: roll back to the previous pairing (or refuse, on
+        // first-time pair) so the operator gets a real failure signal instead of
+        // a cheerful ok on a config that won't expose any tools.
+        if (cfg.selectedTools) {
+            for (const key of cfg.selectedTools) {
+                if (!this.state.toolRoute.has(key))
+                    missing.push(key);
+            }
+        }
         if (missing.length > 0) {
             // Cap the detail string so a wildly broken submit doesn't produce a
             // multi-kilobyte error body; the operator only needs a few names to
@@ -269,6 +300,12 @@ class PairingController {
                 this.log(`  New pairing missing servers (${detail}); restoring previous pairing`);
                 this.state.installConfig(previousConfig, previousHosts);
                 await this.runner.discoverServers();
+                // installConfig replaced toolRoute / promptRoute / resources between
+                // the success-path notify (only fires when missing.length === 0) and
+                // here, so an agent that polled tools/list during the new pairing's
+                // discovery may be holding a partial snapshot that no longer matches
+                // the restored routes. Notify list_changed so it re-fetches.
+                this.notifyAllListsChanged();
                 return {
                     ok: false,
                     error: `Discovery did not complete for: ${detail}. The previous pairing has been restored — verify host reachability and retry.`,
@@ -279,6 +316,10 @@ class PairingController {
             // so the next configure call starts fresh).
             this.log(`  New pairing missing servers (${detail}) and no prior config to restore; reverting to unconfigured`);
             this.state.config = null;
+            // Same notify rationale as the rollback branch above: a polling agent
+            // may have grabbed partial-new routes during discovery; tell it to
+            // re-fetch and find an empty unconfigured set.
+            this.notifyAllListsChanged();
             return {
                 ok: false,
                 error: `Discovery did not complete for: ${detail}. Verify host reachability and retry.`,
@@ -289,16 +330,27 @@ class PairingController {
         // Discovery already populated the aggregated lists. Notify the agent
         // so it re-fetches tools/prompts/resources instead of trusting any
         // cached empty lists from before pairing.
-        this.sendNotification("notifications/tools/list_changed");
-        this.sendNotification("notifications/prompts/list_changed");
-        this.sendNotification("notifications/resources/list_changed");
+        this.notifyAllListsChanged();
         // Defer pairing teardown until /pair/complete's response body has
         // actually drained to the client — a fixed timer races slow clients
         // (mobile data, congested tunnel) and they see a dropped connection
         // on a successful pair.
         return { ok: true, afterFlush: () => this.teardownPairing() };
     }
+    notifyAllListsChanged() {
+        this.sendNotification("notifications/tools/list_changed");
+        this.sendNotification("notifications/prompts/list_changed");
+        this.sendNotification("notifications/resources/list_changed");
+    }
     async closeAllSessions() {
+        // Bump the supersession token before any await so an in-flight forwarder
+        // request that resolves during teardown sees a stale generation and
+        // refuses to write its response. Without this, a fetch completing during
+        // bridge.clear / DELETE awaits emits onto stdout against a pairing that
+        // no longer exists. installConfig() bumps again on the way in; the
+        // double-bump is harmless because the token is only used for equality
+        // comparison.
+        this.state.configGeneration++;
         // Tear down SSE listeners first so loops don't reconnect after DELETE.
         for (const host of this.state.hosts.values()) {
             for (const ctrl of host.sseControllers.values())

package/dist/proxy/pairing/http.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PairingHttpServer = void 0;
 const node_crypto_1 = require("node:crypto");
 const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
 const static_assets_js_1 = require("./static-assets.js");
 class PairingHttpServer {
     bearer;
@@ -17,6 +18,11 @@ class PairingHttpServer {
     listen() {
         return new Promise((resolveP, rejectP) => {
             const srv = (0, protocol_js_1.createServer)((req, res) => this.handle(req, res));
+            // Bound the header + body phases so a slow upload can't drag past
+            // PAIRING_WINDOW_MS. Node defaults (60s / 5min) are too generous for
+            // small JSON pairing payloads.
+            srv.headersTimeout = constants_js_1.PAIRING_HEADERS_TIMEOUT_MS;
+            srv.requestTimeout = constants_js_1.PAIRING_REQUEST_TIMEOUT_MS;
             srv.once("error", rejectP);
             srv.listen(0, "127.0.0.1", () => {
                 const addr = srv.address();
@@ -32,6 +38,11 @@ class PairingHttpServer {
     close() {
         if (!this.server)
             return;
+        // server.close() alone only refuses new connections; idle keep-alive
+        // sockets and any in-flight request body would otherwise outlive the
+        // pairing window. closeAllConnections() (Node ≥18.2) hard-drops them
+        // so teardown is bounded by the window, not by the slowest client.
+        this.server.closeAllConnections();
         this.server.close();
         this.server = null;
     }

package/dist/proxy/runtime/forwarder.js

@@ -39,6 +39,13 @@ class Forwarder {
             return h;
         };
         const body = JSON.stringify({ jsonrpc: "2.0", id, method, params: upstreamParams });
+        // Snapshot the active pairing so a re-pair landing while this fetch is
+        // in flight can be detected before we write a stale response back to the
+        // agent. closeAllSessions clears state.inflight, but our local closure
+        // still holds the id/route, so without this guard the OLD pairing's
+        // response (or its upstream-level error) would be emitted on stdout
+        // against a pairing that no longer exists.
+        const startGeneration = this.state.configGeneration;
         this.state.inflight.set(id, route);
         const progressToken = (upstreamParams?._meta?.progressToken);
         if (progressToken !== undefined)
@@ -82,6 +89,14 @@ class Forwarder {
                 this.runner.captureSessionId(host, route.serverName, refreshed, upstream.headers.get("mcp-session-id"));
                 responseBody = await upstream.text();
             }
+            // Pairing changed underneath us between dispatch and response. Reply
+            // with a generic error so the request doesn't hang — the agent can
+            // retry against the new pairing — but don't write the stale body or
+            // its upstream-level error, since neither applies to the new config.
+            if (this.state.configGeneration !== startGeneration) {
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, "request superseded by reconfiguration", id);
+                return;
+            }
             if (!upstream.ok) {
                 this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, `host returned ${upstream.status}: ${responseBody.slice(0, 200)}`, id);
                 return;
@@ -137,6 +152,13 @@ class Forwarder {
             this.writeOut(JSON.stringify(parsed));
         }
         catch (err) {
+            // Same supersession guard as the success path: if the abort/error
+            // raced a re-pair, the agent should see "superseded" rather than the
+            // raw transport error from a pairing that no longer exists.
+            if (this.state.configGeneration !== startGeneration) {
+                this.sendError(protocol_js_1.ErrorCode.INTERNAL, "request superseded by reconfiguration", id);
+                return;
+            }
             this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, err.message, id);
         }
         finally {

package/dist/proxy/runtime/handlers.d.ts

@@ -40,9 +40,9 @@ export declare class RequestHandlers {
         argument?: unknown;
     }): Promise<void>;
     handleToolDispatch(id: string | number, params: {
-        name: string;
+        name?: string;
         arguments?: Record<string, unknown>;
         _meta?: unknown;
-    }): Promise<void>;
+    } | undefined): Promise<void>;
     handleClientNotification(method: string, params: Record<string, unknown>): Promise<void>;
 }

package/dist/proxy/runtime/handlers.js

@@ -241,7 +241,12 @@ class RequestHandlers {
         });
     }
     async handleToolDispatch(id, params) {
-        if (params.name === "configure") {
+        if (!params || typeof params.name !== "string") {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, "name is required", id);
+            return;
+        }
+        const toolName = params.name;
+        if (toolName === "configure") {
             let text;
             try {
                 text = await this.pairing.handleConfigure();
@@ -257,14 +262,14 @@ class RequestHandlers {
             this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, "Call the `configure` tool first.", id);
             return;
         }
-        const route = this.state.toolRoute.get(params.name);
+        const route = this.state.toolRoute.get(toolName);
         if (!route || !(0, filtering_js_1.isServerSelected)(this.state.config, route.hostId, route.serverName)) {
-            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${params.name}`, id);
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${toolName}`, id);
             return;
         }
         // selectedTools is a tool-level filter on top of the server-level gate.
-        if (this.state.config.selectedTools !== undefined && !this.state.config.selectedTools.includes(params.name)) {
-            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${params.name}`, id);
+        if (this.state.config.selectedTools !== undefined && !this.state.config.selectedTools.includes(toolName)) {
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${toolName}`, id);
             return;
         }
         // Preserve `_meta` so the upstream server still sees the agent's

package/dist/proxy/runtime/sse.js

@@ -132,6 +132,12 @@ class SseReader {
             this.cb.onUpstreamRequest(host, name, msg);
             return;
         }
+        // Symmetric with server.ts: an upstream "request" with id:null can't
+        // be answered (the bridge keys responses by id), so drop rather than
+        // forwarding it to the agent as if it were a notification — that
+        // would silently re-cast a request the upstream expects a response to.
+        if (hasMethod && msg.id === null)
+            return;
         if (!hasMethod)
             return; // stray response — not expected on this stream
         // Notifications: list_changed events trigger a cache refresh BEFORE

package/dist/proxy/runtime/upstream-bridge.js

@@ -106,21 +106,27 @@ class UpstreamBridge {
             const host = hosts.get(ctx.hostId);
             if (!host)
                 return;
+            // Teardown courtesy — share the DELETE budget, not the 5-min tool
+            // budget. A blackholed host would otherwise stall closeAllSessions
+            // (re-pair, rollback, SIGTERM shutdown) until TOOL_FORWARD_TIMEOUT_MS.
+            // The DELETE that follows reaps the session anyway; if this courtesy
+            // doesn't land quickly the upstream's own UPSTREAM_REQUEST_TIMEOUT_MS
+            // catches the orphaned child.
             return this.postResponse(host, ctx.serverName, ctx.sessionId, {
                 jsonrpc: "2.0",
                 id: ctx.originalId,
                 error: { code: protocol_js_1.ErrorCode.INTERNAL, message: "proxy reconfigured before client responded" },
-            });
+            }, constants_js_1.SESSION_DELETE_TIMEOUT_MS);
         }));
     }
-    async postResponse(host, serverName, sessionId, body) {
+    async postResponse(host, serverName, sessionId, body, timeoutMs = constants_js_1.TOOL_FORWARD_TIMEOUT_MS) {
         const target = `${host.config.tunnelUrl}/servers/${serverName}`;
         const headers = { ...this.hostHeaders(host.config), "Mcp-Session-Id": sessionId };
         try {
             const resp = await fetch(target, {
                 method: "POST",
                 headers,
-                signal: (0, fetch_timeout_js_1.timeoutSignal)(constants_js_1.TOOL_FORWARD_TIMEOUT_MS),
+                signal: (0, fetch_timeout_js_1.timeoutSignal)(timeoutMs),
                 body: JSON.stringify(body),
             });
             this.captureSessionId(host, serverName, resp.headers.get("mcp-session-id"));

package/dist/proxy/server.js

@@ -120,6 +120,16 @@ class ProxyServer {
             process.stdout.write((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.INVALID_REQUEST, "missing method", parsed.id ?? null) + "\n");
             return;
         }
+        // JSON-RPC 2.0 discourages id:null in requests because the spec
+        // reserves null for "id couldn't be parsed" in error responses
+        // (we use it ourselves at the PARSE_ERROR / missing-method paths).
+        // Falling through to the notification branch here would silently
+        // drop a request the agent expects an answer to; reject explicitly
+        // so the agent sees a real error instead of hanging.
+        if (parsed.id === null) {
+            process.stdout.write((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.INVALID_REQUEST, "id must not be null in a request", null) + "\n");
+            return;
+        }
         if (!hasId) {
             await this.handlers.handleClientNotification(parsed.method, parsed.params ?? {});
             return;

package/dist/shared/protocol.d.ts

@@ -50,6 +50,13 @@ export interface ServerConfig {
     env?: Record<string, string>;
     shell?: boolean;
 }
+export declare function normalizeServerConfig(raw: unknown): {
+    ok: true;
+    config: ServerConfig;
+} | {
+    ok: false;
+    reasons: string[];
+};
 export interface HostAgentConfig {
     servers: Record<string, ServerConfig>;
     host?: string;

package/dist/shared/protocol.js

@@ -6,6 +6,7 @@ exports.readBody = readBody;
 exports.getArg = getArg;
 exports.createServer = createServer;
 exports.validateServerName = validateServerName;
+exports.normalizeServerConfig = normalizeServerConfig;
 const node_fs_1 = require("node:fs");
 const node_http_1 = require("node:http");
 const node_path_1 = require("node:path");
@@ -181,3 +182,46 @@ function validateServerName(name) {
     }
     return null;
 }
+// Validates a raw ServerConfig from JSON and returns the canonical form
+// with documented defaults installed (args=[]). Every consumer of
+// ServerConfig — McpSession's spawn, the log line, future tooling — can
+// then trust the interface contract instead of re-checking shapes
+// defensively at every use site. All shape reasons are collected so a
+// misconfigured file surfaces a complete diff to fix in one error
+// message rather than one-issue-per-restart.
+function normalizeServerConfig(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reasons: ["must be an object with at least { command }"] };
+    }
+    const r = raw;
+    const reasons = [];
+    if (typeof r.command !== "string" || r.command.length === 0) {
+        reasons.push("command must be a non-empty string");
+    }
+    if (r.args !== undefined
+        && !(Array.isArray(r.args) && r.args.every((a) => typeof a === "string"))) {
+        reasons.push("args must be an array of strings (default: [])");
+    }
+    if (r.env !== undefined) {
+        const envOk = typeof r.env === "object"
+            && r.env !== null
+            && !Array.isArray(r.env)
+            && Object.values(r.env).every((v) => typeof v === "string");
+        if (!envOk)
+            reasons.push("env must be a map of string to string (default: {})");
+    }
+    if (r.shell !== undefined && typeof r.shell !== "boolean") {
+        reasons.push("shell must be boolean (default: false)");
+    }
+    if (reasons.length > 0)
+        return { ok: false, reasons };
+    return {
+        ok: true,
+        config: {
+            command: r.command,
+            args: r.args ?? [],
+            env: r.env,
+            shell: r.shell,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silver886/mcp-proxy",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "MCP proxy bridge: forward MCP requests across network boundaries via Cloudflare tunnel",
   "repository": {
     "type": "git",
@@ -31,6 +31,7 @@
   },
   "files": [
     "dist",
+    "scripts/fetch.mjs",
     "static"
   ],
   "engines": {
@@ -42,10 +43,23 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "js-yaml": "^4.1.0",
     "typescript": "^5.5.0"
   },
-  "bundleDependencies": true,
+  "lockedDependencies": {
+    "cloudflared": {
+      "version": "0.7.1",
+      "tarball": "https://registry.npmjs.org/cloudflared/-/cloudflared-0.7.1.tgz",
+      "integrity": "sha512-jJn1Gu9Tf4qnIu8tfiHZ25Hs8rNcRYSVf8zAd97wvYdOCzftm1CTs1S/RPhijjGi8gUT1p9yzfDi9zYlU/0RwA=="
+    },
+    "eventsource-parser": {
+      "version": "3.0.8",
+      "tarball": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.8.tgz",
+      "integrity": "sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ=="
+    }
+  },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "tsc --noEmit"
   }
 }