ankka 0.12.0 → 0.13.0

package/dist/mcp-endpoint.js

@@ -0,0 +1,256 @@
+// An MCP endpoint (protocol 1.20): a path, an access rule and a table of tools, which the platform
+// serves to any MCP client over Streamable HTTP. The platform answers the protocol, verifies the
+// credential (a client key or a token), checks the arguments against each tool's schema and asks this
+// process to run the tool; the process never sees the credential, only the principal it stood for.
+//
+//   export class CartMcp extends McpEndpoint {
+//     static readonly path = "/mcp"
+//     static readonly acl = Acl.anyOf(Acl.clientKeys, Acl.authenticated)
+//     static readonly tools = tools<CartMcp>()
+//       .tool("get_cart", "Reads one cart", s.record("GetCart", { cartId: s.string }), Cart,
+//             (args, ep) => ep.client.of(ShoppingCart, args.cartId).call(ShoppingCart.handlers.getCart).invoke())
+//       .command("checkout", "Checks a cart out", ShoppingCart, "checkout", { id: "cartId" })
+//   }
+//
+// A tool is either run by this process's own function, or a reference to a component's handler or to
+// a route of one of this service's endpoints. References are resolved at registration, so one that
+// names something not registered stops the service before it starts.
+var _a;
+import { codecFor, isCodec } from "./codec.js";
+import { Endpoint } from "./endpoint.js";
+import { isAcl, parseTemplate } from "./routes.js";
+import { resolve, toJsonSchema } from "./schema.js";
+/** The first protocol whose runtime serves a process's MCP endpoint. */
+export const MCP_ENDPOINTS_SINCE = "1.20";
+/** What a tool name may be: what MCP clients accept everywhere. */
+export const TOOL_NAME = /^[a-z0-9_-]{1,128}$/;
+/**
+ * The base of an MCP endpoint. One instance serves every call, so the call's principal and caller are
+ * on `this.request`, as for an HTTP endpoint; `client`, `secrets`, `services` and `clientKeys` likewise.
+ */
+export class McpEndpoint extends Endpoint {
+}
+/** The tools of an MCP endpoint, built as `tools<CartMcp>().tool(...).command(...)`. */
+export class ToolTable {
+    declared;
+    constructor(declared = []) {
+        this.declared = Object.freeze([...declared]);
+        Object.freeze(this);
+    }
+    #with(tool) {
+        return new _a([...this.declared, Object.freeze(tool)]);
+    }
+    /**
+     * A tool this process runs: its arguments decoded with `input` (a record schema becomes the tool's
+     * object schema), its answer encoded with `reply` (a string answers as text; an object also as
+     * structured content). A thrown error or a refusal is the tool error the client is shown.
+     */
+    tool(name, description, input, reply, run, options) {
+        return this.#with({ kind: "tool", name, description, input, reply, run: run, acl: options?.acl });
+    }
+    /** A tool that runs a command of a component, by its wire name: `command("checkout", "...", ShoppingCart, "checkout", { id: "cartId" })`. */
+    command(name, description, component, handler, options) {
+        return this.#reference("command", name, description, component, handler, options);
+    }
+    /** A tool that runs a query of a component; it cannot change anything. */
+    query(name, description, component, handler, options) {
+        return this.#reference("query", name, description, component, handler, options);
+    }
+    /** A tool that calls a route of one of this service's endpoints, in process: its path names are the arguments, and `body` the body. */
+    route(name, description, endpoint, method, path, options) {
+        return this.#with({ kind: "route", name, description, endpoint, method, path, acl: options?.acl });
+    }
+    #reference(kind, name, description, component, handler, options) {
+        const wire = typeof handler === "string" ? handler : handler?.name;
+        return this.#with({ kind, name, description, component, handler: wire, id: options?.id, input: options?.input, acl: options?.acl });
+    }
+}
+_a = ToolTable;
+/** An empty tool table to build on. */
+export function tools() {
+    return new ToolTable();
+}
+function hasTokens(acl) {
+    if (acl === "authenticated")
+        return true;
+    return typeof acl === "object" && acl.kind === "anyOf" && acl.acls.some(hasTokens);
+}
+function objectSchema(properties, required) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+/** The JSON Schema of a tool's own input: an object schema, whatever the shape (a codec admits any object). */
+function inputSchemaOf(input) {
+    if (isCodec(input))
+        return { type: "object" };
+    const schema = toJsonSchema(input);
+    if (schema.type !== "object")
+        return `its input must be a record, so its arguments are an object; it is ${String(resolve(input).kind)}`;
+    return schema;
+}
+/**
+ * Resolves an MCP endpoint class against the registered components and endpoints, collecting every
+ * problem. A reference to a component or route that is not registered is refused here, before start.
+ */
+export function registerMcpEndpoint(cls, components, endpoints, problems) {
+    const name = typeof cls === "function" && cls.name ? cls.name : String(cls);
+    let ok = true;
+    const fail = (m) => {
+        problems.push(`${name}: ${m}`);
+        ok = false;
+    };
+    const path = cls.path;
+    if (typeof path !== "string" || !path.startsWith("/") || (path.length > 1 && path.endsWith("/")) || path.includes("{")) {
+        fail(`needs a static path starting with "/", with no parameters and not ending with "/", not ${JSON.stringify(path)}`);
+    }
+    else if (path.startsWith("/_ankka/"))
+        fail(`path ${path} is the platform's`);
+    if (!isAcl(cls.acl))
+        fail("needs a static acl — Acl.clientKeys, Acl.authenticated, Acl.anyOf(...) or another rule. An unstated access rule is a decision nobody made");
+    if (cls.brokered !== undefined && typeof cls.brokered !== "boolean")
+        fail("brokered must be true or false");
+    if (cls.brokered === true && isAcl(cls.acl) && !hasTokens(cls.acl))
+        fail("is brokered, which signs people in with the service's issuer; its acl must admit Acl.authenticated");
+    for (const [what, value] of [["serverName", cls.serverName], ["serverVersion", cls.serverVersion]]) {
+        if (value !== undefined && (typeof value !== "string" || value.trim() === ""))
+            fail(`${what} must be a non-empty string`);
+    }
+    const table = cls.tools;
+    if (!(table instanceof ToolTable)) {
+        fail("needs a static tools table: tools().tool(...)");
+        return undefined;
+    }
+    if (table.declared.length === 0)
+        fail("declares no tool; an MCP endpoint needs at least one");
+    const resolved = [];
+    const seen = new Set();
+    for (const t of table.declared) {
+        const where = `tool '${t.name}'`;
+        if (typeof t.name !== "string" || !TOOL_NAME.test(t.name)) {
+            fail(`tool '${String(t.name)}' is not a tool name ([a-z0-9_-]+, at most 128 characters)`);
+            continue;
+        }
+        if (seen.has(t.name))
+            fail(`declares the tool '${t.name}' twice`);
+        seen.add(t.name);
+        if (typeof t.description !== "string" || t.description.trim() === "")
+            fail(`${where} needs a description; it is what a model reads to choose it`);
+        if (t.acl !== undefined && !isAcl(t.acl))
+            fail(`${where}: unknown acl ${JSON.stringify(t.acl)}`);
+        const tool = resolveTool(t, where, components, endpoints, fail);
+        if (tool)
+            resolved.push(tool);
+    }
+    if (!ok)
+        return undefined;
+    return Object.freeze({
+        id: name,
+        cls,
+        path,
+        acl: cls.acl,
+        tools: Object.freeze(resolved),
+        brokered: cls.brokered === true,
+        serverName: cls.serverName,
+        serverVersion: cls.serverVersion,
+    });
+}
+function resolveTool(t, where, components, endpoints, fail) {
+    const base = { name: t.name, description: t.description, acl: t.acl };
+    switch (t.kind) {
+        case "tool": {
+            if (typeof t.run !== "function") {
+                fail(`${where}: the handler is not a function`);
+                return undefined;
+            }
+            const schema = typeof t.input === "object" && t.input !== null ? inputSchemaOf(t.input) : "it needs an input shape";
+            if (typeof schema === "string") {
+                fail(`${where}: ${schema}`);
+                return undefined;
+            }
+            return Object.freeze({ ...base, inputSchema: schema, run: Object.freeze({ kind: "function", input: t.input, reply: t.reply, run: t.run }) });
+        }
+        case "command":
+        case "query": {
+            const componentId = t.component?.componentId;
+            const registered = typeof componentId === "string" ? components.get(componentId) : undefined;
+            if (!registered || registered.cls !== t.component) {
+                fail(`${where} refers to the component ${typeof componentId === "string" ? componentId : String(t.component)}, which is not registered`);
+                return undefined;
+            }
+            if (registered.kind !== "event-sourced" && registered.kind !== "key-value" && registered.kind !== "workflow") {
+                fail(`${where} refers to ${registered.id}, a ${registered.kind}; a reference names an entity's or a workflow's handler`);
+                return undefined;
+            }
+            const handler = registered.handlers.get(t.handler);
+            if (!handler) {
+                fail(`${where} refers to the handler '${String(t.handler)}' of ${registered.id}, which it does not declare`);
+                return undefined;
+            }
+            if (t.kind === "query" && !handler.readOnly)
+                fail(`${where} is a query of '${handler.name}', which is a command`);
+            if (t.kind === "command" && handler.readOnly)
+                fail(`${where} is a command of '${handler.name}', which is a query; declare it with query(...)`);
+            if (handler.streaming)
+                fail(`${where} refers to '${handler.name}', which streams; a tool answers once`);
+            if (typeof t.id !== "string" || t.id.trim() === "") {
+                fail(`${where} needs the argument that names the ${registered.kind === "workflow" ? "workflow" : "entity"}: { id: "cartId" }`);
+                return undefined;
+            }
+            const properties = { [t.id]: { type: "string", description: `The id of the ${registered.id}` } };
+            const required = [t.id];
+            let input;
+            if (handler.input !== undefined) {
+                const shape = handler.input;
+                const json = isCodec(shape) ? { type: "object" } : toJsonSchema(shape);
+                if (t.input !== undefined || json.type !== "object" || isCodec(shape)) {
+                    const argument = t.input ?? "input";
+                    if (argument === t.id)
+                        fail(`${where}: the id and the input are both the argument '${argument}'`);
+                    properties[argument] = json;
+                    required.push(argument);
+                    input = { kind: "argument", name: argument };
+                }
+                else {
+                    const fields = (json.properties ?? {});
+                    if (t.id in fields)
+                        fail(`${where}: the input has a field '${t.id}', which is the id's argument; name the input with { input: "..." }`);
+                    Object.assign(properties, fields);
+                    required.push(...(json.required ?? []));
+                    input = { kind: "merge" };
+                }
+            }
+            else if (t.input !== undefined)
+                fail(`${where} names an input argument, but '${handler.name}' takes no input`);
+            return Object.freeze({
+                ...base,
+                inputSchema: objectSchema(properties, required),
+                run: Object.freeze({ kind: "handler", componentKind: registered.kind, componentId: registered.id, handler, id: t.id, input }),
+            });
+        }
+        case "route": {
+            const endpoint = [...endpoints.values()].find((e) => e.cls === t.endpoint);
+            if (!endpoint) {
+                fail(`${where} refers to the endpoint ${typeof t.endpoint === "function" ? t.endpoint.name : String(t.endpoint)}, which is not registered`);
+                return undefined;
+            }
+            const relative = typeof t.path === "string" && t.path.startsWith(endpoint.prefix) ? t.path.slice(endpoint.prefix === "/" ? 0 : endpoint.prefix.length) || "/" : undefined;
+            const route = relative === undefined ? undefined : [...endpoint.routes.values()].find((r) => r.method === t.method && r.template === relative);
+            if (!route) {
+                fail(`${where} refers to ${t.method} ${t.path}, which ${endpoint.id} does not declare`);
+                return undefined;
+            }
+            if (route.streaming || route.socket) {
+                fail(`${where} refers to ${t.method} ${t.path}, which streams; a tool answers once`);
+                return undefined;
+            }
+            const paramNames = parseTemplate(route.template);
+            const properties = Object.fromEntries(paramNames.map((n) => [n, { type: "string" }]));
+            if (route.body !== undefined)
+                properties.body = { type: "object" };
+            return Object.freeze({ ...base, inputSchema: objectSchema(properties, [...paramNames]), run: Object.freeze({ kind: "route", endpointId: endpoint.id, route, paramNames }) });
+        }
+    }
+}
+/** The codec a tool's own reply is encoded with, when it declares one. */
+export function replyCodecOf(reply) {
+    return reply === undefined ? undefined : codecFor(reply);
+}

