@acid-cat/core-ts 0.8.0 → 0.10.0

package/dist/mcp-poll.js

@@ -0,0 +1,179 @@
+import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
+import { systemClock } from "./clock.js";
+import { MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, canonicalJson, decodePollCursor, encodePollCursor, mcpSubscribeError } from "@acid-cat/spec-ts";
+//#region src/mcp-poll.ts
+/**
+* Poll delivery through MCP (spec/bindings/mcp.md#poll): `events/poll` reads the occurrences of a poll lease. A lease
+* holds one subscription, in a session of its own, and a buffer of its occurrences. The HTTP and the stdio transports
+* share this module. It works in all runtimes.
+*/
+/** The poll leases of one server. `close` ends them all. */
+var PollLeases = class {
+	#leases = /* @__PURE__ */ new Map();
+	/** The leases that start, by key. A second poll with the same key waits for the first. */
+	#starting = /* @__PURE__ */ new Map();
+	#leaseMs;
+	#bufferLimit;
+	#maxEvents;
+	#nextPollMs;
+	#clock;
+	#closed = false;
+	constructor(options = {}, clock = systemClock) {
+		this.#leaseMs = options.leaseMs ?? MCP_POLL_DEFAULTS.leaseMs;
+		this.#bufferLimit = options.bufferLimit ?? MCP_POLL_DEFAULTS.bufferLimit;
+		this.#maxEvents = options.maxEvents ?? MCP_POLL_DEFAULTS.maxEvents;
+		this.#nextPollMs = options.nextPollMs ?? MCP_POLL_DEFAULTS.nextPollMs;
+		this.#clock = clock;
+	}
+	/** The number of leases, for tests. */
+	get size() {
+		return this.#leases.size;
+	}
+	/**
+	* Answer `events/poll`. `principal` is the identity of the client, or `undefined` if the deployment gives none.
+	* `open` opens the session of a new lease.
+	*/
+	async poll(principal, params, open) {
+		const read = subscriptionParams(params);
+		if ("error" in read) return read;
+		const { maxEvents = this.#maxEvents } = params;
+		if (typeof maxEvents !== "number" || !Number.isSafeInteger(maxEvents) || maxEvents < 1) return invalidParams("maxEvents must be a positive integer.");
+		const key = canonicalJson([
+			principal ?? null,
+			read.name,
+			read.input
+		]);
+		await this.#starting.get(key);
+		const lease = this.#leases.get(key);
+		if (lease?.failure !== void 0) {
+			await this.#end(lease);
+			return { error: {
+				code: MCP_EVENT_ERRORS.internal,
+				message: lease.failure
+			} };
+		}
+		const position = read.cursor === void 0 ? void 0 : decodePollCursor(read.cursor);
+		if (lease === void 0) {
+			const provider = read.cursor === void 0 ? void 0 : position?.provider;
+			const started = this.#start(key, read.name, read.input, provider, provider === void 0 ? void 0 : read.maxAgeMs, open);
+			this.#starting.set(key, started);
+			const answer = await started.finally(() => this.#starting.delete(key));
+			if ("error" in answer) return answer;
+			return this.#result([], this.#cursorOf(answer, 0), read.cursor !== void 0 && provider === void 0, false);
+		}
+		this.#renew(lease);
+		if (read.cursor === void 0) return this.#result([], this.#cursorOf(lease, lease.newest), false, false);
+		if (position?.lease === lease.id) return this.#read(lease, position.position, maxEvents, read.cursor);
+		return this.#result([], this.#cursorOf(lease, lease.newest), true, false);
+	}
+	/** End all leases. */
+	async close() {
+		this.#closed = true;
+		await Promise.allSettled(this.#starting.values());
+		await Promise.allSettled([...this.#leases.values()].map((lease) => this.#end(lease)));
+	}
+	/** Start a lease: open its session, subscribe, and keep the occurrences. A failure before the first occurrence starts no lease. */
+	async #start(key, name, input, provider, maxAgeMs, open) {
+		const own = await open();
+		const subscribed = await own.session.subscribe(name, input, {
+			...provider === void 0 ? {} : { cursor: provider },
+			...maxAgeMs === void 0 ? {} : { maxAgeMs }
+		});
+		if ("kind" in subscribed || this.#closed) {
+			if (!("kind" in subscribed)) await subscribed.return();
+			await own.close();
+			if ("kind" in subscribed) return { error: mcpSubscribeError(subscribed) };
+			return { error: {
+				code: MCP_EVENT_ERRORS.internal,
+				message: "The server is closing."
+			} };
+		}
+		const lease = {
+			id: crypto.randomUUID(),
+			key,
+			own,
+			occurrences: subscribed,
+			entries: [],
+			newest: 0,
+			startProvider: provider,
+			lastProvider: provider,
+			failure: void 0,
+			ended: false,
+			cancelTimer: () => {}
+		};
+		this.#leases.set(key, lease);
+		this.#renew(lease);
+		this.#pump(lease);
+		return lease;
+	}
+	/** Read the occurrences of the subscription of a lease into its buffer, until the subscription ends. */
+	async #pump(lease) {
+		try {
+			for (let step = await lease.occurrences.next(); step.done !== true; step = await lease.occurrences.next()) {
+				const occurrence = step.value;
+				if (occurrence.cursor !== void 0) lease.lastProvider = occurrence.cursor;
+				lease.newest += 1;
+				lease.entries.push({
+					position: lease.newest,
+					occurrence,
+					provider: lease.lastProvider
+				});
+				if (lease.entries.length > this.#bufferLimit) lease.entries.shift();
+			}
+		} catch (error) {
+			if (!lease.ended) lease.failure = endMessage(error);
+		}
+		if (!lease.ended) await lease.own.close();
+	}
+	/** Renew a lease: it ends when it gets no poll for the lease time. */
+	#renew(lease) {
+		lease.cancelTimer();
+		lease.cancelTimer = this.#clock.schedule(() => void this.#end(lease), this.#leaseMs);
+	}
+	/** End a lease: cancel its subscription, close its session, and forget it. */
+	async #end(lease) {
+		if (lease.ended) return;
+		lease.ended = true;
+		lease.cancelTimer();
+		if (this.#leases.get(lease.key) === lease) this.#leases.delete(lease.key);
+		await lease.occurrences.return();
+		await lease.own.close();
+	}
+	/** The occurrences of a lease after a position, at most `maxEvents`. */
+	#read(lease, after, maxEvents, requestCursor) {
+		const older = after < (lease.entries[0]?.position ?? lease.newest + 1) - 1;
+		const available = lease.entries.filter((entry) => entry.position > after);
+		const events = available.slice(0, maxEvents);
+		const last = events.at(-1);
+		const truncated = older || events.some((entry) => entry.occurrence.truncated === true);
+		return this.#result(events.map((entry) => withoutTruncated(entry.occurrence)), last === void 0 ? requestCursor : this.#cursorOf(lease, last.position), truncated, available.length > maxEvents);
+	}
+	/** The cursor of a position of a lease. */
+	#cursorOf(lease, position) {
+		const provider = position === 0 ? lease.startProvider : position >= lease.newest ? lease.lastProvider : lease.entries.find((entry) => entry.position === position)?.provider;
+		return encodePollCursor(provider === void 0 ? {
+			lease: lease.id,
+			position
+		} : {
+			lease: lease.id,
+			position,
+			provider
+		});
+	}
+	#result(events, cursor, truncated, hasMore) {
+		return { result: {
+			events: [...events],
+			cursor,
+			truncated,
+			hasMore,
+			nextPollMs: this.#nextPollMs
+		} };
+	}
+};
+/** An occurrence without `truncated`, as an item of `events`. */
+function withoutTruncated(occurrence) {
+	const { truncated: _, ...rest } = occurrence;
+	return { ...rest };
+}
+//#endregion
+export { PollLeases };

