@johnhenry/wsh 0.23.1 → 0.25.0

package/src/server/connection.mjs

@@ -27,6 +27,7 @@ import {
 import { FILE_CHUNK_BYTES } from './fs.mjs';
 import { MAX_ATTACHMENTS } from './sessions.mjs';
 import { MCP_CALL_ID_FEATURE } from '../client.mjs';
+import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } from '../rpc.mjs';
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
@@ -52,6 +53,7 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {{ pubkey: boolean, password: Function | null }} cfg.methods - which auth methods are on
  * @param {object | null} cfg.hostKey - from loadHostKey
  * @param {object | null} cfg.mcp - from createMcpHost
+ * @param {{ protocols: Map<string, Function>, maxMessageBytes: number, maxInflight: number } | null} cfg.rpc - from createRpcHost
  * @param {object | null} cfg.relay - a RelayHub (see relay.mjs); null = not a relay
  * @param {object | null} cfg.sessions - a SessionRegistry (see sessions.mjs); null = sessions die with their connection
  * @param {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
@@ -202,6 +204,9 @@ export function createConnectionFactory(cfg) {
         const features = [STREAM_ANNOUNCE];
         if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
         if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
+        if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
+          features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
+        }
         let hostFingerprint;
         if (cfg.hostKey) {
           hostFingerprint = cfg.hostKey.fingerprint;
@@ -211,6 +216,8 @@ export function createConnectionFactory(cfg) {
             features.push(HOST_KEY_PREFIX + toHex(cfg.hostKey.publicKey), HOST_KEY_SIG_PREFIX + toHex(sig));
           }
         }
+        state.features = features;
+        state.hostFingerprint = hostFingerprint ?? null;
         await send(serverHello({ sessionId: state.sessionId, features, hostFingerprint }));
         if (method === 'pubkey') {
           state.nonce = generateNonce();
@@ -390,6 +397,7 @@ export function createConnectionFactory(cfg) {
         case 'exec': return openExec(m);
         case 'pty': return openPty(m);
         case 'file': return openFile(m);
+        case 'rpc': return openRpc(m);
         default: return send(openFail({ reason: `kind "${m.kind}" is not supported by this server` }));
       }
     }
@@ -650,6 +658,60 @@ export function createConnectionFactory(cfg) {
       }
     }
 
