@acid-cat/core-ts 0.1.0 → 0.3.0

package/dist/mcp.js

@@ -0,0 +1,159 @@
+import { createSession } from "./session.js";
+import { withContext } from "./context.js";
+import { MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, bundle, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
+//#region src/mcp.ts
+/**
+* The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28, with no state on the
+* server between requests.
+*/
+/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
+function mcpHandler(app, options) {
+	const maximumBytes = options.maximumBytes ?? 1048576;
+	return async (request) => {
+		const screened = screenRequest(request, {
+			methods: ["POST"],
+			allowedOrigins: options.allowedOrigins,
+			mediaType: "application/json",
+			maximumBytes
+		});
+		if (screened !== void 0) return rejection(screened);
+		const body = await readBounded(request, maximumBytes);
+		if ("rejection" in body) return rejection(body.rejection);
+		let message;
+		try {
+			message = JSON.parse(body.text);
+		} catch {
+			return rejection("not-utf8");
+		}
+		const version = request.headers.get("MCP-Protocol-Version");
+		const id = message.id ?? null;
+		if (version === null) return error(400, id, -32020, "MCP-Protocol-Version header is required");
+		if (version !== MCP_PROTOCOL_VERSION) return error(400, id, -32022, `Unsupported protocol version ${version}`, { supported: [MCP_PROTOCOL_VERSION] });
+		if (message.id === void 0) return new Response(null, {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+		const metaVersion = message.params?._meta?.["io.modelcontextprotocol/protocolVersion"];
+		if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
+		if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
+		return withContext(options, request, async (context) => {
+			const session = createSession(app, {
+				target: options.target ?? "mcp",
+				context,
+				toJsonSchema: options.toJsonSchema
+			});
+			try {
+				return await answer(session, message, {
+					...options,
+					instructions: options.instructions ?? app.description
+				}, request.signal);
+			} finally {
+				await session.dispose();
+			}
+		});
+	};
+}
+async function answer(session, message, options, signal) {
+	const id = message.id ?? null;
+	const complete = (result, list = false) => reply(id, {
+		_meta: { "io.modelcontextprotocol/serverInfo": {
+			name: options.name,
+			version: options.version
+		} },
+		resultType: "complete",
+		...list ? {
+			ttlMs: 0,
+			cacheScope: "private"
+		} : {},
+		...result
+	});
+	switch (message.method) {
+		case "server/discover": return complete({
+			supportedVersions: [MCP_PROTOCOL_VERSION],
+			capabilities: { tools: { listChanged: false } },
+			...options.instructions === void 0 ? {} : { instructions: options.instructions }
+		}, true);
+		case "tools/list": return complete({ tools: listTools(session) }, true);
+		case "tools/call": {
+			const name = message.params?.name ?? "";
+			const handle = session.handles.get(name);
+			if (handle === void 0 || !handle.availability.getSnapshot().available) return error(200, id, MCP_UNKNOWN_TOOL, `Tool '${name}' not found`);
+			const outcome = await session.invoke(name, message.params?.arguments ?? {}, { signal });
+			return complete(mcpToolResult(outcome, hasObjectOutput(session, name)));
+		}
+		default: return error(404, id, -32601, `Method not found: ${message.method}`);
+	}
+}
+function listTools(session) {
+	const types = session.view.$defs ?? {};
+	return [...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => {
+		const capability = session.view.capabilities[handle.id];
+		const output = capability.output === void 0 ? void 0 : bundle(capability.output, types);
+		return {
+			name: handle.id,
+			description: capability.description,
+			inputSchema: bundle(capability.input ?? { type: "object" }, types),
+			...output?.type === "object" ? { outputSchema: output } : {},
+			annotations: { readOnlyHint: capability.readOnly === true }
+		};
+	});
+}
+function hasObjectOutput(session, id) {
+	const output = session.view.capabilities[id]?.output;
+	return output !== void 0 && bundle(output, session.view.$defs ?? {}).type === "object";
+}
+function reply(id, result) {
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id,
+		result
+	}), {
+		status: 200,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function error(status, id, code, message, data) {
+	const body = {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message,
+			...data === void 0 ? {} : { data }
+		}
+	};
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function rejection(reason) {
+	const { status, code } = MCP_REJECTIONS[reason];
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	if (reason === "method") headers.set("Allow", "POST");
+	if (code === void 0) return new Response(null, {
+		status,
+		headers
+	});
+	headers.set("Content-Type", "application/json");
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code,
+			message: messages[reason]
+		}
+	}), {
+		status,
+		headers
+	});
+}
+const messages = {
+	method: "Use POST.",
+	origin: "This origin is not allowed.",
+	"media-type": "Use application/json.",
+	"too-large": "The request body is too large.",
+	"not-utf8": "The request body is not UTF-8 JSON."
+};
+//#endregion
+export { mcpHandler };

