@aventara/mcp 1.0.0-rc.1 → 1.0.0-rc.11

package/CHANGELOG.md

@@ -1,5 +1,179 @@
 # @aventara/mcp
 
+## 1.0.0-rc.11
+
+### Patch Changes
+
+- Updated dependencies [6197c08]
+- Updated dependencies [e0e89c1]
+- Updated dependencies [186bc29]
+- Updated dependencies [33b5f83]
+- Updated dependencies [6d8b589]
+- Updated dependencies [11ece49]
+- Updated dependencies [92fd093]
+- Updated dependencies [e5e98e6]
+- Updated dependencies [a05d970]
+  - @aventara/core@1.0.0-rc.11
+
+## 1.0.0-rc.10
+
+### Patch Changes
+
+- 04bb39a: `engines.node` is now `^22.23.4 || >=24.22.1`, the Node security releases of 2026-10-20 (CVE-2026-105481,
+  CVE-2026-105482, CVE-2026-105483, CVE-2026-106069, CVE-2026-106072, CVE-2026-106073, CVE-2026-106074,
+  CVE-2026-111497). The bins refuse an older Node in one sentence naming that range.
+- d7e7369: - The tool `me`, offered when the framework's `access` provider states its `client`: it takes `{}` and answers the
+  identity Aventara Access resolves from the request's credentials (`{ sub, claims }`, or `null`) as the protocol
+  envelope's data, projected onto the `access` section's `me` schema (an identity it does not describe answers
+  `A3000`).
+  - An endpoint without `authorization` now also requires a loopback `Host` header (`localhost`, `127.x.x.x` or
+    `[::1]`, any port); any other `Host`, or none, is `403`. This closes DNS rebinding (the class of CVE-2025-66414): a
+    page whose domain is rebound to `127.0.0.1` still names its own domain as `Host`.
+    An HTTP/2 caller (`:authority`, no `Host`) is refused by the open endpoint.
+- 3fb3333: `@aventara/mcp` pins `@modelcontextprotocol/sdk` 1.32.2 (was 1.30.1) and `zod` `^4.6.7` (was `^4.6.5`); `@aventara/core`
+  also takes `zod` `^4.6.7`. This clears the advisories against those versions:
+
+  | Advisory                              | Severity | Package             | What it was                                                                                              |
+  | ------------------------------------- | -------- | ------------------- | -------------------------------------------------------------------------------------------------------- |
+  | GHSA-46jr-4wx8-v453 (CVE-2026-111768) | high     | sdk < 1.32.0        | One HTTP request within the default size limit could exhaust server memory during validation             |
+  | GHSA-22jm-h49p-29qw (CVE-2026-111767) | high     | sdk 1.24.0 – 1.31.x | Experimental tasks were not tied to the session that created them                                        |
+  | GHSA-6qxp-vccf-f47h (CVE-2026-104850) | high     | sdk 1.12.0 – 1.30.x | The OAuth client could send credentials to an authorization server chosen by the MCP server              |
+  | GHSA-mrhx-c7xc-m3w5                   | high     | zod ≤ 4.6.5         | Validating an oversized unconstrained array could exhaust memory                                         |
+  | GHSA-rvq5-wwqv-78pq (CVE-2026-111771) | moderate | sdk 1.6.0 – 1.31.x  | Server bearer authentication accepted tokens issued for another service                                  |
+  | GHSA-6prh-2h8m-c8cw (CVE-2026-111769) | moderate | sdk < 1.32.0        | HTTP client transports and OAuth requests followed cross-origin redirects with custom headers and bodies |
+
+  Aventara's MCP server was already outside most of these: it uses the low-level `Server` (no `taskStore`, no
+  `requireBearerAuth`, no SDK OAuth client), and its transport's `maxRequestBodySize` is the agent layer's
+  `limits.maxRequestBytes`. No API of `@aventara/mcp` changes.
+
+- 88263a1: Documentation: `$access.can([])` answers `[]`, not a refusal; the MCP README states the query and fragment rule for
+  every authorization server.
+- Updated dependencies [587dd01]
+- Updated dependencies [d7e7369]
+- Updated dependencies [7ee547b]
+- Updated dependencies [f52c499]
+- Updated dependencies [2907484]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [3e26549]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [6f3f6f6]
+- Updated dependencies [04bb39a]
+- Updated dependencies [3fb3333]
+- Updated dependencies [827ccb6]
+- Updated dependencies [7f5abc3]
+- Updated dependencies [88263a1]
+- Updated dependencies [10341d5]
+- Updated dependencies [8129844]
+- Updated dependencies [88263a1]
+- Updated dependencies [3020b5c]
+- Updated dependencies [88263a1]
+- Updated dependencies [88263a1]
+  - @aventara/core@1.0.0-rc.10
+
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- Updated dependencies [205a379]
+- Updated dependencies [a0bb05e]
+- Updated dependencies [86ab319]
+- Updated dependencies [fdf52e6]
+  - @aventara/core@1.0.0-rc.9
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [1c8e4ee]
+  - @aventara/core@1.0.0-rc.8
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [f917c1c]
+  - @aventara/core@1.0.0-rc.7
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- Updated dependencies [1cf72e0]
+  - @aventara/core@1.0.0-rc.6
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- Updated dependencies [4795ff1]
+- Updated dependencies [9e178ca]
+  - @aventara/core@1.0.0-rc.5
+
+## 1.0.0-rc.4
+
+### Patch Changes
+
+- d10639a: Faster reads. The read-only copies stages are told cost about half what they did: a read with a computed field
+  copies each row in one pass, a row with several computed fields shares its nested objects between the stages'
+  copies, and after hooks share one frozen copy of the result. A row whose computed field returns a value at once no
+  longer waits a turn per row. The MCP endpoint builds its JSON Schema validator once instead of on every request.
+  What stages are told, the order they run in and what a request answers are unchanged.
+- Updated dependencies [e3d03a7]
+- Updated dependencies [d10639a]
+- Updated dependencies [f67e68c]
+- Updated dependencies [708556c]
+- Updated dependencies [3a0dfca]
+- Updated dependencies [99169d2]
+- Updated dependencies [0fd2608]
+- Updated dependencies [154e440]
+- Updated dependencies [2fcffdb]
+  - @aventara/core@1.0.0-rc.4
+
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+  - @aventara/core@1.0.0-rc.3
+
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- 9366e16: MCP endpoint polish:
+
+  - A request with no bearer credentials (no `Authorization` header, or another scheme such as `Basic`) is answered
+    `401` with `WWW-Authenticate: Bearer resource_metadata="…"` and no error code, as RFC 6750 §3.1 asks; its body no
+    longer says "Missing Authorization header". A bad bearer token keeps `error="invalid_token"`.
+  - A `mcp.authorization.verify` that throws is still answered `401`, and is now reported to the `diagnostics` sink as
+    an `AvMcpDiagnostic` holding the error.
+  - With `mcp` configured and `@aventara/mcp` missing, the startup error names the command that installs it at the
+    installed `@aventara/core`'s exact version: `npm install --save-exact @aventara/mcp@<version>`.
+
+- A tool call whose `resource` or `variant` holds a lone surrogate (JSON can carry one, a URL cannot) is answered as
+  the unknown name it is, as an HTTP call answers it: `fetch` spells a lone surrogate in a URL as U+FFFD, and so does
+  the tool call, so the agent gets `A2001` (`A2002` for the variant). In rc.1 the name could not be encoded, and the
+  call answered the generic `A3000` and reported a diagnostic of kind `mcp`. A `transaction` step that has no canonical
+  form (a lone surrogate in a name or a value) is sent with a `null` fingerprint, as core's plan builders and the
+  generated client send it, so it is judged as over HTTP: an unknown name is `A2001`/`A2002`, a value `A2004` `V1001`
+  at the step's `args`. It answered `V1000` for a missing `fingerprint`, a member the tool does not take.
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+  - @aventara/core@1.0.0-rc.2
+
 ## 1.0.0-rc.1
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@ over the Streamable HTTP transport, stateless. You install this package beside `
 yourself.
 
 ```bash