package/dist/routes.d.ts

@@ -36,25 +36,48 @@ export interface CallersAcl {
     readonly kind: "callers";
     readonly callers: readonly CallerMatcher[];
 }
+/** Admitted when any of `acls` admits: an MCP endpoint's rule (protocol 1.20), `Acl.anyOf(Acl.clientKeys, Acl.authenticated)`. */
+export interface AnyOfAcl {
+    readonly kind: "anyOf";
+    readonly acls: readonly Acl[];
+}
 /**
  * Who may call: everyone, no one, authenticated callers only, or only the callers named. There is no default.
+ * An MCP endpoint may also admit a client key issued for it (`Acl.clientKeys`), and any of several rules
+ * (`Acl.anyOf`); an HTTP endpoint refuses both at registration.
  *
  * Outside a cluster every caller is `{ kind: "local" }`, and `allowCallers` admits it.
  */
-export type Acl = "allow-all" | "deny-all" | "authenticated" | CallersAcl;
+export type Acl = "allow-all" | "deny-all" | "authenticated" | "client-keys" | CallersAcl | AnyOfAcl;
 export declare const Acl: Readonly<{
     allowAll: Acl;
     denyAll: Acl;
     authenticated: Acl;
+    /** A client key issued for the MCP endpoint (protocol 1.20); its subject and attributes are the principal. */
+    clientKeys: Acl;
     allowCallers(first: CallerMatcher, ...rest: CallerMatcher[]): Acl;
+    /** Admitted when any of the rules admits; for an MCP endpoint or one of its tools. */
+    anyOf(first: Acl, ...rest: Acl[]): Acl;
 }>;