package/dist/session.js

@@ -0,0 +1,139 @@
+import { catalogOf } from "./app.js";
+import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
+//#region src/session.ts
+/**
+* Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
+*/
+const always = {
+	getSnapshot: () => AVAILABLE,
+	subscribe: () => ({ unsubscribe() {} })
+};
+/** Open a session for a target. */
+function createSession(app, options) {
+	const view = viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target);
+	const lifetime = new AbortController();
+	const running = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const subscriptions = [];
+	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability failed with a defect: ${id}`, cause));
+	const served = /* @__PURE__ */ new Map();
+	for (const capability of app.capabilities) {
+		if (!(capability.id in view.capabilities)) continue;
+		const availability = capability.availability?.(options.context) ?? always;
+		subscriptions.push(availability.subscribe(() => listeners.forEach((listener) => listener())));
+		served.set(capability.id, {
+			capability,
+			availability
+		});
+	}
+	/** Run a call. The result is a result or a call failure. */
+	async function call(id, input, trusted, signal) {
+		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
+		const entry = served.get(id);
+		if (entry === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
+		const availability = entry.availability.getSnapshot();
+		if (!availability.available) return callFailure("unavailable", availability.reason);
+		const { capability } = entry;
+		let decoded = input ?? {};
+		if (!trusted && capability.input !== void 0) {
+			const validated = await capability.input["~standard"].validate(input);
+			if (validated.issues !== void 0) {
+				const message = validated.issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
+				return callFailure("invalid-input", message);
+			}
+			decoded = validated.value;
+		}
+		const controller = new AbortController();
+		const abort = () => controller.abort();
+		lifetime.signal.addEventListener("abort", abort);
+		signal?.addEventListener("abort", abort);
+		const cancelled = new Promise((resolve) => controller.signal.addEventListener("abort", () => resolve(callFailure("cancelled", "The call was cancelled."))));
+		if (lifetime.signal.aborted || signal?.aborted) controller.abort();
+		const work = Promise.resolve().then(() => capability.run(decoded, {
+			signal: controller.signal,
+			context: options.context
+		})).then((result) => checkResult(capability, result)).catch((cause) => {
+			onDefect(id, cause);
+			return callFailure("internal", "The capability failed.");
+		});
+		const outcome = Promise.race([work, cancelled]);
+		running.add(outcome);
+		try {
+			return await outcome;
+		} finally {
+			running.delete(outcome);
+			lifetime.signal.removeEventListener("abort", abort);
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	const handles = /* @__PURE__ */ new Map();
+	for (const [id, { capability, availability }] of served) {
+		const reject = async (outcome) => {
+			const settled = await outcome;
+			if (isCallFailure(settled)) throw new CallFailureError(settled);
+			return settled;
+		};
+		const state = capability.state?.source(options.context);
+		handles.set(id, {
+			id,
+			description: capability.description,
+			audience: capability.audience,
+			availability,
+			...state === void 0 ? {} : { snapshot: detached(state) },
+			execute: (input, callOptions) => reject(call(id, input, true, callOptions?.signal)),
+			invokeExternal: (input, callOptions) => reject(call(id, input, false, callOptions?.signal))
+		});
+	}
+	return {
+		target: options.target,
+		view,
+		handles,
+		signal: lifetime.signal,
+		invoke: (id, input, callOptions) => call(id, input, false, callOptions?.signal),
+		onChange(listener) {
+			listeners.add(listener);
+			return { unsubscribe: () => listeners.delete(listener) };
+		},
+		async dispose() {
+			lifetime.abort();
+			subscriptions.forEach((subscription) => subscription.unsubscribe());
+			await Promise.allSettled([...running]);
+		}
+	};
+}
+/** An observable whose values are copies, so that a client cannot change the data of the provider. */
+function detached(source) {
+	return {
+		getSnapshot: () => structuredClone(source.getSnapshot()),
+		subscribe: (listener) => source.subscribe((value) => listener(structuredClone(value)))
+	};
+}
+/** Check a result against the output schema or the failure schemas. A result that does not agree is a defect. */
+async function checkResult(capability, result) {
+	if (result.ok) {
+		if (capability.output === void 0) return {
+			ok: true,
+			value: result.value ?? null
+		};
+		const checked = await capability.output["~standard"].validate(result.value);
+		if (checked.issues !== void 0) throw new Error(`The output does not agree with its schema: ${checked.issues[0]?.message}`);
+		return {
+			ok: true,
+			value: checked.value
+		};
+	}
+	const tag = result.error._tag;
+	const schema = tag === void 0 ? void 0 : capability.failures?.[tag];
+	if (schema === void 0) throw new Error(`The failure ${String(tag)} is not in failures.`);
+	const checked = await schema["~standard"].validate(result.error);
+	if (checked.issues !== void 0) throw new Error(`The failure ${tag} does not agree with its schema: ${checked.issues[0]?.message}`);
+	return {
+		ok: false,
+		error: {
+			_tag: tag,
+			...checked.value
+		}
+	};
+}
+//#endregion
+export { createSession };

package/dist/webmcp.js

@@ -0,0 +1,130 @@
+import { CallFailureError, bundle, isCallFailure } from "@acid-cat/spec-ts";
+//#region src/webmcp.ts
+/**
+* The WebMCP binding (spec/bindings/webmcp.md): register capabilities as WebMCP tools in a web page.
+*/
+/** The WebMCP host of the page, if there is one (spec/bindings/webmcp.md#host). */
+function findHost() {
+	const scope = globalThis;
+	for (const candidate of [scope.document?.modelContext, scope.navigator?.modelContext]) if (typeof candidate?.registerTool === "function") return candidate;
+}
+/** Register the capabilities of a session as tools. If there is no host, do nothing and return `undefined`. */
+function installWebMcp(session, options = {}) {
+	const host = options.host ?? findHost();
+	if (host === void 0) return void 0;
+	let status = {
+		phase: "loading",
+		message: null
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const setStatus = (next) => {
+		status = next;
+		listeners.forEach((listener) => listener(next));
+	};
+	const lifetime = new AbortController();
+	const registered = /* @__PURE__ */ new Map();
+	const calls = /* @__PURE__ */ new Set();
+	const types = session.view.$defs ?? {};
+	let running = false;
+	let dirty = false;
+	const toolFor = (id) => {
+		const capability = session.view.capabilities[id];
+		return {
+			name: id,
+			description: capability.description,
+			inputSchema: bundle(capability.input ?? { type: "object" }, types),
+			execute: (input, callOptions) => {
+				const signal = AbortSignal.any([lifetime.signal, ...callOptions?.signal ? [callOptions.signal] : []]);
+				const call = session.invoke(id, input, { signal }).then((outcome) => {
+					if (isCallFailure(outcome)) throw new CallFailureError(outcome);
+					return outcome;
+				});
+				calls.add(call);
+				call.finally(() => calls.delete(call)).catch(() => void 0);
+				return call;
+			}
+		};
+	};
+	/** One update. If it fails, the tools stay as they were before the update. */
+	async function pass() {
+		const wanted = new Set([...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => handle.id));
+		const added = /* @__PURE__ */ new Map();
+		try {
+			for (const id of wanted) {
+				if (registered.has(id)) continue;
+				const controller = new AbortController();
+				added.set(id, controller);
+				await host.registerTool(toolFor(id), { signal: AbortSignal.any([controller.signal, lifetime.signal]) });
+			}
+		} catch (error) {
+			for (const controller of added.values()) controller.abort();
+			throw error;
+		}
+		for (const [id, controller] of added) registered.set(id, controller);
+		for (const [id, controller] of registered) if (!wanted.has(id)) {
+			controller.abort();
+			registered.delete(id);
+		}
+	}
+	/** Run updates one at a time. A request during an update causes one more update. */
+	async function reconcile() {
+		if (lifetime.signal.aborted) return;
+		if (running) {
+			dirty = true;
+			return;
+		}
+		running = true;
+		try {
+			do {
+				dirty = false;
+				setStatus({
+					phase: "reconciling",
+					message: null
+				});
+				try {
+					await pass();
+					setStatus({
+						phase: "ready",
+						message: null
+					});
+				} catch (error) {
+					setStatus({
+						phase: "failed",
+						message: error instanceof Error ? error.message : "A tool could not be registered."
+					});
+					dirty = false;
+				}
+			} while (dirty && !lifetime.signal.aborted);
+		} finally {
+			running = false;
+		}
+	}
+	const subscription = session.onChange(() => void reconcile());
+	reconcile();
+	return {
+		status: {
+			getSnapshot: () => status,
+			subscribe(listener) {
+				listeners.add(listener);
+				return { unsubscribe: () => listeners.delete(listener) };
+			}
+		},
+		retry: () => void reconcile(),
+		async dispose() {
+			setStatus({
+				phase: "closing",
+				message: null
+			});
+			subscription.unsubscribe();
+			lifetime.abort();
+			registered.clear();
+			await Promise.allSettled([...calls]);
+			setStatus({
+				phase: "disposed",
+				message: null
+			});
+		}
+	};
+}
+//#endregion
+export { findHost, installWebMcp };

package/package.json

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