@aventara/nest 1.0.0-rc.0 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,169 @@
 # @aventara/nest
 
+## 1.0.0-rc.1
+
+### Patch Changes
+
+- 7e3d06f: Breaking: the configuration has a new shape. Every layer (the root, `application` and `client`) now holds the
+  same six keys: `exposed`, `transactionsStyle`, `limits`, `pipelines`, `resources` and `exemptions`. Everything about
+  one Resource lives under `resources.<Resource>`: its fields, and each field's `definition` and `pipelines`. The old
+  keys are refused when the framework starts, with a message that names where each one moved:
+
+  | Before (rc.0)                                           | Now (rc.1)                                                                          |
+  | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+  | `fields: { Post: { url: { type, nullable, … } } }`      | `resources: { Post: { fields: { url: { definition: { type, nullable, … } } } } }`   |
+  | `behaviors: { Post: { fields: { slug: { create } } } }` | `resources: { Post: { fields: { slug: { pipelines: { compute: { create } } } } } }` |
+  | `transactions: "none"`                                  | `transactionsStyle: "none"`                                                         |
+  | `restrictions`                                          | `exposed` + `exemptions` (see below)                                                |
+  | `@aventara/core/json`                                   | `@aventara/core/avz`                                                                |
+
+  Before:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactions: "interactive",
+    fields: {
+      Post: {
+        url: {
+          type: { scalar: "string" },
+          nullable: false,
+          list: false,
+          lifecycle: ["VIRTUAL"],
+        },
+      },
+    },
+    behaviors: {
+      Post: {
+        fields: {
+          url: {
+            read: {
+              dependsOn: ["slug"],
+              compute: ({ record }) => `/p/${record.slug}`,
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  After:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactionsStyle: "interactive",
+    resources: {
+      Post: {
+        fields: {
+          url: {
+            definition: {
+              type: { scalar: "string" },
+              nullable: false,
+              list: false,
+              lifecycle: ["VIRTUAL"],
+              format: "url",
+            },
+            pipelines: {
+              compute: {
+                read: {
+                  dependsOn: ["slug"],
+                  compute: ({ record }) => `/p/${record.slug}`,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  What else changed:
+
+  - A field is defined at the root only. A `definition` in `application` or `client` is refused
+    (`CONFIG_FORBIDDEN_IN_OVERLAY`). Define the field
+    at the root; `application` and `client` can still add compute stages to it.
+  - Computed values chain. When the root and an overlay both compute a field, the root's stage runs first and the
+    overlay's receives its result as `value`. A stage can no longer be turned off with `false`. Returning `undefined`
+    keeps the current value. An upsert computes its create branch with `compute.create` and its update branch with
+    `compute.update`.
+  - A discovered field keeps the adapter's facts. On a field the adapter discovered you may restate its own `type`,
+    `nullable` and `list`, and give a Json field its shape (`definition.json`). Setting a different type, any `format`
+    or any `capabilities` on it is refused. `format` is for fields you add, and it must be one of zod's named string
+    formats (`"email"`, `"url"`, `"uuid"`, …); any other name is a type error and refused at startup.
+  - A misplaced key is a type error. In a configuration written inline in `createFramework({ ... })` or
+    `AventaraModule.forRoot`, a key that has no place there (a typo, an old key, `compute` on a relation field, a field
+    name neither your schema nor the root has) is now a type error at that key, and still refused at startup.
+  - A Resource whose name starts with `$` is refused at startup (`$` names are the framework's).
+  - The Json shape builder moved from `@aventara/core/json` to `@aventara/core/avz`. Change the import; `AvZ` is
+    the same.
+
+  `exposed` and `exemptions`, which replace `restrictions`, have their own entry.
+
+- 4907afc: New: `AventaraModule.forRoot` and `forRootAsync` take a `state` option that seeds each protocol request's
+  `ctx.$state` (see `@aventara/core`'s changelog). It is called once per request with the platform's own request, so
+  what your middleware set there reaches every guard, pipe, hook and interceptor of the request:
+
+  ```ts
+  AventaraModule.forRoot({
+    config,
+    state: (req: Request) => ({ user: req.user }), // Passport's req.user, on Express
+  });
+  ```
+
+  On Express the request is Express's `req`. On Fastify it is Fastify's `request`; middleware added with `app.use`
+  writes to its Node request, `request.raw`, so read `request.raw.user` there. Fastify answers a protocol route in its
+  `onRequest` hook, so only what runs before that (`app.use` middleware, an earlier `onRequest` hook) can be read. A
+  `state` function that throws an `AvError` answers that error (`AvError("A4001", …)` is a `403`); any other throw is
+  `500 A3000`. A request the protocol refuses before running (a stale client, an unknown route) never calls it. A
+  `state` that is not a function is refused while Nest builds the application.
+
+- Breaking: the configuration's mount path is `api` (it was `entrypoint`), and the module reads `framework.api`.
+  `forRoot({ config: { api: "/api", adapter } })`. The Fastify refusal of a path with `*` now says "Change `api`, or
+  host on Express."
+
+- New: with `mcp` in the configuration, the module mounts the MCP endpoint of `@aventara/mcp` at that path (and, with
+  `mcp.authorization`, its OAuth metadata at `/.well-known/oauth-protected-resource` plus the path), on Express and on
+  Fastify, as it mounts the protocol's routes: the body read raw, the request's URL and peer address handed over, the
+  answer written as it is. The `state` option seeds each tool call's `ctx.$state`. `@aventara/mcp` is an optional peer
+  dependency, loaded only when `mcp` is configured; with `mcp` set and the package missing, the application refuses to
+  start and names it.
+
+- Fixed on Express: a request whose path matched a mounted route only because Express ignores case reached the route
+  without its body, and was answered as if it had sent none. Express matches routes case-insensitively by default,
+  while the body reader compared the path exactly. The MCP routes now answer their own path only, exactly as written,
+  so `/MCP` or `/mcp/` goes on to Nest's `404`, as on Fastify. The protocol's routes keep Express's matching (it also
+  answers the protocol under `/API` for `api: "/api"`), and the body reader now matches the `api` path the same way, so
+  `POST /API/_resources/…` gets its body.
+
+- The host's log line for an internal failure names the MCP endpoint when the endpoint itself failed
+  (`A3000 on the MCP endpoint (agent origin, request …)`).
+
+- Updated dependencies [800123b]
+- Updated dependencies [8bb1d6a]
+- Updated dependencies [68d4395]
+- Updated dependencies [7e3d06f]
+- Updated dependencies [1b5d3c0]
+- Updated dependencies [6317811]
+- Updated dependencies [6d0e5d6]
+- Updated dependencies [7a0cab9]
+- Updated dependencies [eb2a718]
+- Updated dependencies [03312c5]
+- Updated dependencies [123f6dc]
+- Updated dependencies [b65df2e]
+- Updated dependencies [c6e5010]
+- Updated dependencies [c1f9389]
+- Updated dependencies [9c52482]
+- Updated dependencies [8396148]
+- Updated dependencies [e8fbb02]
+- Updated dependencies [916e5f6]
+- Updated dependencies [6cbd158]
+  - @aventara/core@1.0.0-rc.1
+
 ## 1.0.0-rc.0
 
 ### Major Changes

package/README.md

@@ -1,16 +1,16 @@
 # `@aventara/nest`
 
-Hosts an Aventara `Framework` in a NestJS application. It does one thing: it mounts the framework's HTTP protocol —
-`AvProtocol.bind(framework)` from `@aventara/core/protocol` — on Nest's HTTP platform, and puts the `Framework` into
+Hosts an Aventara `AvFramework` in a NestJS application. It mounts the framework's HTTP protocol
+(`AvProtocol.bind(framework)` from `@aventara/core/protocol`) on Nest's HTTP platform, and puts the `AvFramework` into
 Nest's dependency injection. Every rule of the protocol (routes, decoding, statuses, envelopes, headers, absence) is
 core's; this package only translates a Nest request into the protocol's request and writes the protocol's answer back.
 
-- **Nest 12** (`@nestjs/common` and `@nestjs/core` `^12.0.0`), on **Express** (Nest's default) or **Fastify**.
-- `@aventara/core` is its one dependency.
+It runs on Nest 12 (`@nestjs/common` and `@nestjs/core` `^12.0.0`), on Express (Nest's default) or Fastify.
+`@aventara/core` is its one dependency.
 
 ## Mounting it
 
-`AventaraModule` is a global module, imported once in your root module. It takes the `Framework` in one of four forms.
+`AventaraModule` is a global module, imported once in your root module. It takes the `AvFramework` in one of four forms.
 
 ```ts
 // src/app.module.ts — the shape `aventara init` writes (`@aventara/cli`)
@@ -33,14 +33,27 @@ import { PrismaModule, PrismaService } from "./prisma.service.js";
 })
 export class AppModule {}
 
-// src/aventara.config.ts — the framework's configuration: entrypoint, restrictions, pipelines
+// src/aventara.config.ts — the framework's configuration: api, exposure, pipelines, resources
+import type { AvDiagnostic } from "@aventara/core";
 import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { Logger } from "@nestjs/common";
 import { discovery } from "./generated/aventara/discovery.artifact.js";
 import type { PrismaService } from "./prisma.service.js";
 
+const logger = new Logger("Aventara");
+
 export async function aventaraConfig(prisma: PrismaService) {
 	return {
-		entrypoint: "/api",
+		api: "/api",
+		exposed: true,
+		// The raw error of a server failure, with its stack, in Nest's log.
+		diagnostics: (diagnostic: AvDiagnostic) => {
+			const { error } = diagnostic;
+			logger.error(
+				`${diagnostic.code} (request ${diagnostic.requestId}): raw error`,
+				error instanceof Error ? error.stack : String(error),
+			);
+		},
 		adapter: await createPrismaAdapter({
 			client: prisma,
 			discovery,
@@ -53,15 +66,18 @@ export async function aventaraConfig(prisma: PrismaService) {
 
 | Form | When |
 |---|---|
-| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `Framework<M, Cfg>` in code. |
+| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `AvFramework<M, Cfg>` in code. |
 | `AventaraModule.forRoot({ config })` | The module calls `createFramework(config)` for you. |
 | `AventaraModule.forRootAsync({ imports, inject, useFactory })` resolving `{ framework }` or `{ config }` | What builds the Framework (a Prisma client, a configuration service) is itself a provider. |
 
-The `config` form is typed exactly like `createFramework`'s parameter: an annotated `FrameworkConfig<M>`, an inline
+Each form also takes `state`, which seeds every protocol request's `ctx.$state` from the platform request (see
+*Request state*).
+
+The `config` form is typed exactly like `createFramework`'s parameter: an annotated `AvConfig<M>`, an inline
 literal, an inferred constant and a `satisfies` check are all accepted, and checked against your Adapter's model.
 
-**Injecting it.** `@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `Framework`. DI carries no type
-argument, so type the parameter with your own alias:
+`@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `AvFramework`. DI carries no type argument, so type
+the parameter with your own alias:
 
 ```ts
 export type AppFramework = Awaited<ReturnType<typeof buildFramework>>;
@@ -72,23 +88,23 @@ export class ReportsService {
 }
 ```
 
-**Fails before listen.** These reject while Nest builds the application, before it listens: both or neither of
-`framework` and `config`; a `framework` value that is not a Framework; the module mounted twice in one application; a
-platform other than Express or Fastify (or none, as in `createApplicationContext`); a `FrameworkConstructionError`,
-yours or the module's own, which propagates unchanged. Nest's default `abortOnError: true` **exits the process** on a
-bootstrap error instead of rejecting; pass `abortOnError: false` to `NestFactory.create` to catch it.
+These reject while Nest builds the application, before it listens: both or neither of `framework` and `config`; a
+`framework` value that is not a Framework; a `state` option that is not a function; the module mounted twice in one application; a platform other than Express
+or Fastify (or none, as in `createApplicationContext`); an `AvConstructionError`, yours or the module's own, which
+propagates unchanged. Nest's default `abortOnError: true` exits the process on a bootstrap error instead of rejecting;
+pass `abortOnError: false` to `NestFactory.create` to catch it.
 
-**Nest's testing module works.** `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers
-before any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
-unsupported platform before the application listens. A testing module initialized with no
-application at all is refused at `init()`, as a platform of `none`.
+Nest's testing module works. `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers before
+any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
+unsupported platform before the application listens. A testing module initialized with no application at all is
+refused at `init()`, as a platform of `none`.
 
-**Nothing to shut down.** The module owns no resource. Your Prisma provider closes its own client — in its
+The module owns no resource, so there is nothing to shut down. Your Prisma provider closes its own client in its
 `onModuleDestroy`, with `app.enableShutdownHooks()` for signals.
 
 ## Calling it by hand
 
-Against the shape `aventara init` writes — the entrypoint `/api`, a Prisma `User` model:
+Against the shape `aventara init` writes (the `api` mount path `/api`, a Prisma `User` model):
 
 <!-- pilot-gate:curl -->
 ```bash
@@ -108,18 +124,19 @@ curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
 Leave out an identity header and the answer is `400 A2000`, naming the header that is missing. The hash changes
 whenever the schema or the configuration does: fetch it again, and regenerate the client.
 
-- **Resource keys are the model names, as written.** `model User` is `User` everywhere: on the wire
-  (`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
-  lower-cased or pluralized.
-- **Results are read-only.** A list result is a `readonly` array: type it `readonly User[]`, not `User[]` —
-  `const users: readonly User[] = await avClient.User.find.many({});`.
+Resource keys are the model names, as written. `model User` is `User` everywhere: on the wire
+(`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
+lower-cased or pluralized.
+
+Results are read-only. A list result is a `readonly` array, so type it `readonly User[]`:
+`const users: readonly User[] = await avClient.User.find.many({});`.
 
 ## What runs on a protocol route
 
-The protocol's routes are platform routes, registered from the module's `configure()`, one per
-`protocol.surface()` entry — every advertised operation, `GET <entrypoint>/_contract`, and `POST
-<entrypoint>/_transactions` only when the ClientContract advertises `interactive` — plus the absence handler for the
-rest of `<entrypoint>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
+The protocol's routes are platform routes, registered from the module's `configure()`. There is one per
+`protocol.surface()` entry (every advertised operation, `GET <api>/_contract`, and `POST
+<api>/_transactions` only when the ClientContract advertises `interactive`), plus the absence handler for the
+rest of `<api>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
 own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `logger: false` silences it like any other):
 
 ```text
@@ -127,16 +144,19 @@ own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `log
 ```
 
 An internal failure (`A3000`–`A3004`, answered as a 500) is logged as one error line through Nest's `Logger`
-(context `Aventara`): the code, the operation, the origin and the request id, and the thrown value's class name — never
-its message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
-configure one:
+(context `Aventara`): the code, the operation, the origin and the request id, and the thrown value's class name. It
+never logs the message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
+configure one. The `aventara.config.ts` that `aventara new` and `aventara init` write has one: it logs the raw error with its
+stack through the same `Logger`, at error level, right after this line.
 
 ```text
 [Nest] ERROR [Aventara] A3001 on Post.create.one (client origin, request 3f1c…): PrismaClientValidationError. The raw error goes to the framework's diagnostics sink.
+[Nest] ERROR [Aventara] A3001 (request 3f1c…): raw error
+PrismaClientValidationError: …
 ```
 
-For `A3004` — one of your pipes returned arguments the server contract refuses — the line also names the pipe, the
-operation, the offending field and its V-code; the caller only ever sees the generic message.
+For `A3004` (one of your pipes returned arguments the server contract refuses), the line also names the pipe, the
+operation, the offending field and its V-code. The caller only ever sees the generic message.
 
 The line is added when the module builds the framework from `config`; a framework you build yourself and pass as
 `framework` keeps exactly the `diagnostics` sink you gave it.
@@ -146,42 +166,97 @@ The framework's validation is outermost:
 | | Express | Fastify |
 |---|---|---|
 | Your `app.use(...)` middleware, `app.enableCors()`, helmet | runs | runs |
-| Nest guards, interceptors, pipes (global or not) | **never** | **never** |
-| `MiddlewareConsumer` middleware | **never** | **runs** — Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your entrypoint) to keep it off |
-| Your controller at `<entrypoint>/_contract` (or any `_` path) | never reached | the application does not start |
-| Your controller at `<entrypoint>/health` (outside `_`) | reached | reached |
+| Nest guards, interceptors, pipes (global or not) | never | never |
+| `MiddlewareConsumer` middleware | never | runs, because Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your `api` path) to keep it off |
+| Your controller at `<api>/_contract` (or any `_` path) | never reached | the application does not start |
+| Your controller at `<api>/health` (outside `_`) | reached | reached |
 
-Authentication and authorization therefore belong in Aventara **pipelines** (guards), which read
-`transport.headers` — lower-cased names, repeats joined. A Passport strategy run as Nest middleware sets `req.user`,
-which a pipeline cannot see: verify the bearer token or cookie in the Aventara guard instead.
+Authorization therefore belongs in Aventara pipelines (guards). A guard reads the request's headers as
+`ctx.$transport.headers` (lower-cased names, repeats joined), and whatever your middleware found as `ctx.$state`,
+through the module's `state` option (next section).
 
-**Where it is mounted.** `FrameworkConfig.entrypoint` alone decides it. `app.setGlobalPrefix(...)` does not move the
-protocol; set the entrypoint to where you want it, and point the generated client at the same URL.
+## Request state
+
+`state` seeds each protocol request's `ctx.$state`, the one object every stage of that request reads and writes. It is
+called once per request, with the platform's own request, after the protocol has accepted it (a stale client or an
+unknown route never calls it):
+
+```ts
+declare module "@aventara/core" {
+	interface AvState {
+		user?: { id: string; roles: string[] };
+	}
+}
+
+AventaraModule.forRoot({
+	config,
+	state: (req: Request) => ({ user: req.user }), // what your auth middleware set
+});
+
+// In the configuration: a guard reads it.
+const signedIn: AvGuard = (ctx) => ctx.$state.user !== undefined;
+```
+
+- `forRootAsync`'s `useFactory` returns `state` beside `framework` or `config`.
+- On Express, `req` is Express's request. On Fastify it is Fastify's `request`; `app.use` middleware writes to its
+  Node request, so read `request.raw.user`. Fastify answers a protocol route from its `onRequest` hook, so only what
+  runs before it (`app.use` middleware, an earlier `onRequest` hook) has run.
+- Use `app.use(...)` for the middleware that finds the user (a Passport `authenticate` call, a session or JWT check).
+  Nest guards never run on protocol routes, and `MiddlewareConsumer` middleware does not on Express (the table above).
+- Throw `new AvError("A4001", "…")` from `state` to refuse the request (`403`); any other throw is `500 A3000`, with the
+  error in your `diagnostics` sink.
+- A plan sent to `/_transactions` gets one state for all its steps and transaction stages. A ctx call a stage makes
+  inherits it. Compute reads it but cannot write it.
+- Server code that calls the framework in process seeds it per call:
+  `framework.application.Post.create.one(args, { state: { user } })`.
+
+`AvConfig.api` alone decides where the protocol is mounted. `app.setGlobalPrefix(...)` does not move it; set
+`api` to where you want it, and point the generated client at the same URL.
 
 ## Requests
 
-- **Bodies** on protocol routes are read raw — never through Nest's body parser — up to `limits.maxRequestBytes`; the
+- Bodies on protocol routes are read raw, never through Nest's body parser, up to `limits.maxRequestBytes`. The
   protocol's decoder answers an oversized body (`413 A2010`), another content type (`415 A2011`) and malformed JSON
   (`400 A2000`). Your own routes keep Nest's parsed `req.body`. No `NestFactory.create` option is needed.
-- **`Content-Encoding`:** `gzip`, `deflate` and `br` are inflated, and the limit counts decoded bytes. Any other coding
+- For `Content-Encoding`, `gzip`, `deflate` and `br` are inflated, and the limit counts decoded bytes. Any other coding
   answers `415 A2011`; a body that does not decode in the coding it names answers `400 A2000`. These two answers carry a
   newly minted `Aventara-Request-Id`, not the client's.
-- **The request id** is the client's `Aventara-Request-Id` as it arrived, or one core mints. A middleware that rewrites
-  `req.headers` cannot change it, and `X-Request-Id` is never copied into it — set `Aventara-Request-Id` at your proxy.
-- **A query string** is not part of the protocol path; it is ignored.
+- The request id is the client's `Aventara-Request-Id` as it arrived, or one core mints. A middleware that rewrites
+  `req.headers` cannot change it, and `X-Request-Id` is never copied into it, so set `Aventara-Request-Id` at your
+  proxy.
+- A query string is not part of the protocol path; it is ignored.
+
+## The MCP endpoint
+
+With `mcp` in the configuration, the module also mounts the MCP server of `@aventara/mcp` at that path, on Express and
+Fastify alike, and logs `Aventara mounted the MCP endpoint at /mcp (…)`. Install it beside this package, at the same
+version:
+
+```bash
+npm install @aventara/mcp@rc
+```
+
+It is an optional peer dependency: an application without `mcp` does not need it, and one with `mcp` and without the
+package refuses to start, naming it. As for the protocol's routes, the module only mounts: the endpoint's body is read
+raw, the request's URL comes from the platform's `protocol` and `host` (set `trust proxy` on Express or `trustProxy` on
+Fastify behind a proxy), and every answer is `@aventara/mcp`'s. The `state` option seeds each tool call's `ctx.$state`.
+See `@aventara/mcp`'s README for the tools, the contract resource and authorization.
 
 ## Platform differences
 
-- **Fastify cannot mount some Resource keys or entrypoints as literal routes.** A Resource key that needs `*` or a
-  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an entrypoint containing `*`, is refused at startup
+- Fastify cannot mount some Resource keys or `api` paths as literal routes. A Resource key that needs `*` or a
+  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an `api` path containing `*`, is refused at startup
   with a message naming it. Rename it, or host on Express, which mounts every key.
-- **Express routing is case-insensitive** by default, so it also answers the protocol under, say, `/API/_contract`;
-  Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change.
-- **Express answers `500 A3000`** to a protocol route requested with a percent-encoding a generated client never sends
-  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. A known divergence.
+- Express routing is case-insensitive by default, so it also answers the protocol under, say, `/API/_contract`;
+  Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change. The
+  MCP endpoint is the exception: on both platforms it answers its own path only, exactly as written (`/mcp`, not
+  `/MCP` or `/mcp/`).
+- Express answers `500 A3000` to a protocol route requested with a percent-encoding a generated client never sends
+  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. This is a known divergence.
 - On Express the response carries Express's `X-Powered-By` header; `app.disable("x-powered-by")` removes it.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

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 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,7 +15,9 @@ 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}`;
@@ -24,7 +26,7 @@ export function internalFailureLine(diagnostic) {
 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),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/nest",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "NestJS host integration for Aventara.",
   "type": "module",
@@ -22,24 +22,33 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.0"
+    "@aventara/core": "1.0.0-rc.1"
   },
   "peerDependencies": {
+    "@aventara/mcp": "1.0.0-rc.1",
     "@nestjs/common": "^12.0.0",
     "@nestjs/core": "^12.0.0"
   },
+  "peerDependenciesMeta": {
+    "@aventara/mcp": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/prisma7-adapter": "1.0.0-rc.0",
-    "@aventara/testing": "1.0.0-rc.0",
+    "@aventara/mcp": "1.0.0-rc.1",
+    "@aventara/prisma7-adapter": "1.0.0-rc.1",
+    "@aventara/testing": "1.0.0-rc.1",
+    "@modelcontextprotocol/sdk": "1.30.1",
     "@nestjs/common": "^12.1.2",
     "@nestjs/core": "^12.1.2",
     "@nestjs/platform-express": "^12.1.2",
     "@nestjs/platform-fastify": "^12.1.2",
     "@nestjs/testing": "^12.1.2",
     "@prisma/adapter-better-sqlite3": "7.10.0",
+    "@prisma/adapter-pg": "7.10.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2"
   },