@warlock.js/ai-tools 5.30.0 → 5.31.0

package/cjs/index.cjs

@@ -2,6 +2,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let _warlock_js_ai = require("@warlock.js/ai");
 let node_child_process = require("node:child_process");
 let node_readline = require("node:readline");
+let node_crypto = require("node:crypto");
+let node_http = require("node:http");
+let node_net = require("node:net");
 
 //#region ../../packages/ai-tools/src/errors.ts
 /**
@@ -80,6 +83,25 @@ var McpTransportError = class extends _warlock_js_ai.AIError {
 	}
 };
 /**
+* `ai.mcp.serve` could not build or start the server. Thrown by `serve()`
+* itself for an invalid source or a name collision, and by `start()` for
+* transport configuration and bind failures — never for a single bad request, which gets an HTTP / JSON-RPC
+* error response instead. Extends {@link AIError} (code `TOOL_EXEC_FAILED`);
+* branch on `error.type`.
+*
+* @example
+* if (error instanceof McpServeError && error.type === "collision") {
+*   // two tools share a name — rename one or use a grouped source + prefixToolNames
+* }
+*/
+var McpServeError = class extends _warlock_js_ai.AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "McpServeError";
+		this.type = options.type;
+	}
+};
+/**
 * A web tool failed — a missing optional peer, an absent API key, a host
 * rejected by the `allowHosts` guardrail, an unparseable URL, or a failed
 * network call.
@@ -355,7 +377,7 @@ async function readCappedBody(response, maxBytes) {
 * `application/json` and the `+json` structured-suffix convention
 * (e.g. `application/vnd.api+json`), case-insensitively.
 */