package/dist/mcp-stdio.d.ts

@@ -0,0 +1,41 @@
+import type { App, ToJsonSchema } from "./app.js";
+import type { Clock } from "./clock.js";
+import type { PollOptions } from "./mcp-poll.js";
+export interface McpStdioOptions<Context> {
+    readonly name: string;
+    readonly version: string;
+    /** Guidance for a model about the whole server. The default is the description of the application. */
+    readonly instructions?: string | undefined;
+    /** The context of the session. */
+    readonly context: Context;
+    readonly toJsonSchema: ToJsonSchema;
+    /** The target that the server serves. The default is `"mcp"`. */
+    readonly target?: string | undefined;
+    /** The time with nothing sent on an `events/stream` request after which the server sends a heartbeat, in milliseconds. The default is 15 seconds. */
+    readonly heartbeatMs?: number | undefined;
+    /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
+    readonly bufferLimit?: number | undefined;
+    /**
+     * The settings of poll delivery: the lease time, the size of the buffer, `maxEvents` and `nextPollMs`. Each lease
+     * has a session of its own with `context`. The leases have no identity, because the process serves one client.
+     */
+    readonly poll?: PollOptions | undefined;
+    /** The clock of the poll leases. The default is the clock of the system. Tests give a clock that they control. */
+    readonly clock?: Clock | undefined;
+}
+export interface McpStdioIo {
+    /** Standard input: bytes or text, one JSON-RPC message on each line. */
+    readonly input: AsyncIterable<string | Uint8Array>;
+    /** Write one line to standard output. The text ends with a newline. */
+    readonly write: (text: string) => void;
+}
+/**
+ * Serve the MCP server on the lines of `io.input` until the input ends. Then the session closes: the calls in progress
+ * are cancelled, and the promise resolves. This function works in all runtimes.
+ */
+export declare function runMcpStdio<Context>(app: App<Context>, options: McpStdioOptions<Context>, io: McpStdioIo): Promise<void>;
+/**
+ * Run the MCP server on the standard input and output of the process, until standard input ends. The logs of the
+ * session go to standard error.
+ */
+export declare function main<Context>(app: App<Context>, options: McpStdioOptions<Context>): void;

