@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.10

package/dist/kernel/mcp-apps.d.ts

@@ -0,0 +1,69 @@
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** What `resources/read` passes an HTML loader. */
+export interface McpAppRender {
+    /** The tools this caller's `tools/list` shows on the endpoint, so the HTML names none it cannot see. */
+    readonly tools: ReadonlySet<string>;
+    /** The request's environment as the handler received it: Worker bindings such as `ASSETS`, or whatever a Bun host passes. */
+    readonly env: unknown;
+    /** The `resources/read` request, for its origin. */
+    readonly request: Request;
+}
+/** The CSP a resource asks its host for, as `_meta.ui.csp`. */
+export type McpAppCsp = {
+    readonly connectDomains?: readonly string[];
+    readonly resourceDomains?: readonly string[];
+    readonly frameDomains?: readonly string[];
+    readonly baseUriDomains?: readonly string[];
+};
+/** What a loader may return beside a plain string: the HTML and a CSP known only when it is read. It is sent on `resources/read` and replaces the resource's static `csp` (lists are not merged). */
+export interface McpAppPage {
+    readonly html: string;
+    readonly csp?: McpAppCsp;
+}
+/** One `ui://` resource. The HTML is a reusable asset and never carries caller data: that travels in tool results. */
+export interface McpAppResource {
+    readonly uri: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly html: string | ((render: McpAppRender) => string | McpAppPage | Promise<string | McpAppPage>);
+    readonly csp?: McpAppCsp;
+    readonly permissions?: {
+        readonly camera?: Record<string, never>;
+        readonly microphone?: Record<string, never>;
+        readonly geolocation?: Record<string, never>;
+        readonly clipboardWrite?: Record<string, never>;
+    };
+    readonly prefersBorder?: boolean;
+    /** `_meta.ui.domain`: the dedicated sandbox origin a host should serve this App from, in the form that host documents. */
+    readonly domain?: string;
+    /** Tool names whose results this resource renders. */
+    readonly renders?: readonly string[];
+    /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. A Procedure cannot be hidden from the model. */
+    readonly appOnly?: readonly string[];
+}
+export interface McpApps {
+    readonly resources: readonly McpAppResource[];
+}
+/** An application-owned contributor resolved after the endpoint's caller gate. */
+export type McpAppsSource = McpApps | ((context: Pick<McpAppRender, "env" | "request">) => McpApps | Promise<McpApps>);
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
+export declare const resourcesOf: (apps: McpApps | readonly McpApps[]) => McpApps;
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
+export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlySet<string>, views?: ReadonlySet<string>): {
+    resources: McpAppResource[];
+    renders: Map<string, string>;
+    appOnly: Set<string>;
+};
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export declare function linkSurface(apps: McpApps | readonly McpApps[], selected: readonly {
+    name: string;
+    page?: unknown;
+}[], previous?: {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+}): {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+};

package/dist/kernel/mcp-apps.js

@@ -0,0 +1,40 @@
+import { ContractError } from "./contracts.js";
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
+export const resourcesOf = (apps) => ({ resources: (Array.isArray(apps) ? apps : [apps]).flatMap(app => app.resources) });
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
+export function linkApps(apps, tools, views) {
+    const resources = resourcesOf(apps).resources;
+    const uris = new Set(), names = new Set(), renders = new Map(), appOnly = new Set();
+    const refuse = (message) => { throw new ContractError("MCP_APP_CONFLICT", message, "mcp:apps", { status: 500 }); };
+    for (const resource of resources) {
+        if (!resource.uri.startsWith("ui://"))
+            refuse(`MCP App resource '${resource.name}' must use a ui:// URI.`);
+        if (uris.has(resource.uri))
+            refuse(`MCP App resource URI '${resource.uri}' is registered twice.`);
+        if (names.has(resource.name))
+            refuse(`MCP App resource name '${resource.name}' is registered twice.`);
+        uris.add(resource.uri);
+        names.add(resource.name);
+        for (const tool of [...resource.renders ?? [], ...resource.appOnly ?? []]) {
+            if (tools && !tools.has(tool))
+                refuse(`MCP App resource '${resource.name}' names tool '${tool}', which this endpoint does not serve.`);
+            if (renders.has(tool) && renders.get(tool) !== resource.uri)
+                refuse(`Tool '${tool}' is claimed by two MCP App resources.`);
+            renders.set(tool, resource.uri);
+        }
+        // an App acts for the user without the model seeing the call, so only a read may be hidden from the model
+        for (const tool of resource.appOnly ?? []) {
+            if (views && !views.has(tool))
+                refuse(`App-only tool '${tool}' must be a View this endpoint serves.`);
+            appOnly.add(tool);
+        }
+    }
+    return { resources, renders, appOnly };
+}
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export function linkSurface(apps, selected, previous) {
+    const key = JSON.stringify(selected.map(tool => [tool.name, !!tool.page]).sort(([a], [b]) => a.localeCompare(b)));
+    return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
+}