-/** Whether `x` is an access rule: one of the three words, or a non-empty callers rule. */
+/** Whether `x` is an access rule: one of the words, a non-empty callers rule, or a non-empty `anyOf` of rules. */
 export declare function isAcl(x: unknown): x is Acl;
+/** Whether `acl` is one an HTTP endpoint or route can state: neither client keys nor `anyOf`, which are an MCP endpoint's. */
+export declare function isEndpointAcl(acl: Acl): boolean;
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export declare class HttpProblem extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * @internal An answer whose status and content type the handler chooses, its body as given: the
+ * directory store's objects, served under the content type each was kept with.
+ */
+export declare class RawReply {
+    readonly status: number;
+    readonly contentType: string;
+    readonly body: Uint8Array;
+    constructor(status: number, contentType: string, body: Uint8Array);
+}
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 type MaybePromise<T> = T | Promise<T>;
 /** The parameter names in a template: `ParamNames<"/{cartId}/items/{productId}">` is `"cartId" | "productId"`. */

package/dist/routes.js

@@ -28,19 +28,31 @@ export const Acl = Object.freeze({
     allowAll: "allow-all",
     denyAll: "deny-all",
     authenticated: "authenticated",
+    /** A client key issued for the MCP endpoint (protocol 1.20); its subject and attributes are the principal. */
+    clientKeys: "client-keys",
     allowCallers(first, ...rest) {
         return Object.freeze({ kind: "callers", callers: Object.freeze([first, ...rest]) });
     },
+    /** Admitted when any of the rules admits; for an MCP endpoint or one of its tools. */
+    anyOf(first, ...rest) {
+        return Object.freeze({ kind: "anyOf", acls: Object.freeze([first, ...rest]) });
+    },
 });