-function isJsonContentType(contentType) {
+function isJsonContentType$1(contentType) {
 	if (!contentType) return false;
 	const value = contentType.toLowerCase();
 	return value.includes("application/json") || value.includes("+json");
@@ -471,7 +493,7 @@ function httpRequestTool(options = {}) {
 			});
 			const { text, truncated } = await readCappedBody(response, maxBytes);
 			let parsedBody = text;
-			if (!truncated && isJsonContentType(responseHeaders["content-type"]) && text.length > 0) try {
+			if (!truncated && isJsonContentType$1(responseHeaders["content-type"]) && text.length > 0) try {
 				parsedBody = JSON.parse(text);
 			} catch {
 				parsedBody = text;
@@ -1046,7 +1068,7 @@ function withIdAllocator(client) {
 /** Default per-call timeout for `tools/call`. */
 const DEFAULT_CALL_TIMEOUT_MS = 3e4;
 /** The MCP protocol version this client advertises in `initialize`. */
-const PROTOCOL_VERSION$1 = "2025-06-18";
+const PROTOCOL_VERSION = "2025-06-18";
 /**
 * The internal {@link McpClient} implementation. Owns one JSON-RPC client
 * over a transport, runs the `initialize` handshake on first use, lists
@@ -1059,8 +1081,24 @@ const PROTOCOL_VERSION$1 = "2025-06-18";
 var McpClientImpl = class {
 	constructor(source, options = {}) {
 		this.initialized = false;
+		this.onAbort = () => {
+			this.close().catch(() => void 0);
+		};
 		this.rpc = createJsonRpcClient(source);
 		this.options = options;
+		const signal = options.signal;
+		if (signal?.aborted) this.onAbort();
+		else signal?.addEventListener("abort", this.onAbort, { once: true });
+	}
+	/**
+	* Reject with a typed `"closed"` error once the client was closed or its
+	* `signal` aborted, so no request is sent on a dead transport.
+	*/
+	assertOpen(method) {
+		if (this.closing || this.options.signal?.aborted) throw new McpTransportError(`MCP client is closed; "${method}" was not sent.`, {
+			type: "closed",
+			method
+		});
 	}
 	/**
 	* Run the MCP `initialize` handshake exactly once, then send the
@@ -1070,15 +1108,16 @@ var McpClientImpl = class {
 	*/
 	async handshake() {
 		if (this.initialized) return;
+		this.assertOpen("initialize");
 		try {
 			await this.rpc.call("initialize", {
-				protocolVersion: PROTOCOL_VERSION$1,
+				protocolVersion: PROTOCOL_VERSION,
 				capabilities: {},
 				clientInfo: {
 					name: "@warlock.js/ai-tools",
 					version: "4.4.0"
 				}
-			});
+			}, { signal: this.options.signal });
 			await this.rpc.notify("notifications/initialized");
 		} catch (cause) {
 			if (cause instanceof McpTransportError) throw cause;
@@ -1107,7 +1146,8 @@ var McpClientImpl = class {
 	*/
 	async listAndAdapt() {
 		await this.handshake();
-		const descriptors = (await this.rpc.call("tools/list")).tools ?? [];
+		this.assertOpen("tools/list");
+		const descriptors = (await this.rpc.call("tools/list", void 0, { signal: this.options.signal })).tools ?? [];
 		const filter = this.options.filter;
 		return (filter ? descriptors.filter((d) => filter(d.name)) : descriptors).map((descriptor) => this.adapt(descriptor));
 	}
@@ -1128,11 +1168,12 @@ var McpClientImpl = class {
 			description: descriptor.description ?? `Invoke the remote MCP tool "${remoteName}".`,
 			input,
 			execute: async (args, ctx) => {
+				this.assertOpen("tools/call");
 				const result = await this.rpc.call("tools/call", {
 					name: remoteName,
 					arguments: args ?? {}
 				}, {
-					signal: ctx?.signal,
+					signal: combineSignals(ctx?.signal, this.options.signal),
 					timeoutMs
 				});
 				if (result.isError) throw new McpTransportError(`MCP tool "${remoteName}" returned an error: ${unwrapContent(result.content)}`, {
@@ -1144,10 +1185,20 @@ var McpClientImpl = class {
 		});
 	}
 	close() {
-		return this.rpc.close();
+		this.options.signal?.removeEventListener("abort", this.onAbort);
+		this.closing ??= this.rpc.close();
+		return this.closing;
 	}
 };
 /**
+* The signal a `tools/call` honors: the per-call `ctx.signal`, the
+* client-level `options.signal`, both (whichever aborts first), or none.
+*/
+function combineSignals(callSignal, clientSignal) {
+	if (!callSignal || !clientSignal) return callSignal ?? clientSignal;
+	return AbortSignal.any([callSignal, clientSignal]);
+}
+/**
 * Flatten an MCP `tools/call` result's content blocks into the value a
 * tool returns. Text blocks are concatenated; a single block whose text is
 * valid JSON is parsed so structured tool output flows back as an object
@@ -1219,7 +1270,8 @@ function tryParseJson(text) {
 * @param server - The transport config (`{ type: "stdio" }` /
 *   `{ type: "http" }`). A pre-built transport client may be injected for
 *   testing.
-* @param options - Prefix / filter / per-call timeout.
+* @param options - Prefix / filter / per-call timeout, and a `signal` that
+*   closes the client when it aborts.
 * @returns An {@link McpClient} handle.
 *
 * @example
@@ -1233,6 +1285,462 @@ function mcp$1(server, options) {
 	return new McpClientImpl(server, options);
 }
 
+//#endregion
+//#region ../../packages/ai-tools/src/mcp/protocol.ts
+/**
+* MCP protocol versions the `ai.mcp.serve` server speaks, newest first.
+* `initialize` echoes the client's requested version when it is listed
+* here and otherwise answers with the newest one (lifecycle, version
+* negotiation). The HTTP transport rejects any other value in the
+* `MCP-Protocol-Version` header with 400.
+*
+* Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+* and https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+* (checked 2026-10-17).
+*/
+const SUPPORTED_PROTOCOL_VERSIONS = [
+	"2025-11-25",
+	"2025-06-18",
+	"2025-03-26"
+];
+/** The newest MCP protocol version the server speaks. */
+const LATEST_PROTOCOL_VERSION = "2025-11-25";
+
+//#endregion
+//#region ../../packages/ai-tools/src/mcp/serve-http.ts
+/**
+* MCP Streamable HTTP server transport for `ai.mcp.serve`.
+*
+* Implements the server side of the Streamable HTTP transport from the MCP
+* specification (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports,
+* checked 2026-10-17) on `node:http`, with no SDK dependency:
+*
+* - one endpoint path; each POST carries exactly one JSON-RPC message
+*   (batches were removed from the protocol in 2025-06-18 and get 400);
+* - a request is answered with `Content-Type: application/json` (the spec
+*   lets a server pick JSON or SSE per request); a notification or a
+*   response is acknowledged with `202 Accepted` and no body;
+* - stateless: no `MCP-Session-Id` is issued (optional in the spec), so
+*   GET (server-initiated SSE stream) and DELETE (session end) answer
+*   `405 Method Not Allowed`, as the spec allows;
+* - an unsupported `MCP-Protocol-Version` header gets 400;
+* - security warning items: `Origin` is validated on every request (an
+*   invalid one gets 403), the default bind is `127.0.0.1`, and
+*   authentication is required for any non-loopback bind.
+*/
+/** Default bind interface — loopback only. */
+const DEFAULT_HOST = "127.0.0.1";
+/** Default endpoint path. */
+const DEFAULT_PATH = "/mcp";
+/** Default request body cap: 1 MiB. */
+const DEFAULT_MAX_BODY_BYTES = 1048576;
+/** Default time `close()` waits for in-flight requests. */
+const DEFAULT_DRAIN_TIMEOUT_MS = 5e3;
+/** JSON-RPC codes used for transport-level error bodies. */
+const JSON_RPC_PARSE_ERROR = -32700;
+const JSON_RPC_INVALID_REQUEST$1 = -32600;
+/** Generic server-defined JSON-RPC code for HTTP-level refusals (auth, origin, size). */
+const JSON_RPC_SERVER_ERROR = -32e3;
+/** Host names that always mean "this machine". */
+const LOOPBACK_NAMES = new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]"
+]);
+/**
+* True when `host` names a loopback interface (`localhost`, `127.0.0.0/8`,
+* `::1`, or an IPv4-mapped `::ffff:127.x.x.x`).
+*/
+function isLoopbackHost(host) {
+	const normalized = host.trim().toLowerCase();
+	if (LOOPBACK_NAMES.has(normalized)) return true;
+	const unbracketed = normalized.replace(/^\[|\]$/g, "");
+	const mapped = unbracketed.startsWith("::ffff:") ? unbracketed.slice(7) : unbracketed;
+	return (0, node_net.isIPv4)(mapped) && mapped.startsWith("127.");
+}
+/** Strip the port from a `Host` header value (`[::1]:3000` → `[::1]`, `a.b:80` → `a.b`). */
+function hostnameOf(hostHeader) {
+	const value = hostHeader.trim().toLowerCase();
+	if (value.startsWith("[")) {
+		const end = value.indexOf("]");
+		return end === -1 ? value : value.slice(0, end + 1);
+	}
+	const colon = value.lastIndexOf(":");
+	return colon === -1 ? value : value.slice(0, colon);
+}
+/** SHA-256 digest — equal-length input for `timingSafeEqual`. */
+function digest(value) {
+	return (0, node_crypto.createHash)("sha256").update(value, "utf8").digest();
+}
+/** Normalise a configured origin to `scheme://host[:port]`, or throw a config error. */
+function normalizeOrigin(origin) {
+	try {
+		return new URL(origin).origin;
+	} catch (cause) {
+		throw new McpServeError(`allowedOrigins entry "${origin}" is not a valid origin URL.`, {
+			type: "config",
+			cause
+		});
+	}
+}
+/**
+* Validate and default the transport options. Throws {@link McpServeError}
+* (`"config"`) for a non-loopback bind without auth, an empty bearer
+* token, an `auth` with neither check, a bad path / port / limit.
+*/
+function resolveSettings(transport) {
+	const host = transport.host ?? DEFAULT_HOST;
+	const port = transport.port ?? 0;
+	const path = transport.path ?? DEFAULT_PATH;
+	const loopback = isLoopbackHost(host);
+	const auth = transport.auth;
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new McpServeError(`MCP http port must be an integer in 0–65535 (got ${port}).`, { type: "config" });
+	if (!path.startsWith("/")) throw new McpServeError(`MCP http path must start with "/" (got "${path}").`, { type: "config" });
+	const maxBodyBytes = transport.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+	if (!Number.isInteger(maxBodyBytes) || maxBodyBytes <= 0) throw new McpServeError("MCP http maxBodyBytes must be a positive integer.", { type: "config" });
+	const drainTimeoutMs = transport.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+	if (!Number.isFinite(drainTimeoutMs) || drainTimeoutMs < 0) throw new McpServeError("MCP http drainTimeoutMs must be zero or a positive number.", { type: "config" });
+	const tokens = auth?.bearer === void 0 ? [] : typeof auth.bearer === "string" ? [auth.bearer] : [...auth.bearer];
+	if (tokens.some((token) => token.length === 0)) throw new McpServeError("MCP http auth.bearer tokens must be non-empty strings.", { type: "config" });
+	if (auth && auth.bearer !== void 0 && tokens.length === 0) throw new McpServeError("MCP http auth.bearer needs at least one token.", { type: "config" });
+	if (auth && tokens.length === 0 && !auth.authorize) throw new McpServeError("MCP http auth needs `bearer` and/or `authorize`.", { type: "config" });
+	const authRequired = tokens.length > 0 || auth?.authorize !== void 0;
+	if (!loopback && !authRequired) throw new McpServeError(`Refusing to serve MCP over http on non-loopback host "${host}" without auth. Set transport.auth ({ bearer } or { authorize }), or bind 127.0.0.1.`, {
+		type: "config",
+		context: { host }
+	});
+	return {
+		host,
+		port,
+		path,
+		loopback,
+		maxBodyBytes,
+		drainTimeoutMs,
+		tokenDigests: tokens.map(digest),
+		authorize: auth?.authorize,
+		authRequired,
+		allowedOrigins: new Set((transport.allowedOrigins ?? []).map(normalizeOrigin)),
+		allowedHosts: new Set((transport.allowedHosts ?? []).map((name) => hostnameOf(name)))
+	};
+}
+/** Flatten Node's header bag into lower-cased `name → value` strings. */
+function flattenHeaders(headers) {
+	const flat = {};
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === void 0) continue;
+		flat[name.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+	}
+	return flat;
+}
+/** Write a JSON body with a status code. */
+function sendJson(response, status, body, headers = {}) {
+	if (response.headersSent || response.destroyed) return;
+	const payload = JSON.stringify(body);
+	response.writeHead(status, {
+		...headers,
+		"content-type": "application/json",
+		"content-length": Buffer.byteLength(payload).toString()
+	});
+	response.end(payload);
+}
+/**
+* Write an HTTP-level refusal: the status plus a JSON-RPC error body with
+* no request id (the spec allows such a body on 4xx transport errors).
+*/
+function sendRefusal(response, status, code, message, headers = {}) {
+	sendJson(response, status, {
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code,
+			message
+		}
+	}, headers);
+}
+/** Write an empty-bodied status (202 / 405). */
+function sendEmpty(response, status, headers = {}) {
+	if (response.headersSent || response.destroyed) return;
+	response.writeHead(status, headers);
+	response.end();
+}
+/**
+* Bind an MCP Streamable HTTP endpoint and pump each JSON-RPC request
+* through `dispatch`. Resolves once the port is bound.
+*
+* Throws {@link McpServeError}: `"config"` for invalid / unsafe options
+* (checked before anything binds), `"listen"` when binding fails.
+*
+* @param transport - The http transport options.
+* @param dispatch - Maps one JSON-RPC request (plus call context) to its response.
+*/
+async function startHttpServer(transport, dispatch) {
+	const settings = resolveSettings(transport);
+	const shutdown = new AbortController();
+	const inFlight = /* @__PURE__ */ new Set();
+	let closing;
+	const server = (0, node_http.createServer)((request, response) => {
+		if (closing) {
+			sendRefusal(response, 503, JSON_RPC_SERVER_ERROR, "Server is shutting down.", { connection: "close" });
+			return;
+		}
+		const work = handleRequest(request, response, settings, dispatch, shutdown.signal).catch(() => {
+			sendRefusal(response, 500, JSON_RPC_SERVER_ERROR, "Internal server error.");
+		});
+		inFlight.add(work);
+		work.finally(() => {
+			inFlight.delete(work);
+			if (closing) server.closeIdleConnections();
+		});
+	});
+	await new Promise((resolve, reject) => {
+		const onError = (cause) => {
+			reject(new McpServeError(`MCP http server could not listen on ${settings.host}:${settings.port}: ${cause.message}`, {
+				type: "listen",
+				cause,
+				context: {
+					host: settings.host,
+					port: settings.port
+				}
+			}));
+		};
+		server.once("error", onError);
+		server.listen(settings.port, settings.host, () => {
+			server.off("error", onError);
+			resolve();
+		});
+	});
+	const address = server.address();
+	const boundPort = typeof address === "object" && address !== null ? address.port : settings.port;
+	const url = `http://${(0, node_net.isIPv6)(settings.host) ? `[${settings.host}]` : settings.host}:${boundPort}${settings.path}`;
+	const close = () => {
+		if (closing) return closing;
+		closing = (async () => {
+			const closed = new Promise((resolve) => {
+				server.close(() => resolve());
+			});
+			server.closeIdleConnections();
+			if (inFlight.size > 0) {
+				let timer;
+				const timedOut = new Promise((resolve) => {
+					timer = setTimeout(() => resolve("timeout"), settings.drainTimeoutMs);
+				});
+				const outcome = await Promise.race([Promise.allSettled([...inFlight]).then(() => "drained"), timedOut]);
+				clearTimeout(timer);
+				if (outcome === "timeout") {
+					shutdown.abort();
+					server.closeAllConnections();
+				}
+			}
+			server.closeIdleConnections();
+			await closed;
+		})();
+		return closing;
+	};
+	return {
+		url,
+		close
+	};
+}
+/**
+* Validate and answer one HTTP request: path → Host / Origin → auth →
+* method → headers → body → JSON-RPC dispatch.
+*/
+async function handleRequest(request, response, settings, dispatch, signal) {
+	const headers = flattenHeaders(request.headers);
+	const method = (request.method ?? "GET").toUpperCase();
+	const path = new URL(request.url ?? "/", "http://localhost").pathname;
+	if (!hostAllowed(headers.host, settings)) {
+		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Host header not allowed.");
+		return;
+	}
+	if (!originAllowed(headers.origin, settings)) {
+		sendRefusal(response, 403, JSON_RPC_SERVER_ERROR, "Forbidden: Origin not allowed.");
+		return;
+	}
+	if (path !== settings.path) {
+		sendRefusal(response, 404, JSON_RPC_SERVER_ERROR, "Not found.");
+		return;
+	}
+	const info = {
+		method,
+		path,
+		headers
+	};
+	if (request.socket.remoteAddress !== void 0) info.remoteAddress = request.socket.remoteAddress;
+	if (!await authorized(info, settings)) {
+		sendRefusal(response, 401, JSON_RPC_SERVER_ERROR, "Unauthorized.", settings.tokenDigests.length > 0 ? { "www-authenticate": "Bearer realm=\"mcp\"" } : {});
+		return;
+	}
+	if (method !== "POST") {
+		sendEmpty(response, 405, { allow: "POST" });
+		return;
+	}
+	const protocolVersion = headers["mcp-protocol-version"];
+	if (protocolVersion !== void 0 && !SUPPORTED_PROTOCOL_VERSIONS.includes(protocolVersion)) {
+		sendRefusal(response, 400, JSON_RPC_SERVER_ERROR, `Unsupported MCP-Protocol-Version "${protocolVersion}" (supported: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}).`);
+		return;
+	}
+	if (!isJsonContentType(headers["content-type"])) {
+		sendRefusal(response, 415, JSON_RPC_SERVER_ERROR, "Content-Type must be application/json.");
+		return;
+	}
+	if (!acceptsJson(headers.accept)) {
+		sendRefusal(response, 406, JSON_RPC_SERVER_ERROR, "Accept must allow application/json.");
+		return;
+	}
+	const body = await readBody$1(request, settings.maxBodyBytes);
+	if (body.type === "too-large") {
+		sendRefusal(response, 413, JSON_RPC_SERVER_ERROR, `Request body exceeds ${settings.maxBodyBytes} bytes.`, { connection: "close" });
+		return;
+	}
+	let message;
+	try {
+		message = JSON.parse(body.text);
+	} catch {
+		sendRefusal(response, 400, JSON_RPC_PARSE_ERROR, "Parse error: body is not valid JSON.");
+		return;
+	}
+	if (typeof message !== "object" || message === null || Array.isArray(message)) {
+		sendRefusal(response, 400, JSON_RPC_INVALID_REQUEST$1, "Invalid request: the body must be one JSON-RPC message (batches are not supported).");
+		return;
+	}
+	const record = message;
+	if (record.jsonrpc !== "2.0") {
+		sendRefusal(response, 400, JSON_RPC_INVALID_REQUEST$1, "Invalid request: jsonrpc must be \"2.0\".");
+		return;
+	}
+	const id = record.id;
+	if (typeof record.method === "string") {
+		if (typeof id !== "string" && typeof id !== "number") {
+			sendEmpty(response, 202);
+			return;
+		}
+		const rpcRequest = {
+			jsonrpc: "2.0",
+			id,
+			method: record.method
+		};
+		if (record.params !== void 0) rpcRequest.params = record.params;
+		sendJson(response, 200, await dispatch(rpcRequest, {
+			request: info,
+			signal
+		}));
+		return;
+	}
+	if ((typeof id === "string" || typeof id === "number") && ("result" in record || "error" in record)) {
+		sendEmpty(response, 202);
+		return;
+	}
+	sendRefusal(response, 400, JSON_RPC_INVALID_REQUEST$1, "Invalid request: not a JSON-RPC message.");
+}
+/**
+* Host-header check. While bound to loopback only loopback names (plus
+* `allowedHosts`) are accepted, so a DNS-rebound name pointing at
+* 127.0.0.1 is refused. Off loopback the check applies only when
+* `allowedHosts` is set.
+*/
+function hostAllowed(hostHeader, settings) {
+	if (!settings.loopback && settings.allowedHosts.size === 0) return true;
+	if (hostHeader === void 0) return false;
+	const name = hostnameOf(hostHeader);
+	if (settings.allowedHosts.has(name)) return true;
+	return settings.loopback && isLoopbackHost(name);
+}
+/**
+* Origin check (MCP Streamable HTTP security warning). No `Origin` header —
+* a non-browser client — passes; otherwise the origin must be a loopback
+* `http(s)` origin or listed in `allowedOrigins`. `null` and unparsable
+* origins are refused.
+*/
+function originAllowed(origin, settings) {
+	if (origin === void 0) return true;
+	let parsed;
+	try {
+		parsed = new URL(origin);
+	} catch {
+		return false;
+	}
+	if (settings.allowedOrigins.has(parsed.origin)) return true;
+	return (parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopbackHost(parsed.hostname);
+}
+/**
+* Run the configured auth. Bearer tokens are compared in constant time
+* over SHA-256 digests (equal-length buffers for `timingSafeEqual`), and
+* every configured token is compared so the match position does not leak.
+* An `authorize` hook that throws denies the request.
+*/
+async function authorized(info, settings) {
+	if (!settings.authRequired) return true;
+	if (settings.tokenDigests.length > 0) {
+		const match = /^Bearer[ \t]+(.+)$/i.exec(info.headers.authorization ?? "");
+		const presented = digest(match?.[1]?.trim() ?? "");
+		let matched = false;
+		for (const expected of settings.tokenDigests) matched = (0, node_crypto.timingSafeEqual)(presented, expected) || matched;
+		if (!match || !matched) return false;
+	}
+	if (settings.authorize) try {
+		return await settings.authorize(info) === true;
+	} catch {
+		return false;
+	}
+	return true;
+}
+/** True for `application/json` (any parameters, e.g. `; charset=utf-8`). */
+function isJsonContentType(contentType) {
+	return contentType?.split(";")[0]?.trim().toLowerCase() === "application/json";
+}
+/**
+* True when the `Accept` header allows a JSON reply. Clients are required
+* to list both `application/json` and `text/event-stream`; this server
+* always answers JSON, so it only insists on that half. A missing header
+* is accepted.
+*/
+function acceptsJson(accept) {
+	if (accept === void 0 || accept.trim() === "") return true;
+	return accept.split(",").map((part) => part.split(";")[0]?.trim().toLowerCase()).some((type) => type === "application/json" || type === "application/*" || type === "*/*");
+}
+/**
+* Read the request body as UTF-8, refusing anything over `limit` bytes —
+* up front from `Content-Length`, and while streaming for chunked bodies.
+* A refused body is left unread; the 413 response closes the connection.
+*/
+function readBody$1(request, limit) {
+	const declared = Number(request.headers["content-length"]);
+	if (Number.isFinite(declared) && declared > limit) return Promise.resolve({ type: "too-large" });
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		let done = false;
+		const finish = (result) => {
+			if (!done) {
+				done = true;
+				resolve(result);
+			}
+		};
+		request.on("data", (chunk) => {
+			if (done) return;
+			size += chunk.length;
+			if (size > limit) {
+				request.pause();
+				finish({ type: "too-large" });
+				return;
+			}
+			chunks.push(chunk);
+		});
+		request.on("end", () => finish({
+			type: "ok",
+			text: Buffer.concat(chunks).toString("utf8")
+		}));
+		request.on("error", (error) => {
+			if (!done) {
+				done = true;
+				reject(error);
+			}
+		});
+	});
+}
+
 //#endregion
 //#region ../../packages/ai-tools/src/mcp/serve.ts
 /** JSON-RPC version literal every outbound message carries. */
