@hediet/linkrpc-mcp 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+import { a as HubSenderProvider, c as ConnectionPool, d as HubAccess, f as IConnectionPool, i as McpToolCall, l as ConnectionPoolOptions, m as TraceListener, n as LinkRpcMcpServerOptions, o as McpSessionInfo, p as PooledConnection, r as McpExploreCall, s as ProviderPool, t as LinkRpcMcpServer, u as DefaultTransport } from "./chunks/server-Bquqk9Mk.js";
+import { IRequestSender, LinkRpcInterfaceSchema, SigningCallCtx } from "@hediet/linkrpc";
+//#region src/explore.d.ts
+interface ExploreCommonArgs {
+  /** Exact directory-level filters, applied before browsing or searching. */
+  readonly serviceId?: string;
+  readonly interfaceId?: string;
+  /** Include reflection plumbing such as `hubrpc.directory` and `hubrpc.schemas`. */
+  readonly includeInternal?: boolean;
+  /** Request one broad reflection grant when a gated directory is encountered. */
+  readonly requestPermission?: boolean;
+}
+interface ExploreBrowseArgs extends ExploreCommonArgs {
+  readonly kind: 'browse';
+  /** Number of interfaces to return. Defaults to 20; maximum 100. */
+  readonly limit?: number;
+  /** Opaque continuation cursor returned by a previous browse call. */
+  readonly cursor?: string;
+}
+interface ExploreGrepArgs extends ExploreCommonArgs {
+  readonly kind: 'grep';
+  /** Pattern searched against the generated `defineInterface` source, one line at a time. */
+  readonly pattern: string;
+  /** Defaults to `regex`. Both modes are case-insensitive. */
+  readonly syntax?: 'regex' | 'literal';
+  /** Number of matching virtual documents to return. Defaults to 20; maximum 100. */
+  readonly limit?: number;
+  /** Opaque continuation cursor returned by a previous grep call. */
+  readonly cursor?: string;
+  /** Source lines included before and after each match. Defaults to 1; maximum 5. */
+  readonly contextLines?: number;
+}
+interface ExploreInspectArgs extends ExploreCommonArgs {
+  readonly kind: 'inspect';
+  readonly serviceId: string;
+  readonly interfaceId: string;
+  /** Generated `defineInterface` source by default; use `schema` for the raw wire schema. */
+  readonly format?: 'source' | 'schema';
+}
+type ExploreArgs = ExploreBrowseArgs | ExploreGrepArgs | ExploreInspectArgs;
+interface ExploreDeps {
+  requestReflectionAccess(): Promise<boolean>;
+}
+interface ExploreListing {
+  readonly serviceId: string;
+  readonly serviceDescription?: string;
+  readonly interfaceId: string;
+  readonly interfaceHash: string;
+  readonly documentId: string;
+}
+interface ExploreGrepMatch {
+  /** Matching source plus the requested surrounding context, joined with newlines. */
+  readonly searchResult: string;
+  /** Inclusive, 1-based line range of `searchResult` in the virtual document. */
+  readonly lineRange: readonly [start: number, end: number];
+  /** LinkRPC member containing every matched line in this chunk, when unambiguous. */
+  readonly member?: string;
+}
+interface ExploreGrepEntry extends ExploreListing {
+  readonly matches: readonly ExploreGrepMatch[];
+  /** True when this document contains more matches than were returned. */
+  readonly matchesTruncated?: boolean;
+}
+interface ExploreDocumentError {
+  readonly serviceId: string;
+  readonly interfaceId: string;
+  readonly error: string;
+}
+interface ExploreInaccessible {
+  readonly serviceId: string;
+  readonly reason: string;
+  readonly hint: string;
+}
+interface ExploreBrowseResult {
+  readonly kind: 'browse';
+  readonly total: number;
+  readonly entries: readonly ExploreListing[];
+  readonly nextCursor?: string;
+  readonly inaccessible?: readonly ExploreInaccessible[];
+}
+interface ExploreGrepResult {
+  readonly kind: 'grep';
+  readonly pattern: string;
+  readonly syntax: 'regex' | 'literal';
+  readonly total: number;
+  readonly entries: readonly ExploreGrepEntry[];
+  readonly nextCursor?: string;
+  readonly documentErrors?: readonly ExploreDocumentError[];
+  readonly inaccessible?: readonly ExploreInaccessible[];
+}
+interface ExploreInspectResult extends ExploreListing {
+  readonly kind: 'inspect';
+  readonly format: 'source' | 'schema';
+  readonly source?: string;
+  readonly schema?: LinkRpcInterfaceSchema;
+  readonly inaccessible?: readonly ExploreInaccessible[];
+}
+type ExploreResult = ExploreBrowseResult | ExploreGrepResult | ExploreInspectResult;
+/**
+ * Browse the reflected directory, grep generated interface source, or inspect
+ * one exact virtual document. Generated source is cached by the directory
+ * route and interface hash; every call still walks the live directory.
+ */
+declare function explore(channel: IRequestSender<SigningCallCtx>, args: ExploreArgs, deps?: ExploreDeps): Promise<ExploreResult>;
+//#endregion
+//#region src/sandbox.d.ts
+/**
+ * Async host functions exposed to the guest. Each returns either:
+ *   - a JSON-stringified value (the guest will `JSON.parse` it), or
+ *   - the empty string for `undefined` results (used for `notify`).
+ *
+ * Host rejections become guest `Error`s with a bounded snapshot of every
+ * serializable own data property preserved.
+ */
+interface SandboxHostApi {
+  call(method: string, paramsJson: string, optsJson: string, onStreamMessage: (payloadJson: string) => void, signal: AbortSignal): Promise<string>;
+  notify(method: string, paramsJson: string): Promise<string>;
+  explore(argsJson: string): Promise<string>;
+  requestAccess(argsJson: string): Promise<string>;
+  grants(argsJson: string): Promise<string>;
+}
+type SandboxLog = {
+  level: "log" | "warn" | "error";
+  text: string;
+};
+/** Legacy options for {@link runSandboxed} (run-to-completion, no parking). */
+interface SandboxOptions {
+  /** Foreground budget in ms. Defaults to {@link DEFAULT_FOREGROUND_MS}. */
+  readonly timeoutMs?: number;
+  readonly memoryLimitBytes?: number;
+}
+/** Options for {@link startSandbox} (parking-capable). */
+interface StartSandboxOptions {
+  /**
+   * How long the call may run synchronously before it is parked as a
+   * background task. Defaults to {@link DEFAULT_FOREGROUND_MS}.
+   */
+  readonly foregroundMs?: number;
+  /**
+   * Absolute lifetime cap for a parked task. After this the task is
+   * soft-aborted and settled with an error. Defaults to
+   * {@link DEFAULT_MAX_LIFETIME_MS}. Must be `> foregroundMs` for parking
+   * to be possible.
+   */
+  readonly maxLifetimeMs?: number;
+  readonly memoryLimitBytes?: number;
+  /**
+   * Human-readable debug name for the parked task. When omitted, the name
+   * is inferred from the in-flight RPC(s) at park time, falling back to the
+   * first line of `code`.
+   */
+  readonly label?: string;
+}
+/** Legacy result shape for {@link runSandboxed}. */
+interface SandboxRunResult {
+  readonly resultJson: string;
+  readonly logs: readonly SandboxLog[];
+}
+/** Terminal state of a parked task. */
+type TaskOutcome = {
+  readonly status: "completed";
+  readonly result: unknown;
+  readonly logs: readonly SandboxLog[];
+} | {
+  readonly status: "error";
+  readonly error: string;
+  readonly logs: readonly SandboxLog[];
+} | {
+  readonly status: "cancelled";
+  readonly logs: readonly SandboxLog[];
+};
+/** Result of the foreground phase of {@link startSandbox}. */
+type SandboxOutcome = {
+  readonly status: "completed";
+  readonly result: unknown;
+  readonly logs: readonly SandboxLog[];
+} | {
+  readonly status: "error";
+  readonly error: string;
+  readonly logs: readonly SandboxLog[];
+} | {
+  readonly status: "parked";
+  readonly debugName: string;
+  readonly task: ParkedTask;
+};
+/**
+ * A live sandbox execution that did not settle within the foreground budget
+ * and is now pumping in the background until its in-flight work resolves, it
+ * is cancelled, or it hits the max-lifetime guard.
+ */
+interface ParkedTask {
+  /** Labels of the RPC(s) currently in flight (snapshot). */
+  inFlight(): string[];
+  /** Live view of logs captured so far. */
+  readonly logs: readonly SandboxLog[];
+  /** Resolves when the task reaches a terminal state. Never rejects. */
+  readonly done: Promise<TaskOutcome>;
+  /**
+   * Soft-abort the task and settle it. Resolves with the terminal outcome
+   * (`cancelled`, or `completed`/`error` if the guest settled cleanly
+   * within its grace window).
+   */
+  cancel(): Promise<TaskOutcome>;
+}
+/**
+ * Run-to-completion entry point preserved for callers that just want a result
+ * and treat the timeout as a hard wall (the original behaviour). Throws on
+ * guest error or deadline; never parks.
+ */
+declare function runSandboxed(userCode: string, host: SandboxHostApi, lastResultVal: unknown, options?: SandboxOptions): Promise<SandboxRunResult>;
+/**
+ * Parking-capable entry point. Runs `userCode` for up to `foregroundMs`; if it
+ * settles in that window the result is returned inline, otherwise the live VM
+ * is detached into a {@link ParkedTask} that keeps pumping in the background.
+ */
+declare function startSandbox(userCode: string, host: SandboxHostApi, lastResultVal: unknown, options?: StartSandboxOptions): Promise<SandboxOutcome>;
+//#endregion
+//#region src/connectionDts.d.ts
+/**
+ * Documentation that the MCP server exposes as a resource. The text is the
+ * single source of truth for what `runLinkRpcScript` sees inside the QuickJS
+ * sandbox — it lives as the real declaration file `connection.d.ts` and is
+ * embedded here verbatim. Keep `connection.d.ts` in sync with `sandbox.ts`
+ * and `explore.ts`.
+ */
+declare const CONNECTION_DTS: string;
+//#endregion
+export { CONNECTION_DTS, ConnectionPool, ConnectionPoolOptions, DefaultTransport, ExploreArgs, ExploreBrowseArgs, ExploreBrowseResult, ExploreDeps, ExploreDocumentError, ExploreGrepArgs, ExploreGrepEntry, ExploreGrepMatch, ExploreGrepResult, ExploreInaccessible, ExploreInspectArgs, ExploreInspectResult, ExploreListing, ExploreResult, HubAccess, HubSenderProvider, IConnectionPool, LinkRpcMcpServer, LinkRpcMcpServerOptions, McpExploreCall, McpSessionInfo, McpToolCall, ParkedTask, PooledConnection, ProviderPool, SandboxHostApi, SandboxLog, SandboxOptions, SandboxOutcome, SandboxRunResult, StartSandboxOptions, TaskOutcome, TraceListener, explore, runSandboxed, startSandbox };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as CONNECTION_DTS, i as startSandbox, n as explore, o as ProviderPool, r as runSandboxed, s as ConnectionPool, t as LinkRpcMcpServer } from "./chunks/server-C4ZM6bfK.js";
+export { CONNECTION_DTS, ConnectionPool, LinkRpcMcpServer, ProviderPool, explore, runSandboxed, startSandbox };

