@johnhenry/wsh 0.19.0 → 0.20.0

package/README.md

@@ -186,7 +186,67 @@ paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
 Not implemented (each has a tracking issue): WebTransport, relay/reverse
-mode, attach/resume of server-side sessions, MCP.
+mode, attach/resume of server-side sessions.
+
+### MCP tools
+
+`createWshServer({ mcp })` answers `McpDiscover` and `McpCall`, so the stock
+`client.discoverTools()` / `client.callTool()` and `WshMcpBridge` work against
+it. Off unless you pass it.
+
+```js
+const server = createWshServer({
+  auth,
+  mcp: {
+    tools: [{
+      name: 'read_note',
+      description: 'Read a note by id',
+      inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+      call: async ({ id }, { user, signal }) => ({ success: true, output: await readNote(id, { signal }) }),
+    }],
+    authorize: (user, tool) => tool.name !== 'admin_only' || user === 'root',   // optional
+    // client: mcpSdkClient,   // optional: proxy an @modelcontextprotocol/sdk Client's tools too
+    // maxConcurrent: 8, timeoutMs: 30_000,
+  },
+});
+```
+
+- **Tool shape:** `tools` is an array of `{ name, description, inputSchema,
+  call(args, { user, fingerprint, signal }) }` or a `{ name: { ... } }` map.
+  `inputSchema` is advertised to clients as `parameters` (the `McpToolSpec`
+  field).
+- **Arguments are untrusted.** They are validated against `inputSchema` before
+  `call()` runs; invalid arguments never reach the tool. The package has no
+  runtime dependencies, so the validator covers the keywords tool schemas use
+  (`type`, `enum`, `const`, `properties`, `required`, `additionalProperties`,
+  `items`, length/range/`pattern`/`multipleOf` bounds, `allOf`/`anyOf`/`oneOf`/
+  `not`, local `$ref`); a schema using any other keyword (`if`,
+  `patternProperties`, ...) is **refused when the server is created** rather than
+  silently enforced less strictly. Only tools you list are reachable.
+- **Results:** whatever `call()` returns is `McpResult.result` verbatim (the
+  stock `WshMcpBridge` normalizes the `{ success, output, error }` shape, and
+  wraps anything else as `{ success: true, output }`). A tool that throws, an
+  unknown tool, invalid arguments, a timeout or the concurrency cap all answer
+  `{ success: false, error }` -- the error text is the thrown `message`, so
+  throw messages you are happy for the caller to read.
+- **Correlation:** every `McpResult` echoes the call's `call_id`, and the
+  server advertises `mcp-call-id` (when `mcp` is configured), so concurrent
+  calls from one client get their own results, and a slow tool does not hold up
+  the calls behind it.
+- **Limits:** `maxConcurrent` in-flight calls per connection (default 8) and a
+  `timeoutMs` per call (default 30000). On timeout or disconnect the tool's
+  `signal` aborts; a tool that ignores it keeps running but its reply is dropped.
+- **Access:** discovery and calls are answered after authentication only.
+  `authorize(user, tool, { username, fingerprint })` filters both, and a tool
+  hidden from a caller is indistinguishable from one that does not exist.
+- **Proxying:** `client` takes anything with `listTools()` / `callTool()` (an
+  `@modelcontextprotocol/sdk` `Client`; this package does not import the SDK).
+  Its tools are re-listed on every discovery, validated against their own
+  `inputSchema`s here, and `isError` results become `{ success: false, error }`,
+  else the result is `structuredContent` or the `content` array. A proxied tool
+  whose schema uses an unsupported keyword is not exposed.
+- Without `mcp`, `McpDiscover` answers an empty list and `McpCall` an
+  `{ success: false, error: 'mcp is not enabled on this server' }` result.
 
 ### Host key (fingerprint / TOFU)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",

package/src/client.mjs