@@ -1241,59 +1749,159 @@ const JSONRPC_VERSION = "2.0";
 const DEFAULT_SCHEMA_TARGET = "draft-2020-12";
 /** Default advertised server version when the caller omits one. */
 const DEFAULT_VERSION = "4.4.0";
-/** The MCP protocol version this server advertises in `initialize`. */
-const PROTOCOL_VERSION = "2025-06-18";
 /** JSON-RPC standard error codes we emit. */
 const JSON_RPC_METHOD_NOT_FOUND = -32601;
 const JSON_RPC_INVALID_PARAMS = -32602;
+/** MCP's "resource not found" error code (server/resources, error handling). */
+const MCP_RESOURCE_NOT_FOUND = -32002;
 /**
-* Resolve the {@link McpServeSource} (either an object exposing `tools()`
-* or a literal `ToolContract[]`) into a flat contract array.
+* A JSON-RPC failure raised inside a method handler, carrying the exact
+* code to answer with (unknown resource, missing prompt argument, …).
 */
-function resolveTools(source) {
-	if (Array.isArray(source)) return source;
-	return source.tools();
+var RpcFailure = class extends Error {
+	constructor(code, message, data) {
+		super(message);
+		this.code = code;
+		this.data = data;
+	}
+};
+/** Enumerate one tool set into a flat contract array. */
+function toolsOf(source) {
+	return Array.isArray(source) ? source : source.tools();
+}
+/** Narrow a serve source to its grouped shape. */
+function isGroupedSource(source) {
+	return !Array.isArray(source) && "groups" in source;
+}
+/**
+* Resolve the serve source into the exposed tool list, applying
+* `prefixToolNames` and refusing duplicate names. Throws
+* {@link McpServeError} — `"config"` for `prefixToolNames` on an ungrouped
+* source, `"collision"` when two tools would share a name.
+*/
+function resolveTools(source, options) {
+	const prefix = options.prefixToolNames ?? false;
+	const exposed = [];
+	if (isGroupedSource(source)) for (const [group, groupSource] of Object.entries(source.groups)) for (const contract of toolsOf(groupSource)) {
+		let name = contract.name;
+		if (prefix === true) name = `${group}_${contract.name}`;
+		else if (typeof prefix === "function") name = prefix(group, contract.name);
+		exposed.push({
+			name,
+			contract,
+			origin: `group "${group}"`
+		});
+	}
+	else {
+		if (prefix !== false) throw new McpServeError("prefixToolNames needs a grouped source: serve({ groups: { name: tools } }, …).", { type: "config" });
+		for (const contract of toolsOf(source)) exposed.push({
+			name: contract.name,
+			contract,
+			origin: "the source"
+		});
+	}
+	const seen = /* @__PURE__ */ new Map();
+	for (const tool of exposed) {
+		const previous = seen.get(tool.name);
+		if (previous !== void 0) throw new McpServeError(`MCP tool name "${tool.name}" is exposed twice (from ${previous} and ${tool.origin}). Rename one tool, or serve a grouped source with prefixToolNames.`, {
+			type: "collision",
+			context: { name: tool.name }
+		});
+		seen.set(tool.name, tool.origin);
+	}
+	return exposed.map(({ name, contract }) => ({
+		name,
+		contract
+	}));
+}
+/** Throw a collision error when two entries share the same key. */
+function assertUnique(entries, key, label) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of entries ?? []) {
+		const value = key(entry);
+		if (seen.has(value)) throw new McpServeError(`MCP ${label} "${value}" is declared twice.`, {
+			type: "collision",
+			context: { [label]: value }
+		});
+		seen.add(value);
+	}
 }
 /**
 * The pure protocol core of `serve` — maps one JSON-RPC request to its
-* response, with no I/O. Both the stdio and http serve-transports pump
+* response, with no I/O. Both the stdio and HTTP serve-transports pump
 * their inbound requests through this, and specs can drive it directly.
 *
-* Handles exactly the MCP slice this package serves: `initialize`,
-* `tools/list`, and `tools/call`. Any other method answers with a
-* JSON-RPC `method not found` error.
+* Handles `initialize`, `ping`, `tools/list`, `tools/call`, and — when
+* configured — `resources/list`, `resources/templates/list`,
+* `resources/read`, `prompts/list` and `prompts/get`. Any other method
+* answers with a JSON-RPC `method not found` error.
 *
 * Constructed via {@link createServeHandler}.
 */
 var McpServeHandler = class {
 	constructor(source, options) {
-		this.tools = resolveTools(source);
-		this.byName = new Map(this.tools.map((contract) => [contract.name, contract]));
+		this.tools = resolveTools(source, options);
+		this.byName = new Map(this.tools.map((tool) => [tool.name, tool.contract]));
+		assertUnique(options.resources, (resource) => resource.uri, "resource");
+		assertUnique(options.prompts, (prompt) => prompt.name, "prompt");
+		this.resources = options.resources ? new Map(options.resources.map((resource) => [resource.uri, resource])) : void 0;
+		this.prompts = options.prompts ? new Map(options.prompts.map((prompt) => [prompt.name, prompt])) : void 0;
 		this.options = options;
 	}
 	/**
 	* Dispatch one inbound JSON-RPC request to its handler and produce the
 	* response. A handler that throws is mapped to a JSON-RPC error response
 	* — the serve loop never crashes on a bad request.
+	*
+	* @param request - The JSON-RPC request.
+	* @param context - Per-call context: the inbound HTTP request (headers
+	*   reach tools as `ctx.request`) and an abort signal.
 	*/
-	async handle(request) {
+	async handle(request, context = {}) {
 		try {
-			switch (request.method) {
-				case "initialize": return this.ok(request.id, this.initializeResult());
-				case "tools/list": return this.ok(request.id, { tools: this.listTools() });
-				case "tools/call": return this.ok(request.id, await this.callTool(request.params));
-				default: return this.error(request.id, JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
-			}
+			return this.ok(request.id, await this.dispatch(request, context));
 		} catch (cause) {
+			if (cause instanceof RpcFailure) return this.error(request.id, cause.code, cause.message, cause.data);
 			const message = cause instanceof Error ? cause.message : String(cause);
 			return this.error(request.id, JSON_RPC_INVALID_PARAMS, message);
 		}
 	}
-	/** Build the `initialize` result advertising name / version / capabilities. */
-	initializeResult() {
+	/** Route a method to its result builder. */
+	async dispatch(request, context) {
+		switch (request.method) {
+			case "initialize": return this.initializeResult(request.params);
+			case "ping": return {};
+			case "tools/list": return { tools: this.listTools() };
+			case "tools/call": return this.callTool(request.params, context);
+			default: break;
+		}
+		if (this.resources) switch (request.method) {
+			case "resources/list": return { resources: this.listResources(this.resources) };
+			case "resources/templates/list": return { resourceTemplates: [] };
+			case "resources/read": return this.readResource(this.resources, request.params, context);
+			default: break;
+		}
+		if (this.prompts) switch (request.method) {
+			case "prompts/list": return { prompts: this.listPrompts(this.prompts) };
+			case "prompts/get": return this.getPrompt(this.prompts, request.params, context);
+			default: break;
+		}
+		throw new RpcFailure(JSON_RPC_METHOD_NOT_FOUND, `Method "${request.method}" is not supported by this MCP server.`);
+	}
+	/**
+	* Build the `initialize` result advertising name / version /
+	* capabilities, negotiating the protocol version: the client's requested
+	* version when supported, otherwise the newest this server speaks.
+	*/
+	initializeResult(params) {
+		const requested = readRecord(params).protocolVersion;
+		const protocolVersion = typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;
+		const capabilities = { tools: {} };
+		if (this.resources) capabilities.resources = {};
+		if (this.prompts) capabilities.prompts = {};
 		return {
-			protocolVersion: PROTOCOL_VERSION,
-			capabilities: { tools: {} },
+			protocolVersion,
+			capabilities,
 			serverInfo: {
 				name: this.options.name,
 				version: this.options.version ?? DEFAULT_VERSION
@@ -1302,19 +1910,19 @@ var McpServeHandler = class {
 	}
 	/**
 	* Build the `tools/list` payload: one {@link McpToolDescriptor} per
-	* contract, its `inputSchema` extracted via `extractJsonSchema` at the
-	* configured dialect (default `draft-2020-12` — overriding
+	* exposed tool, its `inputSchema` extracted via `extractJsonSchema` at
+	* the configured dialect (default `draft-2020-12` — overriding
 	* `extractJsonSchema`'s own `openai-strict` default to a neutral MCP draft).
 	*/
 	listTools() {
 		const target = this.options.schemaTarget ?? DEFAULT_SCHEMA_TARGET;
-		return this.tools.map((contract) => {
+		return this.tools.map(({ name, contract }) => {
 			const inputSchema = (0, _warlock_js_ai.extractJsonSchema)(contract.input, { target }) ?? {
 				type: "object",
 				properties: {}
 			};
 			return {
-				name: contract.name,
+				name,
 				description: contract.description,
 				inputSchema
 			};
@@ -1325,15 +1933,27 @@ var McpServeHandler = class {
 	* never-throwing {@link import("@warlock.js/ai").ToolInvokeResult}: `data`
 	* → a text content block, `error` → an `isError: true` result. An unknown
 	* tool name throws (mapped to a JSON-RPC error by {@link handle}).
+	*
+	* The contract receives a `ToolContext` carrying the abort signal and,
+	* over HTTP, the inbound request's headers on `ctx.request`.
 	*/
-	async callTool(params) {
+	async callTool(params, context) {
 		const { name, args } = readCallParams(params);
 		const contract = this.byName.get(name);
 		if (!contract) throw new McpTransportError(`Unknown tool "${name}".`, {
 			type: "protocol",
 			method: "tools/call"
 		});
-		const result = await contract.invoke(args);
+		const toolContext = { artifacts: {} };
+		if (context.signal) toolContext.signal = context.signal;
+		if (context.request) {
+			const { headers, remoteAddress } = context.request;
+			toolContext.request = remoteAddress === void 0 ? { headers } : {
+				headers,
+				remoteAddress
+			};
+		}
+		const result = await contract.invoke(args, toolContext);
 		if (result.error) return {
 			content: [{
 				type: "text",
@@ -1349,6 +1969,75 @@ var McpServeHandler = class {
 			isError: false
 		};
 	}
+	/** Build the `resources/list` payload (metadata only, no contents). */
+	listResources(resources) {
+		return [...resources.values()].map((resource) => compact({
+			uri: resource.uri,
+			name: resource.name,
+			title: resource.title,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+	}
+	/**
+	* Answer `resources/read`: run the resource's `read()` and wrap the
+	* result as one text or base64 blob content entry.
+	*/
+	async readResource(resources, params, context) {
+		const uri = readRecord(params).uri;
+		if (typeof uri !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, "resources/read requires a string `uri`.");
+		const resource = resources.get(uri);
+		if (!resource) throw new RpcFailure(MCP_RESOURCE_NOT_FOUND, "Resource not found", { uri });
+		const body = await resource.read(context);
+		return { contents: [compact(typeof body === "string" ? {
+			uri,
+			mimeType: resource.mimeType,
+			text: body
+		} : {
+			uri,
+			mimeType: resource.mimeType,
+			blob: Buffer.from(body).toString("base64")
+		})] };
+	}
+	/** Build the `prompts/list` payload. */
+	listPrompts(prompts) {
+		return [...prompts.values()].map((prompt) => compact({
+			name: prompt.name,
+			title: prompt.title,
+			description: prompt.description,
+			arguments: prompt.arguments
+		}));
+	}
+	/**
+	* Answer `prompts/get`: validate the arguments (strings only; required
+	* ones present) and build the messages. An unknown prompt or a missing
+	* required argument answers invalid-params, per the MCP prompts spec.
+	*/
+	async getPrompt(prompts, params, context) {
+		const record = readRecord(params);
+		const name = record.name;
+		if (typeof name !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, "prompts/get requires a string `name`.");
+		const prompt = prompts.get(name);
+		if (!prompt) throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Unknown prompt "${name}".`);
+		const args = {};
+		for (const [key, value] of Object.entries(readRecord(record.arguments))) {
+			if (typeof value !== "string") throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Prompt argument "${key}" must be a string.`);
+			args[key] = value;
+		}
+		for (const argument of prompt.arguments ?? []) if (argument.required && args[argument.name] === void 0) throw new RpcFailure(JSON_RPC_INVALID_PARAMS, `Prompt "${name}" requires the "${argument.name}" argument.`);
+		const built = await prompt.get(args, context);
+		const messages = typeof built === "string" ? [{
+			role: "user",
+			content: {
+				type: "text",
+				text: built
+			}
+		}] : built;
+		return compact({
+			description: prompt.description,
+			messages
+		});
+	}
 	/** Build a JSON-RPC success response. */
 	ok(id, result) {
 		return {
@@ -1358,17 +2047,77 @@ var McpServeHandler = class {
 		};
 	}
 	/** Build a JSON-RPC error response. */
-	error(id, code, message) {
+	error(id, code, message, data) {
 		return {
 			jsonrpc: JSONRPC_VERSION,
 			id,
-			error: {
+			error: data === void 0 ? {
 				code,
 				message
+			} : {
+				code,
+				message,
+				data
 			}
 		};
 	}
 };
+/** JSON-RPC "Invalid Request" — the line is JSON but not a request object. */
+const JSON_RPC_INVALID_REQUEST = -32600;
+/** JSON-RPC "Internal error" — answering the request failed unexpectedly. */
+const JSON_RPC_INTERNAL_ERROR = -32603;
+/**
+* Turn one stdio line into the line to write back, or `undefined` when
+* nothing is answered: blank or non-JSON lines and notifications (no `id`).
+* A JSON value that is not a request object (`null`, a number, an array) is
+* answered with a JSON-RPC "Invalid Request" error whose `id` is `null`.
+* Never rejects: a dispatch failure is answered as an internal error.
+*/
+async function answerStdioLine(line, dispatch) {
+	const trimmed = line.trim();
+	if (!trimmed) return;
+	let message;
+	try {
+		message = JSON.parse(trimmed);
+	} catch {
+		return;
+	}
+	if (typeof message !== "object" || message === null || Array.isArray(message)) return `${JSON.stringify({
+		jsonrpc: JSONRPC_VERSION,
+		id: null,
+		error: {
+			code: JSON_RPC_INVALID_REQUEST,
+			message: "Invalid request: not a JSON-RPC object."
+		}
+	})}\n`;
+	const request = message;
+	const id = request.id;
+	if (id === void 0 || id === null) return;
+	try {
+		const response = await dispatch(request);
+		return `${JSON.stringify(response)}\n`;
+	} catch {
+		return `${JSON.stringify({
+			jsonrpc: JSONRPC_VERSION,
+			id,
+			error: {
+				code: JSON_RPC_INTERNAL_ERROR,
+				message: "Internal error."
+			}
+		})}\n`;
+	}
+}
+/** Read an unknown value as a plain record (non-objects read as empty). */
+function readRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	return value;
+}
+/** Drop `undefined` members so optional wire fields are omitted, not `null`. */
+function compact(value) {
+	const result = {};
+	for (const [key, member] of Object.entries(value)) if (member !== void 0) result[key] = member;
+	return result;
+}
 /**
 * Read and validate the `tools/call` params into `{ name, args }`. Throws
 * a typed {@link McpTransportError} when `name` is missing — mapped to a
@@ -1404,9 +2153,12 @@ function serializeData(data) {
 * {@link serve}) so callers and tests can drive the MCP protocol without an
 * actual transport — feed it a JSON-RPC request, get the response.
 *
-* @param source - The tools to expose (an object with `tools()` or a literal array).
-* @param options - Serve options (name / version / schema target).
-* @returns An object whose `handle(request)` maps a request to a response.
+* Throws {@link McpServeError} on duplicate tool names / resource URIs /
+* prompt names, or `prefixToolNames` on an ungrouped source.
+*
+* @param source - The tools to expose (one tool set or `{ groups }`).
+* @param options - Serve options (name / version / schema target / resources / prompts).
+* @returns An object whose `handle(request, context?)` maps a request to a response.
 */
 function createServeHandler(source, options) {
 	return new McpServeHandler(source, options);
@@ -1414,79 +2166,66 @@ function createServeHandler(source, options) {
 /**
 * The internal {@link McpServer} — owns a {@link McpServeHandler} and a
 * transport pump. For `stdio` it reads newline-delimited JSON-RPC requests
-* from `process.stdin` and writes responses to `process.stdout`; the
-* `http` transport is accepted but listening is deferred to the host
-* (a serve-over-HTTP needs a server the caller owns).
+* from `process.stdin` and writes responses to `process.stdout`; for
+* `http` it binds a Streamable HTTP endpoint (see `./serve-http`).
 *
 * Constructed via {@link serve}; the class itself is internal.
 */
 var McpServerImpl = class {
 	constructor(source, options) {
-		this.running = false;
 		this.handler = new McpServeHandler(source, options);
 		this.options = options;
 	}
-	async start() {
-		if (this.running) return;
-		if ((this.options.transport ?? { type: "stdio" }).type !== "stdio") throw new McpTransportError("serve() over http requires a host-provided server; only stdio is auto-pumped.", { type: "connect" });
-		this.running = true;
-		this.reader = (0, node_readline.createInterface)({ input: process.stdin });
-		this.reader.on("line", (line) => {
-			this.onLine(line);
+	start() {
+		if (!this.running) {
+			const transport = this.options.transport ?? { type: "stdio" };
+			const starting = transport.type === "http" ? this.startHttp(transport) : Promise.resolve(this.startStdio());
+			this.running = starting.catch((error) => {
+				this.running = void 0;
+				throw error;
+			});
+		}
+		return this.running;
+	}
+	/** Bind the HTTP endpoint; its `close()` also makes this server startable again. */
+	async startHttp(transport) {
+		const http = await startHttpServer(transport, (request, context) => this.handler.handle(request, context));
+		return {
+			url: http.url,
+			close: async () => {
+				await http.close();
+				this.running = void 0;
+			}
+		};
+	}
+	/** Wire the stdin line reader and answer each request on stdout. */
+	startStdio() {
+		const reader = (0, node_readline.createInterface)({ input: process.stdin });
+		reader.on("line", (line) => {
+			this.onLine(line).catch(() => {});
 		});
+		return { close: async () => {
+			reader.close();
+			this.running = void 0;
+		} };
 	}
-	/**
-	* Parse one stdin line as a JSON-RPC request, dispatch it through the
-	* handler, and write the response as a single line to stdout. Non-JSON
-	* lines and notifications (no `id`) are ignored.
-	*/
+	/** Answer one stdin line on stdout (see {@link answerStdioLine}). */
 	async onLine(line) {
-		const trimmed = line.trim();
-		if (!trimmed) return;
-		let request;
+		const reply = await answerStdioLine(line, (request) => this.handler.handle(request));
+		if (reply !== void 0) process.stdout.write(reply);
+	}
+	async stop() {
+		const running = this.running;
+		if (!running) return;
+		let handle;
 		try {
-			request = JSON.parse(trimmed);
+			handle = await running;
 		} catch {
 			return;
 		}
-		if (request.id === void 0 || request.id === null) return;
-		const response = await this.handler.handle(request);
-		process.stdout.write(`${JSON.stringify(response)}\n`);
-	}
-	async stop() {
-		this.running = false;
-		this.reader?.close();
-		this.reader = void 0;
+		await handle.close();
 	}
 };
-/**
-* Expose a built agent / supervisor / orchestrator (or a raw
-* `ToolContract[]`) AS an MCP server (Direction B: local primitive → MCP
-* server other clients consume).
-*
-* Enumerates `source.tools()` (or the literal array) once at construction.
-* `tools/list` answers with each tool's `inputSchema` extracted via
-* `extractJsonSchema` at the configured `schemaTarget` (default
-* `draft-2020-12`). `tools/call` routes to the named contract's
-* `invoke()` and maps the never-throwing result — `data` becomes a text
-* content block, `error` becomes an `isError: true` result — so a failing
-* tool surfaces as a normal MCP tool error rather than crashing the server.
-*
-* The default transport is `stdio`, pumped over `process.stdin` /
-* `process.stdout`. Serving over HTTP is left to a host-owned server;
-* `start()` rejects an `http` transport (the protocol core is available
-* via {@link createServeHandler} for a caller's own HTTP wiring).
-*
-* @param source - The tools to expose.
-* @param options - Server name, version, transport, and schema dialect.
-* @returns An {@link McpServer} with `start()` / `stop()`.
-*
-* @example
-* serve(
-*   { tools: () => ws.allTools() },
-*   { name: "warlock-workspace", transport: { type: "stdio" } },
-* ).start();
-*/
 function serve(source, options) {
 	return new McpServerImpl(source, options);
 }
@@ -2560,7 +3299,8 @@ _warlock_js_ai.ai.tools = {
 	fetchUrl: fetchUrlTool,
 	http: httpRequestTool,
 	calculator: calculatorTool,
-	dateTime: (options) => dateTimeTool(options)
+	dateTime: (options) => dateTimeTool(options),
+	measure: _warlock_js_ai.measureTools
 };
 _warlock_js_ai.ai.mcp = mcp;
 
@@ -2568,7 +3308,9 @@ _warlock_js_ai.ai.mcp = mcp;
 exports.CalculatorError = CalculatorError;
 exports.DateTimeError = DateTimeError;
 exports.HttpPolicyError = HttpPolicyError;
+exports.McpServeError = McpServeError;
 exports.McpTransportError = McpTransportError;
+exports.SUPPORTED_PROTOCOL_VERSIONS = SUPPORTED_PROTOCOL_VERSIONS;
 exports.WebToolError = WebToolError;
 exports.calculatorTool = calculatorTool;
 exports.createJsonRpcClient = createJsonRpcClient;