akanjs 3.0.2 → 3.1.0-rc.1

package/server/mcp/McpDispatcher.ts

@@ -6,12 +6,12 @@ import { NoDocumentError } from "akanjs/document";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
 import type { Endpoint, EndpointCls } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
-import { Exception } from "../../signal/exception";
+import { Exception, isExceptionLike } from "../../signal/exception";
 import type { GuardCls } from "../../signal/guard";
 import { McpDocument, type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp";
 import type { MiddlewareCls } from "../../signal/middleware";
 import { SignalContext } from "../../signal/signalContext";
-import { McpExecutionContext } from "./McpExecutionContext";
+import { McpArgumentError, McpExecutionContext } from "./McpExecutionContext";
 
 export class McpAuthRequiredError extends Error {}
 
@@ -38,25 +38,44 @@ export class McpDispatcher {
     this.#props = props;
   }
 
-  async call(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<McpToolResult> {
+  async call(
+    exposed: McpExposedEndpoint,
+    args: Record<string, unknown>,
+    req: Request,
+    { forView = false }: { forView?: boolean } = {},
+  ): Promise<McpToolResult> {
     const found = this.#index().get(exposed.key);
     if (!found) return McpDispatcher.#failure(`Tool "${exposed.key}" is declared but not mounted on this server.`);
     try {
-      const value = McpDispatcher.#readable(exposed, await this.#exec(exposed.key, found, args, req));
+      const wire = await this.#exec(exposed.key, found, args, req);
+      const value = McpDispatcher.#readable(exposed, wire);
       const structuredContent = McpDocument.structuredContent(exposed.endpoint, value);
       return {
         content: this.#content(structuredContent, value),
         ...(structuredContent === undefined ? {} : { structuredContent }),
+        ...(forView ? { _meta: { "akanjs/value": wire ?? null } } : {}),
         isError: false,
       };
     } catch (error) {
       const status = McpDispatcher.#statusOf(error);
       
       if ((status === 401 || status === 403) && !req.headers.get("authorization")) throw new McpAuthRequiredError();
-      return McpDispatcher.#failure(this.#message(error, status, exposed.refName));
+      const failure = McpDispatcher.#failure(this.#message(error, status, exposed.refName));
+      const restorable = forView ? McpDispatcher.#restorable(error, status) : null;
+      return restorable ? { ...failure, _meta: { "akanjs/error": restorable } } : failure;
     }
   }
 
+  static #restorable(error: unknown, status: number | undefined) {
+    if (!status || status >= 500 || status === 401 || status === 403 || error instanceof NoDocumentError) return null;
+    const data = (error as { data?: unknown }).data;
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      statusCode: status,
+      ...(data && typeof data === "object" ? { data } : {}),
+    };
+  }
+
   async filterForAccount<T extends { name: string }>(items: T[], req: Request): Promise<T[]> {
     const index = this.#index();
 
@@ -115,6 +134,10 @@ export class McpDispatcher {
     });
   }
 
+  isEndpoint(name: string) {
+    return this.#index().has(name);
+  }
+
   #index() {
     if (this.#endpoints) return this.#endpoints;
     const endpoints = new Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }>();
@@ -146,8 +169,9 @@ export class McpDispatcher {
   }
 
   static #statusOf(error: unknown): number | undefined {
-    const status = (error as { statusCode?: unknown } | null)?.statusCode;
-    return typeof status === "number" ? status : undefined;
+    if (isExceptionLike(error) || error instanceof McpArgumentError || error instanceof NoDocumentError)
+      return error.statusCode;
+    return undefined;
   }
 
   #content(structuredContent: unknown, value: unknown): McpToolResult["content"] {

package/server/mcp/McpRouter.ts