+    // A typed RPC channel (wsh #85): `Open { kind: 'rpc', command: <protocol> }` is answered like an exec channel's -- OpenOk,
+    // then the client's data stream binds in OpenOk order -- but the stream carries a CBOR sequence of JSON-RPC messages
+    // handled by the protocol's handler, not process I/O.
+    async function openRpc(m) {
+      const rpc = cfg.rpc;
+      const protocol = typeof m.command === 'string' ? m.command : '';
+      const handler = rpc?.protocols.get(protocol);
+      if (!rpc || !dataStreams || !handler) {
+        const why = !rpc || !dataStreams ? 'rpc is not enabled on this server' : `protocol "${protocol}" is not supported by this server`;
+        return send(openFail({ reason: `UNSUPPORTED_PROTOCOL: ${why}` }));
+      }
+      const channelId = ++state.nextChannel;
+      let chan = null;
+      let stream = null;
+      const ch = {
+        // The peer closed the channel (or the connection is going away).
+        kill: () => {
+          channels.delete(channelId);
+          chan?.handleClose('peer-closed');
+          try { stream?.close().catch(() => {}); } catch { /* gone */ }
+        },
+        bind(s) {
+          stream = s;
+          chan = new RpcChannel({
+            maxMessageBytes: rpc.maxMessageBytes,
+            maxInflight: rpc.maxInflight,
+            write: (bytes) => s.write(bytes),
+            // The host ended it: close our end of the stream, then tell the client the channel is over.
+            close: async () => { try { await s.close(); } catch { /* peer gone */ } await finishChannel(channelId, 0); },
+          });
+          s.onData = (d) => chan.feed(d);
+          s.onEnd = () => { void chan.close('stream-end'); };
+          s.onReset = () => chan.handleClose('stream-reset');
+          const ctx = {
+            protocol, channelId, user: state.username, fingerprint: state.fingerprint, remote,
+            features: state.features ?? [], hostFingerprint: state.hostFingerprint,
+            log: (line) => log(`rpc ${protocol} channel ${channelId}: ${line}`),
+          };
+          // Inbound messages wait until the handler (possibly async) has registered its methods.
+          chan.hold();
+          let ready;
+          try { ready = Promise.resolve(handler(chan, ctx)); } catch (e) { ready = Promise.reject(e); }
+          ready.then(() => chan.release(), (e) => {
+            log(`rpc ${protocol} channel ${channelId}: handler failed: ${e?.message ?? e}`);
+            void chan.close('handler-error');
+          });
+        },
+      };
+      channels.set(channelId, ch);
+      pendingStreams.push(channelId);
+      await send(openOk({ channelId, dataMode: 'stream', capabilities: [] }));
+      log(`rpc channel ${channelId}: ${protocol}`);
+    }
+
     async function openPty(m) {
       if (!cfg.pty) return send(openFail({ reason: 'pty is not enabled on this server' }));
       const channelId = ++state.nextChannel;

package/src/server/fs.mjs

@@ -25,6 +25,8 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
   let realBase = null;
 
   const fail = (message) => Object.assign(new Error(message), { wsh: true });
+  /** A refusal on policy grounds (confinement, read-only): `wsh-fs` answers these `-32003`. */
+  const deny = (message) => Object.assign(new Error(message), { wsh: true, denied: true });
 
   /** Resolve a client path to an absolute path inside `root`, or throw. */
   async function resolveInside(clientPath) {
@@ -32,13 +34,13 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
     if (clientPath.includes('\0')) throw fail('illegal path');
     realBase ??= await realpath(base);
     const target = path.resolve(base, '.' + path.sep + clientPath.replace(/^[/\\]+/, ''));
-    if (target !== base && !target.startsWith(base + path.sep)) throw fail('path escapes the file root');
+    if (target !== base && !target.startsWith(base + path.sep)) throw deny('path escapes the file root');
     // Symlink escape: the deepest existing ancestor must still be inside the real root.
     let probe = target;
     for (;;) {
       try {
         const real = await realpath(probe);
-        if (real !== realBase && !real.startsWith(realBase + path.sep)) throw fail('path escapes the file root');
+        if (real !== realBase && !real.startsWith(realBase + path.sep)) throw deny('path escapes the file root');
         break;
       } catch (err) {
         if (err.wsh) throw err;
@@ -66,7 +68,7 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
     return entry;
   }
 
-  const assertWritable = () => { if (readOnly) throw fail('file root is read-only'); };
+  const assertWritable = () => { if (readOnly) throw deny('file root is read-only'); };
 
   return {
     maxFileBytes,
@@ -137,6 +139,37 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
       }
     },
 
+    /**
+     * Stream a byte range of a regular file in `chunkBytes` (default `FILE_CHUNK_BYTES`) pieces (for `wsh-fs` `read`/`download`).
+     * `length` omitted = to the end of the file; a range longer than `maxFileBytes` is refused up front.
+     * @returns {Promise<{ size: number, offset: number, length: number, chunks: AsyncGenerator<Uint8Array> }>}
+     */
+    async openRange(clientPath, { offset, length, chunkBytes = FILE_CHUNK_BYTES } = {}) {
+      const full = await resolveInside(clientPath);
+      const st = await stat(full);
+      if (!st.isFile()) throw fail('not a regular file');
+      const start = offset === undefined || offset === null ? 0 : Number(offset);
+      if (!Number.isSafeInteger(start) || start < 0) throw fail('illegal offset');
+      if (length !== undefined && length !== null && (!Number.isSafeInteger(Number(length)) || Number(length) < 0)) throw fail('illegal length');
+      const available = Math.max(0, st.size - start);
+      const want = length === undefined || length === null ? available : Math.min(Number(length), available);
+      if (want > maxFileBytes) throw fail(`read of ${want} bytes exceeds the ${maxFileBytes} byte limit`);
+      async function* chunks() {
+        const fh = await open(full, 'r');
+        try {
+          let pos = start; let left = want;
+          while (left > 0) {
+            const buf = new Uint8Array(Math.min(chunkBytes, left));
+            const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+            if (bytesRead === 0) break; // truncated underneath us
+            yield bytesRead === buf.length ? buf : buf.subarray(0, bytesRead);
+            pos += bytesRead; left -= bytesRead;
+          }
+        } finally { await fh.close(); }
+      }
+      return { size: st.size, offset: start, length: want, chunks: chunks() };
+    },
+
     async readWhole(clientPath) {
       const full = await resolveInside(clientPath);
       const st = await stat(full);

package/src/server/index.d.ts

@@ -3,6 +3,8 @@
  * root (`@johnhenry/wsh`) never imports it.
  */
 
+import type { RpcChannel } from '@johnhenry/wsh';
+
 /** Who is asking to authenticate. */
 export interface WshServerPrincipal {
   username: string;
@@ -290,11 +292,44 @@ export interface WshServerOptions {
   webTransport?: WshServerWebTransportOptions;
   /** Serve MCP tools (`McpDiscover` / `McpCall`) and advertise `mcp-call-id`. Off by default. */
   mcp?: WshServerMcpOptions;
+  /**
+   * Typed RPC channels (wsh #85): `{ [protocol]: handler }`. Each is advertised as `rpc-protocol:<name>` (plus `rpc` and
+   * `rpc-max-message:<n>`). Built-ins: `'wsh-host': true` (`host.info`, `host.ping`), `'wsh-fs': true` (the server's
+   * `fs`) or `{ root, readOnly?, maxFileBytes? }` (`stat list read write upload download rename mkdir remove`). Anything
+   * else is a function run per opened channel, e.g. `mcp: mcpServerAdapter(server)`. Off by default.
+   */
+  rpc?: Record<string, true | WshServerFsOptions | WshRpcHandler | false | null | undefined>;
+  /** Largest single rpc message (default 1048576). */
+  rpcMaxMessageBytes?: number;
+  /** Concurrent requests per rpc channel before `-32002` (default 64). */
+  rpcMaxInflight?: number;
   /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */
   bindTimeoutMs?: number;
   onLog?: (line: string) => void;
 }
 
+/** Per-channel context handed to an rpc protocol handler. */
+export interface WshRpcContext {
+  protocol: string;
+  channelId: number;
+  user: string | null;
+  fingerprint: string | null;
+  remote: { address?: string; headers?: Record<string, unknown> };
+  /** The exact `ServerHello.features` this connection received. */
+  features: string[];
+  hostFingerprint: string | null;
+  log(line: string): void;
+}
+
+/** Runs once per opened channel; register methods on `channel`. Inbound messages wait until the returned promise settles. */
+export type WshRpcHandler = (channel: RpcChannel, ctx: WshRpcContext) => void | Promise<void>;
+
+/**
+ * Expose an MCP `Server` (`@modelcontextprotocol/sdk`) over an rpc channel: `rpc: { mcp: mcpServerAdapter(server) }`.
+ * An instance serves one channel at a time; pass a factory for one `Server` per channel. The SDK is not imported.
+ */
+export function mcpServerAdapter(serverOrFactory: { connect(transport: any): Promise<void>; close?(): Promise<void> } | ((ctx: WshRpcContext) => any)): WshRpcHandler;
+
 export interface WshServerAddress {
   address: string;
   port: number;

package/src/server/index.mjs

@@ -15,8 +15,9 @@ import { SessionRegistry } from './sessions.mjs';
 import { RelayHub } from './relay.mjs';
 import { startWebTransport } from './webtransport.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
+import { createRpcHost, mcpServerAdapter } from './rpc.mjs';
 
-export { parseAuthorizedKeys, STREAM_ANNOUNCE };
+export { parseAuthorizedKeys, STREAM_ANNOUNCE, mcpServerAdapter };
 export { createReverseHost } from './reverse-host.mjs';
 export { generateSelfSignedCertificate } from './self-signed.mjs';
 
@@ -45,6 +46,12 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  *   Keep pty/exec sessions alive across disconnects so a client can `resumeSession()` / `attachSession()`
  *   them: a per-server registry, a ring buffer of the newest `ringBytes` (default 1 MiB) of output, and
  *   `detachTtlMs` (default 300000; 0 = kill on disconnect) / `maxDetached` (default 16) bounds. Off unless given.
+ * @param {Record<string, true | object | Function>} [options.rpc] - Typed RPC channels (wsh #85): `{ [protocol]: handler }`.
+ *   Built-ins: `'wsh-host': true`, `'wsh-fs': true` (confined by `fs`) or `{ root, readOnly?, maxFileBytes? }`; anything else is a
+ *   function `(channel, ctx) => void` run per opened channel -- e.g. `mcp: mcpServerAdapter(server)`. Each protocol is
+ *   advertised as `rpc-protocol:<name>`. Off unless given.
+ * @param {number} [options.rpcMaxMessageBytes=1048576] - Largest single rpc message (advertised as `rpc-max-message:<n>`).
+ * @param {number} [options.rpcMaxInflight=64] - Concurrent requests per rpc channel before `-32002`.
  * @param {string | Uint8Array} [options.sessionSecret] - Alias for `sessions.sessionSecret`.
  * @param {true | { file: string } | CryptoKeyPair} [options.hostKey] - The server's own Ed25519
  *   identity, advertised (with proof of possession) so clients can pin it. See `src/host-key.mjs`.
@@ -55,7 +62,7 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
-  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, sessions, sessionSecret, relay, webTransport, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, rpc, rpcMaxMessageBytes, rpcMaxInflight, sessions, sessionSecret, relay, webTransport, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
@@ -68,6 +75,7 @@ export function createWshServer({
     key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
     failureDelayMs: rl.failureDelayMs ?? 250,
   };
+  const rpcHost = rpc ? createRpcHost(rpc, { files, maxMessageBytes: rpcMaxMessageBytes, maxInflight: rpcMaxInflight }) : null;
   let host_ = null;
   let registry = null;
   let hub = null;
@@ -98,7 +106,7 @@ export function createWshServer({
       if (relay) hub = new RelayHub({ ...relay, log: onLog });
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
-        methods, hostKey: host_, rateLimit, mcp: mcpHost, sessions: registry, relay: hub,
+        methods, hostKey: host_, rateLimit, mcp: mcpHost, rpc: rpcHost, sessions: registry, relay: hub,
       });
 
       wss = new WebSocketServer({ host, port });

package/src/server/rpc.mjs

@@ -0,0 +1,171 @@
+/**
+ * Typed RPC channels for `@johnhenry/wsh/server` -- wsh #85.
+ *
+ * `createWshServer({ rpc: { [protocol]: handler } })`. A handler is
+ *   - `true` for a built-in (`wsh-host`; `wsh-fs`, confined by the server's `fs` option), or `{ root, ... }` for
+ *     `wsh-fs` with its own root;
+ *   - a function `(channel, ctx) => void | Promise<void>` for anything else (including `mcpServerAdapter(server)`),
+ *     called once per opened channel with an `RpcChannel` to register methods on.
+ *
+ * Built-ins:
+ *   wsh-host  host.info, host.ping
+ *   wsh-fs    stat, list, read, write, upload, download, rename, mkdir, remove
+ */
+
+import { createRequire } from 'node:module';
+import { RpcError, RPC_ERROR, RPC_PROTOCOL_NAME_RE, RPC_DEFAULT_MAX_MESSAGE } from '../rpc.mjs';
+import { RpcMcpTransport } from '../rpc-mcp.mjs';
+import { createFileAccess } from './fs.mjs';
+
+const { version: PACKAGE_VERSION } = createRequire(import.meta.url)('../../package.json');
+
+export const WSH_HOST = 'wsh-host';
+export const WSH_FS = 'wsh-fs';
+const BUILT_INS = new Set([WSH_HOST, WSH_FS, 'mcp']);
+
+const needString = (params, key) => {
+  const v = params?.[key];
+  if (typeof v !== 'string') throw new RpcError(RPC_ERROR.INVALID_PARAMS, `"${key}" (string) is required`);
+  return v;
+};
+
+const needBytes = (params, key) => {
+  const v = params?.[key];
+  if (!(v instanceof Uint8Array)) throw new RpcError(RPC_ERROR.INVALID_PARAMS, `"${key}" (byte string) is required`);
+  return v;
+};
+
+/** Map a file-access failure onto an RpcError. */
+function fsError(e) {
+  if (e instanceof RpcError) return e;
+  if (e?.denied) return new RpcError(RPC_ERROR.UNAUTHORIZED, e.message);
+  if (e?.wsh) return new RpcError(RPC_ERROR.INVALID_PARAMS, e.message);
+  if (e?.code === 'ENOENT') return new RpcError(RPC_ERROR.INTERNAL, 'no such file or directory', { code: 'ENOENT' });
+  return new RpcError(RPC_ERROR.INTERNAL, 'file operation failed', e?.code ? { code: e.code } : undefined);
+}
+
+/** @param {ReturnType<typeof createFileAccess>} files */
+function fsProtocol(files) {
+  return (channel, ctx) => {
+    const guarded = (fn) => async (params, rctx) => {
+      try { return await fn(params ?? {}, rctx); } catch (e) {
+        if (!(e instanceof RpcError)) ctx.log?.(`wsh-fs: ${e.wsh ? e.message : (e.stack ?? e)}`);
+        throw fsError(e);
+      }
+    };
+    channel.onRequest('stat', guarded(async (p) => (await files.operate('stat', needString(p, 'path'))).metadata));
+    channel.onRequest('list', guarded(async (p) => {
+      const r = await files.operate('list', typeof p.path === 'string' ? p.path : '/');
+      return { path: r.metadata?.path ?? p.path ?? '/', entries: r.entries ?? [] };
+    }));
+    channel.onRequest('mkdir', guarded(async (p) => (await files.operate('mkdir', needString(p, 'path'))).metadata));
+    channel.onRequest('remove', guarded(async (p) => (await files.operate('remove', needString(p, 'path'))).metadata));
+    channel.onRequest('rename', guarded(async (p) => (await files.operate('rename', needString(p, 'path'), { newPath: needString(p, 'newPath') })).metadata));
+    channel.onRequest('write', guarded(async (p) => (await files.operate('write', needString(p, 'path'), { offset: p.offset, data: needBytes(p, 'data') })).metadata));
+    // upload: the chunk-friendly write. offset omitted/0 creates or truncates the file; offset > 0 continues it in place.
+    channel.onRequest('upload', guarded(async (p) => {
+      const data = needBytes(p, 'data');
+      const offset = p.offset === undefined || p.offset === null ? 0 : Number(p.offset);
+      if (!Number.isSafeInteger(offset) || offset < 0) throw new RpcError(RPC_ERROR.INVALID_PARAMS, 'illegal offset');
+      if (offset === 0) await files.writeAt(needString(p, 'path'), data, undefined, { mkdirs: true });
+      else await files.writeAt(needString(p, 'path'), data, offset);
+      return { written: data.byteLength, offset };
+    }));
+    // read / download: chunks arrive as `$/progress`, the result is a summary.
+    const stream = async (p, rctx) => {
+      const range = await files.openRange(needString(p, 'path'), {
+        offset: p.offset, length: p.length, chunkBytes: Math.max(64, Math.min(64 * 1024, rctx.channel.maxMessageBytes - 512)),
+      });
+      let sent = 0;
+      for await (const chunk of range.chunks) {
+        if (rctx.signal.aborted) break;
+        await rctx.progress(chunk);
+        sent += chunk.byteLength;
+      }
+      return { size: range.size, offset: range.offset, length: sent, eof: range.offset + sent >= range.size };
+    };
+    channel.onRequest('read', guarded(stream));
+    channel.onRequest('download', guarded((p, rctx) => stream({ path: p.path }, rctx)));
+  };
+}
+
+function hostProtocol(info) {
+  return (channel, ctx) => {
+    channel.onRequest('host.info', () => ({
+      version: PACKAGE_VERSION,
+      protocol: 'wsh-v1',
+      features: [...ctx.features],
+      hostFingerprint: ctx.hostFingerprint ?? null,
+      user: ctx.user,
+      rpc: { protocols: info.protocols(), maxMessageBytes: info.maxMessageBytes },
+    }));
+    channel.onRequest('host.ping', () => ({ time: Date.now() }));
+  };
+}
+
+/**
+ * Validate the `rpc` option and build the per-connection protocol table.
+ * @param {Record<string, true | object | Function>} rpc
+ * @param {{ files: object | null, maxMessageBytes?: number, maxInflight?: number }} deps
+ * @returns {{ protocols: Map<string, Function>, maxMessageBytes: number, maxInflight: number }}
+ */
+export function createRpcHost(rpc, { files, maxMessageBytes = RPC_DEFAULT_MAX_MESSAGE, maxInflight = 64 } = {}) {
+  if (!rpc || typeof rpc !== 'object' || Array.isArray(rpc)) throw new TypeError('createWshServer: rpc must be an object of { [protocol]: handler }');
+  if (!(maxMessageBytes >= 256)) throw new TypeError('createWshServer: rpcMaxMessageBytes must be at least 256');
+  const protocols = new Map();
+  const info = { protocols: () => [...protocols.keys()], maxMessageBytes };
+  for (const [name, spec] of Object.entries(rpc)) {
+    if (spec === undefined || spec === false || spec === null) continue;
+    if (!RPC_PROTOCOL_NAME_RE.test(name)) throw new TypeError(`createWshServer: rpc protocol name ${JSON.stringify(name)} is not allowed (letters, digits, ".", "_", "-")`);
+    if (typeof spec === 'function') { protocols.set(name, spec); continue; }
+    if (name === WSH_HOST && spec === true) { protocols.set(name, hostProtocol(info)); continue; }
+    if (name === WSH_FS && (spec === true || (spec && typeof spec === 'object'))) {
+      if (spec === true && !files) throw new TypeError('createWshServer: rpc["wsh-fs"]: true needs the fs option (or pass { root })');
+      protocols.set(name, fsProtocol(spec === true ? files : createFileAccess(spec)));
+      continue;
+    }
+    if (name === 'mcp') throw new TypeError('createWshServer: rpc.mcp needs a handler: mcpServerAdapter(server)');
+    throw new TypeError(`createWshServer: rpc[${JSON.stringify(name)}] needs a handler function (channel, ctx) => void${BUILT_INS.has(name) ? ' or a valid built-in config' : ''}`);
+  }
+  return { protocols, maxMessageBytes, maxInflight };
+}
+
+/**
+ * Expose an MCP `Server` (`@modelcontextprotocol/sdk`) over an `rpc` channel: `rpc: { mcp: mcpServerAdapter(server) }`.
+ *
+ * Pass a Server instance to serve one channel at a time (a second concurrent channel is closed with an error),
+ * or a factory `(ctx) => Server` to give every channel its own. The SDK is not imported here; any object with
+ * `connect(transport)` works.
+ *
+ * @param {{ connect(transport: object): Promise<void>, close?(): Promise<void> } | ((ctx: object) => any)} serverOrFactory
+ * @returns {(channel: import('../rpc.mjs').RpcChannel, ctx: object) => Promise<void>}
+ */
+export function mcpServerAdapter(serverOrFactory) {
+  const isFactory = typeof serverOrFactory === 'function' && typeof serverOrFactory.connect !== 'function';
+  if (!isFactory && typeof serverOrFactory?.connect !== 'function') {
+    throw new TypeError('mcpServerAdapter: expected an MCP Server (with connect(transport)) or a factory returning one');
+  }
+  let busy = false;
+  return async (channel, ctx) => {
+    if (!isFactory && busy) {
+      // The SDK's Server speaks to one transport at a time; saying so beats silently stealing the first channel.
+      throw new Error('mcp server instance is already serving another channel (pass a factory for concurrent channels)');
+    }
+    const server = isFactory ? await serverOrFactory(ctx) : serverOrFactory;
+    if (typeof server?.connect !== 'function') throw new TypeError('mcpServerAdapter: the factory must return an MCP Server');
+    const transport = new RpcMcpTransport(channel);
+    if (!isFactory) busy = true;
+    const prior = channel.onClose;
+    channel.onClose = (reason) => {
+      if (!isFactory) busy = false;
+      try { prior?.(reason); } catch { /* ignore */ }
+      if (isFactory) Promise.resolve(server.close?.()).catch(() => {});
+    };
+    try {
+      await server.connect(transport);
+    } catch (e) {
+      if (!isFactory) busy = false;
+      throw e;
+    }
+  };
+}