@@ -1810,6 +1810,9 @@ export class WshClient {
   async fileOperation(op, path, opts = {}, timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('fileOperation');
     const channelId = this._nextChannelId();
+    // FileOp and FileResult both carry channel_id; each call claims only the
+    // result for its own id, so overlapping operations cannot swap replies (#72).
+    const byChannel = (m) => m.channel_id === channelId;
 
     if (op === 'write' || op === 'rename') {
       const feature = op === 'write' ? 'file-write' : 'file-rename';
@@ -1824,7 +1827,7 @@ export class WshClient {
       }
       // Registered before sending: the host may fail fast (read-only, too big)
       // and answer before the last chunk goes out.
-      const result = this.#waitForMessage([MSG.FILE_RESULT], timeout, `Timed out waiting for file ${op} result`);
+      const result = this.#waitForMessage([MSG.FILE_RESULT], timeout, `Timed out waiting for file ${op} result`, byChannel);
       result.catch(() => {});
       await this.#transport.sendControl(fileOpMsg({
         channelId, op, path, offset: op === 'write' ? opts.offset : undefined, length: data.byteLength,
@@ -1846,7 +1849,8 @@ export class WshClient {
     return this.#waitForMessage(
       [MSG.FILE_RESULT],
       timeout,
-      `Timed out waiting for file ${op} result`
+      `Timed out waiting for file ${op} result`,
+      byChannel
     );
   }
 

package/src/server/connection.mjs

@@ -18,12 +18,13 @@ import { QMuxConnection } from '../qmux-connection.mjs';
 import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
   MSG, serverHello, challenge, authOk, authFail, openOk, openFail, sessionData,
-  exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk,
+  exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk, mcpTools, mcpResult,
 } from '../messages.gen.mjs';
 import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
 } from '../auth.mjs';
 import { FILE_CHUNK_BYTES } from './fs.mjs';
