@ultimat3/mcp 24.0.0 → 25.1.0

package/src/server.ts

@@ -3,9 +3,11 @@
 // 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, forAudience } from './framework-error';
 import { metaCall } from './meta-call';
@@ -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,16 +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 thrown = asFrameworkError(error);
       if (thrown !== undefined) {
         const framework = forAudience(thrown, this.voice.errorAudience);
-        auditResourceRead({ uri, outcome: 'failed', caller, code: framework.code });
+        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,
@@ -463,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 { Bucket, 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;
@@ -79,10 +79,16 @@ 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`. */
@@ -231,24 +237,42 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // 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) return exhausted;
+      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 (
-          (await failures.spend(address)) ??
-          unauthorized(bearerChallenge(metadataUrl, false, challengeScopes))
-        );
+        return refuse('missing-token', bearerChallenge(metadataUrl, false, challengeScopes));
       }
 
-      const resolved = await input.resolveToken(token);
+      const resolved = await input.resolveToken(token, facts);
       if (resolved === null) {
-        return (
-          (await failures.spend(address)) ??
-          unauthorized(bearerChallenge(metadataUrl, true, challengeScopes))
-        );
+        return refuse('rejected-token', bearerChallenge(metadataUrl, true, challengeScopes));
+      }
+      if (!isAgentActor(resolved.actor)) {
+        audit.authRefused('not-an-agent', 403, facts);
+        return notAnAgent();
       }
-      if (!isAgentActor(resolved.actor)) 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

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

@@ -121,6 +121,15 @@ function array(schema: JsonSchema, input: unknown, path: string, issues: ArgIssu
     issues.push({ path, message: 'must be an array' });
     return input;
   }
+  // `@ultimat3/schema` publishes `t.array(items, { min, max })` as these two; a bound on the wire
+  // that nothing here checks is an agent obeying a rule a hand-written tool never enforced.
+  const count = (n: number): string => `${n} item${n === 1 ? '' : 's'}`;
+  if (schema.minItems !== undefined && input.length < schema.minItems) {
+    issues.push({ path, message: `must have at least ${count(schema.minItems)}` });
+  }
+  if (schema.maxItems !== undefined && input.length > schema.maxItems) {
+    issues.push({ path, message: `must have at most ${count(schema.maxItems)}` });
+  }
   const items = schema.items;
   if (items === undefined) return input;
   return input.map((item, index) => walk(items, item, `${path}[${index}]`, issues));

package/src/wire.ts

@@ -113,3 +113,20 @@ export function paramsOf(req: JsonRpcRequest): Record<string, unknown> | null {
   if (typeof req.params !== 'object' || req.params === null) return null;
   return req.params as Record<string, unknown>;
 }
+
+/**
+ * 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. */
+export const messageUnitOf = (wire: McpWire | undefined): string => {
+  if (wire === undefined) return 'message';
+  return wire.transport === 'http' ? `POST ${wire.path}` : 'line';
+};