@aventara/nest 0.1.0-pilot.4 → 1.0.0-rc.1

package/dist/aventara.module.d.ts

@@ -1,24 +1,35 @@
-import { type AdapterModel, type AnyFrameworkConfig, type Framework, type FrameworkConfig } from "@aventara/core";
+import { type AvAdapterModel, type AvConfig, type AvConfigAny, type AvConfigExact, type AvFramework, type AvState } from "@aventara/core";
 import { type DynamicModule, type FactoryProvider, type ModuleMetadata, type NestModule, type OnModuleInit } from "@nestjs/common";
 import { type PendingProtocolHost } from "./protocol-host.factory.js";
 /**
  * How the application's Framework enters Nest: your own instance
  * (`{ framework }`, from `createFramework`) or a configuration the module
- * passes to `createFramework` itself (`{ config }`). Pass exactly one.
+ * passes to `createFramework` itself (`{ config }`). Pass exactly one. Either
+ * arm may add `state`, which seeds each protocol request's `ctx.$state`.
  */
-export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
-    readonly framework: Framework;
+export type AventaraModuleOptions<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = ({
+    readonly framework: AvFramework;
     readonly config?: never;
 } | {
-    readonly config: Cfg & FrameworkConfig<M, Cfg>;
+    readonly config: Cfg & AvConfig<M, Cfg> & AvConfigExact<M, Cfg>;
     readonly framework?: never;
+}) & {
+    /**
+     * Seeds a protocol request's `ctx.$state`, once per request, with the
+     * platform's own request: Express's `req`, or Fastify's `request` (its Node
+     * request is `request.raw`). What middleware already set there, such as
+     * Passport's `req.user`, flows into every stage of the request. A throw is
+     * answered like any developer failure: a thrown `AvError` as its own
+     * outcome, anything else `500 A3000`. Omitted, the state is `{}`.
+     */
+    state?(request: unknown): AvState | Promise<AvState>;
 };
 /**
  * `forRootAsync`'s options: the Nest idiom when what builds the Framework
  * (a Prisma client, a configuration service) is itself a provider. The
  * factory resolves to either arm of {@link AventaraModuleOptions}.
  */
-export type AventaraModuleAsyncOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+export type AventaraModuleAsyncOptions<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny> = {
     /** Modules whose providers the factory injects. */
     readonly imports?: ModuleMetadata["imports"];
     /** The providers passed to `useFactory`, in order. */
@@ -43,11 +54,11 @@ export declare class AventaraModule implements NestModule, OnModuleInit {
      */
     onModuleInit(): void;
     /** Registers the module with a Framework instance or a configuration. */
-    static forRoot<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleOptions<M, Cfg>): DynamicModule;
+    static forRoot<M extends AvAdapterModel, const Cfg = AvConfigAny>(options: AventaraModuleOptions<M, Cfg>): DynamicModule;
     /**
      * Registers the module with options built by a factory, for when the
      * Framework's inputs (a Prisma client, a config service) are providers.
      */
-    static forRootAsync<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleAsyncOptions<M, Cfg>): DynamicModule;
+    static forRootAsync<M extends AvAdapterModel, const Cfg = AvConfigAny>(options: AventaraModuleAsyncOptions<M, Cfg>): DynamicModule;
     private static mount;
 }

package/dist/aventara.module.js

@@ -4,12 +4,14 @@ import { HttpAdapterHost } from "@nestjs/core";
 import { AVENTARA_FRAMEWORK } from "./framework.token.js";
 import { checkedOptions, recordMount } from "./host-bootstrap.validator.js";
 import { withInternalFailureLog } from "./internal-failure.logger.js";
+import { loadMcpBinding } from "./mcp-binding.loader.js";
 import { createPendingProtocolHost, } from "./protocol-host.factory.js";
 const MOUNT = Symbol("AVENTARA_MOUNT");
 let mounts = 0;
 const PROTOCOL_HOST = Symbol("AVENTARA_PROTOCOL_HOST");