+import { MCP_CALL_ID_FEATURE } from '../client.mjs';
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
@@ -47,6 +48,7 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {object | null} cfg.files - from createFileAccess
  * @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 {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
  * @param {number} cfg.bindTimeoutMs - how long exec output waits for the data stream
  * @param {(line: string) => void} cfg.log
@@ -59,12 +61,14 @@ export function createConnectionFactory(cfg) {
     const log = (m) => cfg.log(`[conn ${cid}] ${m}`);
     const state = {
       sessionId: randomUUID(), nonce: null, username: null, authed: false,
-      closed: false, nextChannel: 0,
+      closed: false, nextChannel: 0, fingerprint: null,
     };
     /** @type {Map<number, any>} */
     const channels = new Map();
     /** FileOp `write`/`rename`s awaiting their FileChunk frames, by client-chosen channel id. */
     const fileWrites = new Map();
+    /** AbortControllers of in-flight MCP calls: aborted on disconnect, counted for the cap. */
+    const mcpCalls = new Set();
     /** Channel ids awaiting their client-opened data stream, in OpenOk order. */
     const pendingStreams = [];
     const decoder = new FrameDecoder();
@@ -87,6 +91,8 @@ export function createConnectionFactory(cfg) {
       state.closed = true;
       for (const ch of channels.values()) ch.kill?.();
       channels.clear();
+      for (const c of mcpCalls) c.abort(new Error('connection closed'));
+      mcpCalls.clear();
       for (const w of fileWrites.values()) clearTimeout(w.timer);
       fileWrites.clear();
       try { qmux.destroy(new Error(why)); } catch { /* already gone */ }
@@ -130,6 +136,10 @@ export function createConnectionFactory(cfg) {
         case MSG.CLOSE: { const ch = channels.get(m.channel_id); if (ch) { ch.kill?.(); } return; }
         case MSG.FILE_OP: return handleFileOp(m);
         case MSG.FILE_CHUNK: return (fileWrites.has(m.channel_id) ? handleWriteChunk(m) : channels.get(m.channel_id)?.chunk?.(m));
+        case MSG.MCP_DISCOVER: return handleMcpDiscover();
+        // Not awaited: the handler chain is serial, and a slow tool must not hold up
+        // the next call (or a Close) behind it.
+        case MSG.MCP_CALL: handleMcpCall(m); return;
         default: log(`ignored message type 0x${m.type.toString(16)}`);
       }
     }
@@ -155,6 +165,7 @@ export function createConnectionFactory(cfg) {
         state.username = user;
         state.method = method;
         const features = [STREAM_ANNOUNCE];
+        if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
         if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
         let hostFingerprint;
         if (cfg.hostKey) {
@@ -199,6 +210,7 @@ export function createConnectionFactory(cfg) {
         } catch (e) { log(`authorize threw: ${e.message}`); }
         if (!allowed) return refuse('key not authorized');
         state.authed = true;
+        state.fingerprint = fp;
         state.nonce = null;
         await send(authOk({ sessionId: state.sessionId, token: randomBytes(16), ttl: 3600 }));
         log(`authenticated ${state.username} (${fp.slice(0, 12)}...)`);
@@ -228,6 +240,63 @@ export function createConnectionFactory(cfg) {
       log(`authenticated ${state.username} (password)`);
     }
 
+    // ── MCP ───────────────────────────────────────────────────────────
+
+    const principal = () => ({ username: state.username, fingerprint: state.fingerprint });
+
+    async function handleMcpDiscover() {
+      let tools = [];
+      if (cfg.mcp) {
+        try { tools = await cfg.mcp.list(state.username, principal()); } catch (e) { log(`mcp discover failed: ${e.message}`); }
+      }
+      return send(mcpTools({ tools }));
+    }
+
+    function handleMcpCall(m) {
+      const callId = typeof m.call_id === 'string' ? m.call_id : undefined;
+      const reply = (result) => {
+        try { return send(mcpResult({ result, callId })); } catch (e) {
+          log(`mcp result for ${m.tool} not encodable: ${e.message}`);
+          return send(mcpResult({ result: { success: false, error: 'tool result could not be encoded' }, callId }));
+        }
+      };
+      const fail = (error) => reply({ success: false, error });
+      if (!cfg.mcp) { fail('mcp is not enabled on this server'); return; }
+      if (mcpCalls.size >= cfg.mcp.maxConcurrent) { fail('too many concurrent MCP calls'); return; }
+
+      const abort = new AbortController();
+      mcpCalls.add(abort);
+      (async () => {
+        const name = typeof m.tool === 'string' ? m.tool : '';
+        const tool = name ? await cfg.mcp.find(name, state.username, principal()) : null;
+        if (!tool) return fail(`unknown tool: ${name || String(m.tool)}`);
+        const args = m.arguments ?? {};
+        const problem = cfg.mcp.validate(tool, args);
+        if (problem) return fail(`invalid arguments: ${problem}`);
+
+        let timer = null;
+        const aborted = new Promise((_, reject) => {
+          abort.signal.addEventListener('abort', () => reject(abort.signal.reason ?? new Error('aborted')), { once: true });
+        });
+        aborted.catch(() => {});
+        if (cfg.mcp.timeoutMs > 0) {
+          timer = setTimeout(() => abort.abort(new Error(`tool ${name} timed out after ${cfg.mcp.timeoutMs}ms`)), cfg.mcp.timeoutMs);
+        }
+        try {
+          const ctx = { user: state.username, fingerprint: state.fingerprint, signal: abort.signal };
+          const out = await Promise.race([Promise.resolve().then(() => tool.call(args, ctx)), aborted]);
+          return reply(out === undefined ? null : out);
+        } catch (e) {
+          if (!state.closed) log(`mcp tool ${name} failed: ${e?.message ?? e}`);
+          return fail(String(e?.message ?? e));
+        } finally {
+          clearTimeout(timer);
+        }
+      })()
+        .catch((e) => log(`mcp call ${m.tool}: ${e.message}`))
+        .finally(() => mcpCalls.delete(abort));
+    }
+
     // ── Open ──────────────────────────────────────────────────────────
 
     function handleOpen(m) {

package/src/server/index.d.ts

@@ -119,6 +119,45 @@ export interface WshServerFsOptions {
   maxFileBytes?: number;
 }
 
+/** Context handed to an MCP tool's `call()`. */
+export interface WshMcpCallContext {
+  /** Authenticated username. */
+  user: string;
+  /** Hex SHA-256 of the client's key (`null` for a password login). */
+  fingerprint: string | null;
+  /** Aborts on client disconnect or `timeoutMs`. A tool that ignores it keeps running but its reply is dropped. */
+  signal: AbortSignal;
+}
+
+/** One tool exposed over `McpDiscover` / `McpCall`. */
+export interface WshMcpTool {
+  name: string;
+  description?: string;
+  /** JSON Schema for the arguments (default `{ type: 'object' }`). Enforced before `call()` runs; keywords outside the supported subset are refused at startup. Advertised to clients as `parameters`. */
+  inputSchema?: Record<string, unknown> | boolean;
+  /** The result is sent as `McpResult.result` verbatim (any CBOR-encodable value). Throwing sends `{ success: false, error: message }`. */
+  call(args: any, ctx: WshMcpCallContext): unknown | Promise<unknown>;
+}
+
+/** The part of an `@modelcontextprotocol/sdk` `Client` that the server proxies. */
+export interface WshMcpClientLike {
+  listTools(): Promise<{ tools: Array<{ name: string; description?: string; inputSchema?: Record<string, unknown> }> }>;
+  callTool(params: { name: string; arguments: unknown }, resultSchema?: unknown, options?: { signal?: AbortSignal }): Promise<{ content?: unknown; structuredContent?: unknown; isError?: boolean }>;
+}
+
+export interface WshServerMcpOptions {
+  /** Tools to serve: a list, or a `{ name: { description, inputSchema, call } }` map. */
+  tools?: WshMcpTool[] | Record<string, Omit<WshMcpTool, 'name'>>;
+  /** An MCP client whose tools are proxied (local `tools` win on a name clash). */
+  client?: WshMcpClientLike;
+  /** Per-principal filter, applied to discovery and to calls alike (a hidden tool looks unknown). */
+  authorize?: (user: string, tool: { name: string; description: string; inputSchema: unknown }, who: { username: string; fingerprint: string | null }) => boolean | Promise<boolean>;
+  /** In-flight calls per connection (default 8); further calls get an error result. */
+  maxConcurrent?: number;
+  /** Per-call time limit in ms (default 30000; 0 = none). */
+  timeoutMs?: number;
+}
+
 export interface WshServerOptions {
   /** Bind address (default `127.0.0.1`). */
   host?: string;
@@ -138,6 +177,8 @@ export interface WshServerOptions {
   hostKey?: true | { file: string } | CryptoKeyPair;
   /** Enable file ops and uploads/downloads under one directory. Off by default. */
   fs?: WshServerFsOptions;
+  /** Serve MCP tools (`McpDiscover` / `McpCall`) and advertise `mcp-call-id`. Off by default. */
+  mcp?: WshServerMcpOptions;
   /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */
   bindTimeoutMs?: number;
   onLog?: (line: string) => void;

package/src/server/index.mjs

@@ -13,6 +13,7 @@ import { loadHostKey } from './host-key.mjs';
 import { spawnRunner } from './exec.mjs';
 import { normalizePty } from './pty.mjs';
 import { createFileAccess } from './fs.mjs';
+import { createMcpHost } from './mcp.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE };
@@ -26,6 +27,9 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  *   `{ cwd, env, shell, timeoutMs, clientEnv }`, or a custom `run(command, io)` function.
  * @param {{ spawn: Function, shell?: string, cwd?: string, env?: object }} [options.pty]
  * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} [options.fs]
+ * @param {{ tools?: object[] | object, client?: object, authorize?: Function, maxConcurrent?: number, timeoutMs?: number }} [options.mcp]
+ *   MCP tools served over `McpDiscover` / `McpCall`: `tools` (`{ name, description, inputSchema, call(args, { user, signal }) }`),
+ *   and/or `client` (an `@modelcontextprotocol/sdk` Client to proxy). Off unless given.
  * @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`.
  * @param {object} [options.auth.rateLimit] - Password-failure throttle: `{ maxFailures=5, windowMs=60000,
@@ -35,7 +39,7 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  * @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, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
@@ -50,6 +54,7 @@ export function createWshServer({
   }
   const ptyConfig = pty ? normalizePty(pty) : null;
   const files = fs ? createFileAccess(fs) : null;
+  const mcpHost = mcp ? createMcpHost(mcp) : null;
   const methods = authMethods(auth);
   const rl = auth?.rateLimit ?? {};
   const rateLimit = {
@@ -72,7 +77,7 @@ export function createWshServer({
       host_ = hostKey ? await loadHostKey(hostKey) : null;
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
-        methods, hostKey: host_, rateLimit,
+        methods, hostKey: host_, rateLimit, mcp: mcpHost,
       });
 
       wss = new WebSocketServer({ host, port });

package/src/server/json-schema.mjs

@@ -0,0 +1,204 @@
+/**
+ * A small JSON Schema validator for `@johnhenry/wsh/server`'s MCP tools.
+ *
+ * MCP arguments come off the wire from an authenticated-but-untrusted client,
+ * so the tool's `inputSchema` is enforced before `call()` runs. The package has
+ * no runtime dependencies, so this covers the keywords tool schemas actually
+ * use rather than all of JSON Schema: `type`, `enum`, `const`, `properties`,
+ * `required`, `additionalProperties`, `items`, `min/maxItems`, `uniqueItems`,
+ * `min/maxLength`, `pattern`, `minimum`/`maximum` (and exclusive forms),
+ * `multipleOf`, `allOf`/`anyOf`/`oneOf`/`not`, and local `$ref` (`#/...`).
+ * `format`, `title`, `description`, `default` and other annotations are ignored.
+ *
+ * A schema that uses a keyword this does not understand is refused up front
+ * (`assertSupportedSchema`) rather than silently validating less than the
+ * operator wrote.
+ */
+
+const TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'object', 'array']);
+const IGNORED = new Set([
+  '$schema', '$id', '$comment', 'title', 'description', 'default', 'examples', 'format',
+  'definitions', '$defs', 'deprecated', 'readOnly', 'writeOnly',
+]);
+const KNOWN = new Set([
+  'type', 'enum', 'const', 'properties', 'required', 'additionalProperties', 'items',
+  'minItems', 'maxItems', 'uniqueItems', 'minLength', 'maxLength', 'pattern', 'minimum',
+  'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'allOf', 'anyOf',
+  'oneOf', 'not', '$ref', 'minProperties', 'maxProperties',
+]);
+const MAX_DEPTH = 64;
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function typeOf(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
+  return typeof v;
+}
+
+function matchesType(v, t) {
+  const actual = typeOf(v);
+  return actual === t || (t === 'number' && actual === 'integer');
+}
+
+/** Structural JSON equality (for `enum` / `const` / `uniqueItems`). */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+}
+
+/**
+ * Throw if `schema` uses a keyword this validator does not implement, or is
+ * otherwise malformed. Run once when the operator's tools are configured.
+ */
+export function assertSupportedSchema(schema, path = '#', depth = 0) {
+  if (depth > MAX_DEPTH) throw new TypeError(`inputSchema at ${path} is nested too deeply`);
+  if (schema === true || schema === false) return;
+  if (!isObject(schema)) throw new TypeError(`inputSchema at ${path} must be an object`);
+  for (const key of Object.keys(schema)) {
+    if (!KNOWN.has(key) && !IGNORED.has(key)) {
+      throw new TypeError(`inputSchema at ${path} uses unsupported keyword "${key}"`);
+    }
+  }
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    for (const t of types) if (!TYPES.has(t)) throw new TypeError(`inputSchema at ${path} has unknown type ${JSON.stringify(t)}`);
+  }
+  if (schema.pattern !== undefined) {
+    try { new RegExp(schema.pattern, 'u'); } catch { throw new TypeError(`inputSchema at ${path} has an invalid pattern`); }
+  }
+  if (schema.required !== undefined && !(Array.isArray(schema.required) && schema.required.every((r) => typeof r === 'string'))) {
+    throw new TypeError(`inputSchema at ${path}: required must be an array of strings`);
+  }
+  if (isObject(schema.properties)) {
+    for (const [k, s] of Object.entries(schema.properties)) assertSupportedSchema(s, `${path}/properties/${k}`, depth + 1);
+  } else if (schema.properties !== undefined) {
+    throw new TypeError(`inputSchema at ${path}: properties must be an object`);
+  }
+  if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean') {
+    assertSupportedSchema(schema.additionalProperties, `${path}/additionalProperties`, depth + 1);
+  }
+  if (schema.items !== undefined) assertSupportedSchema(schema.items, `${path}/items`, depth + 1);
+  for (const k of ['allOf', 'anyOf', 'oneOf']) {
+    if (schema[k] === undefined) continue;
+    if (!Array.isArray(schema[k])) throw new TypeError(`inputSchema at ${path}: ${k} must be an array`);
+    schema[k].forEach((s, i) => assertSupportedSchema(s, `${path}/${k}/${i}`, depth + 1));
+  }
+  if (schema.not !== undefined) assertSupportedSchema(schema.not, `${path}/not`, depth + 1);
+  for (const k of ['definitions', '$defs']) {
+    if (isObject(schema[k])) for (const [n, s] of Object.entries(schema[k])) assertSupportedSchema(s, `${path}/${k}/${n}`, depth + 1);
+  }
+  if (schema.$ref !== undefined && !(typeof schema.$ref === 'string' && schema.$ref.startsWith('#'))) {
+    throw new TypeError(`inputSchema at ${path}: only local "#..." $ref is supported`);
+  }
+}
+
+function resolveRef(root, ref) {
+  if (ref === '#') return root;
+  if (!ref.startsWith('#/')) return undefined;
+  let node = root;
+  for (const raw of ref.slice(2).split('/')) {
+    const seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (!isObject(node) && !Array.isArray(node)) return undefined;
+    if (!Object.hasOwn(node, seg)) return undefined;
+    node = node[seg];
+  }
+  return node;
+}
+
+/**
+ * Validate `value` against `schema`.
+ * @returns {string | null} `null` when valid, otherwise a short reason naming the path.
+ */
+export function validateSchema(schema, value) {
+  const fail = (path, msg) => `${path || '/'}: ${msg}`;
+
+  function check(s, v, path, depth) {
+    if (depth > MAX_DEPTH) return fail(path, 'schema or value nested too deeply');
+    if (s === true) return null;
+    if (s === false) return fail(path, 'no value is allowed here');
+    if (s.$ref !== undefined) {
+      const target = resolveRef(schema, s.$ref);
+      if (target === undefined) return fail(path, `unresolvable $ref ${s.$ref}`);
+      const r = check(target, v, path, depth + 1);
+      if (r) return r;
+    }
+    if (s.type !== undefined) {
+      const types = Array.isArray(s.type) ? s.type : [s.type];
+      if (!types.some((t) => matchesType(v, t))) return fail(path, `expected ${types.join(' | ')}, got ${typeOf(v)}`);
+    }
+    if (s.enum !== undefined && !s.enum.some((e) => deepEqual(e, v))) return fail(path, 'not one of the allowed values');
+    if (s.const !== undefined && !deepEqual(s.const, v)) return fail(path, 'does not equal the required constant');
+
+    if (typeof v === 'string') {
+      const len = [...v].length;
+      if (s.minLength !== undefined && len < s.minLength) return fail(path, `shorter than ${s.minLength}`);
+      if (s.maxLength !== undefined && len > s.maxLength) return fail(path, `longer than ${s.maxLength}`);
+      if (s.pattern !== undefined && !new RegExp(s.pattern, 'u').test(v)) return fail(path, 'does not match the required pattern');
+    }
+    if (typeof v === 'number') {
+      if (!Number.isFinite(v)) return fail(path, 'must be a finite number');
+      if (s.minimum !== undefined && v < s.minimum) return fail(path, `below the minimum ${s.minimum}`);
+      if (s.maximum !== undefined && v > s.maximum) return fail(path, `above the maximum ${s.maximum}`);
+      if (typeof s.exclusiveMinimum === 'number' && v <= s.exclusiveMinimum) return fail(path, `must be above ${s.exclusiveMinimum}`);
+      if (typeof s.exclusiveMaximum === 'number' && v >= s.exclusiveMaximum) return fail(path, `must be below ${s.exclusiveMaximum}`);
+      if (s.multipleOf !== undefined) {
+        const q = v / s.multipleOf;
+        if (Math.abs(q - Math.round(q)) > 1e-9) return fail(path, `not a multiple of ${s.multipleOf}`);
+      }
+    }
+    if (Array.isArray(v)) {
+      if (s.minItems !== undefined && v.length < s.minItems) return fail(path, `fewer than ${s.minItems} items`);
+      if (s.maxItems !== undefined && v.length > s.maxItems) return fail(path, `more than ${s.maxItems} items`);
+      if (s.uniqueItems === true) {
+        for (let i = 0; i < v.length; i++) {
+          for (let j = i + 1; j < v.length; j++) if (deepEqual(v[i], v[j])) return fail(path, 'items are not unique');
+        }
+      }
+      if (s.items !== undefined) {
+        for (let i = 0; i < v.length; i++) {
+          const r = check(s.items, v[i], `${path}/${i}`, depth + 1);
+          if (r) return r;
+        }
+      }
+    }
+    if (isObject(v)) {
+      const keys = Object.keys(v);
+      if (s.minProperties !== undefined && keys.length < s.minProperties) return fail(path, `fewer than ${s.minProperties} properties`);
+      if (s.maxProperties !== undefined && keys.length > s.maxProperties) return fail(path, `more than ${s.maxProperties} properties`);
+      for (const r of s.required ?? []) if (!Object.hasOwn(v, r)) return fail(path, `missing required property "${r}"`);
+      const props = isObject(s.properties) ? s.properties : {};
+      for (const k of keys) {
+        if (Object.hasOwn(props, k)) {
+          const r = check(props[k], v[k], `${path}/${k}`, depth + 1);
+          if (r) return r;
+        } else if (s.additionalProperties === false) {
+          return fail(path, `unexpected property "${k}"`);
+        } else if (s.additionalProperties !== undefined && s.additionalProperties !== true) {
+          const r = check(s.additionalProperties, v[k], `${path}/${k}`, depth + 1);
+          if (r) return r;
+        }
+      }
+    }
+
+    for (const sub of s.allOf ?? []) {
+      const r = check(sub, v, path, depth + 1);
+      if (r) return r;
+    }
+    if (s.anyOf && !s.anyOf.some((sub) => check(sub, v, path, depth + 1) === null)) return fail(path, 'matches none of the anyOf alternatives');
+    if (s.oneOf) {
+      const n = s.oneOf.filter((sub) => check(sub, v, path, depth + 1) === null).length;
+      if (n !== 1) return fail(path, `matches ${n} of the oneOf alternatives, expected exactly 1`);
+    }
+    if (s.not !== undefined && check(s.not, v, path, depth + 1) === null) return fail(path, 'matches a schema it must not match');
+    return null;
+  }
+
+  return check(schema, value, '', 0);
+}

package/src/server/mcp.mjs

@@ -0,0 +1,111 @@
+/**
+ * MCP tools for `@johnhenry/wsh/server`: what `createWshServer({ mcp })`
+ * exposes through `McpDiscover` / `McpCall`.
+ *
+ * Two sources, which may be combined:
+ *  - `mcp.tools` -- an array of `{ name, description, inputSchema, call }`, or
+ *    a `{ name: { description, inputSchema, call } }` map.
+ *  - `mcp.client` -- anything shaped like an `@modelcontextprotocol/sdk`
+ *    `Client` (`listTools()` / `callTool({ name, arguments })`); its tools are
+ *    proxied. Duck-typed, so the SDK is never imported by this package.
+ *
+ * Tools the operator did not list are never reachable: a call is looked up by
+ * exact name in the set built here, after the optional `authorize` filter.
+ */
+
+import { assertSupportedSchema, validateSchema } from './json-schema.mjs';
+
+const DEFAULT_SCHEMA = Object.freeze({ type: 'object' });
+export const MCP_DEFAULTS = Object.freeze({ maxConcurrent: 8, timeoutMs: 30_000 });
+
+function normalizeTool(name, spec, origin) {
+  if (typeof name !== 'string' || !name) throw new TypeError('createWshServer: every mcp tool needs a name');
+  if (!spec || typeof spec.call !== 'function') {
+    throw new TypeError(`createWshServer: mcp tool "${name}" needs a call(args, ctx) function`);
+  }
+  const inputSchema = spec.inputSchema ?? spec.parameters ?? DEFAULT_SCHEMA;
+  assertSupportedSchema(inputSchema, `#(${name})`);
+  return { name, description: String(spec.description ?? ''), inputSchema, call: spec.call, origin };
+}
+
+/**
+ * @param {object} mcp - the `createWshServer` `mcp` option
+ * @returns {{ list(user: string, who: object): Promise<object[]>, find(name: string, user: string, who: object): Promise<object | null>, maxConcurrent: number, timeoutMs: number }}
+ */
+export function createMcpHost(mcp) {
+  if (!mcp || typeof mcp !== 'object') throw new TypeError('createWshServer: mcp must be an object');
+  const local = new Map();
+  const entries = Array.isArray(mcp.tools)
+    ? mcp.tools.map((t) => [t?.name, t])
+    : Object.entries(mcp.tools ?? {});
+  for (const [name, spec] of entries) {
+    if (local.has(name)) throw new TypeError(`createWshServer: duplicate mcp tool "${name}"`);
+    local.set(name, normalizeTool(name, spec, 'local'));
+  }
+  const client = mcp.client ?? null;
+  if (client && (typeof client.listTools !== 'function' || typeof client.callTool !== 'function')) {
+    throw new TypeError('createWshServer: mcp.client needs listTools() and callTool() (an @modelcontextprotocol/sdk Client)');
+  }
+  if (typeof mcp.authorize !== 'undefined' && typeof mcp.authorize !== 'function') {
+    throw new TypeError('createWshServer: mcp.authorize must be a function');
+  }
+
+  /** Remote tools, refreshed on every discover; calls use the most recent listing. */
+  let proxied = new Map();
+  async function refreshProxied() {
+    if (!client) return;
+    const next = new Map();
+    const { tools = [] } = await client.listTools();
+    for (const t of tools) {
+      if (!t || typeof t.name !== 'string' || local.has(t.name)) continue; // local tools win
+      try {
+        next.set(t.name, normalizeTool(t.name, {
+          description: t.description,
+          inputSchema: t.inputSchema,
+          call: (args, ctx) => callProxied(t.name, args, ctx),
+        }, 'proxy'));
+      } catch { /* a schema we cannot enforce is not exposed */ }
+    }
+    proxied = next;
+  }
+
+  async function callProxied(name, args, { signal }) {
+    const res = await client.callTool({ name, arguments: args }, undefined, { signal });
+    if (res?.isError) {
+      const text = Array.isArray(res.content) ? res.content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n') : '';
+      throw new Error(text || `tool ${name} failed`);
+    }
+    return res?.structuredContent ?? res?.content ?? null;
+  }
+
+  const allowed = async (tool, user, who) => {
+    if (!mcp.authorize) return true;
+    try { return (await mcp.authorize(user, { name: tool.name, description: tool.description, inputSchema: tool.inputSchema }, who)) === true; } catch { return false; }
+  };
+
+  return {
+    maxConcurrent: mcp.maxConcurrent > 0 ? mcp.maxConcurrent : MCP_DEFAULTS.maxConcurrent,
+    timeoutMs: mcp.timeoutMs >= 0 ? mcp.timeoutMs : MCP_DEFAULTS.timeoutMs,
+
+    async list(user, who) {
+      await refreshProxied();
+      const out = [];
+      for (const t of [...local.values(), ...proxied.values()]) {
+        if (await allowed(t, user, who)) out.push({ name: t.name, description: t.description, parameters: t.inputSchema });
+      }
+      return out;
+    },
+
+    /** A tool this principal may call, or `null` -- indistinguishable for hidden and absent. */
+    async find(name, user, who) {
+      let tool = local.get(name) ?? proxied.get(name);
+      if (!tool && client && !local.has(name)) {
+        await refreshProxied();
+        tool = proxied.get(name);
+      }
+      return tool && await allowed(tool, user, who) ? tool : null;
+    },
+
+    validate: (tool, args) => validateSchema(tool.inputSchema, args),
+  };
+}