package/dist/node.d.ts

@@ -0,0 +1,121 @@
+import { n as LinkRpcMcpServerOptions } from "./chunks/server-Bquqk9Mk.js";
+//#region src/socketHost.d.ts
+/**
+ * Per-session wiring the host asks its owner to provide. Created once per MCP
+ * `initialize`, keyed by `sessionId`. The owner decides how that session reaches
+ * the hub (e.g. an in-process `defaultConnection`) and what to tear down when the
+ * session closes.
+ */
+interface McpSession {
+  /** Options for this session's {@link LinkRpcMcpServer} (e.g. a `defaultConnection`). */
+  readonly serverOptions: LinkRpcMcpServerOptions;
+  /**
+   * Teardown for resources scoped to this session, run after the session's
+   * server is disposed. Note: this fires on MCP *session* close — do **not**
+   * wipe long-lived identity here if you want it to survive a client reload.
+   */
+  readonly dispose?: () => void;
+}
+interface McpSocketHostOptions {
+  /** Display name used only for log lines. */
+  readonly label?: string;
+  /**
+   * Mints per-session wiring. Called once per MCP `initialize`, before the
+   * client's session id is acknowledged. The `sessionId` is the id the host
+   * will report back to the client, so the owner can key identity on it (the
+   * consumer-provisioned mode).
+   */
+  readonly createSession: (ctx: {
+    readonly sessionId: string;
+  }) => Promise<McpSession>;
+  /** Optional structured logger; defaults to a no-op. */
+  readonly log?: (message: string) => void;
+  /**
+   * Where the host listens:
+   * - `"socket"` (default): a local Unix domain socket / named pipe. Most
+   *   private (no TCP port at all), but some MCP clients — notably the Copilot
+   *   harness — don't support `unix`/`pipe` transports yet.
+   * - `"http"`: a loopback (`127.0.0.1`) TCP port with a random bearer token.
+   *   Use this until the socket transport is supported everywhere.
+   */
+  readonly transport?: "socket" | "http";
+}
+/**
+ * Describes where the host is listening, as transport-level facts — not as any
+ * particular client's URI encoding. A consumer (e.g. the VS Code extension)
+ * translates this into whatever its MCP client expects; for VS Code that means a
+ * `unix`/`pipe` URI with the socket path in `uri.path` and {@link requestPath}
+ * in `uri.fragment`, but that encoding is the consumer's concern, not ours.
+ */
+type McpSocketEndpoint = {
+  /**
+   * `unixSocket` on posix, `namedPipe` on Windows. Discriminates how
+   * {@link McpSocketEndpoint.path} is interpreted by the OS / an HTTP
+   * client's `socketPath`.
+   */
+  readonly kind: "unixSocket" | "namedPipe";
+  /**
+   * Exact OS path the server listens on and that an HTTP client passes to
+   * `socketPath`: a filesystem path for `unixSocket`, a `\\.\pipe\…` path
+   * for `namedPipe`. Note a `namedPipe` path contains backslashes and is
+   * therefore not representable as a URL string — keep it as-is rather
+   * than round-tripping through `URL`/`Uri.parse`.
+   */
+  readonly path: string;
+  /** HTTP request path the host serves (defaults to `/mcp`). */
+  readonly requestPath: string;
+  /** Bearer token the client must send in the `Authorization` header. */
+  readonly authorizationToken: string;
+} | {
+  /** A loopback TCP port, reachable over plain `http://`. */
+  readonly kind: "tcp";
+  /** Host the server is bound to (always `127.0.0.1`). */
+  readonly host: string;
+  /** TCP port the server listens on. */
+  readonly port: number;
+  /** HTTP request path the host serves (defaults to `/mcp`). */
+  readonly requestPath: string;
+  /** Bearer token the client must send in the `Authorization` header. */
+  readonly authorizationToken: string;
+};
+/**
+ * Hosts one or more {@link LinkRpcMcpServer} sessions over a local endpoint —
+ * by default a Unix domain socket on posix / a named pipe on Windows, or, when
+ * `transport: "http"` is set, a loopback (`127.0.0.1`) TCP port. The `http`
+ * transport exists for clients that don't yet support the `unix`/`pipe`
+ * transport (e.g. the Copilot harness).
+ *
+ * The host owns the generic plumbing: the socket/pipe or TCP port, bearer-token
+ * auth, and the per-session Streamable HTTP transport lifecycle. *How* each
+ * session reaches the hub — and what identity it signs as — is delegated
+ * entirely to {@link McpSocketHostOptions.createSession}, so the same host serves
+ * both the server-provisioned and consumer-provisioned identity modes.
+ */
+declare class McpSocketHost {
+  static start(options: McpSocketHostOptions): Promise<McpSocketHost>;
+  private readonly _options;
+  private readonly _http;
+  private readonly _token;
+  private readonly _transport;
+  private readonly _kind;
+  /** Set for the socket/pipe transport; the OS path we listen on. */
+  private readonly _path;
+  /** Loopback host for the TCP (`http`) transport. */
+  private readonly _host;
+  /** Bound port for the TCP (`http`) transport; filled in after `_listen`. */
+  private _port;
+  private readonly _transports;
+  private readonly _active;
+  private _disposed;
+  private constructor();
+  /** The advertised endpoint (socket/pipe path or TCP host:port + bearer token). */
+  get endpoint(): McpSocketEndpoint;
+  dispose(): void;
+  private _log;
+  private _listen;
+  private _handleHttp;
+  private _openSession;
+}
+//#endregion
+export { McpSession, McpSocketEndpoint, McpSocketHost, McpSocketHostOptions };
+//# sourceMappingURL=node.d.ts.map