package/dist/kernel/mcp-call.d.ts

@@ -0,0 +1,5 @@
+import type { Caller } from "./contracts.js";
+import type { Tool } from "./mcp.js";
+export declare function callTool<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, db: Database, caller: Caller, handlers: Handlers): Promise<unknown>;
+/** Transport input is checked before acquiring an application-owned native handle. */
+export declare function callToolLazy<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, getDb: () => Database, caller: Caller, handlers: Handlers, dryRun?: () => unknown): Promise<unknown>;

package/dist/kernel/mcp-call.js

@@ -0,0 +1,25 @@
+import { convert, invalid } from "./surface.js";
+import { checkPageLimit } from "./paging.js";
+export async function callTool(tool, raw, db, caller, handlers) {
+    return callToolLazy(tool, raw, () => db, caller, handlers);
+}
+/** Transport input is checked before acquiring an application-owned native handle. */
+export async function callToolLazy(tool, raw, getDb, caller, handlers, dryRun) {
+    if (tool.page) {
+        const { limit, cursor, ...input } = raw;
+        if (limit !== undefined)
+            checkPageLimit(limit, tool.path);
+        if (cursor !== undefined && typeof cursor !== "string")
+            invalid("Invalid paging options.", tool.path);
+        await tool.validate(input);
+        convert(input, tool.convert);
+        if (dryRun)
+            return dryRun();
+        return tool.page(getDb(), caller, input, { limit: limit, cursor: cursor });
+    }
+    const input = await tool.validate(raw);
+    convert(input, tool.convert);
+    if (dryRun)
+        return dryRun();
+    return tool.run(getDb(), caller, input, handlers);
+}

package/dist/kernel/mcp-handler.js

