@mcp-b/webmcp-local-relay 5.1.0 → 6.0.0

package/dist/{mcpRelayServer-DfGkigG5.mjs → mcpRelayServer-DEgebuO2.mjs}

@@ -1,3 +1,4 @@
+import { z } from "zod/v4";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import WebSocket, { WebSocketServer } from "ws";
@@ -5,16 +6,23 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { CallToolRequestParamsSchema, CallToolResultSchema, ToolAnnotationsSchema, ToolSchema } from "@modelcontextprotocol/core";
-import { z } from "zod/v4";
 import { parseArgs } from "node:util";
 import { execFile } from "node:child_process";
 import { McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 
 //#region src/portStrategy.ts
+function isTcpAddress(address) {
+	return address !== null && typeof address !== "string";
+}
 const DEFAULT_RELAY_PORT = 9333;
 const DEFAULT_RELAY_PORT_RANGE_END = 9348;
 const RELAY_PORT_CACHE_MAX_AGE_MS = 1440 * 60 * 1e3;
+const PersistedRelayPortSchema = z.object({
+	port: z.number().int().min(1).max(65535),
+	host: z.string().min(1),
+	updatedAt: z.string()
+});
 function defaultRelayPortPersistPath() {
 	return join(homedir(), ".webmcp", "relay-port.json");
 }
@@ -27,17 +35,13 @@ async function persistPort(port, path = defaultRelayPortPersistPath(), host = "1
 	await mkdir(dirname(path), { recursive: true });
 	await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
-async function readPersistedPort(path = defaultRelayPortPersistPath(), options = {}) {
+async function readPersistedPort(path, expectedHost) {
 	try {
 		const raw = await readFile(path, "utf8");
-		const parsed = JSON.parse(raw);
-		if (typeof parsed.port !== "number" || !Number.isInteger(parsed.port) || parsed.port < 1 || parsed.port > 65535) return null;
-		if (typeof parsed.host !== "string" || parsed.host.length === 0) return null;
-		if (options.expectedHost && parsed.host !== options.expectedHost) return null;
-		const maxAgeMs = options.maxAgeMs ?? RELAY_PORT_CACHE_MAX_AGE_MS;
-		const now = options.now ?? Date.now();
-		const updatedAtMs = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : NaN;
-		if (!Number.isFinite(updatedAtMs) || now - updatedAtMs > maxAgeMs) return null;
+		const parsed = PersistedRelayPortSchema.parse(JSON.parse(raw));
+		if (expectedHost && parsed.host !== expectedHost) return null;
+		const updatedAtMs = Date.parse(parsed.updatedAt);
+		if (!Number.isFinite(updatedAtMs) || Date.now() - updatedAtMs > RELAY_PORT_CACHE_MAX_AGE_MS) return null;
 		return parsed.port;
 	} catch {
 		return null;
@@ -50,7 +54,7 @@ async function buildPortCandidates(options) {
 		wasFixed: true,
 		fromCache: false
 	}];
-	const cachedPort = await readPersistedPort(persistPath, { expectedHost: host });
+	const cachedPort = await readPersistedPort(persistPath, host);
 	const seen = /* @__PURE__ */ new Set();
 	const candidates = [];
 	const pushCandidate = (port, fromCache) => {
@@ -404,11 +408,10 @@ const RelayDescriptorSchema = z.object({
 /**
 * Schema for server hello messages sent immediately after WebSocket connect.
 */
-const ServerHelloMessageSchema = z.object({
+const ServerHelloMessageSchema = RelayDescriptorSchema.extend({
 	type: z.literal("server-hello"),
 	service: z.literal("webmcp-local-relay"),
-	version: z.literal(1),
-	...RelayDescriptorSchema.shape
+	version: z.literal(1)
 });
 /**
 * Schema for acceptance of a browser source hello message.
@@ -507,6 +510,8 @@ const RELAY_INTERNAL_PROTOCOL = "webmcp-relay.v1";
 const RELAY_SERVER_MESSAGE_TIMEOUT_MS = 750;
 const HEARTBEAT_INTERVAL_MS = 15e3;
 const HEARTBEAT_DEAD_THRESHOLD_MS = 25e3;
+const RawMessageTypeSchema = z.object({ type: z.unknown().optional() });
+const RelayProtocolTypeSchema = z.string().startsWith("relay/");
 const SUPPORTED_SUBPROTOCOLS = new Set([
 	RELAY_BROWSER_PROTOCOL,
 	RELAY_DISCOVERY_PROTOCOL,
@@ -644,13 +649,14 @@ var RelayBridgeServer = class extends EventEmitter {
 			await this.startAsServer(0);
 			return;
 		}
-		const candidates = await buildPortCandidates({
+		const strategyOptions = {
 			defaultPort: this.preferredPort,
-			...this.portExplicitlySet ? { fixedPort: this.preferredPort } : {},
 			host: this.host,
 			persistPath: this.persistPath,
 			rangeEnd: this.portRangeEnd
-		});
+		};
+		if (this.portExplicitlySet) strategyOptions.fixedPort = this.preferredPort;
+		const candidates = await buildPortCandidates(strategyOptions);
 		for (const candidate of candidates) try {
 			await this.startAsServer(candidate.port);
 			await this.persistSelectedPort();
@@ -666,8 +672,8 @@ var RelayBridgeServer = class extends EventEmitter {
 		}
 		throw new Error(`No compatible relay port was available in the range ${this.preferredPort}-${this.portRangeEnd}.`);
 	}
-	isAddressInUseError(error) {
-		return error instanceof Error && ("code" in error ? error.code === "EADDRINUSE" : error.message.includes("EADDRINUSE"));
+	isAddressInUseError(cause) {
+		return cause instanceof Error && ("code" in cause ? cause.code === "EADDRINUSE" : cause.message.includes("EADDRINUSE"));
 	}
 	async persistSelectedPort() {
 		try {
@@ -825,7 +831,7 @@ var RelayBridgeServer = class extends EventEmitter {
 		this.wss = wss;
 		this._mode = "server";
 		const address = wss.address();
-		if (address && typeof address !== "string") this.desiredPort = address.port;
+		if (isTcpAddress(address)) this.desiredPort = address.port;
 		this.on("stateChanged", this.onStateChangedPushRelay);
 	}
 	buildServerHello() {
@@ -848,11 +854,10 @@ var RelayBridgeServer = class extends EventEmitter {
 	* for a `relay/result` that never arrives.
 	*/
 	async invokeToolLocally(toolName, args, options) {
-		const resolved = this.registry.resolveInvocation({
-			toolName,
-			...options.sourceId === void 0 ? {} : { sourceId: options.sourceId },
-			...options.requestTabId === void 0 ? {} : { requestTabId: options.requestTabId }
-		});
+		const invocation = { toolName };
+		if (options.sourceId !== void 0) invocation.sourceId = options.sourceId;
+		if (options.requestTabId !== void 0) invocation.requestTabId = options.requestTabId;
+		const resolved = this.registry.resolveInvocation(invocation);
 		if (!resolved) throw new Error(`No active browser source provides tool "${toolName}"`);
 		const socket = this.socketByConnectionId.get(resolved.connectionId);
 		if (!socket || socket.readyState !== WebSocket.OPEN) throw new Error(`Tool source ${resolved.connectionId} disconnected before invocation of "${toolName}"`);
@@ -894,7 +899,7 @@ var RelayBridgeServer = class extends EventEmitter {
 			process.stderr.write(`[webmcp-local-relay] warn: invalid JSON from connection ${connectionId} (${err instanceof Error ? err.message : "parse error"}): ${preview}\n`);
 			return;
 		}
-		const typeField = typeof parsedJson === "object" && parsedJson !== null && "type" in parsedJson ? parsedJson.type : void 0;
+		const typeField = RawMessageTypeSchema.safeParse(parsedJson).data?.type;
 		const socket = this.socketByConnectionId.get(connectionId);
 		if (!socket) return;
 		if (socket.protocol === RELAY_INTERNAL_PROTOCOL) {
@@ -903,7 +908,7 @@ var RelayBridgeServer = class extends EventEmitter {
 			else process.stderr.write(`[webmcp-local-relay] warn: invalid relay message from ${connectionId}: ${relayMsg.error.message}\n`);
 			return;
 		}
-		if (typeof typeField === "string" && typeField.startsWith("relay/")) {
+		if (RelayProtocolTypeSchema.safeParse(typeField).success) {
 			process.stderr.write(`[webmcp-local-relay] warn: connection ${connectionId} used the relay protocol without negotiating it\n`);
 			socket.close(1008, "Relay protocol was not negotiated");
 			return;
@@ -914,9 +919,9 @@ var RelayBridgeServer = class extends EventEmitter {
 			return;
 		}
 		this.registry.touchConnection(connectionId);
-		this.onBrowserClientMessage(connectionId, parsedMessage.data);
+		this.onBrowserClientMessage(connectionId, socket, parsedMessage.data);
 	}
-	onBrowserClientMessage(connectionId, message) {
+	onBrowserClientMessage(connectionId, socket, message) {
 		if (message.type !== "hello" && !this.browserClientConnectionIds.has(connectionId)) {
 			process.stderr.write(`[webmcp-local-relay] warn: connection ${connectionId} sent ${message.type} before hello, ignoring\n`);
 			return;
@@ -924,11 +929,10 @@ var RelayBridgeServer = class extends EventEmitter {
 		switch (message.type) {
 			case "hello":
 				try {
-					const socket = this.socketByConnectionId.get(connectionId);
 					const origin = this.requestOriginByConnectionId.get(connectionId) ?? message.origin;
 					if (!this.isHostOriginAllowed(origin)) {
 						process.stderr.write(`[webmcp-local-relay] warn: rejecting source ${connectionId} with disallowed host origin: ${origin ?? "missing"}\n`);
-						if (socket) this.sendHelloRejected(socket, {
+						this.sendHelloRejected(socket, {
 							type: "hello/rejected",
 							reason: "host-origin-not-allowed",
 							message: "Host page origin is not allowed by this relay."
@@ -940,7 +944,7 @@ var RelayBridgeServer = class extends EventEmitter {
 						origin
 					});
 					this.browserClientConnectionIds.add(connectionId);
-					if (socket) this.sendHelloAccepted(socket, { type: "hello/accepted" });
+					this.sendHelloAccepted(socket, { type: "hello/accepted" });
 					this.emit("stateChanged");
 				} catch (err) {
 					process.stderr.write(`[webmcp-local-relay] error: failed to process hello from connection ${connectionId}: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
@@ -953,7 +957,7 @@ var RelayBridgeServer = class extends EventEmitter {
 					this.emit("stateChanged");
 				} catch (err) {
 					process.stderr.write(`[webmcp-local-relay] error: failed to register tools for connection ${connectionId}: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
-					this.socketByConnectionId.get(connectionId)?.close(1008, "Invalid tool list");
+					socket.close(1008, "Invalid tool list");
 				}
 				break;
 			case "result": {
@@ -1221,7 +1225,7 @@ var RelayBridgeServer = class extends EventEmitter {
 		}
 		const message = RelayServerToClientMessageSchema.safeParse(parsed);
 		if (!message.success) {
-			const typeField = typeof parsed === "object" && parsed !== null && "type" in parsed ? parsed.type : "unknown";
+			const typeField = RawMessageTypeSchema.safeParse(parsed).data?.type ?? "unknown";
 			process.stderr.write(`[webmcp-local-relay] warn: invalid relay server message (type=${typeField}): ${message.error.message}\n`);
 			return null;
 		}
@@ -1424,18 +1428,19 @@ function parseCliOptions(argv) {
 	const maxPayloadBytes = parsePositiveInteger("max-payload", values["max-payload"]);
 	const allowedOrigins = (values["widget-origin"] ?? values["allowed-origin"] ?? values["ws-origin"])?.split(",").map((origin) => origin.trim()).filter(Boolean) ?? ["*"];
 	if (allowedOrigins.length === 0) throw new Error("--widget-origin must include at least one origin.");
-	return {
+	const options = {
 		allowedOrigins,
 		help: values.help ?? false,
 		host: values.host ?? "127.0.0.1",
 		port,
-		portExplicitlySet: values.port !== void 0,
-		...values.label === void 0 ? {} : { label: values.label },
-		...invokeTimeoutMs === void 0 ? {} : { invokeTimeoutMs },
-		...maxPayloadBytes === void 0 ? {} : { maxPayloadBytes },
-		...values["relay-id"] === void 0 ? {} : { relayId: values["relay-id"] },
-		...values.workspace === void 0 ? {} : { workspace: values.workspace }
+		portExplicitlySet: values.port !== void 0
 	};
+	if (values.label !== void 0) options.label = values.label;
+	if (invokeTimeoutMs !== void 0) options.invokeTimeoutMs = invokeTimeoutMs;
+	if (maxPayloadBytes !== void 0) options.maxPayloadBytes = maxPayloadBytes;
+	if (values["relay-id"] !== void 0) options.relayId = values["relay-id"];
+	if (values.workspace !== void 0) options.workspace = values.workspace;
+	return options;
 }
 /**
 * Prints CLI usage to stderr.
@@ -1465,6 +1470,22 @@ function printHelp() {
 
 //#endregion
 //#region src/mcpRelayServer.ts
+const JsonSchemaObjectSchema = z.record(z.string(), z.unknown());
+function textResult(text) {
+	return { content: [{
+		type: "text",
+		text
+	}] };
+}
+function errorResult(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	};
+}
 /**
 * MCP server facade that exposes browser-relayed tools over MCP transport.
 */
@@ -1474,6 +1495,7 @@ var LocalRelayMcpServer = class {
 	*/
 	bridge;
 	mcpServer;
+	launchBrowser;
 	dynamicTools = /* @__PURE__ */ new Map();
 	syncDebounceTimer = null;
 	connected = false;
@@ -1482,6 +1504,7 @@ var LocalRelayMcpServer = class {
 	*/
 	constructor(options = {}) {
 		this.bridge = options.bridge ?? new RelayBridgeServer(options.bridgeOptions);
+		this.launchBrowser = options.launchBrowser ?? execFile;
 		this.mcpServer = new McpServer({
 			name: options.serverName ?? "webmcp-local-relay",
 			version: options.serverVersion ?? "0.0.0"
@@ -1557,10 +1580,10 @@ var LocalRelayMcpServer = class {
 			const clientMode = this.bridge.mode === "client";
 			const sources = clientMode ? this.bridge.listSourcesFromRelay() : this.bridge.registry.listSources();
 			const info = {
-				...clientMode ? { mode: "client" } : {},
 				count: sources.length,
 				sources
 			};
+			if (clientMode) info.mode = "client";
 			return {
 				content: [{
 					type: "text",
@@ -1598,76 +1621,26 @@ var LocalRelayMcpServer = class {
 			}),
 			annotations: { readOnlyHint: false }
 		}, async ({ url, refresh }) => {
-			let parsed;
-			try {
-				parsed = new URL(url);
-			} catch {
-				return {
-					content: [{
-						type: "text",
-						text: `Invalid URL: ${url}`
-					}],
-					isError: true
-				};
-			}
-			if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return {
-				content: [{
-					type: "text",
-					text: `Only http: and https: URLs are allowed. Got: ${parsed.protocol}`
-				}],
-				isError: true
-			};
+			const parsed = URL.parse(url);
+			if (!parsed) return errorResult(`Invalid URL: ${url}`);
+			if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return errorResult(`Only http: and https: URLs are allowed. Got: ${parsed.protocol}`);
 			const existing = this.bridge.mode === "server" ? this.bridge.registry.listSources().find((source) => source.url && URL.parse(source.url)?.origin === parsed.origin) : void 0;
 			if (refresh) {
-				if (this.bridge.mode === "client") return {
-					content: [{
-						type: "text",
-						text: "Refresh is not supported in client mode. Only the server relay can reload sources."
-					}],
-					isError: true
-				};
-				if (!existing) return {
-					content: [{
-						type: "text",
-						text: `No connected source matches origin ${parsed.origin}. The page may not be open or connected.`
-					}],
-					isError: true
-				};
+				if (this.bridge.mode === "client") return errorResult("Refresh is not supported in client mode. Only the server relay can reload sources.");
+				if (!existing) return errorResult(`No connected source matches origin ${parsed.origin}. The page may not be open or connected.`);
 				try {
 					this.bridge.reloadSource(existing.sourceId);
-					return { content: [{
-						type: "text",
-						text: `Reload sent to source ${existing.sourceId} (${existing.url ?? existing.origin}).`
-					}] };
 				} catch (err) {
-					return {
-						content: [{
-							type: "text",
-							text: `Failed to reload source: ${err instanceof Error ? err.message : String(err)}`
-						}],
-						isError: true
-					};
+					return errorResult(`Failed to reload source: ${err instanceof Error ? err.message : String(err)}`);
 				}
+				return textResult(`Reload sent to source ${existing.sourceId} (${existing.url ?? existing.origin}).`);
 			}
 			try {
 				await this.openInBrowser(url);
 			} catch (err) {
-				return {
-					content: [{
-						type: "text",
-						text: `Failed to open browser: ${err instanceof Error ? err.message : String(err)}`
-					}],
-					isError: true
-				};
+				return errorResult(`Failed to open browser: ${err instanceof Error ? err.message : String(err)}`);
 			}
-			if (existing) return { content: [{
-				type: "text",
-				text: `Opened ${url} in the default browser. Note: a source from ${existing.url ?? existing.origin} is already connected.`
-			}] };
-			return { content: [{
-				type: "text",
-				text: `Opened ${url} in the default browser.`
-			}] };
+			return textResult(existing ? `Opened ${url} in the default browser. Note: a source from ${existing.url ?? existing.origin} is already connected.` : `Opened ${url} in the default browser.`);
 		});
 	}
 	/**
@@ -1680,7 +1653,7 @@ var LocalRelayMcpServer = class {
 		const safeUrl = new URL(url).href;
 		const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
 		return new Promise((resolve, reject) => {
-			execFile(command, [safeUrl], (err) => {
+			this.launchBrowser(command, [safeUrl], (err) => {
 				if (err) reject(err);
 				else resolve();
 			});
@@ -1770,30 +1743,25 @@ var LocalRelayMcpServer = class {
 	* Registers a single dynamic tool and returns a removal handle.
 	*/
 	registerDynamicTool(tool) {
-		const inputSchema = fromJsonSchema(tool.inputSchema);
-		const outputSchema = tool.outputSchema ? fromJsonSchema(tool.outputSchema) : void 0;
-		return this.mcpServer.registerTool(tool.name, {
-			...tool.title !== void 0 ? { title: tool.title } : {},
+		const inputSchema = fromJsonSchema(JsonSchemaObjectSchema.parse(tool.inputSchema));
+		const outputSchema = tool.outputSchema !== void 0 ? fromJsonSchema(JsonSchemaObjectSchema.parse(tool.outputSchema)) : void 0;
+		const registration = {
 			description: this.dynamicToolDescription(tool),
-			inputSchema,
-			...outputSchema ? { outputSchema } : {},
-			...tool.annotations ? { annotations: tool.annotations } : {},
-			...tool.icons ? { icons: tool.icons } : {},
-			...tool._meta ? { _meta: tool._meta } : {}
-		}, async (args) => {
+			inputSchema
+		};
+		if (tool.title !== void 0) registration.title = tool.title;
+		if (outputSchema) registration.outputSchema = outputSchema;
+		if (tool.annotations) registration.annotations = tool.annotations;
+		if (tool.icons) registration.icons = tool.icons;
+		if (tool._meta) registration._meta = tool._meta;
+		return this.mcpServer.registerTool(tool.name, registration, async (args) => {
 			try {
 				return await this.bridge.invokeTool(tool.name, args);
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
 				const details = err instanceof Error ? err.stack ?? err.message : String(err);
 				process.stderr.write(`[webmcp-local-relay] error: dynamic tool "${tool.name}" invocation failed: ${details}\n`);
-				return {
-					content: [{
-						type: "text",
-						text: `Failed to invoke relayed tool "${tool.name}": ${message}`
-					}],
-					isError: true
-				};
+				return errorResult(`Failed to invoke relayed tool "${tool.name}": ${message}`);
 			}
 		});
 	}
@@ -1832,4 +1800,4 @@ var LocalRelayMcpServer = class {
 
 //#endregion
 export { NormalizedToolSchema as C, normalizeInboundTool as D, ToolSchema as E, InboundToolSchema as S, ToolAnnotationsSchema as T, extractSanitizedDomain as _, BrowserToRelayMessageSchema as a, CallToolResultSchema as b, RelayHelloAcceptedMessageSchema as c, RelaySourceInfoSchema as d, RelayToBrowserMessageSchema as f, buildPublicToolName as g, RelayRegistry as h, RelayBridgeServer as i, RelayHelloRejectedMessageSchema as l, HelloRequiredError as m, parseCliOptions as n, RelayClientToServerMessageSchema as o, ServerHelloMessageSchema as p, printHelp as r, RelayDescriptorSchema as s, LocalRelayMcpServer as t, RelayServerToClientMessageSchema as u, sanitizeName as v, RelayInvokeArgsSchema as w, DEFAULT_TOOL_INPUT_SCHEMA as x, CallToolRequestParamsSchema as y };
-//# sourceMappingURL=mcpRelayServer-DfGkigG5.mjs.map
+//# sourceMappingURL=mcpRelayServer-DEgebuO2.mjs.map