@ultimat3/mcp 23.0.0 → 25.0.0

package/src/scopes.ts

@@ -4,13 +4,13 @@
 // other is its authz rule, and both belong beside the code they guard. A SCOPE is neither.
 // It is a capability of the CONNECTION — what the token was issued to do — so it is grouped
 // here, once per scope, naming the tools that capability covers. That is also why
-// `toolFromAction` never invents one: a projection cannot know what a token means.
+// `toolFrom` never invents one: a projection cannot know what a token means.
 //
 // Without this map the second outcome is unreachable for a generated app. `ToolRegistry`
 // enforces `scope`, the framework's own dev tools declare one, and until 2026-08 nothing an
 // app could write ever set the field — an enforced gate no app declaration could engage.
 
-import { McpScopeConflictError, McpScopeUnknownError } from './errors';
+import { McpScopeConflictError, McpScopeUncoveredError, McpScopeUnknownError } from './errors';
 import type { AnyMcpTool } from './registry';
 
 /**
@@ -25,14 +25,19 @@ export type McpScopes = Readonly<Record<string, readonly string[]>>;
 /**
  * Attach each declared scope to the tool it covers, refusing anything ambiguous at BOOT.
  *
- * Two refusals, because both silently ship an ungated tool otherwise:
+ * Three refusals, because each silently ships an ungated tool otherwise:
  *
  *  - a name no tool in the catalog answers to (`X_MCP_SCOPE_UNKNOWN`) — a typo, or a primitive
  *    that was renamed or never listed. Skipping it leaves the tool reachable with no scope at
  *    all, which is the opposite of what the author wrote;
  *  - one tool claimed by two scopes (`X_MCP_SCOPE_CONFLICT`) — a tool carries ONE scope, so
  *    the second claim would either overwrite the first or be dropped, and which one wins would
- *    be decided by object key order.
+ *    be decided by object key order;
+ *  - a projected tool no scope names (`X_MCP_SCOPE_UNCOVERED`). The registry gates a tool only
+ *    when it carries a scope, so an unnamed one answered EVERY token — while `bearerMount`, handed
+ *    the same map, serves an unnamed primitive to nobody. Giving a map is declaring the cut; a
+ *    tool outside it is a mistake, not a public tool. A tool that arrived with its own `scope`
+ *    (a ready `McpTool`) is covered by it.
  *
  * Runs AFTER duplicate names are refused, so a name resolves to exactly one tool.
  */
@@ -64,6 +69,12 @@ export function withScopes(
     }
   }
 
