@silver886/mcp-proxy 0.1.4 → 0.2.0

package/dist/proxy/pairing/http.js

@@ -0,0 +1,155 @@
+"use strict";
+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 static_assets_js_1 = require("./static-assets.js");
+class PairingHttpServer {
+    bearer;
+    handlers;
+    server = null;
+    bearerExpected;
+    constructor(bearer, handlers) {
+        this.bearer = bearer;
+        this.handlers = handlers;
+        this.bearerExpected = Buffer.from(`Bearer ${bearer}`);
+    }
+    listen() {
+        return new Promise((resolveP, rejectP) => {
+            const srv = (0, protocol_js_1.createServer)((req, res) => this.handle(req, res));
+            srv.once("error", rejectP);
+            srv.listen(0, "127.0.0.1", () => {
+                const addr = srv.address();
+                if (typeof addr !== "object" || !addr) {
+                    rejectP(new Error("Could not bind pairing HTTP server"));
+                    return;
+                }
+                this.server = srv;
+                resolveP(addr.port);
+            });
+        });
+    }
+    close() {
+        if (!this.server)
+            return;
+        this.server.close();
+        this.server = null;
+    }
+    authorized(req) {
+        const got = Buffer.from(req.headers.authorization ?? "");
+        if (got.length !== this.bearerExpected.length)
+            return false;
+        return (0, node_crypto_1.timingSafeEqual)(got, this.bearerExpected);
+    }
+    sendJson(res, status, body) {
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(typeof body === "string" ? body : JSON.stringify(body));
+    }
+    sendStatic(res, contentType, body) {
+        res.writeHead(200, {
+            "Content-Type": contentType,
+            "Cache-Control": "no-store",
+            "Content-Length": String(body.length),
+        });
+        res.end(body);
+    }
+    // Read the request body and JSON.parse it. On failure, write a 400 to the
+    // response and return null so the handler can early-return without a
+    // separate try/catch ladder. readBody itself is awaited outside so a
+    // BodyTooLargeError propagates up to createServer (→ 413) instead of
+    // being misreported as "Invalid JSON".
+    async readJson(req, res) {
+        const raw = await (0, protocol_js_1.readBody)(req);
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            this.sendJson(res, 400, { error: "Invalid JSON" });
+            return null;
+        }
+    }
+    async handle(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        // Static routes are public — they're the setup page itself, served on
+        // the same origin as the API so no CORS is involved. The bearer gate
+        // only matters for /pair/* endpoints (which the page calls with the
+        // token from its URL fragment).
+        if (req.method === "GET") {
+            if (url.pathname === "/" || url.pathname === "/setup.html") {
+                this.sendStatic(res, "text/html; charset=utf-8", static_assets_js_1.SETUP_HTML);
+                return;
+            }
+            if (url.pathname === "/style.css") {
+                this.sendStatic(res, "text/css; charset=utf-8", static_assets_js_1.SETUP_CSS);
+                return;
+            }
+            if (url.pathname === "/setup.css") {
+                this.sendStatic(res, "text/css; charset=utf-8", static_assets_js_1.SETUP_PAGE_CSS);
+                return;
+            }
+            if (url.pathname === "/setup.js") {
+                this.sendStatic(res, "application/javascript; charset=utf-8", static_assets_js_1.SETUP_JS);
+                return;
+            }
+        }
+        if (!this.authorized(req)) {
+            this.sendJson(res, 401, { error: "Unauthorized" });
+            return;
+        }
+        if (req.method === "GET" && url.pathname === "/pair/info") {
+            this.sendJson(res, 200, this.handlers.info());
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/pair/list-servers") {
+            const parsed = await this.readJson(req, res);
+            if (!parsed)
+                return;
+            try {
+                const result = await this.handlers.listServers(parsed);
+                const status = result.status ?? (result.ok ? 200 : 502);
+                this.sendJson(res, status, result);
+            }
+            catch (err) {
+                this.sendJson(res, 502, { ok: false, error: `Upstream unreachable: ${err.message}` });
+            }
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/pair/discover") {
+            const parsed = await this.readJson(req, res);
+            if (!parsed)
+                return;
+            try {
+                const result = await this.handlers.discover(parsed);
+                const status = result.status ?? (result.ok ? 200 : 502);
+                this.sendJson(res, status, result);
+            }
+            catch (err) {
+                this.sendJson(res, 502, { ok: false, error: `Upstream unreachable: ${err.message}` });
+            }
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/pair/complete") {
+            const cfg = await this.readJson(req, res);
+            if (!cfg)
+                return;
+            const out = await this.handlers.complete(cfg);
+            if (!out.ok) {
+                this.sendJson(res, 400, { error: out.error });
+                return;
+            }
+            // Only run afterFlush once the response body has actually drained.
+            // The pairing tunnel teardown rides this callback so a slow client
+            // (mobile data, congested tunnel) doesn't lose the success body to
+            // a tunnel that closed on a fixed timer.
+            const afterFlush = out.afterFlush;
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }), () => {
+                if (afterFlush)
+                    afterFlush();
+            });
+            return;
+        }
+        this.sendJson(res, 404, { error: "Not found" });
+    }
+}
+exports.PairingHttpServer = PairingHttpServer;