package/dist/node.js

@@ -0,0 +1,163 @@
+import { t as LinkRpcMcpServer } from "./chunks/server-C4ZM6bfK.js";
+import { randomBytes, randomUUID } from "crypto";
+import * as fs from "fs";
+import * as http from "http";
+import * as os from "os";
+import * as path from "path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+//#region src/socketHost.ts
+const REQUEST_PATH = "/mcp";
+/**
+* Hosts one or more {@link LinkRpcMcpServer} sessions over a local endpoint —
+* by default a Unix domain socket on posix / a named pipe on Windows, or, when
+* `transport: "http"` is set, a loopback (`127.0.0.1`) TCP port. The `http`
+* transport exists for clients that don't yet support the `unix`/`pipe`
+* transport (e.g. the Copilot harness).
+*
+* The host owns the generic plumbing: the socket/pipe or TCP port, bearer-token
+* auth, and the per-session Streamable HTTP transport lifecycle. *How* each
+* session reaches the hub — and what identity it signs as — is delegated
+* entirely to {@link McpSocketHostOptions.createSession}, so the same host serves
+* both the server-provisioned and consumer-provisioned identity modes.
+*/
+var McpSocketHost = class McpSocketHost {
+	static async start(options) {
+		const host = new McpSocketHost(options);
+		await host._listen();
+		return host;
+	}
+	_options;
+	_http;
+	_token = randomBytes(24).toString("base64url");
+	_transport;
+	_kind;
+	/** Set for the socket/pipe transport; the OS path we listen on. */
+	_path;
+	/** Loopback host for the TCP (`http`) transport. */
+	_host = "127.0.0.1";
+	/** Bound port for the TCP (`http`) transport; filled in after `_listen`. */
+	_port = 0;
+	_transports = /* @__PURE__ */ new Map();
+	_active = /* @__PURE__ */ new Map();
+	_disposed = false;
+	constructor(options) {
+		this._options = options;
+		this._http = http.createServer((req, res) => void this._handleHttp(req, res));
+		this._transport = options.transport ?? "socket";
+		if (this._transport === "http") {
+			this._kind = "tcp";
+			this._path = void 0;
+		} else {
+			this._kind = process.platform === "win32" ? "namedPipe" : "unixSocket";
+			this._path = process.platform === "win32" ? `\\\\.\\pipe\\linkrpc-mcp-${randomUUID()}` : path.join(os.tmpdir(), `linkrpc-mcp-${randomUUID()}.sock`);
+		}
+	}
+	/** The advertised endpoint (socket/pipe path or TCP host:port + bearer token). */
+	get endpoint() {
+		if (this._kind === "tcp") return {
+			kind: "tcp",
+			host: this._host,
+			port: this._port,
+			requestPath: REQUEST_PATH,
+			authorizationToken: this._token
+		};
+		return {
+			kind: this._kind,
+			path: this._path,
+			requestPath: REQUEST_PATH,
+			authorizationToken: this._token
+		};
+	}
+	dispose() {
+		if (this._disposed) return;
+		this._disposed = true;
+		for (const { server, session } of this._active.values()) {
+			server.dispose();
+			session.dispose?.();
+		}
+		this._active.clear();
+		this._transports.clear();
+		this._http.close();
+		if (this._kind === "unixSocket" && this._path) fs.rm(this._path, { force: true }, () => {});
+	}
+	_log(message) {
+		this._options.log?.(this._options.label ? `[${this._options.label}] ${message}` : message);
+	}
+	_listen() {
+		return new Promise((resolve, reject) => {
+			this._http.once("error", reject);
+			const onListening = () => {
+				this._http.removeListener("error", reject);
+				if (this._kind === "tcp") {
+					const addr = this._http.address();
+					if (!addr || typeof addr === "string") {
+						reject(/* @__PURE__ */ new Error("linkrpc-mcp: failed to bind loopback TCP port"));
+						return;
+					}
+					this._port = addr.port;
+					this._log(`listening on tcp ${this._host}:${this._port}`);
+				} else this._log(`listening on ${this._kind} ${this._path}`);
+				resolve();
+			};
+			if (this._kind === "tcp") this._http.listen(0, this._host, onListening);
+			else this._http.listen(this._path, onListening);
+		});
+	}
+	async _handleHttp(req, res) {
+		if (!req.url || !req.url.startsWith(REQUEST_PATH)) {
+			res.statusCode = 404;
+			res.end();
+			return;
+		}
+		if (req.headers.authorization !== `Bearer ${this._token}`) {
+			this._log(`${req.method} ${req.url} → 401 (bad/missing auth)`);
+			res.statusCode = 401;
+			res.end();
+			return;
+		}
+		const sessionHeader = req.headers["mcp-session-id"];
+		const sessionId = Array.isArray(sessionHeader) ? sessionHeader[0] : sessionHeader;
+		let transport = sessionId ? this._transports.get(sessionId) : void 0;
+		if (!transport) {
+			if (req.method !== "POST") {
+				this._log(`${req.method} without known session id → 400 (only POST initialize starts a session)`);
+				res.statusCode = 400;
+				res.end();
+				return;
+			}
+			transport = await this._openSession();
+		}
+		await transport.handleRequest(req, res);
+	}
+	async _openSession() {
+		const sessionId = randomUUID();
+		const session = await this._options.createSession({ sessionId });
+		const server = new LinkRpcMcpServer(session.serverOptions);
+		const transport = new StreamableHTTPServerTransport({
+			sessionIdGenerator: () => sessionId,
+			onsessioninitialized: (sid) => {
+				this._transports.set(sid, transport);
+				this._log(`session initialized sid=${sid}`);
+			}
+		});
+		this._active.set(transport, {
+			server,
+			session
+		});
+		transport.onclose = () => {
+			if (transport.sessionId) {
+				this._transports.delete(transport.sessionId);
+				this._log(`session closed sid=${transport.sessionId}`);
+			}
+			this._active.delete(transport);
+			server.dispose();
+			session.dispose?.();
+		};
+		await server.connect(transport);
+		return transport;
+	}
+};
+//#endregion
+export { McpSocketHost };
+
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","names":[],"sources":["../src/socketHost.ts"],"sourcesContent":["import * as fs from \"fs\";\nimport * as http from \"http\";\nimport * as os from \"os\";\nimport * as path from \"path\";\nimport { randomBytes, randomUUID } from \"crypto\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { LinkRpcMcpServer, type LinkRpcMcpServerOptions } from \"./server\";\n\n/**\n * Per-session wiring the host asks its owner to provide. Created once per MCP\n * `initialize`, keyed by `sessionId`. The owner decides how that session reaches\n * the hub (e.g. an in-process `defaultConnection`) and what to tear down when the\n * session closes.\n */\nexport interface McpSession {\n    /** Options for this session's {@link LinkRpcMcpServer} (e.g. a `defaultConnection`). */\n    readonly serverOptions: LinkRpcMcpServerOptions;\n    /**\n     * Teardown for resources scoped to this session, run after the session's\n     * server is disposed. Note: this fires on MCP *session* close — do **not**\n     * wipe long-lived identity here if you want it to survive a client reload.\n     */\n    readonly dispose?: () => void;\n}\n\nexport interface McpSocketHostOptions {\n    /** Display name used only for log lines. */\n    readonly label?: string;\n    /**\n     * Mints per-session wiring. Called once per MCP `initialize`, before the\n     * client's session id is acknowledged. The `sessionId` is the id the host\n     * will report back to the client, so the owner can key identity on it (the\n     * consumer-provisioned mode).\n     */\n    readonly createSession: (ctx: { readonly sessionId: string }) => Promise<McpSession>;\n    /** Optional structured logger; defaults to a no-op. */\n    readonly log?: (message: string) => void;\n    /**\n     * Where the host listens:\n     * - `\"socket\"` (default): a local Unix domain socket / named pipe. Most\n     *   private (no TCP port at all), but some MCP clients — notably the Copilot\n     *   harness — don't support `unix`/`pipe` transports yet.\n     * - `\"http\"`: a loopback (`127.0.0.1`) TCP port with a random bearer token.\n     *   Use this until the socket transport is supported everywhere.\n     */\n    readonly transport?: \"socket\" | \"http\";\n}\n\n/**\n * Describes where the host is listening, as transport-level facts — not as any\n * particular client's URI encoding. A consumer (e.g. the VS Code extension)\n * translates this into whatever its MCP client expects; for VS Code that means a\n * `unix`/`pipe` URI with the socket path in `uri.path` and {@link requestPath}\n * in `uri.fragment`, but that encoding is the consumer's concern, not ours.\n */\nexport type McpSocketEndpoint =\n    | {\n          /**\n           * `unixSocket` on posix, `namedPipe` on Windows. Discriminates how\n           * {@link McpSocketEndpoint.path} is interpreted by the OS / an HTTP\n           * client's `socketPath`.\n           */\n          readonly kind: \"unixSocket\" | \"namedPipe\";\n          /**\n           * Exact OS path the server listens on and that an HTTP client passes to\n           * `socketPath`: a filesystem path for `unixSocket`, a `\\\\.\\pipe\\…` path\n           * for `namedPipe`. Note a `namedPipe` path contains backslashes and is\n           * therefore not representable as a URL string — keep it as-is rather\n           * than round-tripping through `URL`/`Uri.parse`.\n           */\n          readonly path: string;\n          /** HTTP request path the host serves (defaults to `/mcp`). */\n          readonly requestPath: string;\n          /** Bearer token the client must send in the `Authorization` header. */\n          readonly authorizationToken: string;\n      }\n    | {\n          /** A loopback TCP port, reachable over plain `http://`. */\n          readonly kind: \"tcp\";\n          /** Host the server is bound to (always `127.0.0.1`). */\n          readonly host: string;\n          /** TCP port the server listens on. */\n          readonly port: number;\n          /** HTTP request path the host serves (defaults to `/mcp`). */\n          readonly requestPath: string;\n          /** Bearer token the client must send in the `Authorization` header. */\n          readonly authorizationToken: string;\n      };\n\nconst REQUEST_PATH = \"/mcp\";\n\ninterface ActiveSession {\n    readonly server: LinkRpcMcpServer;\n    readonly session: McpSession;\n}\n\n/**\n * Hosts one or more {@link LinkRpcMcpServer} sessions over a local endpoint —\n * by default a Unix domain socket on posix / a named pipe on Windows, or, when\n * `transport: \"http\"` is set, a loopback (`127.0.0.1`) TCP port. The `http`\n * transport exists for clients that don't yet support the `unix`/`pipe`\n * transport (e.g. the Copilot harness).\n *\n * The host owns the generic plumbing: the socket/pipe or TCP port, bearer-token\n * auth, and the per-session Streamable HTTP transport lifecycle. *How* each\n * session reaches the hub — and what identity it signs as — is delegated\n * entirely to {@link McpSocketHostOptions.createSession}, so the same host serves\n * both the server-provisioned and consumer-provisioned identity modes.\n */\nexport class McpSocketHost {\n    public static async start(options: McpSocketHostOptions): Promise<McpSocketHost> {\n        const host = new McpSocketHost(options);\n        await host._listen();\n        return host;\n    }\n\n    private readonly _options: McpSocketHostOptions;\n    private readonly _http: http.Server;\n    private readonly _token = randomBytes(24).toString(\"base64url\");\n    private readonly _transport: \"socket\" | \"http\";\n    private readonly _kind: McpSocketEndpoint[\"kind\"];\n    /** Set for the socket/pipe transport; the OS path we listen on. */\n    private readonly _path: string | undefined;\n    /** Loopback host for the TCP (`http`) transport. */\n    private readonly _host = \"127.0.0.1\";\n    /** Bound port for the TCP (`http`) transport; filled in after `_listen`. */\n    private _port = 0;\n    private readonly _transports = new Map<string, StreamableHTTPServerTransport>();\n    private readonly _active = new Map<StreamableHTTPServerTransport, ActiveSession>();\n    private _disposed = false;\n\n    private constructor(options: McpSocketHostOptions) {\n        this._options = options;\n        this._http = http.createServer((req, res) => void this._handleHttp(req, res));\n        this._transport = options.transport ?? \"socket\";\n        if (this._transport === \"http\") {\n            this._kind = \"tcp\";\n            this._path = undefined;\n        } else {\n            this._kind = process.platform === \"win32\" ? \"namedPipe\" : \"unixSocket\";\n            this._path =\n                process.platform === \"win32\"\n                    ? `\\\\\\\\.\\\\pipe\\\\linkrpc-mcp-${randomUUID()}`\n                    : path.join(os.tmpdir(), `linkrpc-mcp-${randomUUID()}.sock`);\n        }\n    }\n\n    /** The advertised endpoint (socket/pipe path or TCP host:port + bearer token). */\n    public get endpoint(): McpSocketEndpoint {\n        if (this._kind === \"tcp\") {\n            return {\n                kind: \"tcp\",\n                host: this._host,\n                port: this._port,\n                requestPath: REQUEST_PATH,\n                authorizationToken: this._token,\n            };\n        }\n        return {\n            kind: this._kind,\n            path: this._path!,\n            requestPath: REQUEST_PATH,\n            authorizationToken: this._token,\n        };\n    }\n\n    public dispose(): void {\n        if (this._disposed) {\n            return;\n        }\n        this._disposed = true;\n        for (const { server, session } of this._active.values()) {\n            server.dispose();\n            session.dispose?.();\n        }\n        this._active.clear();\n        this._transports.clear();\n        this._http.close();\n        // Node unlinks the Unix socket on graceful close; remove it best-effort\n        // in case the server never fully started. Named pipes / TCP need no cleanup.\n        if (this._kind === \"unixSocket\" && this._path) {\n            fs.rm(this._path, { force: true }, () => {});\n        }\n    }\n\n    private _log(message: string): void {\n        this._options.log?.(this._options.label ? `[${this._options.label}] ${message}` : message);\n    }\n\n    private _listen(): Promise<void> {\n        return new Promise((resolve, reject) => {\n            this._http.once(\"error\", reject);\n            const onListening = () => {\n                this._http.removeListener(\"error\", reject);\n                if (this._kind === \"tcp\") {\n                    const addr = this._http.address();\n                    if (!addr || typeof addr === \"string\") {\n                        reject(new Error(\"linkrpc-mcp: failed to bind loopback TCP port\"));\n                        return;\n                    }\n                    this._port = addr.port;\n                    this._log(`listening on tcp ${this._host}:${this._port}`);\n                } else {\n                    this._log(`listening on ${this._kind} ${this._path}`);\n                }\n                resolve();\n            };\n            if (this._kind === \"tcp\") {\n                this._http.listen(0, this._host, onListening);\n            } else {\n                this._http.listen(this._path!, onListening);\n            }\n        });\n    }\n\n    private async _handleHttp(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {\n        if (!req.url || !req.url.startsWith(REQUEST_PATH)) {\n            res.statusCode = 404;\n            res.end();\n            return;\n        }\n        if (req.headers.authorization !== `Bearer ${this._token}`) {\n            this._log(`${req.method} ${req.url} → 401 (bad/missing auth)`);\n            res.statusCode = 401;\n            res.end();\n            return;\n        }\n\n        const sessionHeader = req.headers[\"mcp-session-id\"];\n        const sessionId = Array.isArray(sessionHeader) ? sessionHeader[0] : sessionHeader;\n        let transport = sessionId ? this._transports.get(sessionId) : undefined;\n\n        if (!transport) {\n            if (req.method !== \"POST\") {\n                this._log(`${req.method} without known session id → 400 (only POST initialize starts a session)`);\n                res.statusCode = 400;\n                res.end();\n                return;\n            }\n            transport = await this._openSession();\n        }\n\n        await transport.handleRequest(req, res);\n    }\n\n    private async _openSession(): Promise<StreamableHTTPServerTransport> {\n        // The session id is fixed up front so `createSession` can key identity on\n        // it (the consumer-provisioned mode) and the transport reports it back.\n        const sessionId = randomUUID();\n        const session = await this._options.createSession({ sessionId });\n        const server = new LinkRpcMcpServer(session.serverOptions);\n\n        const transport = new StreamableHTTPServerTransport({\n            sessionIdGenerator: () => sessionId,\n            onsessioninitialized: (sid) => {\n                this._transports.set(sid, transport);\n                this._log(`session initialized sid=${sid}`);\n            },\n        });\n        this._active.set(transport, { server, session });\n\n        transport.onclose = () => {\n            if (transport.sessionId) {\n                this._transports.delete(transport.sessionId);\n                this._log(`session closed sid=${transport.sessionId}`);\n            }\n            this._active.delete(transport);\n            // Dispose the server (tears down its connection pool / in-process leg)\n            // before the session's own teardown.\n            server.dispose();\n            session.dispose?.();\n        };\n\n        await server.connect(transport);\n        return transport;\n    }\n}\n"],"mappings":";;;;;;;;AAyFA,MAAM,eAAe;;;;;;;;;;;;;;AAoBrB,IAAa,gBAAb,MAAa,cAAc;CACvB,aAAoB,MAAM,SAAuD;EAC7E,MAAM,OAAO,IAAI,cAAc,OAAO;EACtC,MAAM,KAAK,QAAQ;EACnB,OAAO;CACX;CAEA;CACA;CACA,SAA0B,YAAY,EAAE,CAAC,CAAC,SAAS,WAAW;CAC9D;CACA;;CAEA;;CAEA,QAAyB;;CAEzB,QAAgB;CAChB,8BAA+B,IAAI,IAA2C;CAC9E,0BAA2B,IAAI,IAAkD;CACjF,YAAoB;CAEpB,YAAoB,SAA+B;EAC/C,KAAK,WAAW;EAChB,KAAK,QAAQ,KAAK,cAAc,KAAK,QAAQ,KAAK,KAAK,YAAY,KAAK,GAAG,CAAC;EAC5E,KAAK,aAAa,QAAQ,aAAa;EACvC,IAAI,KAAK,eAAe,QAAQ;GAC5B,KAAK,QAAQ;GACb,KAAK,QAAQ,KAAA;EACjB,OAAO;GACH,KAAK,QAAQ,QAAQ,aAAa,UAAU,cAAc;GAC1D,KAAK,QACD,QAAQ,aAAa,UACf,4BAA4B,WAAW,MACvC,KAAK,KAAK,GAAG,OAAO,GAAG,eAAe,WAAW,EAAE,MAAM;EACvE;CACJ;;CAGA,IAAW,WAA8B;EACrC,IAAI,KAAK,UAAU,OACf,OAAO;GACH,MAAM;GACN,MAAM,KAAK;GACX,MAAM,KAAK;GACX,aAAa;GACb,oBAAoB,KAAK;EAC7B;EAEJ,OAAO;GACH,MAAM,KAAK;GACX,MAAM,KAAK;GACX,aAAa;GACb,oBAAoB,KAAK;EAC7B;CACJ;CAEA,UAAuB;EACnB,IAAI,KAAK,WACL;EAEJ,KAAK,YAAY;EACjB,KAAK,MAAM,EAAE,QAAQ,aAAa,KAAK,QAAQ,OAAO,GAAG;GACrD,OAAO,QAAQ;GACf,QAAQ,UAAU;EACtB;EACA,KAAK,QAAQ,MAAM;EACnB,KAAK,YAAY,MAAM;EACvB,KAAK,MAAM,MAAM;EAGjB,IAAI,KAAK,UAAU,gBAAgB,KAAK,OACpC,GAAG,GAAG,KAAK,OAAO,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC;CAEnD;CAEA,KAAa,SAAuB;EAChC,KAAK,SAAS,MAAM,KAAK,SAAS,QAAQ,IAAI,KAAK,SAAS,MAAM,IAAI,YAAY,OAAO;CAC7F;CAEA,UAAiC;EAC7B,OAAO,IAAI,SAAS,SAAS,WAAW;GACpC,KAAK,MAAM,KAAK,SAAS,MAAM;GAC/B,MAAM,oBAAoB;IACtB,KAAK,MAAM,eAAe,SAAS,MAAM;IACzC,IAAI,KAAK,UAAU,OAAO;KACtB,MAAM,OAAO,KAAK,MAAM,QAAQ;KAChC,IAAI,CAAC,QAAQ,OAAO,SAAS,UAAU;MACnC,uBAAO,IAAI,MAAM,+CAA+C,CAAC;MACjE;KACJ;KACA,KAAK,QAAQ,KAAK;KAClB,KAAK,KAAK,oBAAoB,KAAK,MAAM,GAAG,KAAK,OAAO;IAC5D,OACI,KAAK,KAAK,gBAAgB,KAAK,MAAM,GAAG,KAAK,OAAO;IAExD,QAAQ;GACZ;GACA,IAAI,KAAK,UAAU,OACf,KAAK,MAAM,OAAO,GAAG,KAAK,OAAO,WAAW;QAE5C,KAAK,MAAM,OAAO,KAAK,OAAQ,WAAW;EAElD,CAAC;CACL;CAEA,MAAc,YAAY,KAA2B,KAAyC;EAC1F,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,IAAI,WAAW,YAAY,GAAG;GAC/C,IAAI,aAAa;GACjB,IAAI,IAAI;GACR;EACJ;EACA,IAAI,IAAI,QAAQ,kBAAkB,UAAU,KAAK,UAAU;GACvD,KAAK,KAAK,GAAG,IAAI,OAAO,GAAG,IAAI,IAAI,0BAA0B;GAC7D,IAAI,aAAa;GACjB,IAAI,IAAI;GACR;EACJ;EAEA,MAAM,gBAAgB,IAAI,QAAQ;EAClC,MAAM,YAAY,MAAM,QAAQ,aAAa,IAAI,cAAc,KAAK;EACpE,IAAI,YAAY,YAAY,KAAK,YAAY,IAAI,SAAS,IAAI,KAAA;EAE9D,IAAI,CAAC,WAAW;GACZ,IAAI,IAAI,WAAW,QAAQ;IACvB,KAAK,KAAK,GAAG,IAAI,OAAO,wEAAwE;IAChG,IAAI,aAAa;IACjB,IAAI,IAAI;IACR;GACJ;GACA,YAAY,MAAM,KAAK,aAAa;EACxC;EAEA,MAAM,UAAU,cAAc,KAAK,GAAG;CAC1C;CAEA,MAAc,eAAuD;EAGjE,MAAM,YAAY,WAAW;EAC7B,MAAM,UAAU,MAAM,KAAK,SAAS,cAAc,EAAE,UAAU,CAAC;EAC/D,MAAM,SAAS,IAAI,iBAAiB,QAAQ,aAAa;EAEzD,MAAM,YAAY,IAAI,8BAA8B;GAChD,0BAA0B;GAC1B,uBAAuB,QAAQ;IAC3B,KAAK,YAAY,IAAI,KAAK,SAAS;IACnC,KAAK,KAAK,2BAA2B,KAAK;GAC9C;EACJ,CAAC;EACD,KAAK,QAAQ,IAAI,WAAW;GAAE;GAAQ;EAAQ,CAAC;EAE/C,UAAU,gBAAgB;GACtB,IAAI,UAAU,WAAW;IACrB,KAAK,YAAY,OAAO,UAAU,SAAS;IAC3C,KAAK,KAAK,sBAAsB,UAAU,WAAW;GACzD;GACA,KAAK,QAAQ,OAAO,SAAS;GAG7B,OAAO,QAAQ;GACf,QAAQ,UAAU;EACtB;EAEA,MAAM,OAAO,QAAQ,SAAS;EAC9B,OAAO;CACX;AACJ"}