package/dist/mcp-stdio.js

@@ -0,0 +1,325 @@
+import { createSession } from "./session.js";
+import { eventCapabilities, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
+import { PollLeases } from "./mcp-poll.js";
+import { hasObjectOutput, listTools } from "./mcp.js";
+import { KEEPALIVE_MS, MCP_PROTOCOL_VERSION, MCP_UNKNOWN_TOOL, isJsonObject, mcpToolResult } from "@acid-cat/spec-ts";
+//#region src/mcp-stdio.ts
+/**
+* The MCP binding through standard input and standard output (spec/bindings/mcp.md#stdio). The process is one session.
+* The server serves revision 2026-07-28, and the `initialize` handshake of revisions 2025-11-25 and 2025-06-18.
+*/
+/** The revisions with an `initialize` handshake that the server serves, the latest first. */
+const HANDSHAKE_VERSIONS = ["2025-11-25", "2025-06-18"];
+const SUPPORTED_VERSIONS = [MCP_PROTOCOL_VERSION, ...HANDSHAKE_VERSIONS];
+const PROTOCOL_VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+const SUBSCRIPTION_ID_KEY = "io.modelcontextprotocol/subscriptionId";
+function readMessage(body) {
+	const { id, method, params } = body;
+	const members = isJsonObject(params) ? params : {};
+	const meta = members["_meta"];
+	return {
+		id: typeof id === "string" || typeof id === "number" ? id : "id" in body ? null : void 0,
+		method: typeof method === "string" ? method : void 0,
+		params: members,
+		protocolVersion: isJsonObject(meta) ? meta[PROTOCOL_VERSION_KEY] : void 0
+	};
+}
+/**
+* Serve the MCP server on the lines of `io.input` until the input ends. Then the session closes: the calls in progress
+* are cancelled, and the promise resolves. This function works in all runtimes.
+*/
+async function runMcpStdio(app, options, io) {
+	const session = createSession(app, {
+		target: options.target ?? "mcp",
+		context: options.context,
+		toJsonSchema: options.toJsonSchema,
+		...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
+	});
+	const instructions = options.instructions ?? app.description;
+	const open = () => {
+		const own = createSession(app, {
+			target: options.target ?? "mcp",
+			context: options.context,
+			toJsonSchema: options.toJsonSchema,
+			...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
+		});
+		return Promise.resolve({
+			session: own,
+			close: own.dispose
+		});
+	};
+	const leases = new PollLeases(options.poll, options.clock);
+	const server = new StdioServer(session, {
+		name: options.name,
+		version: options.version,
+		instructions,
+		heartbeatMs: options.heartbeatMs ?? KEEPALIVE_MS
+	}, io.write, {
+		leases,
+		open
+	});
+	try {
+		for await (const line of lines(io.input)) server.receive(line);
+	} finally {
+		await server.close();
+	}
+}
+/**
+* Run the MCP server on the standard input and output of the process, until standard input ends. The logs of the
+* session go to standard error.
+*/
+function main(app, options) {
+	runMcpStdio(app, options, {
+		input: process.stdin,
+		write: (text) => process.stdout.write(text)
+	});
+}
+/** The lines of a stream of bytes or text, without their line ends. */
+async function* lines(input) {
+	const decoder = new TextDecoder();
+	let rest = "";
+	for await (const chunk of input) {
+		rest += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+		const parts = rest.split("\n");
+		rest = parts.pop() ?? "";
+		yield* parts;
+	}
+	rest += decoder.decode();
+	if (rest !== "") yield rest;
+}
+/** The state of the one session of the process: the requests in progress, the subscriptions, and the handshake. */
+var StdioServer = class {
+	#session;
+	#options;
+	#write;
+	/** The calls in progress, by request id. `notifications/cancelled` aborts them. */
+	#calls = /* @__PURE__ */ new Map();
+	/**
+	* The `events/stream` requests in progress, by request id. `notifications/cancelled` aborts them. When the session
+	* closes, their subscriptions end as complete, so they are not aborted then.
+	*/
+	#streams = /* @__PURE__ */ new Map();
+	/** The work of each `events/stream` request. `close` waits for it, so that the last result is written. */
+	#streaming = /* @__PURE__ */ new Set();
+	/** The open `subscriptions/listen` requests of revision 2026-07-28 that asked for tool list changes. */
+	#subscriptions = /* @__PURE__ */ new Set();
+	/** True after the `initialize` handshake: the client then gets `notifications/tools/list_changed` with no subscription. */
+	#initialized = false;
+	#listed;
+	#changes;
+	#poll;
+	constructor(session, options, write, poll) {
+		this.#session = session;
+		this.#poll = poll;
+		this.#options = options;
+		this.#write = write;
+		this.#listed = this.#availableIds();
+		this.#changes = session.onChange(() => this.#announce());
+	}
+	/** Read one line of standard input. An empty line is ignored. */
+	receive(line) {
+		if (line.trim() === "") return;
+		let body;
+		try {
+			body = JSON.parse(line);
+		} catch {
+			return this.#error(null, -32700, "The line is not JSON.");
+		}
+		if (Array.isArray(body)) return this.#error(null, -32600, "JSON-RPC batches are not supported.");
+		if (!isJsonObject(body)) return this.#error(null, -32600, "A message must be a JSON object.");
+		const message = readMessage(body);
+		if (message.method === void 0) {
+			if (message.id !== void 0) return;
+			return this.#error(null, -32600, "A message must have a method.");
+		}
+		if (message.id === void 0) return this.#notification(message);
+		this.#request({
+			...message,
+			id: message.id ?? null
+		});
+	}
+	/** Close the session: stop the subscriptions and the poll leases, and cancel the calls in progress. */
+	async close() {
+		this.#changes.unsubscribe();
+		await this.#poll.leases.close();
+		this.#subscriptions.clear();
+		for (const controller of this.#calls.values()) controller.abort();
+		await this.#session.dispose();
+		await Promise.allSettled(this.#streaming);
+	}
+	#notification(message) {
+		if (message.method !== "notifications/cancelled") return;
+		const requestId = message.params["requestId"];
+		if (typeof requestId !== "string" && typeof requestId !== "number") return;
+		this.#calls.get(requestId)?.abort();
+		this.#streams.get(requestId)?.abort();
+		this.#subscriptions.delete(requestId);
+	}
+	async #request(message) {
+		const { id, method, protocolVersion } = message;
+		if (method === "initialize") return this.#initialize(id, message.params["protocolVersion"]);
+		if (method === "ping") return this.#result(id, {});
+		const modern = protocolVersion !== void 0;
+		if (modern && protocolVersion !== MCP_PROTOCOL_VERSION) return this.#error(id, -32022, `Unsupported protocol version ${JSON.stringify(protocolVersion)}`, { supported: SUPPORTED_VERSIONS });
+		/** The result of a request: in revision 2026-07-28 it has the server information and a result type. */
+		const complete = (result, list = false) => this.#result(id, modern ? {
+			_meta: this.#serverInfo(),
+			resultType: "complete",
+			...list ? {
+				ttlMs: 0,
+				cacheScope: "private"
+			} : {},
+			...result
+		} : result);
+		switch (method) {
+			case "server/discover": return complete({
+				supportedVersions: SUPPORTED_VERSIONS,
+				capabilities: {
+					tools: { listChanged: true },
+					...eventCapabilities(this.#session)
+				},
+				...this.#options.instructions === void 0 ? {} : { instructions: this.#options.instructions }
+			}, true);
+			case "subscriptions/listen": return this.#listen(id, message.params);
+			case "tools/list": return complete({ tools: listTools(this.#session) }, true);
+			case "tools/call": return this.#call(id, message.params, complete);
+		}
+		if (modern && servesEvents(this.#session)) switch (method) {
+			case "events/list": return complete({ events: listEvents(this.#session) }, true);
+			case "events/poll": {
+				const answered = await this.#poll.leases.poll(void 0, message.params, this.#poll.open);
+				if ("error" in answered) return this.#error(id, answered.error.code, answered.error.message, answered.error.data);
+				return complete(answered.result);
+			}
+			case "events/unsubscribe":
+			case "events/subscribe": {
+				const { code, message: text, data } = unsupportedWebhook;
+				return this.#error(id, code, text, data);
+			}
+			case "events/stream": if (id !== null) {
+				const work = this.#stream(id, message.params).finally(() => this.#streaming.delete(work));
+				this.#streaming.add(work);
+				return work;
+			}
+		}
+		return this.#error(id, -32601, `Method not found: ${method}`);
+	}
+	/**
+	* An `events/stream` request: the messages of the subscription go to standard output. `notifications/cancelled` with
+	* the id of the request cancels it, and then the server sends nothing more for it.
+	*/
+	async #stream(id, params) {
+		const controller = new AbortController();
+		this.#streams.set(id, controller);
+		try {
+			const started = await startEventStream(this.#session, id, params, {
+				heartbeatMs: this.#options.heartbeatMs,
+				resultMeta: this.#serverInfo(),
+				signal: controller.signal
+			});
+			if (controller.signal.aborted) return;
+			if ("error" in started) return this.#error(id, started.error.code, started.error.message, started.error.data);
+			for (let messages = await started.messages(); messages !== void 0; messages = await started.messages()) {
+				if (controller.signal.aborted) return;
+				messages.forEach((message) => this.#send(message));
+			}
+		} finally {
+			if (this.#streams.get(id) === controller) this.#streams.delete(id);
+		}
+	}
+	/** The `_meta` of a result of revision 2026-07-28: the information about the server. */
+	#serverInfo() {
+		return { "io.modelcontextprotocol/serverInfo": {
+			name: this.#options.name,
+			version: this.#options.version
+		} };
+	}
+	/** The `initialize` handshake. The server selects the revision of the client if it serves it, or else its latest. */
+	#initialize(id, offered) {
+		const version = HANDSHAKE_VERSIONS.find((each) => each === offered) ?? HANDSHAKE_VERSIONS[0];
+		this.#result(id, {
+			protocolVersion: version,
+			capabilities: { tools: { listChanged: true } },
+			serverInfo: {
+				name: this.#options.name,
+				version: this.#options.version
+			},
+			...this.#options.instructions === void 0 ? {} : { instructions: this.#options.instructions }
+		});
+		this.#initialized = true;
+	}
+	/**
+	* A `subscriptions/listen` request of revision 2026-07-28. The server honors only tool list changes. The request
+	* stays open until the client cancels it or standard input ends, so the server never answers it.
+	*/
+	#listen(id, params) {
+		const wanted = params["notifications"];
+		const tools = isJsonObject(wanted) && wanted["toolsListChanged"] === true && id !== null;
+		this.#send({
+			jsonrpc: "2.0",
+			method: "notifications/subscriptions/acknowledged",
+			params: {
+				_meta: { [SUBSCRIPTION_ID_KEY]: id },
+				notifications: tools ? { toolsListChanged: true } : {}
+			}
+		});
+		if (tools) this.#subscriptions.add(id);
+	}
+	async #call(id, params, complete) {
+		const name = typeof params["name"] === "string" ? params["name"] : "";
+		const handle = this.#session.handles.get(name);
+		if (handle === void 0 || !handle.availability.getSnapshot().available) return this.#error(id, MCP_UNKNOWN_TOOL, `Tool '${name}' not found`);
+		const controller = new AbortController();
+		if (id !== null) this.#calls.set(id, controller);
+		try {
+			const outcome = await this.#session.invoke(name, params["arguments"] ?? {}, { signal: controller.signal });
+			if (controller.signal.aborted) return;
+			complete({ ...mcpToolResult(outcome, hasObjectOutput(this.#session, name)) });
+		} finally {
+			if (id !== null && this.#calls.get(id) === controller) this.#calls.delete(id);
+		}
+	}
+	/** The ids of the available tools, as one string, to compare two sets. */
+	#availableIds() {
+		return [...this.#session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => handle.id).join("\n");
+	}
+	/** Tell the client when the set of available tools changes. */
+	#announce() {
+		const next = this.#availableIds();
+		if (next === this.#listed) return;
+		this.#listed = next;
+		if (this.#initialized) this.#send({
+			jsonrpc: "2.0",
+			method: "notifications/tools/list_changed",
+			params: {}
+		});
+		for (const id of this.#subscriptions) this.#send({
+			jsonrpc: "2.0",
+			method: "notifications/tools/list_changed",
+			params: { _meta: { [SUBSCRIPTION_ID_KEY]: id } }
+		});
+	}
+	#result(id, result) {
+		this.#send({
+			jsonrpc: "2.0",
+			id,
+			result
+		});
+	}
+	#error(id, code, message, data) {
+		this.#send({
+			jsonrpc: "2.0",
+			id,
+			error: {
+				code,
+				message,
+				...data === void 0 ? {} : { data }
+			}
+		});
+	}
+	#send(message) {
+		this.#write(`${JSON.stringify(message)}\n`);
+	}
+};
+//#endregion
+export { main, runMcpStdio };