package/dist/proxy/pairing/static-assets.d.ts

@@ -0,0 +1,4 @@
+export declare const SETUP_HTML: NonSharedBuffer;
+export declare const SETUP_CSS: NonSharedBuffer;
+export declare const SETUP_PAGE_CSS: NonSharedBuffer;
+export declare const SETUP_JS: NonSharedBuffer;

package/dist/proxy/pairing/static-assets.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETUP_JS = exports.SETUP_PAGE_CSS = exports.SETUP_CSS = exports.SETUP_HTML = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// dist/proxy/pairing/static-assets.js → ../../../static (project root).
+// Resolved at module load so we fail fast at startup rather than on the
+// first browser hit.
+const STATIC_DIR = (0, node_path_1.resolve)(__dirname, "..", "..", "..", "static");
+exports.SETUP_HTML = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(STATIC_DIR, "setup.html"));
+exports.SETUP_CSS = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(STATIC_DIR, "style.css"));
+exports.SETUP_PAGE_CSS = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(STATIC_DIR, "setup.css"));
+exports.SETUP_JS = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(STATIC_DIR, "setup.js"));

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

@@ -0,0 +1,13 @@
+export declare class PairingTunnel {
+    private wrapper;
+    private url;
+    private lastError;
+    private waiters;
+    private onUnexpectedExit;
+    start(port: number, onUnexpectedExit?: (reason: string) => void): Promise<string>;
+    private handleUrl;
+    private handleExit;
+    private failWaiters;
+    private urlReady;
+    stop(): void;
+}

