@acid-cat/core-ts 0.8.0 → 0.9.0

package/README.md

@@ -58,7 +58,8 @@ 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 |
@@ -91,6 +92,19 @@ console.log(server.url); // http://127.0.0.1:3000
 
 `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:

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -36,11 +36,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.8.0",
-    "@acid-cat/spec-ts": "0.8.0"
+    "@acid-cat/catalog": "0.9.0",
+    "@acid-cat/spec-ts": "0.9.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.8.0",
+    "@acid-cat/cli": "0.9.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "playwright": "1.64.0",