-async function frameworkOf(options) {
-    const checked = checkedOptions(options);
+const OPTIONS = Symbol("AVENTARA_OPTIONS");
+const MCP_BINDING = Symbol("AVENTARA_MCP_BINDING");
+async function frameworkOf(checked) {
     if (checked.framework !== undefined) {
         return checked.framework;
     }
@@ -44,17 +46,27 @@ export class AventaraModule {
             providers: [
                 { provide: MOUNT, useValue: mounts },
                 {
-                    provide: AVENTARA_FRAMEWORK,
+                    provide: OPTIONS,
                     inject: [HttpAdapterHost, ...inject],
                     useFactory: async (application, ...deps) => {
                         recordMount(application);
-                        return frameworkOf(await resolve(...deps));
+                        return checkedOptions(await resolve(...deps));
                     },
                 },
+                {
+                    provide: AVENTARA_FRAMEWORK,
+                    inject: [OPTIONS],
+                    useFactory: (options) => frameworkOf(options),
+                },
+                {
+                    provide: MCP_BINDING,
+                    inject: [AVENTARA_FRAMEWORK],
+                    useFactory: async (framework) => (await loadMcpBinding(framework)) ?? null,
+                },
                 {
                     provide: PROTOCOL_HOST,
-                    inject: [HttpAdapterHost, AVENTARA_FRAMEWORK],
-                    useFactory: (application, framework) => createPendingProtocolHost(application, framework),
+                    inject: [HttpAdapterHost, AVENTARA_FRAMEWORK, OPTIONS, MCP_BINDING],
+                    useFactory: (application, framework, options, mcp) => createPendingProtocolHost(application, framework, options.state?.bind(options), mcp ?? undefined),
                 },
             ],
             exports: [AVENTARA_FRAMEWORK],

package/dist/express-protocol.mounter.d.ts

@@ -1,16 +1,25 @@
 import type { AvProtocolBinding } from "@aventara/core/protocol";
+import type { McpBinding } from "./mcp-binding.loader.js";
 import { type NodeIncoming, type NodeOutgoing } from "./node-exchange.translator.js";
-import type { ProtocolHost } from "./protocol-host.factory.js";
+import type { HostState, ProtocolHost } from "./protocol-host.factory.js";
 /**
  * The protocol on Nest's Express platform: one platform route per protocol
  * route under the entrypoint, translating the Express request into the
  * protocol's request and the protocol's response back onto the wire. A path the
  * protocol does not own goes on to Nest.
  */
-/** Express's request: Node's `IncomingMessage`, plus `originalUrl`. */
+/**
+ * Express's request: Node's `IncomingMessage`, plus `originalUrl`, and the
+ * protocol and host Express reports (its `trust proxy` setting applied).
+ */
 type ExpressRequest = NodeIncoming & {
     readonly method: string;
     readonly originalUrl: string;
+    readonly protocol: string;
+    readonly host: string;
+    readonly socket: {
+        readonly remoteAddress?: string | undefined;
+    };
 };
 /** Express's response, written through Node's own `writeHead`. */
 type ExpressResponse = NodeOutgoing;
@@ -19,11 +28,12 @@ type ExpressHandler = (request: ExpressRequest, response: ExpressResponse, next?
 export type ExpressPlatform = {
     get(path: string, handler: ExpressHandler): unknown;
     post(path: string, handler: ExpressHandler): unknown;
+    delete(path: string, handler: ExpressHandler): unknown;
     use(handler: ExpressHandler): unknown;
 };
 /**
  * Installs the pre-parser on `platform` now, and returns the host whose
  * `mount` registers the routes and the absence fallback under `entrypoint`.
  */
-export declare function createExpressProtocolHost(platform: ExpressPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number): ProtocolHost;
+export declare function createExpressProtocolHost(platform: ExpressPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number, state: HostState | undefined, mcp: McpBinding | undefined): ProtocolHost;
 export {};

package/dist/express-protocol.mounter.js

@@ -1,25 +1,42 @@
-import { NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
-import { PROTOCOL_ROUTES } from "./protocol-route.table.js";
+import { mcpRequest, NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
+import { MCP_ROUTES, PROTOCOL_ROUTES, } from "./protocol-route.table.js";
 import { readRequestBody, unreadBodyAnswer, } from "./request-body.reader.js";
-const REGISTER = { GET: "get", POST: "post" };
+const REGISTER = { GET: "get", POST: "post", DELETE: "delete" };
 const NOTHING_READ = { kind: "read", content: NO_BYTES };
-export function createExpressProtocolHost(platform, binding, entrypoint, maxRequestBytes) {
+export function createExpressProtocolHost(platform, binding, entrypoint, maxRequestBytes, state, mcp) {
     const bodies = new WeakMap();
     const bodyOf = (request) => bodies.get(request) ?? NOTHING_READ;
+    const mcpEndpoint = mcp
+        ?.surface()
+        .find((route) => route.kind === "endpoint")?.path;
+    const namespace = asciiLowerCase(`${entrypoint}/_`);
     platform.use(async (request, _response, next) => {
-        if (pathnameOf(request.originalUrl).startsWith(`${entrypoint}/_`)) {
+        const pathname = pathnameOf(request.originalUrl);
+        if (asciiLowerCase(pathname.slice(0, namespace.length)) === namespace) {
             bodies.set(request, await readRequestBody(request, request.headersDistinct["content-encoding"], maxRequestBytes));
         }
+        else if (mcp !== undefined && pathname === mcpEndpoint) {
+            bodies.set(request, await readRequestBody(request, undefined, mcp.maxRequestBytes));
+        }
         handOn(next);
     });
     return {
         mount: () => {
+            for (const route of mcp?.surface() ?? []) {
+                const answer = MCP_ROUTES[route.kind](mcp);
+                for (const method of route.methods) {
+                    platform[REGISTER[method]](literalPath(route.path), exactly(route.path, async (request, response) => {
+                        const body = bodyOf(request);
+                        writeAnswer(response, await answer(mcpRequest(request.method, request, request.originalUrl, request, body.kind === "read" ? body.content : NO_BYTES, request.socket.remoteAddress), state === undefined ? undefined : () => state(request)));
+                    }));
+                }
+            }
             for (const route of binding.surface()) {
                 const answer = PROTOCOL_ROUTES[route.kind](binding);
                 platform[REGISTER[route.method]](literalPath(`${entrypoint}${route.path}`), async (request, response) => {
                     const body = bodyOf(request);
                     writeAnswer(response, body.kind === "read"
-                        ? await answer(translated(request, entrypoint, body.content))
+                        ? await answer(translated(request, entrypoint, body.content), state === undefined ? undefined : () => state(request))
                         : unreadBodyAnswer(binding, body));
                 });
             }
@@ -39,6 +56,18 @@ export function createExpressProtocolHost(platform, binding, entrypoint, maxRequ
         },
     };
 }
+function exactly(path, handler) {
+    return (request, response, next) => {
+        if (pathnameOf(request.originalUrl) !== path) {
+            handOn(next);
+            return undefined;
+        }
+        return handler(request, response, next);
+    };
+}
+function asciiLowerCase(text) {
+    return text.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
 function handOn(next) {
     if (typeof next === "function") {
         next();

package/dist/fastify-protocol.mounter.d.ts

@@ -1,6 +1,7 @@
 import type { AvProtocolBinding } from "@aventara/core/protocol";
+import type { McpBinding } from "./mcp-binding.loader.js";
 import { type NodeIncoming, type NodeOutgoing, type PlatformHeaders } from "./node-exchange.translator.js";
-import type { ProtocolHost } from "./protocol-host.factory.js";
+import type { HostState, ProtocolHost } from "./protocol-host.factory.js";
 /**
  * The protocol on Nest's Fastify platform: one Fastify route per protocol route
  * under the entrypoint, answered from its own `onRequest` hook before Fastify's
@@ -10,13 +11,21 @@ import type { ProtocolHost } from "./protocol-host.factory.js";
  * reserved escape) is refused while Nest builds the application, naming the
  * Resource keys.
  */
-/** Fastify's request: Node's own under `raw`, and whether a route matched. */
+/**
+ * Fastify's request: Node's own under `raw`, whether a route matched, and the
+ * protocol and host Fastify reports (its `trustProxy` setting applied).
+ */
 type FastifyRequest = {
     readonly raw: NodeIncoming & {
         readonly method: string;
         readonly url: string;
+        readonly socket: {
+            readonly remoteAddress?: string | undefined;
+        };
     };
     readonly is404: boolean;
+    readonly protocol: string;
+    readonly host: string;
 };
 /** Fastify's reply: hijacked, then written through Node's response under `raw`. */
 type FastifyReply = {
@@ -27,7 +36,7 @@ type FastifyReply = {
 type OnRequestHook = (request: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply | undefined>;
 export type FastifyPlatform = {
     route(options: {
-        readonly method: string;
+        readonly method: string | readonly string[];
         readonly url: string;
         readonly exposeHeadRoute: false;
         readonly onRequest: OnRequestHook;
@@ -39,5 +48,5 @@ export type FastifyPlatform = {
  * The host whose `mount` registers the routes and the absence hook under
  * `entrypoint` — after refusing, now, a surface it cannot mount literally.
  */
-export declare function createFastifyProtocolHost(platform: FastifyPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number): ProtocolHost;
+export declare function createFastifyProtocolHost(platform: FastifyPlatform, binding: AvProtocolBinding, entrypoint: string, maxRequestBytes: number, state: HostState | undefined, mcp: McpBinding | undefined): ProtocolHost;
 export {};

package/dist/fastify-protocol.mounter.js

@@ -1,10 +1,10 @@
-import { NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
-import { PROTOCOL_ROUTES } from "./protocol-route.table.js";
+import { mcpRequest, NO_BYTES, pathnameOf, protocolRequest, writeAnswer, } from "./node-exchange.translator.js";
+import { MCP_ROUTES, PROTOCOL_ROUTES } from "./protocol-route.table.js";
 import { readRequestBody, unreadBodyAnswer } from "./request-body.reader.js";
 const UNMATCHABLE = /\*|%(?:3A|2B|23|24|26|2C|2F|3B|3D|3F|40)/i;
 function checkLiteralRoutes(binding, entrypoint) {
     if (entrypoint.includes("*")) {
-        throw new Error(`AventaraModule cannot mount the entrypoint \`${entrypoint}\` as a literal path on Nest's Fastify platform: it may not carry \`*\`. Change the entrypoint, or host on Express.`);
+        throw new Error(`AventaraModule cannot mount the api path \`${entrypoint}\` as a literal path on Nest's Fastify platform: it may not carry \`*\`. Change \`api\`, or host on Express.`);
     }
     const refused = binding
         .surface()
@@ -16,11 +16,35 @@ function checkLiteralRoutes(binding, entrypoint) {
         throw new Error(`AventaraModule cannot mount Resource ${refused.map((key) => `\`${key}\``).join(", ")} as literal routes on Nest's Fastify platform: a route path may not carry \`*\` or a reserved character (: + # $ & , / ; = ? @). Rename the Resource, or host on Express.`);
     }
 }
-export function createFastifyProtocolHost(platform, binding, entrypoint, maxRequestBytes) {
+function checkLiteralMcpRoutes(mcp) {
+    for (const route of mcp?.surface() ?? []) {
+        if (UNMATCHABLE.test(route.path)) {
+            throw new Error(`AventaraModule cannot mount the mcp path \`${route.path}\` as a literal path on Nest's Fastify platform: it may not carry \`*\` or a reserved escape. Change \`mcp\`, or host on Express.`);
+        }
+    }
+}
+export function createFastifyProtocolHost(platform, binding, entrypoint, maxRequestBytes, state, mcp) {
     checkLiteralRoutes(binding, entrypoint);
+    checkLiteralMcpRoutes(mcp);
     const translated = (request, content) => protocolRequest(request.raw.method, request.raw.url, request.raw, entrypoint, content);
     return {
         mount: () => {
+            for (const route of mcp?.surface() ?? []) {
+                const answer = MCP_ROUTES[route.kind](mcp);
+                platform.route({
+                    method: [...route.methods],
+                    url: literalPath(route.path),
+                    exposeHeadRoute: false,
+                    onRequest: async (request, reply) => {
+                        const body = await readRequestBody(request.raw, undefined, mcp.maxRequestBytes);
+                        write(reply, await answer(mcpRequest(request.raw.method, request, request.raw.url, request.raw, body.kind === "read" ? body.content : NO_BYTES, request.raw.socket.remoteAddress), state === undefined ? undefined : () => state(request)));
+                        return reply;
+                    },
+                    handler: () => {
+                        throw new Error("AventaraModule: an MCP route's onRequest hook answers every request; its handler is unreachable.");
+                    },
+                });
+            }
             for (const route of binding.surface()) {
                 const answer = PROTOCOL_ROUTES[route.kind](binding);
                 platform.route({
@@ -30,7 +54,7 @@ export function createFastifyProtocolHost(platform, binding, entrypoint, maxRequ
                     onRequest: async (request, reply) => {
                         const body = await readRequestBody(request.raw, request.raw.headersDistinct["content-encoding"], maxRequestBytes);
                         write(reply, body.kind === "read"
-                            ? await answer(translated(request, body.content))
+                            ? await answer(translated(request, body.content), state === undefined ? undefined : () => state(request))
                             : unreadBodyAnswer(binding, body));
                         return reply;
                     },

package/dist/framework.token.d.ts

@@ -1,6 +1,6 @@
 /**
  * The injection token under which `AventaraModule` provides the application's
- * `Framework`. Type the injected value with your own `Framework<M, Cfg>` alias.
+ * `AvFramework`. Type the injected value with your own `AvFramework<M, Cfg>` alias.
  */
 export declare const AVENTARA_FRAMEWORK: unique symbol;
 /** `@InjectFramework()`: `@Inject(AVENTARA_FRAMEWORK)` in one call. */

package/dist/host-bootstrap.validator.js

@@ -1,6 +1,7 @@
 const NEITHER_ARM = "AventaraModule: the options carry neither `framework` nor `config`; pass exactly one.";
 const BOTH_ARMS = "AventaraModule: the options carry both `framework` and `config`; pass exactly one.";
-const NOT_A_FRAMEWORK = "AventaraModule: `framework` is not an Aventara Framework (it has no string `entrypoint` and no `contracts.client`); pass what `createFramework` resolved to.";
+const NOT_A_FRAMEWORK = "AventaraModule: `framework` is not an Aventara Framework (it has no string `api` and no `contracts.client`); pass what `createFramework` resolved to.";
+const STATE_NOT_A_FUNCTION = "AventaraModule: `state` is not a function; pass `(request) => ({ … })`, called once per protocol request.";
 const MOUNTED_TWICE = "AventaraModule is mounted twice in one application; import AventaraModule.forRoot or forRootAsync once.";
 export function checkedOptions(options) {
     const record = typeof options === "object" && options !== null
@@ -17,6 +18,10 @@ export function checkedOptions(options) {
     if (hasFramework && !isFramework(record.framework)) {
         throw new Error(NOT_A_FRAMEWORK);
     }
+    const state = record.state;
+    if (state !== undefined && typeof state !== "function") {
+        throw new Error(STATE_NOT_A_FUNCTION);
+    }
     return record;
 }
 function isFramework(value) {
@@ -24,7 +29,7 @@ function isFramework(value) {
         return false;
     }
     const candidate = value;
-    return (typeof candidate.entrypoint === "string" &&
+    return (typeof candidate.api === "string" &&
         typeof candidate.contracts?.client === "object" &&
         candidate.contracts.client !== null);
 }

package/dist/internal-failure.logger.d.ts

@@ -1,8 +1,8 @@
-import type { FrameworkDiagnostic, FrameworkDiagnosticsSink } from "@aventara/core";
+import type { AvDiagnostic, AvDiagnosticsSink } from "@aventara/core";
 /** Wraps the application's sink (if any): log an internal failure, then forward. */
-export declare function withInternalFailureLog(sink: FrameworkDiagnosticsSink | undefined): FrameworkDiagnosticsSink;
+export declare function withInternalFailureLog(sink: AvDiagnosticsSink | undefined): AvDiagnosticsSink;
 /**
- * e.g. `A3001 on Post.create.one (client scope, request 7f3c…): Error. The raw
+ * e.g. `A3001 on Post.create.one (client origin, request 7f3c…): Error. The raw
  * error goes to the framework's diagnostics sink.`
  */
-export declare function internalFailureLine(diagnostic: FrameworkDiagnostic): string;
+export declare function internalFailureLine(diagnostic: AvDiagnostic): string;

package/dist/internal-failure.logger.js

@@ -15,16 +15,18 @@ export function withInternalFailureLog(sink) {
 export function internalFailureLine(diagnostic) {
     const subject = diagnostic.kind === "operation"
         ? `${diagnostic.resource}.${diagnostic.family}.${diagnostic.variant}`
-        : "a transaction";
+        : diagnostic.kind === "transaction"
+            ? "a transaction"
+            : "the MCP endpoint";
     const step = diagnostic.operation === undefined
         ? ""
         : `, plan operation ${diagnostic.operation}`;
-    return `${diagnostic.code} on ${subject} (${diagnostic.scope} scope, request ${diagnostic.requestId}${step}): ${thrownKind(diagnostic.error)}${frameworkDetail(diagnostic.error)}. The raw error goes to the framework's diagnostics sink.`;
+    return `${diagnostic.code} on ${subject} (${diagnostic.origin} origin, request ${diagnostic.requestId}${step}): ${thrownKind(diagnostic.error)}${frameworkDetail(diagnostic.error)}. The raw error goes to the framework's diagnostics sink.`;
 }
 function frameworkDetail(error) {
     try {
         if (error instanceof Error &&
-            error.name === "PipeOutputError" &&
+            error.name === "AvPipeOutputError" &&
             typeof error.message === "string") {
             return ` — ${error.message}`;
         }

package/dist/mcp-binding.loader.d.ts

@@ -0,0 +1,30 @@
+import type { AvFramework, AvState } from "@aventara/core";
+import type { AvProtocolResponse } from "@aventara/core/protocol";
+/** One request to the MCP endpoint, as `@aventara/mcp` reads it. */
+export type McpRequest = {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, readonly string[]>>;
+    readonly body: Uint8Array;
+    readonly remoteAddress: string | undefined;
+};
+/** One route the MCP binding lists. */
+export type McpRoute = {
+    readonly kind: "endpoint" | "metadata";
+    readonly path: string;
+    readonly methods: readonly ("GET" | "POST" | "DELETE")[];
+};
+export type McpBinding = {
+    readonly surface: () => readonly McpRoute[];
+    readonly maxRequestBytes: number;
+    readonly handleEndpoint: (request: McpRequest, options?: {
+        readonly state?: () => AvState | Promise<AvState>;
+    }) => Promise<AvProtocolResponse>;
+    readonly encodeMetadata: (request: McpRequest) => AvProtocolResponse;
+};
+/**
+ * The MCP binding for `framework`, or `undefined` when its configuration has no
+ * `mcp`. Called while Nest instantiates providers, so a missing package rejects
+ * `NestFactory.create` before the application listens, naming the package.
+ */
+export declare function loadMcpBinding(framework: AvFramework, specifier?: string): Promise<McpBinding | undefined>;

package/dist/mcp-binding.loader.js

@@ -0,0 +1,25 @@
+const MCP_PACKAGE = "@aventara/mcp";
+const missing = (specifier) => `AventaraModule: the configuration has \`mcp\`, and the package that serves it, ${specifier}, is not installed. Install it beside @aventara/nest, at the same version (npm install ${specifier}), or remove \`mcp\` from the configuration.`;
+function isMissing(error, specifier) {
+    const { code, message } = (error ?? {});
+    return ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") &&
+        typeof message === "string" &&
+        message.includes(`'${specifier}'`));
+}
+export async function loadMcpBinding(framework, specifier = MCP_PACKAGE) {
+    if (framework.mcp === undefined) {
+        return undefined;
+    }
+    let loaded;
+    try {
+        loaded = await import(specifier);
+    }
+    catch (error) {
+        if (isMissing(error, specifier)) {
+            throw new Error(missing(specifier));
+        }
+        throw error;
+    }
+    const { AvMcp } = loaded;
+    return AvMcp.bind(framework);
+}

package/dist/node-exchange.translator.d.ts

@@ -1,4 +1,5 @@
 import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
+import type { McpRequest } from "./mcp-binding.loader.js";
 export type NodeIncoming = AsyncIterable<Uint8Array> & {
     readonly headersDistinct: Readonly<Record<string, readonly string[]>>;
 };
@@ -14,6 +15,11 @@ export declare const NO_BYTES: Uint8Array<ArrayBuffer>;
 export declare function pathnameOf(url: string): string;
 /** The request as the protocol reads it: path relative to the entrypoint, distinct headers, raw body. */
 export declare function protocolRequest(method: string, url: string, incoming: NodeIncoming, entrypoint: string, content: Uint8Array): AvProtocolRequest;
+/** The request as `@aventara/mcp` reads it: absolute URL, distinct headers, raw body, peer address. */
+export declare function mcpRequest(method: string, origin: {
+    readonly protocol: string;
+    readonly host: string;
+}, url: string, incoming: NodeIncoming, content: Uint8Array, remoteAddress: string | undefined): McpRequest;
 /**
  * Writes the protocol's answer as it is. Headers the platform's hooks already
  * set (CORS, say) go beneath it; a protocol header of the same name, in any

package/dist/node-exchange.translator.js

@@ -11,6 +11,15 @@ export function protocolRequest(method, url, incoming, entrypoint, content) {
         body: { kind: "raw", content },
     };
 }
+export function mcpRequest(method, origin, url, incoming, content, remoteAddress) {
+    return {
+        method,
+        url: `${origin.protocol}://${origin.host}${url}`,
+        headers: incoming.headersDistinct,
+        body: content,
+        remoteAddress,
+    };
+}
 export function writeAnswer(response, answer, beneath = {}) {
     const own = new Set(Object.keys(answer.headers).map((name) => name.toLowerCase()));
     const headers = {};

package/dist/protocol-host.factory.d.ts

@@ -1,6 +1,9 @@
-import type { Framework } from "@aventara/core";
+import type { AvFramework, AvState } from "@aventara/core";
 import type { AbstractHttpAdapter } from "@nestjs/core";
+import type { McpBinding, McpRoute } from "./mcp-binding.loader.js";
 import type { SurfaceRoute } from "./protocol-route.table.js";
+/** The developer's `state` option: seeds a request's `ctx.$state` from its platform request. */
+export type HostState = (request: unknown) => AvState | Promise<AvState>;
 /** The protocol, bound once at startup, and the one call that mounts it. */
 export type ProtocolHost = {
     readonly mount: () => void;
@@ -11,7 +14,14 @@ export type ProtocolHost = {
  * rejects before the application listens. The routes are mounted later, from
  * the module's `configure()`.
  */
-export declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: Framework): ProtocolHost;
+export declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: AvFramework, state?: HostState, mcp?: McpBinding): ProtocolHost;
+/**
+ * What the MCP mount registered: the endpoint, and its OAuth metadata route
+ * or, without one, the rule an open endpoint answers by — e.g. `Aventara
+ * mounted the MCP endpoint at /mcp (+ GET
+ * /.well-known/oauth-protected-resource/mcp)`.
+ */
+export declare function mcpMountedLine(routes: readonly McpRoute[]): string;
 /**
  * What one mount registered, read off `protocol.surface()`: the operation
  * count under the entrypoint, then each framework route by method and path —
@@ -35,4 +45,4 @@ export type AdapterHostView = {
  * A host for an application whose HTTP adapter may arrive after the providers
  * are instantiated (Nest's testing module).
  */
-export declare function createPendingProtocolHost(application: AdapterHostView, framework: Framework): PendingProtocolHost;
+export declare function createPendingProtocolHost(application: AdapterHostView, framework: AvFramework, state?: HostState, mcp?: McpBinding): PendingProtocolHost;

package/dist/protocol-host.factory.js

@@ -4,24 +4,35 @@ import { createExpressProtocolHost } from "./express-protocol.mounter.js";
 import { createFastifyProtocolHost, } from "./fastify-protocol.mounter.js";
 import { checkedPlatform, } from "./host-bootstrap.validator.js";
 const PLATFORM_MOUNTERS = {
-    express: (adapter, binding, entrypoint, maxRequestBytes) => createExpressProtocolHost({
+    express: (adapter, binding, entrypoint, maxRequestBytes, state, mcp) => createExpressProtocolHost({
         get: (path, handler) => adapter.get(path, handler),
         post: (path, handler) => adapter.post(path, handler),
+        delete: (path, handler) => adapter.delete(path, handler),
         use: (handler) => adapter.use(handler),
-    }, binding, entrypoint, maxRequestBytes),
-    fastify: (adapter, binding, entrypoint, maxRequestBytes) => createFastifyProtocolHost(adapter.getInstance(), binding, entrypoint, maxRequestBytes),
+    }, binding, entrypoint, maxRequestBytes, state, mcp),
+    fastify: (adapter, binding, entrypoint, maxRequestBytes, state, mcp) => createFastifyProtocolHost(adapter.getInstance(), binding, entrypoint, maxRequestBytes, state, mcp),
 };
-export function createProtocolHost(adapter, framework) {
+export function createProtocolHost(adapter, framework, state, mcp) {
     const platform = checkedPlatform(adapter?.getType());
     const binding = AvProtocol.bind(framework);
-    const host = PLATFORM_MOUNTERS[platform](adapter, binding, framework.entrypoint, framework.contracts.client.limits.maxRequestBytes);
+    const host = PLATFORM_MOUNTERS[platform](adapter, binding, framework.api, framework.contracts.client.limits.maxRequestBytes, state, mcp);
     return {
         mount: () => {
             host.mount();
-            MOUNT_LOGGER.log(mountedLine(binding.surface(), framework.entrypoint));
+            MOUNT_LOGGER.log(mountedLine(binding.surface(), framework.api));
+            if (mcp !== undefined) {
+                MOUNT_LOGGER.log(mcpMountedLine(mcp.surface()));
+            }
         },
     };
 }
+export function mcpMountedLine(routes) {
+    const endpoint = routes.find((route) => route.kind === "endpoint");
+    const metadata = routes.find((route) => route.kind === "metadata");
+    return `Aventara mounted the MCP endpoint at ${endpoint?.path ?? "/"} (${metadata === undefined
+        ? "no authorization: it answers callers on this machine only"
+        : `+ GET ${metadata.path}`})`;
+}
 const MOUNT_LOGGER = new Logger("AventaraModule");
 export function mountedLine(routes, entrypoint) {
     const operations = routes.filter((route) => route.kind === "operation");
@@ -30,16 +41,16 @@ export function mountedLine(routes, entrypoint) {
         .map((route) => `${route.method} ${entrypoint}${route.path}`);
     return `Aventara mounted ${operations.length} ${operations.length === 1 ? "operation" : "operations"} at ${entrypoint === "" ? "/" : entrypoint} (+ ${framework.join(", ")})`;
 }
-export function createPendingProtocolHost(application, framework) {
+export function createPendingProtocolHost(application, framework, state, mcp) {
     if (application.httpAdapter !== undefined) {
-        const host = createProtocolHost(application.httpAdapter, framework);
+        const host = createProtocolHost(application.httpAdapter, framework, state, mcp);
         return { mount: host.mount, assertReady: () => undefined };
     }
     let host;
     let refusal;
     application.init$.subscribe(() => {
         try {
-            host = createProtocolHost(application.httpAdapter, framework);
+            host = createProtocolHost(application.httpAdapter, framework, state, mcp);
         }
         catch (error) {
             refusal = error;
@@ -49,7 +60,7 @@ export function createPendingProtocolHost(application, framework) {
         if (refusal !== undefined) {
             throw refusal;
         }
-        return host ?? createProtocolHost(undefined, framework);
+        return host ?? createProtocolHost(undefined, framework, state, mcp);
     };
     return {
         mount: () => ready().mount(),

package/dist/protocol-route.table.d.ts

@@ -1,10 +1,20 @@
+import type { AvState } from "@aventara/core";
 import type { AvProtocolBinding, AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
+import type { McpBinding, McpRequest, McpRoute } from "./mcp-binding.loader.js";
 /** One route `protocol.surface()` lists. */
 export type SurfaceRoute = ReturnType<AvProtocolBinding["surface"]>[number];
+/** The developer's `state` option over one platform request: seeds its `ctx.$state`. */
+export type StateSeed = () => AvState | Promise<AvState>;
 /** What a mounted route answers its request with: a bound protocol member. */
-export type RouteAnswer = (request: AvProtocolRequest) => AvProtocolResponse | Promise<AvProtocolResponse>;
+export type RouteAnswer = (request: AvProtocolRequest, state: StateSeed | undefined) => AvProtocolResponse | Promise<AvProtocolResponse>;
 /** The bound member each kind of surface route is answered by. */
 export type ProtocolRouteTable = {
     readonly [K in SurfaceRoute["kind"]]: (binding: AvProtocolBinding) => RouteAnswer;
 };
 export declare const PROTOCOL_ROUTES: ProtocolRouteTable;
+/** What a mounted MCP route answers its request with: a bound `@aventara/mcp` member. */
+export type McpRouteAnswer = (request: McpRequest, state: StateSeed | undefined) => AvProtocolResponse | Promise<AvProtocolResponse>;
+/** The bound `@aventara/mcp` member each kind of MCP route is answered by. */
+export declare const MCP_ROUTES: {
+    readonly [K in McpRoute["kind"]]: (binding: McpBinding) => McpRouteAnswer;
+};

package/dist/protocol-route.table.js

@@ -1,5 +1,9 @@
 export const PROTOCOL_ROUTES = {
-    operation: (binding) => (request) => binding.handleOperation(request),
+    operation: (binding) => (request, state) => binding.handleOperation(request, state === undefined ? {} : { state }),
     contract: (binding) => (request) => binding.encodeContract(request),
-    transactions: (binding) => (request) => binding.handleTransaction(request),
+    transactions: (binding) => (request, state) => binding.handleTransaction(request, state === undefined ? {} : { state }),
+};
+export const MCP_ROUTES = {
+    endpoint: (binding) => (request, state) => binding.handleEndpoint(request, state === undefined ? {} : { state }),
+    metadata: (binding) => (request) => binding.encodeMetadata(request),
 };