@@ -7,7 +7,9 @@ import {
   MCP_META_CLIENT_CAPABILITIES,
   MCP_META_PROTOCOL_VERSION,
   MCP_META_SERVER_INFO,
+  MCP_MODERN_VERSION,
   MCP_SUPPORTED_VERSIONS,
+  MCP_UI_EXTENSION,
   McpDocument,
   type McpEra,
   McpErrorCode,
@@ -15,14 +17,17 @@ import {
   type McpJsonRpcRequest,
   type McpOutputSchemaMode,
   McpProgress,
+  type McpProtocolVersion,
   type McpSignalCost,
   type McpToolResult,
 } from "../../signal/mcp";
+import type { PromptMessage } from "../../signal/mcp/Msg";
 import type { McpPrompt } from "../../signal/mcp/mcpProtocol";
-import type { PagePromptEntry, PagePromptSource } from "../../signal/mcp/pagePrompt";
+import type { PagePromptEntry, PagePromptRun, PagePromptSource } from "../../signal/mcp/pagePrompt";
 import type { MiddlewareCls } from "../../signal/middleware";
 import { FetchSerializer } from "../../signal/serializer";
 import type { HttpRoutes } from "../types";
+import { type McpAppShellSource, McpApps } from "./McpApps";
 import { McpAuth, type McpAuthOption } from "./McpAuth";
 import { McpAuthRequiredError, McpDispatcher } from "./McpDispatcher";
 import { McpEventStream } from "./McpEventStream";
@@ -47,6 +52,9 @@ export interface McpRouterProps {
   outputSchema?: McpOutputSchemaMode;
   auth?: McpAuthOption;
   rateLimit?: McpRateLimitOption | false;
+  apps?: boolean;
+  appShell?: McpAppShellSource;
+  modern?: boolean;
 }
 
 interface McpCall {
@@ -63,6 +71,8 @@ interface McpErrorOptions {
   headers?: Record<string, string>;
 }
 
+type McpPageRun = { refusal: string } | { run: Extract<PagePromptRun, { ok: true }> | null; messages: PromptMessage[] };
+
 interface McpCacheHint {
   ttlMs: number;
   cacheScope: "public" | "private";
@@ -85,7 +95,10 @@ export class McpRouter {
   readonly #dispatcher: McpDispatcher;
   readonly #auth: McpAuth;
   readonly #limiter: McpRateLimiter | null;
+  readonly #apps: McpApps | null;
+  readonly #versions: readonly McpProtocolVersion[];
   #document: McpDocument | null = null;
+  #pageListFailed = false;
 
   constructor(props: McpRouterProps) {
     this.#props = props;
@@ -94,6 +107,10 @@ export class McpRouter {
     
     this.#dispatcher = new McpDispatcher({ ...props, legacyTextBlock, language: props.language ?? defaultLanguage });
     this.#auth = new McpAuth({ ...props.auth, path: props.path ?? "/mcp" });
+    this.#apps = props.apps && props.pagePrompts ? new McpApps(props.appShell ?? null) : null;
+
+    const modern = props.modern ?? !this.#apps?.rendersUi;
+    this.#versions = modern ? MCP_SUPPORTED_VERSIONS : MCP_SUPPORTED_VERSIONS.filter((v) => v !== MCP_MODERN_VERSION);
     this.#limiter =
       props.rateLimit === false
         ? null
@@ -108,7 +125,7 @@ export class McpRouter {
       [this.#props.path ?? "/mcp"]: {
         POST: async (req: Request) => this.#cors(req, await this.#post(req)),
         OPTIONS: (req: Request) => this.#preflight(req),
-        
+
         GET: (req: Request) => this.#cors(req, notAllowed()),
         DELETE: (req: Request) => this.#cors(req, notAllowed()),
       },
@@ -121,7 +138,8 @@ export class McpRouter {
       const document = this.#getDocument();
       const { tools, resourceTemplates, refusals, undescribed } = document;
       const cost = document.listingCost;
-      const counts = `tools=${tools.length} resourceTemplates=${resourceTemplates.length}`;
+      const appTools = document.appTools.length ? ` appTools=${document.appTools.length}` : "";
+      const counts = `tools=${tools.length}${appTools} resourceTemplates=${resourceTemplates.length}`;
       const readOnly = this.#props.readOnly ? " (read-only deployment)" : "";
       McpRouter.logger.debug(`MCP catalogue: ${counts}${readOnly} · listing ${McpRouter.#kb(cost.bytes)}`);
       if (cost.bySignal.length) McpRouter.logger.debug(`MCP catalogue cost: ${McpRouter.#costLine(cost.bySignal)}`);
@@ -142,6 +160,10 @@ export class McpRouter {
       this.#reportPagePrompts();
       this.#reportUnverifiable(tools.map((tool) => tool.name));
       for (const { key, reason } of refusals) McpRouter.logger.verbose(`MCP did not expose "${key}": ${reason}`);
+      for (const { name } of document.appTools)
+        McpRouter.logger.verbose(
+          `MCP kept "${name}" for the views an MCP Apps host renders: it declares \`mcp: false\`, so no model is shown it.`,
+        );
       for (const { key, reason } of undescribed)
         McpRouter.logger.warn(`MCP exposed "${key}" with no description: ${reason}`);
     } catch (error) {
@@ -185,6 +207,7 @@ export class McpRouter {
       resolveDescription: (key) => lookup.text(key),
       readOnly: this.#props.readOnly,
       outputSchema: this.#props.outputSchema,
+      apps: !!this.#apps?.rendersUi,
     });
     return this.#document;
   }
@@ -212,11 +235,21 @@ export class McpRouter {
     
     const meta = McpRouter.#meta(params);
     const era: McpEra = method !== "initialize" && meta && MCP_META_PROTOCOL_VERSION in meta ? "modern" : "legacy";
-    const rejection = era === "modern" ? McpRouter.#validateModern(req, method, params, meta ?? {}, id) : null;
+    const discoverable = method !== "server/discover" || this.#versions.includes(MCP_MODERN_VERSION);
+    const rejection =
+      era === "modern" && discoverable ? this.#validateModern(req, method, params, meta ?? {}, id) : null;
     if (rejection) return rejection;
 
+    const started = Date.now();
     try {
-      return await this.#dispatch({ id, method, params, era, req });
+      const call = { id, method, params, era, req };
+      const res = await this.#dispatch(call);
+      const subject = typeof params.name === "string" ? params.name : typeof params.uri === "string" ? params.uri : "";
+      const client = `${era}${this.#apps ? (this.#uiCapable(call) ? ", ui" : ", text") : ""}`;
+      McpRouter.logger.verbose(
+        `MCP ${method}${subject ? ` ${subject}` : ""} (${client}) → ${res.status} (${Date.now() - started}ms)`,
+      );
+      return res;
     } catch (error) {
       if (error instanceof McpAuthRequiredError) return this.#auth.unauthorized(req);
       McpRouter.logger.error(
@@ -231,40 +264,54 @@ export class McpRouter {
     switch (call.method) {
       case "initialize":
         
-        return this.#result(call, {
-          protocolVersion: McpRouter.#negotiate(call.params.protocolVersion),
-          capabilities: this.#capabilities(document),
-          serverInfo: this.#serverInfo(),
-          ...(this.#props.instructions ? { instructions: this.#props.instructions } : {}),
-        });
+        return this.#result(
+          call,
+          {
+            protocolVersion: this.#negotiate(call.params.protocolVersion),
+            capabilities: this.#capabilities(document),
+            serverInfo: this.#serverInfo(),
+            ...(this.#props.instructions ? { instructions: this.#props.instructions } : {}),
+          },
+          undefined,
+          this.#uiSession(call),
+        );
       case "ping":
         
         return this.#result(call, {});
       case "server/discover":
+        
+        if (!this.#versions.includes(MCP_MODERN_VERSION))
+          return McpRouter.#error(call.id, McpErrorCode.methodNotFound, this.#methodNotFound(call.method));
         return this.#result(
           call,
           {
-            supportedVersions: MCP_SUPPORTED_VERSIONS,
+            supportedVersions: this.#versions,
             capabilities: this.#capabilities(document),
             ...(this.#props.instructions ? { instructions: this.#props.instructions } : {}),
           },
           discoverCache,
         );
       case "tools/list":
-        return await this.#list(call, "tools", document.tools);
+        return await this.#list(call, "tools", [...document.tools, ...(await this.#appTools(call, document))]);
       case "resources/list":
-        return await this.#list(call, "resources", document.resources);
+        return await this.#list(call, "resources", [...document.resources, ...(await this.#appResources(call))]);
       case "resources/templates/list":
         return await this.#list(call, "resourceTemplates", document.resourceTemplates);
       case "prompts/list":
-        return await this.#list(
-          call,
-          "prompts",
-          ((await this.#props.pagePrompts?.list()) ?? []).map(McpRouter.#promptOf),
-        );
+        return await this.#list(call, "prompts", (await this.#pageEntries()).map(McpRouter.#promptOf));
       case "tools/call": {
         const slot = await this.#acquire(call);
-        return "refused" in slot ? slot.refused : await this.#toolsCall(call, document, slot.release);
+        if ("refused" in slot) return slot.refused;
+        let release = slot.release;
+        try {
+          const page = await this.#pageToolOf(call.params.name);
+          if (page) return await this.#pageToolCall(call, document, page);
+          
+          release = () => {};
+          return await this.#toolsCall(call, document, slot.release);
+        } finally {
+          release();
+        }
       }
       case "prompts/get":
         return await this.#limited(call, () => this.#promptsGet(call, document));
@@ -272,7 +319,7 @@ export class McpRouter {
         return await this.#limited(call, () => this.#resourcesRead(call, document));
       default:
         
-        return McpRouter.#error(call.id, McpErrorCode.methodNotFound, McpRouter.#methodNotFound(call.method), {
+        return McpRouter.#error(call.id, McpErrorCode.methodNotFound, this.#methodNotFound(call.method), {
           status: call.era === "modern" ? 404 : 200,
         });
     }
@@ -318,13 +365,16 @@ export class McpRouter {
     try {
       const name = call.params.name;
       if (typeof name !== "string") return McpRouter.#error(call.id, McpErrorCode.invalidParams, "Missing tool name.");
-      const exposed = document.findTool(name);
+      
+      const exposed = document.isAppOnly(name) && !this.#uiCapable(call) ? undefined : document.findTool(name);
       
       if (!exposed) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown tool: ${name}.`);
       const args = McpRouter.#arguments(call.params);
       if (!args) return McpRouter.#error(call.id, McpErrorCode.invalidParams, McpRouter.#badArguments);
       const progressToken = McpRouter.#progressToken(call);
-      if (progressToken === undefined) return this.#result(call, await this.#dispatcher.call(exposed, args, call.req));
+      const option = { forView: this.#forView(call) };
+      if (progressToken === undefined)
+        return this.#result(call, await this.#dispatcher.call(exposed, args, call.req, option));
       streaming = true;
       return await this.#streamedToolCall(call, exposed, args, progressToken, release);
     } finally {
@@ -340,7 +390,8 @@ export class McpRouter {
     release: () => void,
   ) {
     const channel = new McpProgress();
-    const settled = McpProgress.run(channel, async () => await this.#dispatcher.call(exposed, args, call.req))
+    const option = { forView: this.#forView(call) };
+    const settled = McpProgress.run(channel, async () => await this.#dispatcher.call(exposed, args, call.req, option))
       .then(
         (result) => ({ result }),
         (error: unknown) => ({ error }),
@@ -394,10 +445,13 @@ export class McpRouter {
   }
 
   #capabilities(document: McpDocument) {
+    const ui = !!this.#apps?.rendersUi;
     return {
-      ...(document.tools.length ? { tools: {} } : {}),
-      ...(document.resources.length || document.resourceTemplates.length ? { resources: {} } : {}),
+      ...(document.tools.length || this.#apps ? { tools: {} } : {}),
+      ...(document.resources.length || document.resourceTemplates.length || ui ? { resources: {} } : {}),
       ...(this.#props.pagePrompts ? { prompts: {} } : {}),
+      
+      ...(ui ? { extensions: { [MCP_UI_EXTENSION]: {} } } : {}),
     };
   }
 
@@ -409,6 +463,13 @@ export class McpRouter {
       .then((entries) => {
         const names = entries.map((entry) => entry.name).join(", ");
         McpRouter.logger.debug(`MCP page prompts: ${entries.length}${entries.length ? ` (${names})` : ""}`);
+        if (!this.#apps || !entries.length) return;
+        for (const { name } of entries.filter((entry) => this.#isEndpointName(entry.name)))
+          McpRouter.logger.warn(
+            `MCP did not publish page "${name}" as a tool: an endpoint already takes that name, so it stays a prompt only. Rename the prompt.`,
+          );
+        const ui = this.#apps.rendersUi ? "rendered from the CSR shell by an MCP Apps host" : "with no view to render";
+        McpRouter.logger.debug(`MCP page tools: ${ui}`);
       })
       .catch((error: unknown) => {
         McpRouter.logger.warn(
@@ -435,12 +496,33 @@ export class McpRouter {
   async #promptsGet(call: McpCall, document: McpDocument) {
     const name = call.params.name;
     if (typeof name !== "string") return McpRouter.#error(call.id, McpErrorCode.invalidParams, "Missing prompt name.");
+    const entry = await this.#pageEntry(name);
+    if (!entry) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown prompt: ${name}.`);
+    const page = await this.#runPage(call, document, entry);
+    if (page instanceof Response) return page;
+    if ("refusal" in page) return McpRouter.#error(call.id, McpErrorCode.invalidParams, page.refusal);
+    return this.#result(call, { description: entry.description, messages: page.messages });
+  }
+
+  async #pageToolCall(call: McpCall, document: McpDocument, entry: PagePromptEntry) {
+    const apps = this.#apps;
+    const page = await this.#runPage(call, document, entry);
+    if (page instanceof Response) return page;
+    if ("refusal" in page)
+      return this.#result(call, { content: [{ type: "text", text: page.refusal }], isError: true });
+    if (!page.run || !apps) return this.#result(call, { content: page.messages.map((message) => message.content) });
+    const origin = this.#auth.publicOrigin(call.req);
+    const forView = this.#uiCapable(call) ? { account: McpApps.accountOf(call.req) } : null;
+    return this.#result(call, apps.resultOf(page.run, page.messages, origin, forView));
+  }
+
+  async #runPage(call: McpCall, document: McpDocument, entry: PagePromptEntry): Promise<Response | McpPageRun> {
     const source = this.#props.pagePrompts;
-    const entry = source ? (await source.list()).find((candidate) => candidate.name === name) : undefined;
-    if (!source || !entry) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown prompt: ${name}.`);
+    const { name } = entry;
+    if (!source) return { refusal: `Unknown prompt: ${name}.` };
     const args = McpRouter.#arguments(call.params);
-    if (!args) return McpRouter.#error(call.id, McpErrorCode.invalidParams, McpRouter.#badArguments);
-    const strings = Object.fromEntries(Object.entries(args).map(([key, value]) => [key, String(value)]));
+    const strings = args ? McpRouter.#pageArguments(args) : null;
+    if (!strings) return McpRouter.#error(call.id, McpErrorCode.invalidParams, McpRouter.#badArguments);
     const composer = new PagePromptComposer({
       document,
       budget: this.#props.promptBudget ?? PagePromptComposer.defaultBudget,
@@ -455,8 +537,7 @@ export class McpRouter {
     const missing = entry.arguments
       .filter((arg) => arg.required && strings[arg.name] === undefined)
       .map((arg) => arg.name);
-    if (missing.length)
-      return this.#result(call, { description: entry.description, messages: composer.missing(entry, missing) });
+    if (missing.length) return { run: null, messages: composer.missing(entry, missing) };
     const run = await source.run({
       name,
       arguments: strings,
@@ -476,14 +557,95 @@ export class McpRouter {
             : run.reason === "not-found"
               ? "No screen exists for these arguments."
               : "The page failed to load.";
-      return McpRouter.#error(call.id, McpErrorCode.invalidParams, message);
+      return { refusal: message };
+    }
+    return { run, messages: await composer.compose(entry, run) };
+  }
+
+  static #pageArguments(args: Record<string, unknown>): Record<string, string> | null {
+    const strings: Record<string, string> = {};
+    const plain = (value: unknown) => ["string", "number", "boolean"].includes(typeof value);
+    for (const [key, value] of Object.entries(args)) {
+      if (value === null || value === undefined) continue;
+      if (plain(value)) strings[key] = String(value);
+      else if (Array.isArray(value) && value.every(plain)) strings[key] = value.join(",");
+      else return null;
+    }
+    return strings;
+  }
+
+  async #pageEntries(): Promise<PagePromptEntry[]> {
+    const source = this.#props.pagePrompts;
+    if (!source) return [];
+    try {
+      const entries = await source.list();
+      this.#pageListFailed = false;
+      return entries;
+    } catch (error) {
+      if (!this.#pageListFailed)
+        McpRouter.logger.warn(
+          `MCP page prompts could not be listed, so they are left out: ${error instanceof Error ? error.message : error}`,
+        );
+      this.#pageListFailed = true;
+      return [];
     }
-    return this.#result(call, { description: entry.description, messages: await composer.compose(entry, run) });
+  }
+
+  async #pageEntry(name: unknown) {
+    if (typeof name !== "string") return undefined;
+    return (await this.#pageEntries()).find((candidate) => candidate.name === name);
+  }
+
+  #isEndpointName(name: string) {
+    return !!this.#getDocument().findTool(name) || this.#dispatcher.isEndpoint(name);
+  }
+
+  async #pageTools() {
+    if (!this.#apps) return [];
+    return (await this.#pageEntries()).filter((entry) => !this.#isEndpointName(entry.name));
+  }
+
+  async #pageToolOf(name: unknown) {
+    if (!this.#apps || typeof name !== "string" || this.#isEndpointName(name)) return undefined;
+    return await this.#pageEntry(name);
+  }
+
+  async #appTools(call: McpCall, document: McpDocument) {
+    const apps = this.#apps;
+    if (!apps) return [];
+    const pages = (await this.#pageTools()).map((entry) => apps.toolOf(entry));
+    return this.#uiCapable(call) ? [...document.appTools, ...pages] : pages;
+  }
+
+  async #appResources(call: McpCall) {
+    const apps = this.#apps;
+    if (!apps?.rendersUi || !this.#uiCapable(call)) return [];
+    return apps.resourcesOf(await this.#pageEntries());
+  }
+
+  #uiCapable(call: McpCall) {
+    if (!this.#apps?.rendersUi) return false;
+    if (call.era === "modern") return McpApps.declaresUi(McpRouter.#meta(call.params)?.[MCP_META_CLIENT_CAPABILITIES]);
+    return call.req.headers.get("mcp-session-id")?.startsWith(McpApps.sessionPrefix) ?? false;
+  }
+
+  #forView(call: McpCall) {
+    return this.#uiCapable(call) && McpRouter.#meta(call.params)?.["akanjs/view"] === true;
+  }
+
+  #uiSession(call: McpCall): Record<string, string> | undefined {
+    if (!this.#apps?.rendersUi || !McpApps.declaresUi(call.params.capabilities)) return undefined;
+    return { "mcp-session-id": `${McpApps.sessionPrefix}${crypto.randomUUID()}` };
   }
 
   async #resourcesRead(call: McpCall, document: McpDocument) {
     const uri = call.params.uri;
     if (typeof uri !== "string") return McpRouter.#error(call.id, McpErrorCode.invalidParams, "Missing resource uri.");
+    if (this.#apps && uri.startsWith(McpApps.scheme)) {
+      const contents = await this.#apps.read(uri, this.#auth.publicOrigin(call.req));
+      if (!contents) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown resource: ${uri}.`);
+      return this.#result(call, { contents: [contents] });
+    }
     const resolved = document.resolveResource(uri);
     if (!resolved) return McpRouter.#error(call.id, McpErrorCode.invalidParams, `Unknown resource: ${uri}.`);
     const result = await this.#dispatcher.call(resolved.exposed, resolved.args, call.req);
@@ -517,7 +679,7 @@ export class McpRouter {
       new Response(null, {
         status: 204,
         headers: {
-          "access-control-allow-methods": "POST, OPTIONS",
+          "access-control-allow-methods": "POST, GET, DELETE, OPTIONS",
           "access-control-allow-headers":
             req.headers.get("access-control-request-headers") ?? "authorization, content-type",
           "access-control-max-age": "600",
@@ -531,6 +693,7 @@ export class McpRouter {
     if (!origin || !this.#originAllowed(req)) return res;
     res.headers.set("access-control-allow-origin", origin);
     res.headers.set("vary", "origin");
+    if (res.headers.has("mcp-session-id")) res.headers.set("access-control-expose-headers", "mcp-session-id");
     return res;
   }
 
@@ -539,8 +702,8 @@ export class McpRouter {
     return { name: `${env.appName}-mcp`, version: this.#props.version ?? "0.0.0" };
   }
 
-  #result(call: McpCall, result: object, cache?: McpCacheHint) {
-    return Response.json(this.#envelope(call, result, cache));
+  #result(call: McpCall, result: object, cache?: McpCacheHint, headers?: Record<string, string>) {
+    return Response.json(this.#envelope(call, result, cache), { headers });
   }
 
   #envelope(call: McpCall, result: object, cache?: McpCacheHint) {
@@ -577,18 +740,18 @@ export class McpRouter {
     return meta && typeof meta === "object" ? (meta as Record<string, unknown>) : null;
   }
 
-  static #negotiate(requested: unknown) {
+  #negotiate(requested: unknown) {
     if (typeof requested !== "string") return MCP_LEGACY_VERSION;
-    if (MCP_SUPPORTED_VERSIONS.includes(requested as (typeof MCP_SUPPORTED_VERSIONS)[number])) return requested;
-    const [newest] = MCP_SUPPORTED_VERSIONS;
-    return requested > newest ? newest : MCP_SUPPORTED_VERSIONS[MCP_SUPPORTED_VERSIONS.length - 1];
+    if (this.#versions.includes(requested as McpProtocolVersion)) return requested;
+    const [newest] = this.#versions;
+    return requested > newest ? newest : this.#versions[this.#versions.length - 1];
   }
 
-  static #methodNotFound(method: string) {
-    return `Method not found: ${method}. This server speaks MCP ${MCP_SUPPORTED_VERSIONS.join(", ")}.`;
+  #methodNotFound(method: string) {
+    return `Method not found: ${method}. This server speaks MCP ${this.#versions.join(", ")}.`;
   }
 
-  static #validateModern(
+  #validateModern(
     req: Request,
     method: string,
     params: Record<string, unknown>,
@@ -598,10 +761,10 @@ export class McpRouter {
     const version = meta[MCP_META_PROTOCOL_VERSION];
     if (typeof version !== "string" || !(MCP_META_CLIENT_CAPABILITIES in meta))
       return McpRouter.#error(id, McpErrorCode.invalidParams, "Missing required `_meta` fields.", { status: 400 });
-    if (!MCP_SUPPORTED_VERSIONS.includes(version as (typeof MCP_SUPPORTED_VERSIONS)[number]))
+    if (!this.#versions.includes(version as McpProtocolVersion))
       return McpRouter.#error(id, McpErrorCode.unsupportedProtocolVersion, "Unsupported protocol version.", {
         status: 400,
-        data: { requested: version, supported: MCP_SUPPORTED_VERSIONS },
+        data: { requested: version, supported: this.#versions },
       });
     const named = params.name ?? params.uri;
     const mismatch =

package/server/ops/opsToken.ts

@@ -1,4 +1,5 @@
-import { createPublicKey, type KeyObject, verify } from "node:crypto";
+import { type KeyObject, verify } from "node:crypto";
+import { Ed25519Key } from "../ed25519Key";
 
 export interface OpsTokenClaims {
   aud: string;
@@ -29,15 +30,7 @@ export class OpsTokenVerifier {
   }
 
   static parsePublicKey(value: string): KeyObject {
-    const trimmed = value.trim();
-    if (trimmed.startsWith("{")) return createPublicKey({ key: JSON.parse(trimmed) as JsonWebKey, format: "jwk" });
-    const pem = trimmed.includes("-----BEGIN") ? trimmed.replace(/\\n/g, "\n") : null;
-    if (pem) return createPublicKey(pem);
-    const raw = Buffer.from(trimmed, "base64url");
-    if (raw.length === 32)
-      return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") }, format: "jwk" });
-    if (raw.length === 44) return createPublicKey({ key: raw, format: "der", type: "spki" });
-    throw new Error("AKAN_OPS_PUBLIC_KEY must be a PEM, a JWK, base64 SPKI DER, or a raw 32-byte base64url key");
+    return Ed25519Key.parsePublic(value, "AKAN_OPS_PUBLIC_KEY");
   }
 
   verifyRequest(req: Request, nowSec = Math.floor(Date.now() / 1000)): OpsTokenVerdict {

package/server/resolver/database.resolver.ts

@@ -31,6 +31,7 @@ import {
   DatabaseAdaptorRole,
   type DocumentStore,
   ServiceModel,
+  type UpsertByIdOptions,
 } from "akanjs/service";
 import { Exception, getCurrentTrace, traceDataLoaderBatch } from "akanjs/signal";
 
@@ -293,6 +294,8 @@ export class DatabaseResolver {
           updateById: (id: string, update: DocumentUpdateInput, options?: DocumentUpdateOptions) =>
             timedQuery(() => store.updateOneByQuery({ id }, update, options)),
           removeById: (id: string) => timedQuery(() => store.removeOneByQuery({ id })),
+          upsertById: (data: Record<string, unknown> & { id: string }, options?: UpsertByIdOptions) =>
+            timedQuery(() => store.upsertById(data, options)),
           
           countDocuments: (query: QueryOf<any>) => timedQuery(() => store.count(query)),
           bulkWrite: (