package/dist/mcp.d.ts

@@ -1,5 +1,10 @@
+import type { JsonObject } from "@acid-cat/spec-ts";
 import type { App, ToJsonSchema } from "./app.js";
 import type { ContextOption } from "./context.js";
+import type { Clock } from "./clock.js";
+import type { WebhookDelivery } from "./mcp-events.js";
+import type { PollOptions } from "./mcp-poll.js";
+import type { Session } from "./session.js";
 /** The options of `mcpHandler`. Give `context` to share one context, or `createContext` to make one for each request. */
 export type McpOptions<Context> = McpSettings & ContextOption<Context>;
 export interface McpSettings {
@@ -17,6 +22,50 @@ export interface McpSettings {
     readonly target?: string | undefined;
     /** The maximum size of a request body, in bytes. The default is 1 MiB. */
     readonly maximumBytes?: number | undefined;
+    /** The time with nothing sent on an `events/stream` response after which the server sends a heartbeat, in milliseconds. The default is 15 seconds. */
+    readonly heartbeatMs?: number | undefined;
+    /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
+    readonly bufferLimit?: number | undefined;
+    /**
+     * The identity of the client of a request: the principal (spec/bindings/mcp.md#webhook). It is part of the key of a
+     * poll lease and of a webhook subscription. `undefined` means that the request has no identity. With no function, no
+     * request has an identity.
+     */
+    readonly principal?: ((request: Request) => string | undefined | Promise<string | undefined>) | undefined;
+    /** The settings of poll delivery: the lease time, the size of the buffer, `maxEvents` and `nextPollMs`. */
+    readonly poll?: PollOptions | undefined;
+    /**
+     * Webhook delivery. It is off when this member is absent. `webhookDelivery` of `@acid-cat/core-ts/node` makes it.
+     * A request to `events/subscribe` or `events/unsubscribe` with no principal gets `Forbidden`.
+     */
+    readonly webhooks?: WebhookDelivery | undefined;
+    /** The clock of the poll leases. The default is the clock of the system. Tests give a clock that they control. */
+    readonly clock?: Clock | undefined;
+}
+/**
+ * The web request handler of an MCP server through HTTP. `close` ends the poll leases and the webhook subscriptions.
+ * `await using` calls it at the end of its block.
+ */
+export interface McpHandler {
+    (request: Request): Promise<Response>;
+    readonly close: () => Promise<void>;
+    readonly [Symbol.asyncDispose]: () => Promise<void>;
 }
-/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
-export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): (request: Request) => Promise<Response>;
+/**
+ * A web request handler for the MCP server. Each request has its own session, and with `createContext` its own
+ * context. Each poll lease and each webhook subscription also has its own session, opened with the context of the
+ * request that started it.
+ */
+export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): McpHandler;
+/** The tools of the available capabilities in the view of a session (spec/bindings/mcp.md#tools). */
+export declare function listTools(session: Session): {
+    name: string;
+    description: string;
+    inputSchema: JsonObject;
+    outputSchema?: JsonObject;
+    annotations: {
+        readOnlyHint: boolean;
+    };
+}[];
+/** True if the bundled output schema of a capability has `"type": "object"`. */
+export declare function hasObjectOutput(session: Session, id: string): boolean;