@acid-cat/core-ts 0.7.0 → 0.9.0

package/README.md

@@ -58,13 +58,53 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 | Function | Binding | Result |
 | --- | --- | --- |
 | `createSession(app, options)` | [TypeScript](../../spec/bindings/typescript.md) | A session with a handle for each capability in the view |
-| `mcpHandler(app, options)` | [MCP](../../spec/bindings/mcp.md) | `(request: Request) => Promise<Response>` |
+| `mcpHandler(app, options)` | [MCP](../../spec/bindings/mcp.md#http) through HTTP | `(request: Request) => Promise<Response>` |
+| `mcpStdioMain(app, options)`, `runMcpStdio(…)` | [MCP](../../spec/bindings/mcp.md#stdio) through stdio | The MCP server of the process, or a promise that resolves when the input ends |
 | `httpHandler(app, options)` | [HTTP](../../spec/bindings/http.md) | `(request: Request) => Promise<Response>` |
 | `cliMain(app, options)`, `runCli(…)` | [CLI](../../spec/bindings/cli.md) | The command line of the process, or an exit code |
 | `installWebMcp(session)` | [WebMCP](../../spec/bindings/webmcp.md) | Tools in the page, with a status |
+| `serve(handler, options)`, from `@acid-cat/core-ts/node` | MCP and HTTP | A Node.js server for the web handlers. See [Serve on Node.js](#serve-on-nodejs) |
 
 When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call of the request.
 
+### Serve on Node.js
+
+`@acid-cat/core-ts/node` serves web handlers on Node.js, with only `node:http`. It has no other dependency.
+
+```ts
+import { serve } from "@acid-cat/core-ts/node";
+
+const mcp = mcpHandler(aircon, { name: "aircon", version: "1.0.0", allowedOrigins: [], toJsonSchema, context: { unit } });
+const http = httpHandler(aircon, { allowedOrigins: [], toJsonSchema, context: { unit } });
+
+const server = await serve({ "/mcp": mcp, "/": http }, { port: 3000 });
+console.log(server.url); // http://127.0.0.1:3000
+```
+
+`serve(handler, options)` takes one handler for all paths, or handlers by path prefix. The longest prefix that matches gets the request, and the prefix `/` matches all paths. The MCP handler answers on all paths, so give it only its own prefix. A path that no prefix matches gets `404`. A handler that rejects gets `500`.
+
+| Option | Default | Use |
+| --- | --- | --- |
+| `port` | `3000` | The port. With `0`, the system chooses a free port. `server.port` gives it |
+| `hostname` | `127.0.0.1` | The address. Only the same computer can connect. Use `0.0.0.0` or `::` to accept connections from the network |
+
+`serve` resolves when the server listens. `server.close()` stops it, and `await using server = await serve(…)` closes it at the end of the block. When a client closes its connection, the signal of its request aborts, so the handler cancels the call.
+
+`serve` gives a plain HTTP/1.1 server. For more, use a library for web handlers, for example [srvx](https://srvx.h3.dev): HTTPS, HTTP/2, middleware, or the same server code on Bun and Deno. Give it the handler. Make sure that the library aborts the signal of a request when the client closes the connection. If it does not, a closed connection does not cancel the call.
+
+### MCP through stdio
+
+An MCP client, for example a coding agent, can start the server as a local process. `mcpStdioMain` serves the standard input and output of the process. The process is one session, with one `context`. The server serves revision `2026-07-28`, and the `initialize` handshake of revisions `2025-11-25` and `2025-06-18`. When the availability of a capability changes, the server sends `notifications/tools/list_changed`. `notifications/cancelled` cancels a call. When standard input ends, the session closes and the calls in progress are cancelled.
+
+```ts
+#!/usr/bin/env node
+import { mcpStdioMain } from "@acid-cat/core-ts";
+
+mcpStdioMain(aircon, { name: "aircon", version: "1.0.0", context: { unit }, toJsonSchema });
+```
+
+Standard output carries only MCP messages. The session writes defects to standard error. Do not write to standard output from a capability. `runMcpStdio(app, options, { input, write })` is the same server on any stream: `input` is an async iterable of bytes or text, for example a `ReadableStream`, and `write` writes one line. It works in all runtimes.
+
 ### Typed calls and handles
 
 `createSession` gives a `Session<Context>`. It calls a capability with the types of the capability in two ways. Both take the capability object, so the types come from its schemas:
@@ -102,6 +142,20 @@ const handler = httpHandler(aircon, {
 });
 ```
 
+### Command line
+
+The command line has one command for each capability in the view of the `cli` target. Each top-level property of the input is a flag with the same name, for example `--celsius 22` or `--celsius=22`. A boolean property is a switch, for example `--on`. A property with an array of strings, numbers or values of a string enum is a repeated flag: each occurrence gives one item, in the order of the flags. A repeated flag that occurs once can also give the whole array as JSON text. Other properties take JSON text. For example, with the command line of the air conditioner, [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts):
+
+```sh
+node cli.ts aircon temperature set --celsius 22
+node cli.ts aircon schedule set --days mon --days fri --hours 7 --hours 18   # {"days":["mon","fri"],"hours":[7,18]}
+node cli.ts aircon schedule set --days '["mon","fri"]' --hours '[7,18]'      # the same input, as JSON text
+node cli.ts aircon schedule set --days '[]'                                   # an empty array
+node cli.ts list                                                             # the usage of each command
+```
+
+`list` gives a usage line for each capability. The usage of a repeated flag ends with `...`, for example `--days <mon|tue|wed|thu|fri|sat|sun>... [--hours <integer>...]`. See the [CLI binding](../../spec/bindings/cli.md#commands) for all the rules.
+
 ### Commands of the application
 
 The option `commands` of `cliMain` and `runCli` adds commands of the application beside the commands of the capabilities, `call` and `list`. A command has a `name`, a `description` for the help, and `run(args, io)`. `run` gets the arguments after the name of the command, and `io` with `stdout`, `stderr`, `signal` and the `context`. It returns the exit code. The name must not be `call`, `list`, the name of another command of the application, or the first word of the command of a capability. If it is, `runCli` throws. The option `description` gives the text at the top of the help. The default is the description of the application, then its title, then the name of the program.

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { createSession } from "./session.js";
-import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, cliFlags, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
+import { CLI_EXIT_CODES, bundle, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
 //#region src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
@@ -119,21 +119,32 @@ function parseFlags(args, schema) {
 	const properties = objectOrEmpty(schema.properties);
 	const definitions = objectOrEmpty(schema.$defs);
 	const input = {};
+	const repeated = /* @__PURE__ */ new Map();
 	const remaining = args.values();
 	for (const arg of remaining) {
 		if (!arg.startsWith("--")) throw new UsageError(`Unexpected argument ${arg}.`, CLI_EXIT_CODES["invalid-input"]);
 		const [name = "", inline] = arg.slice(2).split(/=(.*)/s, 2);
 		const property = properties[name];
 		if (property === void 0) throw new UsageError(`Unknown flag --${name}.`, CLI_EXIT_CODES["invalid-input"]);
-		const type = resolve(objectOrEmpty(property), definitions);
+		const type = cliResolve(objectOrEmpty(property), definitions);
 		if (type.type === "boolean") {
 			input[name] = inline === void 0 ? true : inline === "true";
 			continue;
 		}
 		const text = inline ?? remaining.next().value;
 		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
-		input[name] = valueOf(name, text, type);
+		const items = cliRepeatedItems(type, definitions);
+		if (items === void 0) input[name] = valueOf(name, text, type);
+		else {
+			const flag = repeated.get(name) ?? {
+				items,
+				values: []
+			};
+			flag.values.push(text);
+			repeated.set(name, flag);
+		}
 	}
+	for (const [name, { items, values }] of repeated) input[name] = cliJsonArray(values) ?? values.map((text) => valueOf(name, text, items));
 	const required = Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : [];
 	for (const name of required) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
 	return input;
@@ -155,10 +166,6 @@ function valueOf(name, text, type) {
 		throw new UsageError(`The flag --${name} must be JSON.`, CLI_EXIT_CODES["invalid-input"]);
 	}
 }
-function resolve(property, definitions) {
-	const name = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
-	return name === void 0 ? property : objectOrEmpty(definitions[name] ?? property);
-}
 /** A value as a JSON object, or an empty object when it is not one. */
 const objectOrEmpty = (value) => isJsonObject(value) ? value : {};
 /** The capability `id` of a view. The view has it, because the session serves it. */

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { createSession } from "./session.js";
 export type { Handle, HandleOf, Session, SessionOptions } from "./session.js";
 export { mcpHandler } from "./mcp.js";
 export type { McpOptions, McpSettings } from "./mcp.js";
+export { main as mcpStdioMain, runMcpStdio } from "./mcp-stdio.js";
+export type { McpStdioIo, McpStdioOptions } from "./mcp-stdio.js";
 export { httpHandler } from "./http.js";
 export type { HttpOptions, HttpSettings } from "./http.js";
 export type { ContextOption } from "./context.js";

package/dist/index.js

@@ -1,8 +1,9 @@
 import { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
 import { createSession } from "./session.js";
 import { mcpHandler } from "./mcp.js";
+import { main as main$1, runMcpStdio } from "./mcp-stdio.js";
 import { httpHandler } from "./http.js";
 import { main, runCli } from "./cli.js";
 import { findHost, installWebMcp } from "./webmcp.js";
 import { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
-export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };
+export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, main$1 as mcpStdioMain, ok, renderCatalog, runCli, runMcpStdio, unavailable };

package/dist/mcp-stdio.d.ts

@@ -0,0 +1,28 @@
+import type { App, ToJsonSchema } from "./app.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;
+}
+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,244 @@
+import { createSession } from "./session.js";
+import { hasObjectOutput, listTools } from "./mcp.js";
+import { 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
+	});
+	const instructions = options.instructions ?? app.description;
+	const server = new StdioServer(session, {
+		...options,
+		instructions
+	}, io.write);
+	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 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;
+	constructor(session, options, write) {
+		this.#session = session;
+		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 cancel the calls in progress. */
+	async close() {
+		this.#changes.unsubscribe();
+		this.#subscriptions.clear();
+		for (const controller of this.#calls.values()) controller.abort();
+		await this.#session.dispose();
+	}
+	#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.#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: { "io.modelcontextprotocol/serverInfo": {
+				name: this.#options.name,
+				version: this.#options.version
+			} },
+			resultType: "complete",
+			...list ? {
+				ttlMs: 0,
+				cacheScope: "private"
+			} : {},
+			...result
+		} : result);
+		switch (method) {
+			case "server/discover": return complete({
+				supportedVersions: SUPPORTED_VERSIONS,
+				capabilities: { tools: { listChanged: true } },
+				...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);
+			default: return this.#error(id, -32601, `Method not found: ${method}`);
+		}
+	}
+	/** 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,6 @@
 import type { App, ToJsonSchema } from "./app.js";
 import type { ContextOption } from "./context.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 {
@@ -20,3 +21,15 @@ export interface McpSettings {
 }
 /** 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>;
+/** 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: import("@acid-cat/spec-ts").JsonObject;
+    outputSchema?: import("@acid-cat/spec-ts").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;

package/dist/mcp.js

@@ -100,6 +100,7 @@ async function answer(session, message, options, signal) {
 		default: return error(404, id, -32601, `Method not found: ${message.method}`);
 	}
 }
+/** The tools of the available capabilities in the view of a session (spec/bindings/mcp.md#tools). */
 function listTools(session) {
 	const types = session.view.$defs ?? {};
 	return [...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => {
@@ -115,6 +116,7 @@ function listTools(session) {
 		};
 	});
 }
+/** True if the bundled output schema of a capability has `"type": "object"`. */
 function hasObjectOutput(session, id) {
 	const output = session.view.capabilities[id]?.output;
 	return output !== void 0 && bundle(output, session.view.$defs ?? {}).type === "object";
@@ -173,4 +175,4 @@ const messages = {
 	"not-utf8": "The request body is not UTF-8 JSON."
 };
 //#endregion
-export { mcpHandler };
+export { hasObjectOutput, listTools, mcpHandler };

package/dist/node.d.ts

@@ -0,0 +1,39 @@
+/** A web request handler. */
+export type WebHandler = (request: Request) => Promise<Response> | Response;
+/**
+ * Handlers by path prefix, for example `{ "/mcp": mcp, "/api": http }`. A prefix matches its own path and the paths
+ * below it: `/api` matches `/api` and `/api/status`, but not `/apis`. The longest prefix that matches gets the request.
+ * The prefix `/` matches all paths. The handler gets the full URL of the request.
+ */
+export interface Routes {
+    readonly [prefix: string]: WebHandler;
+}
+export interface ServeOptions {
+    /** The port. The default is `3000`. With `0`, the system chooses a free port. */
+    readonly port?: number | undefined;
+    /**
+     * The address to listen on. The default is `127.0.0.1`, so that only the same computer can connect. Use `0.0.0.0`
+     * or `::` to accept connections from the network.
+     */
+    readonly hostname?: string | undefined;
+}
+/** A server that runs. `await using` closes it at the end of its block. */
+export interface Served extends AsyncDisposable {
+    /** The base URL, for example `http://127.0.0.1:3000`. */
+    readonly url: string;
+    /** The port that the server listens on. */
+    readonly port: number;
+    /** Stop accepting connections, and resolve when the open requests are complete. */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Serve one handler for all paths, or handlers by path prefix. The promise resolves when the server listens, and rejects
+ * when it cannot listen, for example when the port is in use.
+ *
+ * - The signal of each request aborts when the client closes the connection before the response is complete. A handler
+ *   that follows the signal then cancels its work.
+ * - A path that no prefix matches gets `404`. A handler that throws or rejects gets `500`. A request that is not valid
+ *   HTTP for a URL gets `400`.
+ * - The body of a request is a stream that reads from the connection only when the handler reads it.
+ */
+export declare function serve(handler: WebHandler | Routes, options?: ServeOptions): Promise<Served>;

package/dist/node.js

@@ -0,0 +1,172 @@
+import { createServer } from "node:http";
+//#region src/node.ts
+/**
+* The functions that need Node.js. The main entry point, `@acid-cat/core-ts`, works in all runtimes.
+*
+* `serve` serves web request handlers, `(request: Request) => Promise<Response>`, such as the handlers of `mcpHandler`
+* and `httpHandler`, on Node.js, with only `node:http`. The server serves plain HTTP/1.1. For HTTPS, HTTP/2 or
+* middleware, use a library for web handlers.
+*/
+/**
+* Serve one handler for all paths, or handlers by path prefix. The promise resolves when the server listens, and rejects
+* when it cannot listen, for example when the port is in use.
+*
+* - The signal of each request aborts when the client closes the connection before the response is complete. A handler
+*   that follows the signal then cancels its work.
+* - A path that no prefix matches gets `404`. A handler that throws or rejects gets `500`. A request that is not valid
+*   HTTP for a URL gets `400`.
+* - The body of a request is a stream that reads from the connection only when the handler reads it.
+*/
+function serve(handler, options = {}) {
+	const route = router(handler);
+	const hostname = options.hostname ?? "127.0.0.1";
+	const server = createServer((incoming, outgoing) => {
+		answer(incoming, outgoing, route);
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port ?? 3e3, hostname, () => {
+			server.off("error", reject);
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : 0;
+			const close = () => new Promise((done) => server.close(() => done()));
+			resolve({
+				url: `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`,
+				port,
+				close,
+				[Symbol.asyncDispose]: close
+			});
+		});
+	});
+}
+/** The handler of a path, or `undefined` when no prefix matches. */
+function router(handler) {
+	if (typeof handler === "function") return () => handler;
+	const prefixes = Object.keys(handler).sort((a, b) => b.length - a.length);
+	const matches = (path, prefix) => prefix.endsWith("/") ? path.startsWith(prefix) || path === prefix.slice(0, -1) : path === prefix || path.startsWith(`${prefix}/`);
+	return (path) => {
+		const prefix = prefixes.find((candidate) => matches(path, candidate));
+		return prefix === void 0 ? void 0 : handler[prefix];
+	};
+}
+async function answer(incoming, outgoing, route) {
+	const abort = new AbortController();
+	outgoing.on("close", () => {
+		if (!outgoing.writableFinished) abort.abort();
+	});
+	let request;
+	try {
+		request = requestOf(incoming, abort.signal);
+	} catch {
+		outgoing.writeHead(400).end();
+		return;
+	}
+	const handler = route(new URL(request.url).pathname);
+	if (handler === void 0) {
+		outgoing.writeHead(404).end();
+		return;
+	}
+	try {
+		await send(await handler(request), outgoing);
+	} catch {
+		if (outgoing.headersSent) outgoing.destroy();
+		else outgoing.writeHead(500).end();
+	}
+}
+/** The web request of an incoming request. It throws when the request has no valid URL. */
+function requestOf(incoming, signal) {
+	const url = new URL(incoming.url ?? "/", `http://${incoming.headers.host ?? "localhost"}`);
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(incoming.headers)) if (Array.isArray(value)) value.forEach((item) => headers.append(name, item));
+	else if (value !== void 0) headers.set(name, value);
+	const method = incoming.method ?? "GET";
+	const init = {
+		method,
+		headers,
+		signal
+	};
+	if (method === "GET" || method === "HEAD") return new Request(url, init);
+	const withBody = {
+		...init,
+		body: bodyOf(incoming),
+		duplex: "half"
+	};
+	return new Request(url, withBody);
+}
+/**
+* Write a web response. The body waits when the connection is full. When the client closes the connection, the body
+* is cancelled.
+*/
+async function send(response, outgoing) {
+	const headers = {};
+	for (const [name, value] of response.headers) if (name !== "set-cookie") headers[name] = value;
+	const cookies = response.headers.getSetCookie();
+	if (cookies.length > 0) headers["set-cookie"] = cookies;
+	outgoing.writeHead(response.status, response.statusText, headers);
+	if (response.body === null) {
+		outgoing.end();
+		return;
+	}
+	const reader = response.body.getReader();
+	const cancel = () => void reader.cancel().catch(() => void 0);
+	outgoing.on("close", cancel);
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) break;
+			if (outgoing.destroyed) return;
+			if (!outgoing.write(chunk.value)) await drained(outgoing);
+		}
+		outgoing.end();
+	} finally {
+		outgoing.off("close", cancel);
+	}
+}
+/** Resolve when the connection can take more data, or when it closes. */
+function drained(outgoing) {
+	return new Promise((resolve) => {
+		const done = () => {
+			outgoing.off("drain", done);
+			outgoing.off("close", done);
+			resolve();
+		};
+		outgoing.on("drain", done);
+		outgoing.on("close", done);
+	});
+}
+/**
+* The body of an incoming request, as a web stream. The stream reads the request only when the handler reads the body,
+* and the request pauses after each chunk until the handler reads again. A request that the handler does not read stays
+* unread, so that Node.js discards it after the response. When the handler cancels the stream, the request discards the
+* rest of its body.
+*/
+function bodyOf(incoming) {
+	let open = true;
+	let reading = false;
+	const close = (end) => {
+		if (open) end();
+		open = false;
+	};
+	return new ReadableStream({
+		pull(controller) {
+			if (!reading) {
+				reading = true;
+				incoming.on("data", (chunk) => {
+					if (!open) return;
+					if (!(chunk instanceof Uint8Array)) return close(() => controller.error(/* @__PURE__ */ new TypeError("a chunk of the request body is not bytes")));
+					controller.enqueue(chunk);
+					incoming.pause();
+				});
+				incoming.on("end", () => close(() => controller.close()));
+				incoming.on("error", (error) => close(() => controller.error(error)));
+			}
+			incoming.resume();
+		},
+		cancel() {
+			open = false;
+			incoming.resume();
+		}
+	}, { highWaterMark: 0 });
+}
+//#endregion
+export { serve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -26,17 +26,21 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.7.0",
-    "@acid-cat/spec-ts": "0.7.0"
+    "@acid-cat/catalog": "0.9.0",
+    "@acid-cat/spec-ts": "0.9.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.7.0",
+    "@acid-cat/cli": "0.9.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "playwright": "1.64.0",