-npm install @aventara/mcp@rc
+npm install --save-exact @aventara/mcp@<your @aventara/core version>
 ```
 
 It depends on `@aventara/core` and the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`).
@@ -49,12 +49,16 @@ One tool per operation family the agent layer exposes, and none for a family not
 | `delete` | `{ resource, variant, args }` | destructive |
 | `upsert` | `{ resource, variant, args }` | destructive |
 | `transaction` | `{ steps: [{ resource, family, variant, args? }] }` | destructive |
+| `me` | `{}` | read-only |
 
 `resource` and `variant` are enums read from the agent layer, so a resource the agent layer hides is not offered (and is
 refused with `A2001` if an agent names it anyway). `args` is the operation's arguments as the protocol defines them
 (`where`, `select`, `data`, …). `transaction` is offered when the agent layer's transactions are interactive. A step can
 use a value an earlier step returned with `{ "$ref": { "operation": 0, "path": ["id"] } }`; the server adds the
-fingerprints the protocol requires.
+fingerprints the protocol requires. `me` is offered when the framework's `access` provider states its `client`: it
+answers the identity Aventara Access resolves from the request's credentials (`{ sub, claims }`, or `null`) as the
+envelope's data, holding only what the `access` section's `me` schema declares (an identity the schema does not
+describe is the server's own failure, `A3000`). There is no sign-in tool.
 
 Every call runs as the `agent` origin, through the same decoding and validation as an HTTP call, with the agent
 layer's pipelines. A success answers the protocol's envelope (`{ data, code, cause }`) as structured content and as
@@ -107,11 +111,26 @@ mcp: {
 },
 ```
 
+Each server is an https URL. One on your own machine may be http instead, so a local setup needs no TLS:
+`http://127.0.0.1:4000` or `http://[::1]:4000`, with any port and path. That is the whole list. Use the address, not
+`localhost`: a name is looked up, and `localhost` can resolve somewhere else (RFC 8252, section 8.3), so
+`http://localhost:4000` is refused with the spelling to use, `http://127.0.0.1:4000`. `0.0.0.0`, `[::]`, other
+`127.x` addresses, IPv4-mapped addresses, names such as `auth.localhost` and URLs with credentials are refused like
+any other http URL. Write the URL the way a browser would show it: `http://127.1:4000` is refused, and the error gives
+the spelling to use. No server URL, https included, may have a query or fragment (an issuer has neither), an empty
+path segment (`//`) or port 0.
+
+An http authorization server is for local development only. Tokens and authorization codes cross it unencrypted, and
+only clients on the same machine can reach it. Deploy with an https server.
+
 - `GET /.well-known/oauth-protected-resource/mcp` answers the protected-resource metadata (RFC 9728): the endpoint's
   URL as `resource`, your `servers` as `authorization_servers`, and `bearer_methods_supported: ["header"]`.
-- A request without `Authorization: Bearer <token>` is `401` with a `WWW-Authenticate` header naming that metadata,
-  which is how an MCP client discovers where to sign in.
-- Each token goes to `verify`. `null` (or `undefined`, or a throw) is `401`. Anything else lets the request in, and
+- A request without `Authorization: Bearer <token>` is `401` with `WWW-Authenticate: Bearer resource_metadata="…"`
+  naming that metadata, which is how an MCP client discovers where to sign in. As RFC 6750 asks, it carries no error
+  code: the request had no token to be wrong.
+- Each token goes to `verify`. `null` (or `undefined`, or a throw) is `401` with `error="invalid_token"`. A `verify`
+  that throws is also reported to your `diagnostics` sink (an `AvMcpDiagnostic` holding the error), so an outage of
+  your token check shows in your logs rather than as a run of rejected agents. Anything else lets the request in, and
   what `verify` returned is the request's `ctx.$state.mcp.claims`, beside what the host's `state` option seeds. Declare
   its type with the rest of your state:
 
@@ -129,8 +148,11 @@ or Fastify's `trustProxy` for `https` and the public host to appear in the metad
 ## Without authorization
 
 An endpoint without `authorization` takes no token, so it answers callers on the same machine only: a loopback peer
-address, no proxy forwarding header (`Forwarded`, `X-Forwarded-For`, `X-Real-IP`), and no `Origin` header but a
-loopback one. Every other caller gets `403`. This is for local development and for an agent running beside the
+address, no proxy forwarding header (`Forwarded`, `X-Forwarded-For`, `X-Real-IP`), a loopback `Host` (`localhost`,
+`127.x.x.x` or `[::1]`, any port), and no `Origin` header but a loopback one. Every other caller gets `403`. The `Host`
+rule closes DNS rebinding: a page whose domain is rebound to `127.0.0.1` still sends its own domain as `Host`. An HTTP/2
+caller sends `:authority` instead of `Host`, so the open endpoint refuses it too; serve it over HTTP/1.1, or configure
+`authorization`. This is for local development and for an agent running beside the
 application. To serve remote agents, configure `authorization`.
 
 ## The transport

package/dist/endpoint-access.policy.d.ts

@@ -1,7 +1,7 @@
 import type { AvMcpEndpoint } from "@aventara/core";
 import type { AvProtocolResponse } from "@aventara/core/protocol";
 /** The authorization `mcp.authorization` configures. */
-export type EndpointAuthorization = NonNullable<AvMcpEndpoint["authorization"]>;
+type EndpointAuthorization = NonNullable<AvMcpEndpoint["authorization"]>;
 /** What a request to the endpoint is let through with, or the answer that refuses it. */
 export type EndpointAccess = {
     readonly ok: true;
@@ -24,10 +24,12 @@ export declare function jsonAnswer(status: number, body: unknown, headers?: Read
  */
 export declare function metadataAnswer(method: string, origin: string, endpointPath: string, authorization: EndpointAuthorization): AvProtocolResponse;
 /**
- * A protected endpoint's check: the request's bearer token, verified. A missing
+ * A protected endpoint's check: the request's bearer token, verified. No bearer
  * token, one `verify` rejects (`null`, `undefined`) and a `verify` that throws
- * are each `401`; a good one passes with what `verify` resolved it to.
+ * are each `401`; a good one passes with what `verify` resolved it to. A throw
+ * is handed to `reportFailure` (the diagnostics sink) as well.
  */
-export declare function authorizedAccess(authorizationHeader: string | undefined, origin: string, endpointPath: string, authorization: EndpointAuthorization): Promise<EndpointAccess>;
+export declare function authorizedAccess(authorizationHeader: string | undefined, origin: string, endpointPath: string, authorization: EndpointAuthorization, reportFailure: (error: unknown) => void): Promise<EndpointAccess>;
 /** An open endpoint's check: the caller is on this machine. */
 export declare function loopbackAccess(remoteAddress: string | undefined, header: (name: string) => string | undefined): EndpointAccess;
+export {};

package/dist/endpoint-access.policy.js

@@ -23,31 +23,37 @@ function bearerTokenOf(header) {
     const match = /^Bearer[ \t]+([^ \t].*?)[ \t]*$/i.exec(header ?? "");
     return match?.[1];
 }
-function challenge(origin, endpointPath, description) {
-    const metadata = `${origin}${metadataPathOf(endpointPath)}`;
-    return jsonAnswer(401, { error: "invalid_token", error_description: description }, {
-        "WWW-Authenticate": `Bearer error="invalid_token", error_description="${description}", resource_metadata="${metadata}"`,
+function challenge(origin, endpointPath, invalid) {
+    const metadata = `resource_metadata="${origin}${metadataPathOf(endpointPath)}"`;
+    if (invalid === undefined) {
+        return jsonAnswer(401, {
+            error: "unauthorized",
+            error_description: "This MCP endpoint requires a bearer token in the Authorization header.",
+        }, { "WWW-Authenticate": `Bearer ${metadata}` });
+    }
+    return jsonAnswer(401, { error: "invalid_token", error_description: invalid.description }, {
+        "WWW-Authenticate": `Bearer error="invalid_token", error_description="${invalid.description}", ${metadata}`,
     });
 }
-export async function authorizedAccess(authorizationHeader, origin, endpointPath, authorization) {
+export async function authorizedAccess(authorizationHeader, origin, endpointPath, authorization, reportFailure) {
     const token = bearerTokenOf(authorizationHeader);
     if (token === undefined) {
-        return {
-            ok: false,
-            response: challenge(origin, endpointPath, "Missing Authorization header"),
-        };
+        return { ok: false, response: challenge(origin, endpointPath) };
     }
     let claims;
     try {
         claims = await authorization.verify(token);
     }
-    catch {
+    catch (error) {
+        reportFailure(error);
         claims = null;
     }
     if (claims === null || claims === undefined) {
         return {
             ok: false,
-            response: challenge(origin, endpointPath, "The access token is invalid"),
+            response: challenge(origin, endpointPath, {
+                description: "The access token is invalid",
+            }),
         };
     }
     return { ok: true, caller: { claims } };
@@ -72,10 +78,25 @@ function isLoopbackOrigin(origin) {
     }
 }
 const LOOPBACK_ONLY = "This MCP endpoint has no authorization, so it answers callers on this machine only. Configure mcp.authorization to serve remote agents.";
+function isLoopbackHost(host) {
+    if (host === undefined || host === "" || /[\s/?#@\\,]/.test(host)) {
+        return false;
+    }
+    try {
+        const { hostname } = new URL(`http://${host}`);
+        return (hostname === "localhost" ||
+            hostname === "[::1]" ||
+            isLoopbackAddress(hostname));
+    }
+    catch {
+        return false;
+    }
+}
 export function loopbackAccess(remoteAddress, header) {
     const origin = header("origin");
     const local = isLoopbackAddress(remoteAddress) &&
         FORWARDING_HEADERS.every((name) => header(name) === undefined) &&
+        isLoopbackHost(header("host")) &&
         (origin === undefined || isLoopbackOrigin(origin));
     return local
         ? { ok: true }

package/dist/mcp.binder.d.ts

@@ -51,7 +51,8 @@ export type AvMcpBinding = {
      * then the MCP message answered as JSON, statelessly. A tool call runs as an
      * agent-origin protocol request. Never rejects: a failure of its own (the MCP
      * SDK's) is answered `500` with no detail and reported to the Framework's
-     * diagnostics sink as an `AvMcpDiagnostic`.
+     * diagnostics sink as an `AvMcpDiagnostic`; a `verify` that throws is
+     * answered `401` and reported the same way.
      */
     readonly handleEndpoint: (request: AvMcpRequest, options?: {
         /**

package/dist/mcp.binder.js

@@ -1,11 +1,12 @@
-import { mcpFailureReporterOf } from "@aventara/core/internal";
+import { accessProviderOf, mcpFailureReporterOf, projectJsonValue, } from "@aventara/core/internal";
 import { AvProtocol, } from "@aventara/core/protocol";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
 import { authorizedAccess, jsonAnswer, loopbackAccess, metadataAnswer, metadataPathOf, } from "./endpoint-access.policy.js";
 import { translateOperationCall, translateTransactionCall, } from "./tool-call.translator.js";
-import { CONTRACT_RESOURCE_URI, compileToolCatalog, OPERATION_FAMILIES, TRANSACTION_TOOL, } from "./tool-catalog.compiler.js";
+import { CONTRACT_RESOURCE_URI, compileToolCatalog, ME_TOOL, OPERATION_FAMILIES, TRANSACTION_TOOL, } from "./tool-catalog.compiler.js";
 import { internalFailureResult, refusedCallResult, toolResultOf, } from "./tool-result.encoder.js";
 const SERVER_INSTRUCTIONS = `This server reads and writes an application's data through Aventara. Read the resource ${CONTRACT_RESOURCE_URI} first: it describes every resource, its fields and the operations it offers. Then call a tool with { resource, variant, args }. A failed call answers isError with the outcome code and the issues to fix.`;
 export function bind(framework) {
@@ -15,6 +16,7 @@ export function bind(framework) {
     }
     const agent = framework.contracts.agent;
     const protocol = AvProtocol.bind(framework, { origin: "agent" });
+    const me = accessProviderOf(framework)?.client?.verbs.me;
     const bound = {
         endpoint,
         protocol,
@@ -22,6 +24,7 @@ export function bind(framework) {
         tools: compileToolCatalog({
             surface: protocol.surface(),
             maxTransactionOperations: agent.limits.maxTransactionOperations,
+            me: me !== undefined,
         }),
         contractDocument: protocol.encodeContract({
             method: "GET",
@@ -31,6 +34,8 @@ export function bind(framework) {
         }).body,
         maxRequestBytes: agent.limits.maxRequestBytes,
         reportFailure: mcpFailureReporterOf(framework),
+        schemaValidator: new AjvJsonSchemaValidator(),
+        me,
     };
     const routes = Object.freeze([
         Object.freeze({
@@ -105,7 +110,7 @@ async function answerEndpoint(bound, request, state) {
         const { authorization } = bound.endpoint;
         const access = authorization === undefined
             ? loopbackAccess(request.remoteAddress, header)
-            : await authorizedAccess(header("authorization"), url.origin, bound.endpoint.path, authorization);
+            : await authorizedAccess(header("authorization"), url.origin, bound.endpoint.path, authorization, bound.reportFailure);
         if (!access.ok) {
             return access.response;
         }
@@ -186,6 +191,7 @@ function serverFor(bound, headers, state) {
     const server = new Server({ name: "aventara", title: "Aventara", version: bound.identity.hash }, {
         capabilities: { tools: {}, resources: {} },
         instructions: SERVER_INSTRUCTIONS,
+        jsonSchemaValidator: bound.schemaValidator,
     });
     const options = state === undefined ? {} : { state };
     server.setRequestHandler(ListToolsRequestSchema, guarded(bound, () => ({ tools: bound.tools })));
@@ -242,6 +248,9 @@ function guarded(bound, handler) {
     };
 }
 async function callTool(bound, name, input, headers, options) {
+    if (name === ME_TOOL) {
+        return (await answerMe(bound, input, headers));
+    }
     if (name === TRANSACTION_TOOL) {
         const translated = await translateTransactionCall(input, headers, bound.identity);
         return (translated.ok
@@ -254,3 +263,33 @@ async function callTool(bound, name, input, headers, options) {
         ? toolResultOf(await bound.protocol.handleOperation(translated.request, options))
         : refusedCallResult(translated.message));
 }
+async function answerMe(bound, input, headers) {
+    if (input !== undefined &&
+        (typeof input !== "object" ||
+            input === null ||
+            Array.isArray(input) ||
+            Object.keys(input).length > 0)) {
+        return refusedCallResult("me takes no arguments: call it with {}.");
+    }
+    const me = bound.me;
+    if (me === undefined) {
+        throw new Error("The me tool was called on a binding that offers none.");
+    }
+    const identity = await me.call({
+        args: undefined,
+        headers: webHeadersOf(headers),
+    });
+    const data = identity === null || identity === undefined
+        ? null
+        : projectJsonValue(identity, me.result);
+    return toolResultOf(jsonAnswer(200, { code: "A1000", data, cause: null }));
+}
+function webHeadersOf(headers) {
+    const web = new Headers();
+    for (const [name, value] of Object.entries(headers)) {
+        for (const item of typeof value === "string" ? [value] : (value ?? [])) {
+            web.append(name, item);
+        }
+    }
+    return web;
+}

package/dist/tool-call.translator.d.ts

@@ -6,7 +6,7 @@ export type AgentIdentity = {
     readonly hash: string;
 };
 /** A tool call as the protocol request that runs it, or why it cannot be one. */
-export type TranslatedCall = {
+type TranslatedCall = {
     readonly ok: true;
     readonly kind: "operation" | "transaction";
     readonly request: AvProtocolRequest;
@@ -30,3 +30,4 @@ export declare function translateOperationCall(family: OperationFamily, input: u
  * left as written, for the protocol to refuse.
  */
 export declare function translateTransactionCall(input: unknown, received: Readonly<Record<string, string | readonly string[] | undefined>>, identity: AgentIdentity): Promise<TranslatedCall>;
+export {};

package/dist/tool-call.translator.js

@@ -32,6 +32,9 @@ function protocolRequest(path, body, headers) {
         body: { kind: "raw", content: jsonTextOf(body) },
     };
 }
+function routeSegmentOf(name) {
+    return encodeURIComponent(name.replace(/\p{Surrogate}/gu, "\uFFFD"));
+}
 export function translateOperationCall(family, input, received, identity) {
     if (!isRecord(input)) {
         return {
@@ -46,7 +49,7 @@ export function translateOperationCall(family, input, received, identity) {
             message: `${family}: \`resource\` and \`variant\` must be strings (read ${CONTRACT_RESOURCE_URI}).`,
         };
     }
-    const path = `/_resources/${[resource, family, variant].map(encodeURIComponent).join("/")}`;
+    const path = `/_resources/${[resource, family, variant].map(routeSegmentOf).join("/")}`;
     return {
         ok: true,
         kind: "operation",
@@ -80,8 +83,8 @@ export async function translateTransactionCall(input, received, identity) {
             args,
         };
         const fingerprint = await fingerprintOf(node);
-        fingerprints.push(fingerprint ?? "");
-        operations.push(fingerprint === undefined ? node : { ...node, fingerprint });
+        fingerprints.push(fingerprint);
+        operations.push({ ...node, fingerprint });
     }
     return {
         ok: true,
@@ -94,7 +97,7 @@ async function fingerprintOf(node) {
         return await computeOperationFingerprint(node);
     }
     catch {
-        return undefined;
+        return null;
     }
 }
 function referenced(value, fingerprints) {
@@ -163,7 +166,7 @@ function withFingerprint(value, fingerprints) {
     const fingerprint = typeof operation === "number" && Number.isInteger(operation)
         ? fingerprints[operation]
         : undefined;
-    return fingerprint === undefined || fingerprint === ""
+    return fingerprint === undefined || fingerprint === null
         ? value
         : { $ref: { ...reference, fingerprint } };
 }

package/dist/tool-catalog.compiler.d.ts

@@ -5,8 +5,10 @@ export declare const OPERATION_FAMILIES: readonly ["find", "create", "update", "
 export type OperationFamily = (typeof OPERATION_FAMILIES)[number];
 /** The name of the tool that runs a plan of operations. */
 export declare const TRANSACTION_TOOL = "transaction";
+/** The name of the tool that answers who the agent acts for. */
+export declare const ME_TOOL = "me";
 /** Every tool name the catalog can offer. */
-export type McpToolName = OperationFamily | typeof TRANSACTION_TOOL;
+export type McpToolName = OperationFamily | typeof TRANSACTION_TOOL | typeof ME_TOOL;
 /** An MCP tool's behaviour hints. */
 export type McpToolAnnotations = {
     readonly readOnlyHint: boolean;
@@ -31,14 +33,17 @@ export type McpToolDefinition = {
 };
 /** The URI of the MCP resource that holds the Agent Contract. */
 export declare const CONTRACT_RESOURCE_URI = "aventara://contract";
-/** What the catalog is compiled from: the agent binding's surface, and its plan limit. */
+/** What the catalog is compiled from: the agent binding's surface, its plan limit, and whether `me` is offered. */
 export type CatalogSource = {
     readonly surface: ReturnType<AvProtocolBinding["surface"]>;
     readonly maxTransactionOperations: number;
+    /** The access provider states its `client`, so `me` has an answer. */
+    readonly me?: boolean;
 };
 /**
  * The tools the agent binding's surface supports: one per family it offers, in
  * the protocol's family order, then `transaction` when the surface has the
- * transactions route and at least one operation.
+ * transactions route and at least one operation, then `me` when the access
+ * provider states its `client`.
  */
 export declare function compileToolCatalog(source: CatalogSource): readonly McpToolDefinition[];

package/dist/tool-catalog.compiler.js

@@ -6,6 +6,7 @@ export const OPERATION_FAMILIES = [
     "upsert",
 ];
 export const TRANSACTION_TOOL = "transaction";
+export const ME_TOOL = "me";
 const VARIANT_ORDER = {
     find: ["first", "unique", "many", "count"],
     create: ["one", "many", "count"],
@@ -59,6 +60,7 @@ const ANNOTATIONS = {
         destructiveHint: true,
         openWorldHint: false,
     },
+    me: { readOnlyHint: true, openWorldHint: false },
 };
 export const CONTRACT_RESOURCE_URI = "aventara://contract";
 const ENVELOPE_SCHEMA = {
@@ -193,6 +195,17 @@ function transactionTool(offers, maxTransactionOperations) {
         annotations: ANNOTATIONS.transaction,
     };
 }
+const ME_TOOL_DEFINITION = {
+    name: ME_TOOL,
+    title: "Who is signed in",
+    description: [
+        "Answers who this agent acts for: the identity Aventara Access resolved from this request's credentials, { sub, claims }, as the data, or null when no one is signed in.",
+        "Takes no arguments: call it with {}.",
+    ].join(" "),
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    outputSchema: ENVELOPE_SCHEMA,
+    annotations: ANNOTATIONS.me,
+};
 export function compileToolCatalog(source) {
     const offers = offersOf(source.surface);
     const tools = [];
@@ -206,5 +219,8 @@ export function compileToolCatalog(source) {
         source.surface.some((route) => route.kind === "transactions")) {
         tools.push(transactionTool(offers, source.maxTransactionOperations));
     }
+    if (source.me === true) {
+        tools.push(ME_TOOL_DEFINITION);
+    }
     return Object.freeze(tools);
 }

package/dist/tool-result.encoder.d.ts

@@ -1,7 +1,7 @@
 import type { AvOperationFailureResponse } from "@aventara/core";
 import type { AvProtocolResponse } from "@aventara/core/protocol";
 /** A tool call's result, as `tools/call` answers it. */
-export type McpToolResult = {
+type McpToolResult = {
     readonly content: readonly [{
         readonly type: "text";
         readonly text: string;
@@ -25,3 +25,4 @@ export declare function refusedCallResult(message: string): McpToolResult;
  * protocol's own `A3000`. Nothing of the thrown error is in it.
  */
 export declare function internalFailureResult(envelope: AvOperationFailureResponse): McpToolResult;
+export {};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@aventara/mcp",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.11",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The MCP server for an Aventara application: its agent layer as Model Context Protocol tools.",
   "type": "module",
   "engines": {
-    "node": "^22.18.0 || >=24.2.0"
+    "node": "^22.23.4 || >=24.22.1"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,15 +22,15 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.1",
-    "@modelcontextprotocol/sdk": "1.30.1",
-    "zod": "^4.6.5"
+    "@aventara/core": "1.0.0-rc.11",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "1.0.0-rc.1"
+    "@aventara/testing": "1.0.0-rc.11"
   },
   "scripts": {
     "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",