+  const uncovered = tools
+    .filter((tool) => tool.scope === undefined && !required.has(tool.name))
+    .map((tool) => tool.name)
+    .sort();
+  if (uncovered.length > 0) throw new McpScopeUncoveredError({ uncovered });
+
   return tools.map((tool) => {
     const scope = required.get(tool.name);
     return scope === undefined ? tool : { ...tool, scope };

package/src/server-voice.ts

@@ -8,7 +8,7 @@ import { formatIssues } from '@ultimat3/schema';
 import type { McpCaller, McpToolResult } from './registry';
 import type { ArgIssue } from './validate-args';
 
-/** See `CreateMcpServerInput.instructions`. */
+/** See `McpServerInput.instructions`. */
 export type McpInstructions = string | ((caller: McpCaller) => string | undefined);
 
 /** The server's per-caller wording: `initialize`'s advice and the audience of every `fix:` line. */

package/src/server.ts

@@ -3,11 +3,13 @@
 // and an already-resolved caller, and returns a response or `null` for a notification.
 // Both transports (http, stdio) and every test drive this one function.
 
-import type { ErrorAudience } from '@ultimat3/core';
+import type { Clock, ErrorAudience } from '@ultimat3/core';
 import { fixFor } from '@ultimat3/core';
-import { auditResourceRead, auditToolCall, outcomeForResult } from './audit';
+import { outcomeForResult } from './audit';
+import type { McpAuditHook, McpAuditor } from './audit-hook';
+import { LOG_ONLY_AUDITOR, mcpAuditor } from './audit-hook';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
-import { asFrameworkError } from './framework-error';
+import { asFrameworkError, forAudience } from './framework-error';
 import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
@@ -27,7 +29,7 @@ import { ResourceRegistry } from './resources';
 import type { McpInstructions, McpServerVoice } from './server-voice';
 import { instructionsFor, invalidArgsResult } from './server-voice';
 import { admitted, thrownResponse } from './tool-thrown';
-import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpWire, ServerInfo } from './wire';
 import {
   defaultServerInfo,
   errorResponse,
@@ -38,28 +40,14 @@ import {
   isNotification,
   MCP_PROTOCOL_VERSION,
   METHOD_NOT_FOUND,
+  messageUnitOf,
   paramsOf,
   resultResponse,
 } from './wire';
 
-/**
- * Which wire one message arrived on, so a refusal can name the unit THAT transport counts in.
- * `handle` is transport-independent and stays so — this is a hint for the wording of one fix, never
- * a branch in dispatch. HTTP carries its mounted path because `mcpHttpRoute({ path })` is a knob:
- * a batch refusal that told every client to retry `POST /mcp` was wrong for an app mounted at
- * `/app-mcp`, which is how this came to be threaded rather than spelled.
- */
-export type McpWire =
-  | { readonly transport: 'http'; readonly path: string }
-  | { readonly transport: 'stdio' };
-
-/** The unit a transport counts one request in — or the neutral word when no wire said. */
-const messageUnitOf = (wire: McpWire | undefined): string => {
-  if (wire === undefined) return 'message';
-  return wire.transport === 'http' ? `POST ${wire.path}` : 'line';
-};
+export type { McpWire } from './wire';
 
-export interface CreateMcpServerInput {
+export interface McpServerInput {
   readonly tools?: readonly AnyMcpTool[];
   readonly resources?: readonly McpResource[];
   readonly prompts?: readonly McpPrompt[];
@@ -82,6 +70,10 @@ export interface CreateMcpServerInput {
    * serves `'caller'`.
    */
   readonly errorAudience?: ErrorAudience | undefined;
+  /** Every gate decision as data, after its log line — see `audit-hook.ts`. The route reads it too. */
+  readonly onAudit?: McpAuditHook | undefined;
+  /** Stamps each `onAudit` event's `at`. */
+  readonly clock?: Clock | undefined;
 }
 
 /** The set of JSON-RPC methods this server answers. Kept in sync with `classify`. */
@@ -96,7 +88,7 @@ const METHODS = [
   'prompts/get',
 ] as const;
 
-export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
+export function mcpServer(input: McpServerInput = {}): McpServer {
   const tools = new ToolRegistry().registerAll(input.tools ?? []);
   const resources = new ResourceRegistry().registerAll(input.resources ?? []);
   const meta = MetaSurface.build({
@@ -111,6 +103,9 @@ export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
     input.serverInfo ?? defaultServerInfo(),
     meta,
     { instructions: input.instructions, errorAudience: input.errorAudience ?? 'developer' },
+    input.onAudit === undefined && input.clock === undefined
+      ? LOG_ONLY_AUDITOR
+      : mcpAuditor({ onAudit: input.onAudit, clock: input.clock }),
   );
 }
 
@@ -122,6 +117,8 @@ export class McpServer {
   /** `undefined` for a flat-only server — every existing app, byte for byte. */
   private readonly meta: MetaSurface | undefined;
   private readonly voice: McpServerVoice;
+  /** Where every decision is audited — the log line, then `onAudit`. Public for the HTTP route. */
+  readonly audit: McpAuditor;
 
   constructor(
     tools: ToolRegistry,
@@ -130,6 +127,7 @@ export class McpServer {
     serverInfo: ServerInfo,
     meta?: MetaSurface,
     voice: McpServerVoice = { errorAudience: 'developer' },
+    audit: McpAuditor = LOG_ONLY_AUDITOR,
   ) {
     this.tools = tools;
     this.resources = resources;
@@ -137,6 +135,7 @@ export class McpServer {
     this.serverInfo = serverInfo;
     this.meta = meta;
     this.voice = voice;
+    this.audit = audit;
   }
 
   async handle(
@@ -275,6 +274,7 @@ export class McpServer {
       const answered = await metaCall(
         {
           tools: this.tools,
+          audit: this.audit,
           dispatch: (at, tool, resolved, who) => this.dispatch(at, tool, resolved, who),
           notFound: (at, tool, who, fix) => this.notFound(at, tool, who, fix),
         },
@@ -293,7 +293,7 @@ export class McpServer {
 
   /** OUTCOME 1, the one answer for absent and hidden alike. See `dispatch`. */
   private notFound(id: JsonRpcId, name: string, caller: McpCaller, fix: string): JsonRpcResponse {
-    auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
+    this.audit.toolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
     return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name} — ${fix}`);
   }
 
@@ -327,7 +327,7 @@ export class McpServer {
       // nothing — and the fix travels with it, built by the error that owns the wording.
       case 'scope-denied': {
         const denial = new McpScopeDeniedError({ name, scope: resolved.scope });
-        auditToolCall({
+        this.audit.toolCall({
           tool: name,
           outcome: 'scope-denied',
           caller,
@@ -346,9 +346,10 @@ export class McpServer {
         // they send gets the denial `handle` would give, never the issue list — which describes
         // the arguments of a tool they may not call.
         const refused = admitted(resolved.tool, caller);
-        if (refused !== undefined) return thrownResponse(id, name, refused, caller, audience);
+        if (refused !== undefined)
+          return thrownResponse(id, name, refused, caller, audience, this.audit);
         const invalid = invalidArgsResult(name, resolved.issues, audience);
-        auditToolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
+        this.audit.toolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
         return resultResponse(id, invalid.result);
       }
       case 'ok':
@@ -359,13 +360,13 @@ export class McpServer {
     try {
       result = await resolved.tool.handle(resolved.args, caller);
     } catch (error) {
-      return thrownResponse(id, name, error, caller, audience);
+      return thrownResponse(id, name, error, caller, audience, this.audit);
     }
 
     // A tool may answer `isError` itself (admin renders its own denial). Outcome 3 unless it
     // NAMED the code it refused with, in which case the same classifier a thrown error goes
     // through decides — a tool's own argument check is not a denial a prober drove.
-    auditToolCall({
+    this.audit.toolCall({
       tool: name,
       outcome: outcomeForResult(result),
       caller,
@@ -406,7 +407,7 @@ export class McpServer {
       // `code` on the audit line either, because the wire carries none — the tool surface's
       // `X_MCP_TOOL_UNKNOWN` is an error class this branch has no twin for.
       case 'not-found':
-        auditResourceRead({ uri, outcome: 'hidden', caller });
+        this.audit.resourceRead({ uri, outcome: 'hidden', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       // OUTCOME 2. The caller can already see this resource, so naming the missing scope leaks
       // nothing — and the fix travels with it, built by the error that owns the wording.
@@ -416,7 +417,7 @@ export class McpServer {
           scope: resolved.scope,
           subject: 'resource',
         });
-        auditResourceRead({
+        this.audit.resourceRead({
           uri,
           outcome: 'scope-denied',
           caller,
@@ -444,15 +445,16 @@ export class McpServer {
       if (contents === undefined) {
         // The resolver said `ok` and the registry then had nothing: a bug here, not a walk, so it
         // is `failed` in the log while the caller still gets the same not-found it would have.
-        auditResourceRead({ uri, outcome: 'failed', caller });
+        this.audit.resourceRead({ uri, outcome: 'failed', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       }
-      auditResourceRead({ uri, outcome: 'ok', caller });
+      this.audit.resourceRead({ uri, outcome: 'ok', caller });
       return resultResponse(id, { contents: [contents] });
     } catch (error) {
-      const framework = asFrameworkError(error);
-      if (framework !== undefined) {
-        auditResourceRead({ uri, outcome: 'failed', caller, code: framework.code });
+      const thrown = asFrameworkError(error);
+      if (thrown !== undefined) {
+        const framework = forAudience(thrown, this.voice.errorAudience);
+        this.audit.resourceRead({ uri, outcome: 'failed', caller, code: framework.code });
         return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
           code: framework.code,
           cause: framework.cause,
@@ -462,7 +464,7 @@ export class McpServer {
       }
       // No internals: a provider's own message names a path, a query or a host the caller has no
       // business seeing, exactly as a failing tool's does.
-      auditResourceRead({ uri, outcome: 'failed', caller });
+      this.audit.resourceRead({ uri, outcome: 'failed', caller });
       return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`);
     }
   }

package/src/tool-thrown.ts

@@ -3,7 +3,8 @@
 // raised it. Split from `server.ts` for the file ceiling; the server is its only caller.
 
 import type { ErrorAudience } from '@ultimat3/core';
-import { auditToolCall, outcomeForCode } from './audit';
+import { outcomeForCode } from './audit';
+import type { McpAuditor } from './audit-hook';
 import { asFrameworkError, renderFrameworkError } from './framework-error';
 import type { AnyMcpTool, McpCaller } from './registry';
 import type { JsonRpcId, JsonRpcResponse } from './wire';
@@ -21,10 +22,11 @@ export function thrownResponse(
   error: unknown,
   caller: McpCaller,
   audience: ErrorAudience,
+  audit: McpAuditor,
 ): JsonRpcResponse {
   const framework = asFrameworkError(error);
   if (framework !== undefined) {
-    auditToolCall({
+    audit.toolCall({
       tool: name,
       outcome: outcomeForCode(framework.code),
       caller,
@@ -35,7 +37,7 @@ export function thrownResponse(
       isError: true,
     });
   }
-  auditToolCall({ tool: name, outcome: 'failed', caller });
+  audit.toolCall({ tool: name, outcome: 'failed', caller });
   return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
 }
 

package/src/transport-http.ts

@@ -21,9 +21,9 @@
 
 import type { Actor, Clock } from '@ultimat3/core';
 import { finiteCount, readWithinLimit, systemClock } from '@ultimat3/core';
-import type { RateLimitStore } from '@ultimat3/http';
-import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
-import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
+import type { Bucket, RequestFacts as McpRequestFacts, RateLimitStore } from '@ultimat3/http';
+import { memoryRateLimitStore, requestFacts, toBucket } from '@ultimat3/http';
+import { McpBodyTooLargeError, McpRateLimitedError } from './errors-transport';
 import type { McpOAuth } from './oauth-metadata';
 import {
   assertMcpOAuth,
@@ -43,7 +43,7 @@ import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './w
 /**
  * The same 1 MiB `@ultimat3/http`'s `bodyLimitBytes` defaults to. This descriptor is driven from a
  * bare `Request` and never passes through that pipeline, so without a cap here Bun's 128 MiB
- * default was the only ceiling — and `x mcp serve` and `createServer` both pass no
+ * default was the only ceiling — and `x mcp serve` and `httpServer` both pass no
  * `maxRequestBodySize`.
  */
 export const DEFAULT_MCP_BODY_LIMIT_BYTES = 1_048_576;
@@ -57,6 +57,18 @@ export const MCP_RATE_LIMITS: Readonly<Record<McpVerbClass, number>> = {
   write: 20,
 };
 
+/**
+ * Failed authentications per minute per ADDRESS. An address past it is refused before
+ * `resolveToken` runs, so guessing tokens is bounded and a valid guess is answered the same 429.
+ */
+export const MCP_UNAUTHENTICATED_LIMIT = 20;
+
+/** `rateLimits` as declared: the two per-actor classes, and the per-address failure allowance. */
+export type McpRateLimits = Readonly<Record<McpVerbClass, number>> & {
+  /** Failed authentications per minute per address. Defaults to `MCP_UNAUTHENTICATED_LIMIT`. */
+  readonly unauthenticated?: number | undefined;
+};
+
 /** What a token resolves to. `null` = unauthenticated, answered 401 with no catalog. */
 export interface ResolvedToken {
   readonly actor: Actor;
@@ -67,16 +79,25 @@ export interface ResolvedToken {
 export interface McpHttpTransportInput {
   readonly server: McpServer;
   /**
-   * Resolve an OAuth bearer / personal token to a caller. The framework supplies the token
-   * string only — credential storage belongs to `@ultimat3/policy` and the app, never here.
+   * Resolve an OAuth bearer / personal token to a caller. The framework supplies the token and
+   * how the request arrived (`McpRequestFacts`: the host-resolved address, user agent, `Origin`,
+   * path) — so a token can be bound to a network or refused from a browser origin. Credential
+   * storage belongs to `@ultimat3/policy` and the app, never here. A one-argument resolver is
+   * still one: the facts are an extra argument it may ignore.
    */
-  resolveToken(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
+  resolveToken(
+    token: string,
+    facts: McpRequestFacts,
+  ): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Route path. Overridable so an app can mount a second, app-scoped surface. */
   readonly path?: string;
   /** Bytes this transport will hold for one request. Defaults to `DEFAULT_MCP_BODY_LIMIT_BYTES`. */
   readonly bodyLimitBytes?: number | undefined;
-  /** Requests per minute per caller, by class. Defaults to `MCP_RATE_LIMITS`. */
-  readonly rateLimits?: Readonly<Record<McpVerbClass, number>> | undefined;
+  /**
+   * Requests per minute per caller, by class — defaults to `MCP_RATE_LIMITS` — and failed
+   * authentications per minute per address (`unauthenticated`, `MCP_UNAUTHENTICATED_LIMIT`).
+   */
+  readonly rateLimits?: McpRateLimits | undefined;
   /**
    * Where the buckets are counted. Defaults to a per-PROCESS memory store, which is the honest
    * default for `x mcp serve` and a lie for N replicas behind one URL — each would enforce the
@@ -100,6 +121,12 @@ export interface McpHttpTransportInput {
 export interface McpRequestOrigin {
   /** The PUBLIC origin, `https://www.example.com`. Defaults to the request URL's own. */
   readonly origin?: string | undefined;
+  /**
+   * The caller's address as the host resolved it (a trusted proxy's `x-forwarded-for` honoured) —
+   * what failed authentications are counted against. Absent, they are not counted here: one
+   * shared key would let a stranger's failures lock every agent out.
+   */
+  readonly address?: string | undefined;
 }
 
 /** The metadata half of an `oauth` route: where to serve it and what to answer. */
@@ -116,7 +143,7 @@ export interface McpRouteDescriptor {
   /** Bucket for one already-parsed body. Metering only — never an authz decision. */
   rateLimitClass(body: unknown): McpVerbClass;
   /** Requests per minute per caller, by class — what `handle` actually spends against. */
-  readonly limits: Readonly<Record<McpVerbClass, number>>;
+  readonly limits: McpRateLimits;
   /** Present exactly when the route was built with `oauth`. */
   readonly protectedResource?: McpProtectedResource;
   handle(request: Request, seen?: McpRequestOrigin): Promise<Response>;
@@ -144,7 +171,7 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     input.bodyLimitBytes ?? DEFAULT_MCP_BODY_LIMIT_BYTES,
     0,
   );
-  const limits = input.rateLimits ?? MCP_RATE_LIMITS;
+  const limits: McpRateLimits = input.rateLimits ?? MCP_RATE_LIMITS;
   const clock = input.clock ?? systemClock;
   const store = input.rateLimitStore ?? memoryRateLimitStore();
   // Built once, at construction: `toBucket` refuses an unusable pair (`X_RATE_LIMIT_INVALID`), and
@@ -159,6 +186,20 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     windowMs: MCP_RATE_LIMIT_WINDOW_MS,
   });
 
+  // A COUNT of failures, screened where it is declared: `toBucket` alone would read `NaN` as a
+  // bound only at its own check, and `??` never fires for one.
+  const unauthenticated = finiteCount(
+    'mcpHttpRoute',
+    'rateLimits.unauthenticated',
+    limits.unauthenticated ?? MCP_UNAUTHENTICATED_LIMIT,
+    1,
+  );
+  const failureBucket = toBucket('mcpHttpRoute rateLimits.unauthenticated', {
+    limit: unauthenticated,
+    windowMs: MCP_RATE_LIMIT_WINDOW_MS,
+  });
+  const failures = failureMeter(store, failureBucket, clock);
+
   const path = input.path ?? '/mcp';
   const oauth = input.oauth;
   if (oauth !== undefined) assertMcpOAuth(oauth);
@@ -193,13 +234,45 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // remove, and it costs nothing to close: the body is not an input to any of these.
       const resource = resourceOf(request, seen);
       const metadataUrl = resource === undefined ? undefined : metadataUrlFor(resource);
+      // An address that has spent its failures is refused BEFORE the credential store is asked:
+      // counting only after the fact turned a 401 into a 429 and still answered a valid guess.
+      const address = seen?.address;
+      // Built once per request: the resolver's second argument and every refusal's audit facts.
+      // The address inside is the host's answer (`seen.address`), never a header read here.
+      const facts = requestFacts({ headers: request.headers, url: request.url, address });
+      const audit = server.audit;
+      const exhausted = await failures.refusing(address);
+      if (exhausted !== undefined) {
+        audit.authRefused('throttled', exhausted.status, facts);
+        return exhausted;
+      }
+      // A failure spends the address's allowance; the 429 wins when that one did not fit.
+      const refuse = async (
+        reason: 'missing-token' | 'rejected-token',
+        challenge: string,
+      ): Promise<Response> => {
+        const throttledNow = await failures.spend(address);
+        const response = throttledNow ?? unauthorized(challenge);
+        audit.authRefused(
+          throttledNow === undefined ? reason : 'throttled',
+          response.status,
+          facts,
+        );
+        return response;
+      };
       const token = bearerToken(request);
-      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false, challengeScopes));
+      if (token === null) {
+        return refuse('missing-token', bearerChallenge(metadataUrl, false, challengeScopes));
+      }
 
-      const resolved = await input.resolveToken(token);
-      if (resolved === null)
-        return unauthorized(bearerChallenge(metadataUrl, true, challengeScopes));
-      if (!isAgentActor(resolved.actor)) return notAnAgent();
+      const resolved = await input.resolveToken(token, facts);
+      if (resolved === null) {
+        return refuse('rejected-token', bearerChallenge(metadataUrl, true, challengeScopes));
+      }
+      if (!isAgentActor(resolved.actor)) {
+        audit.authRefused('not-an-agent', 403, facts);
+        return notAnAgent();
+      }
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
       // WHILE the bytes arrive, or a `transfer-encoding: chunked` payload is materialised in full
@@ -275,6 +348,31 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   };
 }
 
+/**
+ * The per-address failure allowance. `refusing` reads the bucket (`RateLimitStore.peek`, which
+ * writes nothing) and answers the 429 when not one more failure fits; `spend` charges one
+ * failure and answers the 429 when that one did not fit. `undefined` from either: carry on.
+ */
+function failureMeter(store: RateLimitStore, bucket: Bucket, clock: Clock) {
+  const keyOf = (address: string): string => `mcp:unauthenticated|ip:${address}`;
+  const refusal = (retryAfterSeconds: number): Response =>
+    throttled('unauthenticated', bucket.capacity, retryAfterSeconds);
+  return {
+    async refusing(address: string | undefined): Promise<Response | undefined> {
+      if (address === undefined) return undefined;
+      // READ ONLY: this runs on every request, an agent's included, and a write per call would be
+      // a Postgres upsert on the hot path of every authenticated one.
+      const peek = await store.peek(keyOf(address), bucket, clock.now().getTime());
+      return peek.remaining >= 1 ? undefined : refusal(peek.retryAfterSeconds);
+    },
+    async spend(address: string | undefined): Promise<Response | undefined> {
+      if (address === undefined) return undefined;
+      const spent = await store.take(keyOf(address), bucket, 1, clock.now().getTime());
+      return spent.allowed ? undefined : refusal(spent.retryAfterSeconds);
+    },
+  };
+}
+
 /** `Authorization: Bearer <token>`, the only accepted form. No query-string tokens. */
 export function bearerToken(request: Request): string | null {
   const header = request.headers.get('authorization');
@@ -298,7 +396,11 @@ export function isAgentActor(actor: Actor): boolean {
  * call to answer. `retry-after` carries the same number the `fix:` line names, because an agent
  * reads one of the two and must not get different answers from them.
  */
-function throttled(verbClass: McpVerbClass, limit: number, retryAfterSeconds: number): Response {
+function throttled(
+  verbClass: keyof McpRateLimits,
+  limit: number,
+  retryAfterSeconds: number,
+): Response {
   const error = new McpRateLimitedError({ verbClass, limit, retryAfterSeconds });
   return new Response(JSON.stringify({ code: error.code, cause: error.cause, fix: error.fix }), {
     status: 429,

package/src/transport-stdio.ts

@@ -9,7 +9,7 @@
 // stderr and this file never calls `console.log`.
 
 import { finiteCount } from '@ultimat3/core';
-import { McpBodyTooLargeError } from './errors';
+import { McpBodyTooLargeError } from './errors-transport';
 import type { McpCaller } from './registry';
 import type { McpServer } from './server';
 import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './wire';

package/src/type-pins.ts

@@ -0,0 +1,52 @@
+// Compile-time pins for this package's public types. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level claim written in one can never fail. This module emits nothing and exports nothing
+// anybody imports — a regression here is a build error, the only enforcement that counts.
+
+import type {
+  McpListParams as CoreListParams,
+  McpAnnotationHints,
+  McpExposureDeclaration,
+} from '@ultimat3/core';
+import type { ProjectablePrimitive } from './from-action';
+import type { McpListParams } from './list-params';
+import type { McpToolAnnotations } from './registry';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+type Projected = NonNullable<ProjectablePrimitive['mcp']>;
+
+/**
+ * 25.0.0: the projection reads core's ONE `mcp` block. `McpExposure` restated it here, a field
+ * looser (`expose?`) than the block an action or query is held to; a twin coming back as a
+ * different shape flips this to `false`.
+ */
+export type _ProjectionReadsCoresBlock = Assert<Identical<Projected, McpExposureDeclaration>>;
+
+/**
+ * 25.0.0 (plan 101, M4): a projected tool is named by its primitive's `name` and by nothing
+ * else. `McpExposure.name` was a second naming field no declaration could set; one coming back
+ * on core's block flips this to `false`.
+ */
+export type _McpBlockCarriesNoName = Assert<Equals<Extract<keyof Projected, 'name'>, never>>;
+
+/**
+ * The tool's own wire types (`McpTool.annotations`, `McpTool.listParams`) are what the block's
+ * fields become, so they must stay the block's shapes exactly: a hint or a whitelist key added
+ * on one side only is a declaration the other silently drops.
+ */
+export type _ToolAnnotationsAreTheBlocks = Assert<
+  Identical<McpToolAnnotations, McpAnnotationHints>
+>;
+export type _ToolListParamsAreTheBlocks = Assert<Identical<McpListParams, CoreListParams>>;

package/src/validate-args.ts

@@ -174,7 +174,8 @@ export const compiledPatternCount = (): number => compilations;
  * A pattern this server cannot COMPILE is refused, not skipped. `tools/list` published it, so an
  * agent has already been told the rule — passing a call the server cannot check is the silent-pass
  * this whole module exists to prevent. Every framework-projected pattern is a `RegExp.source` and
- * compiles; only a hand-written tool can reach the second branch, and that is its author's bug.
+ * its own flags and compiles; only a hand-written tool can reach the second branch, and that is its
+ * author's bug.
  */
 function matchesPattern(
   schema: JsonSchema,
@@ -183,21 +184,28 @@ function matchesPattern(
   path: string,
   issues: ArgIssue[],
 ): void {
+  // The flags `@ultimat3/schema` published beside the source. Without them `/^[a-z]+$/i` refused
+  // `ABC` and `/^\p{L}+$/u` refused `é` here, while the action's own parse accepted both.
+  const flags = schema['x-ultimate-pattern-flags'] ?? '';
+  const shown = flags === '' ? pattern : `/${pattern}/${flags}`;
   let compiled = compiledPatterns.get(schema);
   if (compiled === undefined) {
     compilations += 1;
     try {
-      compiled = new RegExp(pattern);
+      compiled = new RegExp(pattern, flags);
     } catch {
       compiled = null;
     }
     compiledPatterns.set(schema, compiled);
   }
   if (compiled === null) {
-    issues.push({ path, message: `declares a pattern this server cannot compile: ${pattern}` });
+    issues.push({ path, message: `declares a pattern this server cannot compile: ${shown}` });
     return;
   }
-  if (!compiled.test(input)) issues.push({ path, message: `must match ${pattern}` });
+  // A `g` or `y` RegExp carries `lastIndex` between calls, and this one is cached per node: the
+  // second `.test()` of an accepted value would answer false. Reset, as the schema's tester does.
+  compiled.lastIndex = 0;
+  if (!compiled.test(input)) issues.push({ path, message: `must match ${shown}` });
 }
 
 function number(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {