@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

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 ??= requiredScopes.join(" ");
+                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,106 @@
+/** 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";
+export { callTool, callToolLazy } from "./mcp-call.js";
+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[];
+    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>;

package/dist/kernel/mcp.js

@@ -0,0 +1,49 @@
+import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.js";
+export { callTool, callToolLazy } from "./mcp-call.js";
+/** The selected MCP routes; all request work loads only when an MCP request arrives. */
+export function mcp(tools, options, reads = []) {
+    let serve;
+    // Check known static App configuration now; factories wait for the request caller gate.
+    const linked = {};
+    const apps = {};
+    for (const surface of ["public", "admin"]) {
+        const declared = options.apps?.[surface];
+        if (declared) {
+            // Read each static contributor's resources getter once, including mixed arrays.
+            const sources = (Array.isArray(declared) ? declared : [declared])
+                .map(source => typeof source === "function" ? source : resourcesOf(source));
+            const fixed = resourcesOf(sources.filter(source => typeof source !== "function"));
+            const dynamic = sources.some(source => typeof source === "function");
+            apps[surface] = dynamic ? sources : fixed;
+            // Known static conflicts still fail before any request or dynamic factory runs.
+            if (typeof tools === "function")
+                linkApps(fixed);
+            else {
+                const current = linkSurface(fixed, tools.filter(tool => tool.surface === surface));
+                if (!dynamic)
+                    linked[surface] = current;
+            }
+        }
+    }
+    options = { ...options, apps, allowedOrigins: originHostnames(options.allowedOrigins) };
+    return async (request, env, ctx) => {
+        if (!/^\/mcp(?:\/admin)?\/*$/.test(new URL(request.url).pathname))
+            return;
+        const { handler } = await import("./mcp-handler.js");
+        serve ??= handler(tools, options, linked, reads);
+        return serve(request, env, ctx);
+    };
+}
+/** `allowedOrigins` as the hostnames the official SDK compares; a bad entry fails here, not on each request. */
+function originHostnames(origins = []) {
+    return Object.freeze(origins.map(origin => {
+        let url;
+        try {
+            url = new URL(/^[a-z][a-z\d+.-]*:\/\//i.test(origin) ? origin : `http://${origin}`);
+        }
+        catch { }
+        if (origin.includes("*") || !url?.hostname || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+            throw new TypeError(`mcp allowedOrigins: "${origin}" is not an origin (https://host[:port]) or a host[:port]; wildcards never match.`);
+        return url.hostname;
+    }));
+}

package/dist/kernel/media.d.ts

@@ -0,0 +1,27 @@
+/** 0.2 media lifecycle over native target drivers. No bytes pass through this module. */
+import { ContractError, type Row } from "./contracts.js";
+import type { Bound } from "./binds.js";
+import type { Dialect } from "./dialect/common.js";
+import type { MediaAsset, MediaLibrary, MediaStorage, MediaPurposePolicy } from "./site-types.js";
+export interface MediaDatabase {
+    read(sql: string, binds: unknown[]): Row[] | PromiseLike<Row[]>;
+    write(steps: readonly Bound[]): Promise<Row[][]>; /** Positive native evidence that the write rolled back; absence is uncertain. */
+    definitive?(error: unknown): boolean;
+}
+/**
+ * A media, site or partial-failure error with the HTTP status (and `failure` payload) its code has on the wire. Code
+ * outside this module raising these codes uses it: core `statusOf` maps only the core codes.
+ */
+export declare const mediaError: (code: string, message: string, path?: string, options?: ErrorOptions) => ContractError;
+export declare function mediaLibrary(driver: MediaDatabase, d: Pick<Dialect, "param" | "escapeLike" | "likeEscape" | "like">, storage: MediaStorage, policies: readonly MediaPurposePolicy[], now?: () => number): MediaLibrary;
+/** The 0.2 Admin library item's convenience fields, without changing the storage DTO. */
+export declare function mediaItem(asset: MediaAsset): {
+    id: string;
+    variants: readonly import("./site-types.js").MediaVariant[];
+    primaryUrl: string | null;
+    mime: string | null;
+    byteSize: number | null;
+    alt: string | null;
+    caption: string | null;
+    createdAt: number;
+};