@@ -0,0 +1,371 @@
+/** Request-only MCP implementation, excluded from Worker startup. */
+import { authorized, authorizeTarget } from "./authorization.js";
+import { forwarded, isAdmin, ContractError, checkOrigin, surfaceCaller, surfaceError, wire } from "./contracts.js";
+import { draining } from "./drain.js";
+import { callToolLazy as callTool } from "./mcp-call.js";
+import { RESOURCE_MIME_TYPE, linkSurface, resourcesOf } from "./mcp-apps.js";
+const text = (value, locale) => {
+    if (typeof value === "string")
+        return value;
+    if (!value)
+        return;
+    return Object.hasOwn(value, locale) ? value[locale] : Object.hasOwn(value, "en") ? value.en : Object.values(value)[0];
+};
+function observe(listener, event) {
+    if (listener)
+        try {
+            void Promise.resolve(listener(event)).catch(() => { });
+        }
+        catch { }
+}
+const paging = (schema) => ({ ...schema, properties: { ...schema.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } });
+/**
+ * Characters of `JSON.stringify(page)` an MCP View page may hold. A result carries its rows twice (text block and
+ * `structuredContent`) and hosts are reported to truncate near 150k characters, so one copy stays at 60k.
+ * ponytail: one fixed number; raise it or make it an option if hosts publish their limits.
+ */
+const MCP_PAGE_BUDGET = 60_000;
+/** The scopes a challenge asks for: the credential's, plus what the request needs. */
+const union = (scopes, extra) => [...new Set([...scopes, ...extra])].join(" ");
+/** The handler for `/mcp` (public tools) and `/mcp/admin` (tools for `admin` roles); other paths are undefined. */
+export function handler(tools, options, apps = {}, reads = []) {
+    const allowed = options.allowedOrigins ?? [];
+    return draining(async (request, env, ctx) => {
+        const access = options.gateway ? (await import("./host-access.js")).accessRequest(ctx, options) : undefined;
+        let resolved;
+        try {
+            const requiredScopes = options.requiredScopes ?? ["mcp"], locale = options.locale ?? "en";
+            const url = new URL(request.url), path = url.pathname.replace(/\/+$/, ""), surface = path === "/mcp" ? "public" : path === "/mcp/admin" ? "admin" : undefined;
+            if (!surface)
+                return;
+            // MCP transport MUST: a present Origin is a browser, answered only for loopback or `allowedOrigins`. The request's own
+            // host is not implied, since a DNS-rebinding page sends Origin == its rebound Host; a missing Origin is a server client.
+            if (request.headers.has("origin")) {
+                const sdk = await import("@modelcontextprotocol/server");
+                const foreign = sdk.originValidationResponse(request, [...sdk.localhostAllowedOrigins(), ...allowed]);
+                if (foreign) {
+                    access?.finish(new ContractError("AUTH_DENIED", "Origin is not allowed.", "request:origin"));
+                    observe(options.onObservation, { kind: "request-refused", at: Date.now(), surface, status: 403 });
+                    observe(options.onRefusal, { at: Date.now(), status: 403, reason: "origin" });
+                    return foreign;
+                }
+            }
+            const select = async () => (typeof tools === "function" ? await tools(request, env) : tools).filter(tool => tool.surface === surface);
+            // Dynamic admin tables stay behind the admin gate; cache classification uses generated metadata only.
+            let selected = surface === "public" ? await select() : [];
+            let parsedBody, tooLarge = false;
+            const cookieOnly = request.headers.has("cookie") && !request.headers.has("authorization");
+            const parse = async () => {
+                if (options.gateway) {
+                    try {
+                        const raw = await (await import("./json-body.js")).bytes(request, 1024 * 1024, () => { tooLarge = true; throw new Error("Body limit"); });
+                        parsedBody = JSON.parse(new TextDecoder().decode(raw));
+                    }
+                    catch { }
+                    return;
+                }
+                const { readRequestBody } = await import("@modelcontextprotocol/server");
+                try {
+                    const body = await readRequestBody(request.clone(), 1024 * 1024);
+                    tooLarge = body.tooLarge;
+                    if (!body.tooLarge)
+                        parsedBody = JSON.parse(body.text);
+                }
+                catch { }
+            };
+            if (request.method === "POST" && (cookieOnly || options.gateway))
+                await parse();
+            const messages = Array.isArray(parsedBody) ? parsedBody : [parsedBody];
+            const readOnly = request.method === "POST" && messages.length > 0 && messages.every(message => {
+                if (!isRecord(message) || message.jsonrpc !== "2.0" || typeof message.method !== "string")
+                    return false;
+                if (["initialize", "tools/list", "resources/list", "resources/read"].includes(message.method))
+                    return true;
+                if (message.method !== "tools/call")
+                    return false;
+                const name = isRecord(message.params) ? message.params.name : undefined;
+                return reads.some(tool => tool.surface === surface && tool.name === name);
+            });
+            const challenge = async (error, scope, bare = false) => {
+                access?.finish(error);
+                const result = wire(error);
+                if (result.status === 401 || result.status === 403) {
+                    observe(options.onObservation, { kind: "request-refused", at: Date.now(), surface, status: result.status });
+                    observe(options.onRefusal, { at: Date.now(), status: result.status, reason: "credential" });
+                }
+                if (result.status === 401)
+                    scope = union(scope === undefined ? requiredScopes : scope.split(" "), options.authorizationScopes ?? []);
+                return (await import("./host-caller.js")).hostFailure(error, resolved, `mcp ${path}`, bare ? undefined : 'Bearer ' + (scope ? (result.status === 403 ? 'error="insufficient_scope", ' : '') + 'scope="' + scope + '", ' : '') + 'resource_metadata="' + (options.resourceMetadata ?? url.origin + '/.well-known/oauth-protected-resource/mcp') + '"');
+            };
+            let caller;
+            try {
+                const requested = isRecord(parsedBody) && isRecord(parsedBody.params) ? parsedBody.params.name : undefined;
+                const requestedTool = selected.find(t => t.name === requested) ?? (typeof tools === "function" ? undefined : tools.find(t => t.surface === surface && t.name === requested));
+                await access?.select(requestedTool?.target ? `${requestedTool.target.kind}:${requestedTool.target.name}` : typeof requested === "string" ? `mcp:${requested}` : "mcp");
+                caller = resolved = forwarded(ctx, options.gateway)
+                    ? (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields)
+                    : await surfaceCaller(request, env, options.caller ?? (() => ({ kind: "anonymous" })), readOnly);
+                await access?.select(requestedTool?.target ? `${requestedTool.target.kind}:${requestedTool.target.name}` : "target" in caller && caller.target ? caller.target : "mcp", caller);
+                if (caller.kind === "anonymous" && (surface === "admin" || selected.length > 0 && selected.every(tool => tool.closed)))
+                    throw new ContractError("UNAUTHENTICATED", "Authentication is required.", "mcp");
+                if (caller.kind === "system")
+                    return challenge(new ContractError("AUTH_DENIED", "System callers cannot use MCP.", "mcp"), undefined, true);
+                if (surface === "admin" && !isAdmin(caller))
+                    return challenge(new ContractError("AUTH_DENIED", "Admin role is required.", "mcp/admin"), undefined, true);
+                if (!options.gateway && caller.kind === "user" && caller.credential !== "session" && requiredScopes.some(scope => !caller.scopes.includes(scope)))
+                    return challenge(new ContractError("AUTH_DENIED", "The credential needs the required MCP scopes.", "mcp"), union(caller.scopes, requiredScopes));
+            }
+            catch (error) {
+                return challenge(error);
+            }
+            if (surface === "admin")
+                selected = await select();
+            // Before per-caller filtering, so every caller of a deploy sees one catalogue version.
+            const version = catalogueVersion(selected);
+            const { McpServer, ProtocolError, ProtocolErrorCode, createMcpHandler, fromJsonSchema } = await import("@modelcontextprotocol/server");
+            if (request.method === "POST" && !cookieOnly && !options.gateway)
+                await parse();
+            if (tooLarge && access)
+                return challenge(new ContractError("INPUT_VALIDATION_FAILED", "MCP body exceeds its limit.", "mcp"), undefined, true);
+            if (tooLarge)
+                return Response.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: "Request body exceeds 1048576 bytes." } }, { status: 413 });
+            const host = options.gateway && (await import("./host-caller.js")).isHostCaller(caller);
+            if (host) {
+                try {
+                    if (Array.isArray(parsedBody))
+                        throw new ContractError("INPUT_VALIDATION_FAILED", "Host calls cannot batch MCP messages.", "mcp");
+                    if (isRecord(parsedBody) && typeof parsedBody.method === "string" && !["initialize", "tools/call"].includes(parsedBody.method))
+                        throw new ContractError("AUTH_DENIED", "Host callers may only initialize or call a tool.", "mcp", { status: 403 });
+                    if (isRecord(parsedBody) && parsedBody.method === "initialize") {
+                        const pinned = "target" in caller ? caller.target : undefined;
+                        if (pinned && !selected.some(tool => (tool.target ? `${tool.target.kind}:${tool.target.name}` : `admin:tool:${tool.name}`) === pinned))
+                            throw new ContractError("TARGET_MISMATCH", "Initialize must pin a mounted tool.", pinned, { status: 412 });
+                        await access?.select(pinned ?? "mcp", caller);
+                        await access?.check(true);
+                    }
+                    else {
+                        const params = isRecord(parsedBody) && isRecord(parsedBody.params) ? parsedBody.params : undefined;
+                        const tool = selected.find(t => t.name === params?.name);
+                        if (tool) {
+                            await access?.select(tool.target ? `${tool.target.kind}:${tool.target.name}` : `admin:tool:${tool.name}`, caller);
+                            await access?.check(!!tool.page || tool.readOnly === true);
+                        }
+                    }
+                }
+                catch (error) {
+                    return challenge(error, undefined, true);
+                }
+            }
+            if (request.method === "POST") {
+                for (const message of Array.isArray(parsedBody) ? parsedBody : [parsedBody]) {
+                    if (!message || message.method !== "tools/call")
+                        continue;
+                    const tool = selected.find(tool => tool.name === message.params?.name);
+                    if (!tool)
+                        continue;
+                    const scopes = tool.scopes ?? [];
+                    if (caller.kind === "anonymous" && tool.closed)
+                        return challenge(new ContractError("UNAUTHENTICATED", "Authentication is required.", "mcp"), union(requiredScopes, scopes));
+                    if (!options.gateway && caller.kind === "user" && caller.credential === "oauth" && scopes.some(scope => !caller.scopes.includes(scope)))
+                        return challenge(new ContractError("AUTH_DENIED", "The credential needs additional scopes.", "mcp"), union(caller.scopes, scopes));
+                }
+            }
+            const app = options.apps?.[surface];
+            let links;
+            if (app) {
+                const sources = (Array.isArray(app) ? app : [app]);
+                const dynamic = sources.some(source => typeof source === "function");
+                const resolved = resourcesOf(await Promise.all(sources.map(source => typeof source === "function" ? source({ env, request }) : source)));
+                // Equal tool names say nothing about request-bound resource identity or ownership.
+                const current = linkSurface(resolved, selected, dynamic ? undefined : apps[surface]);
+                if (!dynamic)
+                    apps[surface] = current;
+                links = current.links;
+            }
+            if (options.authorize) {
+                try {
+                    for (const message of Array.isArray(parsedBody) ? parsedBody : [parsedBody]) {
+                        if (message?.method !== "tools/call")
+                            continue;
+                        const tool = selected.find(tool => tool.name === message.params?.name);
+                        if (!tool)
+                            continue;
+                        tool.check?.(caller);
+                        await authorizeTarget(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller);
+                    }
+                    // an App's HTML is rendered for the same tools the caller's tools/list shows
+                    if ((Array.isArray(parsedBody) ? parsedBody : [parsedBody]).some(message => message?.method === "tools/list" || message?.method === "resources/read")) {
+                        const visible = [];
+                        for (const tool of selected) {
+                            if (caller.kind === "anonymous" && tool.closed || !options.gateway && caller.kind === "user" && caller.credential === "oauth" && tool.scopes?.some(scope => !caller.scopes.includes(scope)))
+                                continue;
+                            try {
+                                tool.check?.(caller);
+                            }
+                            catch (error) {
+                                if (error instanceof ContractError && ["AUTH_DENIED", "UNAUTHENTICATED"].includes(error.code))
+                                    continue;
+                                throw error;
+                            }
+                            if (await authorized(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller))
+                                visible.push(tool);
+                        }
+                        selected = visible;
+                    }
+                }
+                catch (error) {
+                    return challenge(error);
+                }
+            }
+            const serverInfo = { name: "aotter.mantle", ...options.serverInfo, version: options.serverInfo?.version ?? version };
+            // Host calls execute in the SDK callback, after transport validation.
+            const handler = createMcpHandler(() => {
+                const schema = (value) => fromJsonSchema(value, { getValidator() { return (input) => ({ valid: true, data: input, errorMessage: undefined }); } });
+                // Tools capability after construction: given to the constructor, the SDK installs its tools/call handler before the wrap below.
+                const server = new McpServer(serverInfo, options.instructions ? { instructions: options.instructions } : {});
+                server.server.registerCapabilities({ tools: { listChanged: false } });
+                if (host)
+                    server.server.onclose = () => access?.finish(isRecord(parsedBody) && parsedBody.method === "initialize" ? undefined : new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: 400 }));
+                const appMeta = links ? registerApps(server, links, parsedBody, new Set(selected.map(tool => tool.name)), { env, request }) : undefined;
+                // A host's stale copy names a tool this catalogue lacks: say so, with the catalogue version, instead of the SDK's bare "not found".
+                // Wrapped where the SDK stores it, so transport and request validation still answer first.
+                const registered = new Set(), set = server.server.setRequestHandler.bind(server.server);
+                server.server.setRequestHandler = ((method, handler) => set(method, method === "tools/call" && typeof handler === "function" ? (request, context) => {
+                    if (!registered.has(request.params.name))
+                        throw new ProtocolError(ProtocolErrorCode.InvalidParams, `No tool named ${JSON.stringify(request.params.name)} exists in the current catalogue (catalogue version ${serverInfo.version}).`);
+                    return handler(request, context);
+                } : handler));
+                for (const tool of selected) {
+                    const meta = appMeta?.(tool.name);
+                    if (meta === false)
+                        continue;
+                    registered.add(tool.name);
+                    // Not part of structured output: the version, and on failure the current input contract.
+                    const about = (contract) => { const text = [tool.version && `tool version ${tool.version}`, contract && `input schema ${JSON.stringify(tool.page ? paging(tool.inputSchema) : tool.inputSchema)}`].filter(Boolean).join("; "); return text ? [{ type: "text", text }] : []; };
+                    server.registerTool(tool.name, { ...(meta ? { _meta: meta } : {}), ...(tool.title ? { title: text(tool.title, locale) } : {}), description: text(tool.description, locale) ?? text(tool.title, locale) ?? tool.name, inputSchema: schema(tool.page ? paging(tool.inputSchema) : tool.inputSchema), ...(tool.outputSchema ? { outputSchema: schema(tool.outputSchema) } : {}), ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (raw) => {
+                        const metadata = options.onObservation ? { kind: "invocation", surface, invocationId: crypto.randomUUID(), tool: tool.name, caller: Object.freeze(caller.kind === "user" ? { ...caller, scopes: Object.freeze([...caller.scopes]) } : { ...caller }) } : undefined;
+                        const started = metadata ? performance.now() : 0;
+                        if (metadata)
+                            observe(options.onObservation, { ...metadata, phase: "attempt", at: Date.now() });
+                        let outcome = "succeeded", code;
+                        try {
+                            if (host)
+                                tool.check?.(caller);
+                            if (tool.run && (!host || !tool.readOnly))
+                                checkOrigin(request, caller);
+                            let db;
+                            const run = (input) => callTool(tool, input, () => db ??= options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                            let data = await run(raw);
+                            // A page is cut before the first row that overflows the budget: the same page re-runs with the limit that fits, so the cursor is the View's own.
+                            // Data can change between reads, so the re-run is measured again. A View without an order is one page and refuses a smaller limit: it stays whole.
+                            for (let tries = 0; tool.page && isRecord(data) && Array.isArray(data.rows); tries++) {
+                                const rows = data.rows, total = JSON.stringify(data).length;
+                                if (total <= MCP_PAGE_BUDGET)
+                                    break;
+                                if (rows.length === 1 || tries === 4)
+                                    break;
+                                const sizes = rows.map(row => JSON.stringify(row).length);
+                                let size = total - sizes.reduce((sum, n) => sum + n, 0) - (rows.length - 1), fit = 0;
+                                for (const n of sizes) {
+                                    size += n + (fit ? 1 : 0);
+                                    if (size > MCP_PAGE_BUDGET)
+                                        break;
+                                    fit++;
+                                }
+                                const cut = await run({ ...raw, limit: Math.max(1, fit) }).catch(() => undefined);
+                                if (cut === undefined)
+                                    break;
+                                data = cut;
+                            }
+                            if (host)
+                                access?.finish();
+                            const text = JSON.stringify(data), notice = tool.page && text.length > MCP_PAGE_BUDGET;
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text }, ...about(false), ...(notice ? [{ type: "text", text: `This page is larger than the ${MCP_PAGE_BUDGET}-character page size budget (a single row over it, or a View without an order, is returned whole), so a host may truncate it. Continue with nextCursor, if any.` }] : [])], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
+                        }
+                        catch (error) {
+                            if (host)
+                                access?.finish(error);
+                            const diagnostic = host ? (await (await import("./host-caller.js")).hostFailure(error, caller, `mcp ${tool.name}`).json()).error : surfaceError(error, `mcp ${tool.name}`).error;
+                            code = diagnostic.code;
+                            outcome = code === "AUTH_DENIED" || code === "UNAUTHENTICATED" ? "denied" : "failed";
+                            if (diagnostic.path === "request:origin")
+                                observe(options.onRefusal, { at: Date.now(), status: 403, reason: "origin" });
+                            const payload = { diagnostics: [diagnostic] };
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), isError: true, content: [{ type: "text", text: JSON.stringify(payload) }, ...about(outcome === "failed")], ...(tool.outputSchema ? {} : { structuredContent: payload }) };
+                        }
+                        finally {
+                            if (metadata)
+                                observe(options.onObservation, { ...metadata, phase: "completion", at: Date.now(), outcome, durationMs: Math.max(0, performance.now() - started), ...(code ? { code } : {}) });
+                        }
+                    });
+                }
+                // An empty catalogue still answers tools/list and refuses calls the same way.
+                if (registered.size === 0) {
+                    server.server.setRequestHandler("tools/list", () => ({ tools: [] }));
+                    server.server.setRequestHandler("tools/call", () => ({ content: [] }));
+                }
+                return server;
+            }, { legacy: "stateless", maxRequestBodySize: 1024 * 1024, onerror: error => console.error("[mantle mcp] request failed", error) });
+            const response = await handler.fetch(request, { parsedBody });
+            if (host) {
+                if (response.status >= 400)
+                    access?.finish(new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: response.status }));
+            }
+            return response;
+        }
+        catch (error) {
+            access?.finish(error);
+            return (await import("./host-caller.js")).hostFailure(error, resolved, "mcp");
+        }
+    });
+}
+/** A hash of the tools an endpoint serves (`surface:name:version`, sorted), as 32-bit FNV-1a hex: it changes with any tool's definition. */
+function catalogueVersion(tools) {
+    const text = JSON.stringify(tools.map(tool => `${tool.surface}:${tool.name}:${tool.version ?? ""}`).sort());
+    return [...text].reduce((h, c) => Math.imul(h ^ c.codePointAt(0), 16777619) >>> 0, 2166136261).toString(16).padStart(8, "0");
+}
+const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** `unknown`: a stateless request after `initialize` carries no capabilities, so only an explicit refusal hides Apps. */
+function clientUiSupport(message) {
+    for (const m of Array.isArray(message) ? message : [message]) {
+        if (!isRecord(m) || !isRecord(m.params))
+            continue;
+        const meta = m.params._meta;
+        const declared = isRecord(meta) && isRecord(meta[CLIENT_CAPABILITIES_META_KEY]) ? meta[CLIENT_CAPABILITIES_META_KEY] : m.method === "initialize" && isRecord(m.params.capabilities) ? m.params.capabilities : undefined;
+        if (!declared)
+            continue;
+        const extensions = declared.extensions, ui = isRecord(extensions) ? extensions["io.modelcontextprotocol/ui"] : undefined;
+        return isRecord(ui) && Array.isArray(ui.mimeTypes) && ui.mimeTypes.includes(RESOURCE_MIME_TYPE) ? "supported" : "unsupported";
+    }
+    return "unknown";
+}
+function appMeta(r, csp = r.csp) {
+    const ui = { ...(csp ? { csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.domain !== undefined ? { domain: r.domain } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
+    return Object.keys(ui).length > 0 ? { ui } : undefined;
+}
+/** Registration uses the official SDK; HTML loaders run only on resources/read. */
+function registerApps(server, links, message, tools, request) {
+    const enabled = clientUiSupport(message) !== "unsupported";
+    if (enabled)
+        for (const resource of links.resources) {
+            const meta = appMeta(resource);
+            server.registerResource(resource.name, resource.uri, { mimeType: RESOURCE_MIME_TYPE, title: resource.title, description: resource.description, ...(meta ? { _meta: meta } : {}) }, async () => {
+                try {
+                    const loaded = typeof resource.html === "string" ? resource.html : await resource.html({ tools, ...request });
+                    const page = typeof loaded === "string" ? { html: loaded } : loaded, read = page.csp ? appMeta(resource, page.csp) : meta;
+                    return { contents: [{ uri: resource.uri, mimeType: RESOURCE_MIME_TYPE, text: page.html, ...(read ? { _meta: read } : {}) }] };
+                }
+                catch (error) {
+                    console.error("[mantle mcp] resource rendering failed:", error instanceof Error ? error.message : String(error));
+                    throw new Error("Internal error.");
+                }
+            });
+        }
+    return (tool) => {
+        if (!enabled)
+            return links.appOnly.has(tool) ? false : undefined;
+        const uri = links.renders.get(tool);
+        return uri ? { ui: { resourceUri: uri, ...(links.appOnly.has(tool) ? { visibility: ["app"] } : {}) }, "ui/resourceUri": uri, ...(links.appOnly.has(tool) ? {} : { "openai/outputTemplate": uri }) } : undefined;
+    };
+}

package/dist/kernel/mcp.d.ts

@@ -0,0 +1,110 @@
+/** MCP request handling for a generated tool table; the official SDK loads on the first MCP request. */
+import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
+import type { Conversions } from "./surface.js";
+import { type McpAppsSource } from "./mcp-apps.js";
+type Call = typeof import("./mcp-call.js");
+export declare const callTool: Call["callTool"];
+export declare const callToolLazy: Call["callToolLazy"];
+export type { McpApps, McpAppsSource, McpAppResource, McpAppRender, McpAppPage, McpAppCsp } from "./mcp-apps.js";
+/** Options of a generated `mcp(...)`; it adds required `handlers` when the app declares ref Procedures. */
+export interface Options<Env, Database> extends GatewayOptions {
+    apps?: Readonly<Partial<Record<"public" | "admin", McpAppsSource | readonly McpAppsSource[]>>>;
+    authorize?: Authorize;
+    gateway?: Gateway;
+    fields?: import("./user-fields.js").UserFields;
+    db: (env: Env) => Database;
+    caller?: (request: Request, env: Env, authority: {
+        readonly readOnly: boolean;
+    }) => Caller | Promise<Caller>;
+    locale?: string;
+    instructions?: string;
+    serverInfo?: {
+        name?: string;
+        title?: string;
+        version?: string;
+        icons?: {
+            src: string;
+            mimeType?: string;
+            sizes?: string[];
+            theme?: "light" | "dark";
+        }[];
+    };
+    requiredScopes?: readonly string[];
+    /** Additional scopes requested by an unauthenticated OAuth challenge (for example offline_access), not an API scope floor. */
+    authorizationScopes?: readonly string[];
+    resourceMetadata?: string;
+    /** Browser origins MCP answers besides loopback, compared by hostname: `https://console.example` or the official SDK's bare `console.example`. The site's own origin is not implied. */
+    allowedOrigins?: readonly string[];
+    onObservation?: (event: McpObservation) => void | Promise<void>;
+    onRefusal?: (event: CallerRefusal) => void | Promise<void>;
+}
+export interface CallerRefusal {
+    readonly at: number;
+    readonly status: 401 | 403;
+    readonly reason: "origin" | "credential";
+}
+export type McpObservation = {
+    readonly kind: "request-refused";
+    readonly at: number;
+    readonly surface: "public" | "admin";
+    readonly status: 401 | 403;
+} | {
+    readonly kind: "invocation";
+    readonly at: number;
+    readonly surface: "public" | "admin";
+    readonly invocationId: string;
+    readonly tool: string;
+    readonly caller: Caller;
+} & ({
+    readonly phase: "attempt";
+} | {
+    readonly phase: "completion";
+    readonly outcome: "succeeded" | "failed" | "denied";
+    readonly durationMs: number;
+    readonly code?: string;
+});
+type LocalizedText = string | Readonly<Record<string, string>>;
+type Paging = {
+    limit?: number;
+    cursor?: string;
+};
+/** One tool: a paged View (`page`) or a Procedure (`run`, a write), on the public or admin surface. */
+export interface Tool<Database, Handlers = never> {
+    readonly readOnly?: boolean;
+    readonly name: string;
+    readonly target?: Target;
+    /** Generated requires guard, used before application authorization. */
+    readonly check?: (caller: Caller) => void;
+    readonly surface: string;
+    readonly title?: LocalizedText;
+    readonly description: LocalizedText;
+    readonly outputSchema?: unknown;
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly openWorldHint?: boolean;
+        readonly idempotentHint?: boolean;
+    };
+    readonly inputSchema: unknown;
+    /** The listed definition's version; results carry it so a model holding an older definition can tell. */
+    readonly version?: string;
+    /** Declares an auth requirement: anonymous callers are challenged. */
+    readonly closed?: boolean;
+    /** OAuth scopes the requirement names. */
+    readonly scopes?: readonly string[];
+    readonly validate: (raw: unknown) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    readonly convert?: Conversions;
+    /** A View tool: its operation path and paged boundary. */
+    readonly path?: string;
+    readonly page?: (db: Database, caller: Caller, input: never, paging: Paging) => Promise<unknown>;
+    readonly run?: (db: Database, caller: Caller, input: never, handlers: Handlers) => Promise<unknown>;
+}
+/** Request-bound tool tables keep native environment bindings outside the cached App catalogue. */
+export type Tools<Env, Database, Handlers = never> = readonly Tool<Database, Handlers>[] | ((request: Request, env: Env) => readonly Tool<Database, Handlers>[] | Promise<readonly Tool<Database, Handlers>[]>);
+/** The selected MCP routes; all request work loads only when an MCP request arrives. */
+export declare function mcp<Env, Database, Handlers = never>(tools: Tools<Env, Database, Handlers>, options: Options<Env, Database> & {
+    handlers?: Handlers;
+}, reads?: readonly {
+    readonly name: string;
+    readonly surface: string;
+}[]): (request: Request, env: Env, ctx?: RequestContext) => Promise<Response | undefined>;