-/** Whether `x` is an access rule: one of the three words, or a non-empty callers rule. */
+/** Whether `x` is an access rule: one of the words, a non-empty callers rule, or a non-empty `anyOf` of rules. */
 export function isAcl(x) {
-    if (x === "allow-all" || x === "deny-all" || x === "authenticated")
+    if (x === "allow-all" || x === "deny-all" || x === "authenticated" || x === "client-keys")
         return true;
     if (typeof x !== "object" || x === null)
         return false;
     const rule = x;
+    if (rule.kind === "anyOf")
+        return Array.isArray(rule.acls) && rule.acls.length > 0 && rule.acls.every(isAcl);
     return rule.kind === "callers" && Array.isArray(rule.callers) && rule.callers.length > 0;
 }
+/** Whether `acl` is one an HTTP endpoint or route can state: neither client keys nor `anyOf`, which are an MCP endpoint's. */
+export function isEndpointAcl(acl) {
+    return acl !== "client-keys" && !(typeof acl === "object" && acl.kind === "anyOf");
+}
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export class HttpProblem extends Error {
     status;
@@ -50,6 +62,21 @@ export class HttpProblem extends Error {
         this.status = status;
     }
 }
+/**
+ * @internal An answer whose status and content type the handler chooses, its body as given: the
+ * directory store's objects, served under the content type each was kept with.
+ */
+export class RawReply {
+    status;
+    contentType;
+    body;
+    constructor(status, contentType, body) {
+        this.status = status;
+        this.contentType = contentType;
+        this.body = body;
+        Object.freeze(this);
+    }
+}
 const TEMPLATE = /^(\/(?:[^/{}]+|\{[A-Za-z_][A-Za-z0-9_]*\})?)*$/;
 export function parseTemplate(template) {
     if (typeof template !== "string" || !template.startsWith("/") || !TEMPLATE.test(template) || template.includes("//")) {

package/dist/server/discovery.d.ts

@@ -6,6 +6,8 @@ import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
  * naming what declares them, rather than served wrong.
  */
 export declare function refusal(spec: Spec, sidecarProtocol: string): string | undefined;
+/** The protocol version whose runtimes admit a process's endpoint at `/_ankka/storage`. */
+export declare const STORAGE_SINCE: readonly [number, number];
 /** Every problem the sidecar has reported to this process, in order. */
 export declare const problems: string[];
 export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void): void;
@@ -19,3 +21,8 @@ export declare const GRANTS_SINCE: readonly [number, number];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
  * does not know `Callers.granted`, and would admit nobody by it. */
 export declare function grantsRefusal(spec: Spec, runtime: string): string | undefined;
+/** The protocol version whose runtimes serve a process's MCP endpoint. */
+export declare const MCP_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20
+ * does not know an MCP endpoint, and would serve nothing at its path. */
+export declare function mcpRefusal(spec: Spec, runtime: string): string | undefined;

package/dist/server/discovery.js

@@ -7,6 +7,7 @@ import { Discovery } from "../_proto/ankka/protocol/v1/discovery_pb.js";
 import { EmptySchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 import { PROTOCOL_VERSION } from "../spec.js";
 import { Kind } from "../_proto/ankka/protocol/v1/discovery_pb.js";
+import { STORAGE_PATH } from "../storage.js";
 import { olderThan, olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions, olderThanViewStreams, olderThanWorkflowSources } from "../startFrom.js";
 /**
  * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
@@ -137,16 +138,26 @@ function startPositionRefusal(spec, sidecarProtocol) {
     return (`${declaring.join(", ")} declare where a topic source starts or its version, which the sidecar ignores: ` +
         `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.7 or later.`);
 }
+/** The protocol version whose runtimes admit a process's endpoint at `/_ankka/storage`. */
+export const STORAGE_SINCE = [1, 21];
 /** Every problem the sidecar has reported to this process, in order. */
 export const problems = [];
 export function discoveryRoutes(router, spec, log = console.error) {
     router.service(Discovery, {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
-            const answer = spec();
+            let answer = spec();
+            // A runtime before 1.21 refuses a process's endpoint under /_ankka; the directory store's URLs then
+            // go unanswered, and nothing else of the store needs the runtime.
+            if (olderThan(info.protocolVersion, STORAGE_SINCE) && answer.endpoints.some((e) => e.prefix === STORAGE_PATH)) {
+                log(`ankka: the sidecar speaks protocol ${info.protocolVersion}; the directory store's URLs at ${STORAGE_PATH} need 1.21 and are not served`);
+                answer = { ...answer, endpoints: answer.endpoints.filter((e) => e.prefix !== STORAGE_PATH) };
+            }
             const why = refusal(answer, info.protocolVersion) ??
                 socketRefusal(answer, info.protocolVersion) ??
-                grantsRefusal(answer, info.protocolVersion);
+                grantsRefusal(answer, info.protocolVersion) ??
+                // Last: an older runtime is told the oldest thing it lacks first.
+                mcpRefusal(answer, info.protocolVersion);
             if (why !== undefined) {
                 log(`ankka: ${why}`);
                 problems.push(why);
@@ -200,3 +211,16 @@ export function grantsRefusal(spec, runtime) {
         return undefined;
     return `this runtime speaks protocol ${runtime || "unknown"}; granted callers and another project's topics need 1.15 (${endpoints.join(", ")})`;
 }
+/** The protocol version whose runtimes serve a process's MCP endpoint. */
+export const MCP_SINCE = [1, 20];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20
+ * does not know an MCP endpoint, and would serve nothing at its path. */
+export function mcpRefusal(spec, runtime) {
+    if (spec.mcpEndpoints.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > MCP_SINCE[0] || (speaks[0] === MCP_SINCE[0] && speaks[1] >= MCP_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; an MCP endpoint needs 1.20 (${spec.mcpEndpoints.map((e) => e.path).join(", ")})`;
+}

package/dist/server/http.d.ts

@@ -1,6 +1,14 @@
 import type { ConnectRouter } from "@connectrpc/connect";
 import { type HttpRequest, type HttpReply, type SocketIn, type SocketOut, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
+import { type Caller, type Principal } from "../context.ts";
+import { type Schema } from "../schema.ts";
 import type { ServerContext } from "./server.ts";
+/** The principal the sidecar verified, for a route or a tool call; never the credential. */
+export declare function principalOf(req: Pick<HttpRequest, "principal">): Principal | null;
+/** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
+export declare function callerOf(req: Pick<HttpRequest, "caller">): Caller;
+/** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
+export declare function parseParam(name: string, text: string, shape: Schema | undefined): unknown;
 export interface HttpDispatcher {
     handle(req: HttpRequest): Promise<HttpReply>;
     handleStream(req: HttpRequest): AsyncIterable<StreamFrame>;

package/dist/server/http.js

@@ -11,7 +11,7 @@ import { Headers, Query, metadataFromProto, withRequest } from "../context.js";
 import { CommandError, ErrorCode, httpStatusOf } from "../effects/common.js";
 import { DecodingError } from "../json.js";
 import { errorCodeToProto } from "../kinds.js";
-import { HttpProblem } from "../routes.js";
+import { HttpProblem, RawReply } from "../routes.js";
 import { done, resolve } from "../schema.js";
 import { SocketClosed, socketOf } from "../socket.js";
 import { AsyncQueue } from "./queue.js";
@@ -25,7 +25,8 @@ function failureReply(message) {
 function messageOf(e) {
     return e instanceof Error ? e.message : String(e);
 }
-function principalOf(req) {
+/** The principal the sidecar verified, for a route or a tool call; never the credential. */
+export function principalOf(req) {
     const p = req.principal;
     if (!p)
         return null;
@@ -40,7 +41,7 @@ function principalOf(req) {
     });
 }
 /** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
-function callerOf(req) {
+export function callerOf(req) {
     const kind = req.caller?.kind;
     switch (kind?.case) {
         case "gateway":
@@ -54,7 +55,7 @@ function callerOf(req) {
     }
 }
 /** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
-function parseParam(name, text, shape) {
+export function parseParam(name, text, shape) {
     if (!shape)
         return text;
     const r = resolve(shape);
@@ -71,6 +72,9 @@ function parseParam(name, text, shape) {
     }
 }
 function encodeResult(route, result) {
+    if (result instanceof RawReply) {
+        return create(HttpReplySchema, { message: { case: "response", value: { status: result.status, contentType: result.contentType, body: result.body, headers: [] } } });
+    }
     if (result === undefined || result === done) {
         return create(HttpReplySchema, { message: { case: "response", value: { status: 204, contentType: "", body: new Uint8Array(), headers: [] } } });
     }
@@ -93,6 +97,8 @@ export function createHttpDispatcher(ctx) {
         if (!instance) {
             instance = new endpoint.cls();
             instance._bindClient(ctx.client);
+            if (ctx.storage)
+                instance.storage = ctx.storage;
             instances.set(endpoint.id, instance);
         }
         try {

package/dist/server/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type McpToolReply, type McpToolRequest } from "../_proto/ankka/protocol/v1/mcp_pb.ts";
+import { type Shape } from "../codec.ts";
+import type { ServerContext } from "./server.ts";
+/** What a tool answered: its text, and the same as structured content when it is a JSON object. */
+export interface ToolAnswer {
+    readonly text: string;
+    readonly structuredJson?: string;
+}
+/** A tool's result as text and structured content, encoded with its reply shape when it has one. */
+export declare function answerOf(value: unknown, reply: Shape<unknown> | undefined): ToolAnswer;
+export interface McpDispatcher {
+    invokeTool(req: McpToolRequest): Promise<McpToolReply>;
+}
+/** The behaviour behind `Mcp.InvokeTool`, over the registry's MCP endpoints. */
+export declare function createMcpDispatcher(ctx: ServerContext): McpDispatcher;
+export declare function mcpRoutes(router: ConnectRouter, ctx: ServerContext): void;