package/dist/proxy/pairing/tunnel.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingTunnel = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const protocol_js_1 = require("../../shared/protocol.js");
+const constants_js_1 = require("../core/constants.js");
+// Owns the cloudflared child via wrapper.js. The wrapper guarantees that
+// cloudflared cannot outlive the proxy: it watches stdin EOF and kills the
+// child on either side dying, with 0ms detection latency on every supported
+// OS. From the proxy's side we only need to start, await the URL, and stop.
+class PairingTunnel {
+    wrapper = null;
+    url = null;
+    // Most recent cloudflared error, captured from wrapper "ERR" lines. Lets
+    // us include the actual cause in any rejection / unexpected-exit log so
+    // the user sees something more useful than "exited before becoming
+    // ready".
+    lastError = null;
+    waiters = [];
+    // Fired only when the wrapper dies AFTER the URL was advertised — i.e.,
+    // a runtime crash, not a startup failure. Pre-ready exits already reject
+    // the start() promise, so the caller learns about those synchronously.
+    // The reason string carries whatever cloudflared error we last saw, so
+    // the caller can log a meaningful line (e.g., "tunnel: connection
+    // refused") instead of a generic "exited unexpectedly".
+    onUnexpectedExit = null;
+    start(port, onUnexpectedExit) {
+        if (this.wrapper)
+            return this.urlReady();
+        this.onUnexpectedExit = onUnexpectedExit ?? null;
+        // dist/proxy/pairing/tunnel.js → ../../wrapper.js. Two `..` segments
+        // because tunnel lives two directories below dist/, not one — keep this
+        // aligned with the emitted layout if the file ever moves again.
+        const wrapperPath = (0, node_path_1.resolve)(__dirname, "..", "..", "wrapper.js");
+        const child = (0, node_child_process_1.spawn)(process.execPath, [wrapperPath, String(port)], {
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+        this.wrapper = child;
+        const buf = new protocol_js_1.LineBuffer();
+        child.stdout.on("data", (chunk) => {
+            for (const line of buf.push(chunk.toString("utf-8"))) {
+                if (line.startsWith("URL "))
+                    this.handleUrl(line.slice(4).trim());
+                else if (line.startsWith("ERR "))
+                    this.lastError = line.slice(4).trim();
+            }
+        });
+        child.on("exit", () => this.handleExit());
+        child.on("error", (err) => {
+            // The spawn itself failed (binary missing, EPERM, etc.) — capture as
+            // the cause so the rejection isn't blank.
+            if (!this.lastError)
+                this.lastError = err.message;
+            this.failWaiters(new Error(`Pairing tunnel wrapper failed: ${err.message}`));
+        });
+        return this.urlReady();
+    }
+    handleUrl(url) {
+        this.url = url;
+        for (const w of this.waiters) {
+            clearTimeout(w.timer);
+            w.resolve(url);
+        }
+        this.waiters = [];
+    }
+    handleExit() {
+        const wasReady = this.url !== null;
+        const reason = this.lastError
+            ? `Pairing tunnel exited: ${this.lastError}`
+            : "Pairing tunnel exited before becoming ready";
+        this.failWaiters(new Error(reason));
+        this.wrapper = null;
+        this.url = null;
+        if (wasReady) {
+            const cb = this.onUnexpectedExit;
+            this.onUnexpectedExit = null;
+            cb?.(this.lastError ?? "exit without error message");
+        }
+        this.lastError = null;
+    }
+    failWaiters(err) {
+        for (const w of this.waiters) {
+            clearTimeout(w.timer);
+            w.reject(err);
+        }
+        this.waiters = [];
+    }
+    urlReady() {
+        if (this.url)
+            return Promise.resolve(this.url);
+        return new Promise((resolveP, rejectP) => {
+            const timer = setTimeout(() => {
+                this.waiters = this.waiters.filter((w) => w.timer !== timer);
+                const cause = this.lastError ? ` (last error: ${this.lastError})` : "";
+                rejectP(new Error(`Pairing tunnel startup timed out after ${constants_js_1.TUNNEL_STARTUP_TIMEOUT_MS / 1000}s${cause}`));
+            }, constants_js_1.TUNNEL_STARTUP_TIMEOUT_MS);
+            this.waiters.push({ resolve: resolveP, reject: rejectP, timer });
+        });
+    }
+    stop() {
+        const child = this.wrapper;
+        if (!child)
+            return;
+        this.wrapper = null;
+        this.url = null;
+        this.lastError = null;
+        // Caller-initiated stop; suppress the unexpected-exit callback so a
+        // teardownPairing() chain doesn't reenter via the exit handler.
+        this.onUnexpectedExit = null;
+        try {
+            child.stdin?.write("stop\n");
+        }
+        catch { /* already closed */ }
+        try {
+            child.stdin?.end();
+        }
+        catch { /* already closed */ }
+        // Hard-kill fallback if the wrapper does not exit promptly.
+        setTimeout(() => {
+            if (!child.killed) {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* already dead */ }
+            }
+        }, 5000).unref();
+    }
+}
+exports.PairingTunnel = PairingTunnel;

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

@@ -0,0 +1,2 @@
+export declare function allowedTunnelUrl(raw: string): URL | null;
+export declare function isUnknownSessionError(body: string): boolean;

package/dist/proxy/pairing/validation.js

@@ -0,0 +1,62 @@
+"use strict";
+// Validation for pairing-time inputs: which tunnel hostnames the proxy is
+// willing to dial out to from /pair/* endpoints. Centralised here so the
+// browser can't trick the proxy into hitting arbitrary URLs even if the
+// pairing bearer leaks. Kept structurally identical to the runtime path
+// (handleComplete validates host configs through the same predicate) so
+// what passes pairing-time discovery is exactly what passes pairing-time
+// save.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allowedTunnelUrl = allowedTunnelUrl;
+exports.isUnknownSessionError = isUnknownSessionError;
+// Tunnel-URL allowlist for /pair/* discovery endpoints. The bearer token
+// alone must not authorize SSRF — without this, anyone holding the token
+// (browser extension, XSS, leaked terminal scrollback) could pivot the
+// proxy to any URL, including http://127.0.0.1 on the host's LAN.
+const DEFAULT_TUNNEL_HOST_SUFFIXES = [".trycloudflare.com", ".cfargotunnel.com"];
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function tunnelHostSuffixes() {
+    const extra = (process.env.MCP_TUNNEL_HOST_SUFFIXES ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.startsWith("."));
+    return [...new Set([...DEFAULT_TUNNEL_HOST_SUFFIXES, ...extra])];
+}
+function allowedTunnelUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.username || url.password)
+        return null;
+    const host = url.hostname.toLowerCase();
+    const allowLocal = process.env.MCP_ALLOW_LOCAL === "true";
+    if (allowLocal && LOCAL_HOSTNAMES.has(host)) {
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        return url;
+    }
+    if (url.protocol !== "https:")
+        return null;
+    const suffixes = tunnelHostSuffixes();
+    const ok = suffixes.some((suffix) => host.endsWith(suffix) && host.length > suffix.length);
+    return ok ? url : null;
+}
+// Host returns 404 + JSON error when a forwarded request points at a session
+// it doesn't know about — typically because the host GC'd it after 30 min idle
+// or the host process restarted. Matched here so the proxy can re-init + retry
+// instead of bubbling the failure up to the client.
+function isUnknownSessionError(body) {
+    try {
+        const e = JSON.parse(body).error;
+        if (typeof e !== "string")
+            return false;
+        return e.startsWith("Unknown session") || e === "Mcp-Session-Id header required";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/proxy/routing/filtering.d.ts

@@ -0,0 +1,13 @@
+import type { HostState, PairingConfig, Prompt, Resource, ResourceTemplate, Tool, ToolRoute } from "../core/types.js";
+export declare function serverKey(hostId: string, serverName: string): string;
+export declare function isServerSelected(config: PairingConfig | null, hostId: string, serverName: string): boolean;
+export declare function getFilteredTools(config: PairingConfig | null, hosts: Map<string, HostState>, toolRoute: Map<string, ToolRoute>): Tool[];
+export declare function getAggregatedPrompts(config: PairingConfig | null, hosts: Map<string, HostState>, promptRoute: Map<string, ToolRoute>): Prompt[];
+export declare function getAggregatedResources(config: PairingConfig | null, hosts: Map<string, HostState>, exact: Array<{
+    uri: string;
+    route: ToolRoute;
+}>): Resource[];
+export declare function getAggregatedResourceTemplates(config: PairingConfig | null, hosts: Map<string, HostState>, templates: Array<{
+    uriTemplate: string;
+    route: ToolRoute;
+}>): ResourceTemplate[];

package/dist/proxy/routing/filtering.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverKey = serverKey;
+exports.isServerSelected = isServerSelected;
+exports.getFilteredTools = getFilteredTools;
+exports.getAggregatedPrompts = getAggregatedPrompts;
+exports.getAggregatedResources = getAggregatedResources;
+exports.getAggregatedResourceTemplates = getAggregatedResourceTemplates;
+const constants_js_1 = require("../core/constants.js");
+const uri_js_1 = require("./uri.js");
+// One key per server in `selectedServers`. Centralised so the format never
+// drifts between the filter, the setup page, and validation.
+function serverKey(hostId, serverName) {
+    return `${hostId}${constants_js_1.TOOL_SEPARATOR}${serverName}`;
+}
+// Server-level allow check. undefined = no filter (every server exposed);
+// array = only the listed entries (each `<hostId>__<serverName>`). This is
+// the single gate that hides ALL of a server's capabilities — tools,
+// prompts, resources, templates, and the routed methods that read them.
+// Without it a server with all tools deselected still leaked prompts and
+// resources through the proxy (CR-01).
+function isServerSelected(config, hostId, serverName) {
+    if (!config)
+        return false;
+    if (config.selectedServers === undefined)
+        return true;
+    return config.selectedServers.includes(serverKey(hostId, serverName));
+}
+// Build the agent-facing tools list. Filters by both selectedServers
+// (server-level) and selectedTools (tool-level within an allowed server).
+// Description is prefixed with origin so two servers with same-named tools
+// don't confuse the agent.
+function getFilteredTools(config, hosts, toolRoute) {
+    if (!config)
+        return [];
+    const selectedToolSet = config.selectedTools !== undefined ? new Set(config.selectedTools) : null;
+    const tools = [];
+    for (const [prefixed, route] of toolRoute) {
+        if (!isServerSelected(config, route.hostId, route.serverName))
+            continue;
+        if (selectedToolSet && !selectedToolSet.has(prefixed))
+            continue;
+        const server = hosts.get(route.hostId)?.servers.get(route.serverName);
+        const original = server?.tools.find((t) => t.name === route.originalName);
+        if (!original)
+            continue;
+        tools.push({
+            ...original,
+            name: prefixed,
+            description: `[${route.hostId}/${route.serverName}] ${original.description ?? ""}`.trim(),
+        });
+    }
+    return tools;
+}
+// Prompts have no per-prompt filter today — only the server-level gate.
+// Description prefixed with origin for the same disambiguation reason as
+// tools.
+function getAggregatedPrompts(config, hosts, promptRoute) {
+    if (!config)
+        return [];
+    const prompts = [];
+    for (const [prefixed, route] of promptRoute) {
+        if (!isServerSelected(config, route.hostId, route.serverName))
+            continue;
+        const server = hosts.get(route.hostId)?.servers.get(route.serverName);
+        const original = server?.prompts.find((p) => p.name === route.originalName);
+        if (!original)
+            continue;
+        prompts.push({
+            ...original,
+            name: prefixed,
+            description: `[${route.hostId}/${route.serverName}] ${original.description ?? ""}`.trim(),
+        });
+    }
+    return prompts;
+}
+// Resources are namespaced on the way out: every URI is wrapped with the
+// owning (hostId, serverName) so two upstream servers exposing the same
+// raw URI (or overlapping templates) are unambiguous to the agent and to
+// the routing path. Server-level gate hides every URI from a deselected
+// server. Round-trip is symmetric — handleResourceMethod unwraps on the
+// way back in.
+function getAggregatedResources(config, hosts, exact) {
+    if (!config)
+        return [];
+    const out = [];
+    for (const { uri, route } of exact) {
+        if (!isServerSelected(config, route.hostId, route.serverName))
+            continue;
+        const server = hosts.get(route.hostId)?.servers.get(route.serverName);
+        const original = server?.resources.find((r) => r.uri === uri);
+        if (!original)
+            continue;
+        out.push({ ...original, uri: (0, uri_js_1.wrapResourceUri)(route.hostId, route.serverName, original.uri) });
+    }
+    return out;
+}
+function getAggregatedResourceTemplates(config, hosts, templates) {
+    if (!config)
+        return [];
+    const out = [];
+    for (const { uriTemplate, route } of templates) {
+        if (!isServerSelected(config, route.hostId, route.serverName))
+            continue;
+        const server = hosts.get(route.hostId)?.servers.get(route.serverName);
+        const original = server?.resourceTemplates.find((t) => t.uriTemplate === uriTemplate);
+        if (!original)
+            continue;
+        // Wrapping the template is safe: RFC 6570 expansion is left-to-right
+        // substitution of `{...}` literals, and the prefix has no braces, so
+        // an agent expanding the wrapped template yields a URI the proxy can
+        // structurally unwrap on the way back.
+        out.push({ ...original, uriTemplate: (0, uri_js_1.wrapResourceUri)(route.hostId, route.serverName, original.uriTemplate) });
+    }
+    return out;
+}

package/dist/proxy/routing/router.d.ts

@@ -0,0 +1,17 @@
+import type { Resource, ResourceTemplate, ToolRoute } from "../core/types.js";
+export declare class ResourceRouter {
+    private exact;
+    private exactByUri;
+    private templates;
+    private templatesByUri;
+    clear(): void;
+    add(hostId: string, serverName: string, resources: Resource[], templates: ResourceTemplate[]): string[];
+    exactEntries(): Array<{
+        uri: string;
+        route: ToolRoute;
+    }>;
+    templateEntries(): Array<{
+        uriTemplate: string;
+        route: ToolRoute;
+    }>;
+}

package/dist/proxy/routing/router.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceRouter = void 0;
+// ResourceRouter is now a bookkeeping store — routing itself is structural
+// (see resource-uri.ts: every URI the agent sees is wrapped with its
+// owning hostId/serverName, so unwrap → route is a pure parse, no map
+// lookup, no template engine).
+//
+// What this class still owns:
+//   - The exact-URI list per (host, server), used by getAggregatedResources
+//     to render the agent-facing resources/list (with origin-wrapped URIs).
+//     Stored as an array, not a URI-keyed map, because two servers can
+//     legitimately expose the same concrete URI — both must surface under
+//     their own envelopes (hence the wrap step in filtering.ts).
+//   - The template list per (host, server), used the same way for
+//     resources/templates/list.
+//   - Cross-origin collision logging when two servers happen to expose
+//     the same raw URI or template string. The wrap step makes them
+//     distinct on the wire, so this is informational only — no longer
+//     load-bearing for routing correctness.
+class ResourceRouter {
+    exact = [];
+    exactByUri = new Map();
+    templates = [];
+    templatesByUri = new Map();
+    clear() {
+        this.exact = [];
+        this.exactByUri.clear();
+        this.templates = [];
+        this.templatesByUri.clear();
+    }
+    // Add one server's resources + templates. Returns a list of human-readable
+    // collision messages that the caller should write to stderr — kept out of
+    // this module so logging stays at the orchestrator layer.
+    add(hostId, serverName, resources, templates) {
+        const log = [];
+        const route = (originalName) => ({ hostId, serverName, originalName });
+        for (const r of resources) {
+            const existing = this.exactByUri.get(r.uri);
+            if (existing && (existing.hostId !== hostId || existing.serverName !== serverName)) {
+                log.push(`Resource URI also exposed by ${hostId}/${serverName}: ${r.uri} (already advertised by ${existing.hostId}/${existing.serverName}); both surfaced under their own envelopes`);
+            }
+            const rt = route(r.uri);
+            this.exact.push({ uri: r.uri, route: rt });
+            // First-writer wins for the dedup map — only used to detect repeats.
+            // The list above is the source of truth for the agent-facing listing.
+            if (!existing)
+                this.exactByUri.set(r.uri, rt);
+        }
+        for (const t of templates) {
+            const existing = this.templatesByUri.get(t.uriTemplate);
+            if (existing && (existing.hostId !== hostId || existing.serverName !== serverName)) {
+                log.push(`Resource template also exposed by ${hostId}/${serverName}: ${t.uriTemplate} (already advertised by ${existing.hostId}/${existing.serverName}); both surfaced under their own envelopes`);
+            }
+            const r = route(t.uriTemplate);
+            this.templates.push({ uriTemplate: t.uriTemplate, route: r });
+            if (!existing)
+                this.templatesByUri.set(t.uriTemplate, r);
+        }
+        return log;
+    }
+    // For getAggregatedResources / templates list. Iteration order matches
+    // insertion (array semantics), which matches the order servers were added
+    // in rebuildToolRoute — stable across runs. Two servers exposing the same
+    // raw URI yield two distinct entries; wrapResourceUri disambiguates them
+    // on the way out.
+    exactEntries() {
+        return this.exact.map(({ uri, route }) => ({ uri, route }));
+    }
+    templateEntries() {
+        return this.templates.map(({ uriTemplate, route }) => ({ uriTemplate, route }));
+    }
+}
+exports.ResourceRouter = ResourceRouter;

package/dist/proxy/routing/uri.d.ts

@@ -0,0 +1,7 @@
+export declare function wrapResourceUri(hostId: string, serverName: string, original: string): string;
+export interface UnwrappedResourceUri {
+    hostId: string;
+    serverName: string;
+    originalUri: string;
+}
+export declare function unwrapResourceUri(wrapped: string): UnwrappedResourceUri | null;

package/dist/proxy/routing/uri.js

@@ -0,0 +1,39 @@
+"use strict";
+// Resource URIs are namespaced with the upstream's (hostId, serverName) so
+// routing is structural — every URI the agent ever sees encodes its origin
+// server, and `resources/read` / `subscribe` / completion can be dispatched
+// without consulting any routing table or template engine. This eliminates
+// the cross-server overlap problem that first-match-wins template routing
+// had before: two upstreams exposing `file:///{path}` are now distinct
+// `mcp+host://hostA/srvA/file:///{path}` and `mcp+host://hostB/srvB/...`
+// strings the agent cannot conflate.
+//
+// Format: `mcp+host://<hostId>/<serverName>/<originalUri>` — the original
+// URI is appended verbatim. hostId and serverName are validated upstream
+// to match `[A-Za-z0-9._-]+` (see SERVER_NAME_PATTERN in shared/protocol),
+// so they cannot contain `/` and the parse is unambiguous.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapResourceUri = wrapResourceUri;
+exports.unwrapResourceUri = unwrapResourceUri;
+const SCHEME = "mcp+host://";
+function wrapResourceUri(hostId, serverName, original) {
+    return `${SCHEME}${hostId}/${serverName}/${original}`;
+}
+function unwrapResourceUri(wrapped) {
+    if (!wrapped.startsWith(SCHEME))
+        return null;
+    const rest = wrapped.slice(SCHEME.length);
+    const firstSlash = rest.indexOf("/");
+    if (firstSlash <= 0)
+        return null;
+    const hostId = rest.slice(0, firstSlash);
+    const afterHost = rest.slice(firstSlash + 1);
+    const secondSlash = afterHost.indexOf("/");
+    if (secondSlash <= 0)
+        return null;
+    const serverName = afterHost.slice(0, secondSlash);
+    const originalUri = afterHost.slice(secondSlash + 1);
+    if (!originalUri)
+        return null;
+    return { hostId, serverName, originalUri };
+}