@ultimat3/mcp 11.3.0 → 12.0.0

package/CLAUDE.md

@@ -3,6 +3,10 @@
 Tier 4. May import tier 0–3: `core schema i18n money time cache seo entity policy http action
 query jobs realtime`. **Never** `render manifest ai pwa ui admin testing cli`.
 
+`@ultimat3/http` is a DIRECT dependency since 2026-08-24 (`transport-http.ts`, the rate limiter) and
+was already a transitive one through `action` and `query` — declaring it added nothing to the
+install graph and made the edge readable.
+
 Same-tier data (routes, manifest, policy catalog) arrives as an **injected thunk**, never an
 import. The CLI wires it.
 
@@ -19,7 +23,7 @@ import. The CLI wires it.
 | `resources.ts` | resources + prompts, stable `ultimate://` URIs |
 | `dev-server.ts` | the 13 dev tools; depends only on an injected `DevHost` |
 | `dev-host.ts` | wires `describe*` from entity/action/query/jobs into a `DevHost` |
-| `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor |
+| `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor, and the per-caller rate limit it enforces itself |
 | `transport-stdio.ts` | NDJSON on stdin/stdout for `x mcp serve` |
 | `app-tools.ts` | `defineAppMcp` — a generated app's own MCP surface, one call |
 | `app-tool.ts` | the authored `tools: { name: {...} }` record → `ProjectablePrimitive` |
@@ -247,6 +251,32 @@ import. The CLI wires it.
 - The caps run in the **tool**, not the host. A host that forgets them answers a million rows
   into a model's context. `guards` names the layers that engaged; a layer that could not engage
   is absent from the list, never assumed present.
+- **`MCP_RATE_LIMITS` is ENFORCED, in `handle`, and it has to be there** (2026-08-24). `limits` and
+  `rateLimitClass` were published on `McpRouteDescriptor` and read by no mount point — `x mcp serve`
+  runs `route.handle` in a bare `Bun.serve` and `defineAppMcp` hands its route to the app — so the
+  type promised 20 writes a minute while the real ceiling was Bun's accept rate: an agent looping on
+  `db.query` was never UNSAFE (the `readonly-sql` parse and `query-limits` caps hold per call) and
+  never BOUNDED. It cannot be enforced from OUTSIDE, which is why deleting the option was the wrong
+  half of the choice: `rateLimitClass(body)` takes an ALREADY-PARSED body and `handle` is the only
+  thing that parses one, so a limiter above it would have to consume the request stream first and a
+  `Request` body reads once. The maths, the `Bucket`, `toBucket`, `rateLimitKey` and the store are
+  `@ultimat3/http`'s — tier 2, a legal downward import — and **never** a second token bucket written
+  here. Metered after the parse and before dispatch; an unauthenticated caller is answered 401 first,
+  so a token nobody issued cannot spend an actor's allowance. The key is
+  `mcp:<class>|actor:<id>`, never the TOKEN: a bucket key reaches a log and an error reporter, and a
+  credential in one is a leak wearing a throttle's clothes.
+- **`X_MCP_RATE_LIMITED`, not `@ultimat3/http`'s `X_RATE_LIMITED`, and the reason is the KNOB.** The
+  enforcement is shared to the last function; only the sentence differs. `X_RATE_LIMITED`'s `fix:`
+  says to raise `rateLimit.buckets` in `app.config.ts`, which governs the HTTP pipeline and has no
+  effect on this route — an instruction that runs and changes nothing is worse than none, which is
+  the same call `@ultimat3/realtime`'s `SubscriptionLimitError` makes when it names the knob rather
+  than the default. The 429 renders `{ code, cause, fix }` plus `Retry-After`, the shape this file's
+  401 and 403 already use, never a JSON-RPC envelope: the transport refused before dispatch, so
+  there is no call to answer.
+- **A per-process store is the default and a lie for a fleet.** `mcpHttpRoute({ rateLimitStore })`
+  and `defineAppMcp({ rateLimitStore })` are the seam; N replicas on the memory store enforce N x
+  every number, silently and only in production. Forwarded through `defineAppMcp` deliberately —
+  an app that builds its route through that one call has no other way to reach it.
 - **Every authentication answer lands before `request.json()`.** A missing token, a token
   `resolveToken` rejects and a non-agent actor all return before the body is read: parsing first
   answered `400 parse error` for a malformed payload and `401` for a well-formed one under the

package/README.md

@@ -174,12 +174,23 @@ stays the only rule that reads the input. A name this server does not project is
 | HTTP | `mcpHttpRoute({ server, resolveToken })` → `POST /mcp` | `Authorization: Bearer <token>` → `Actor { kind: 'agent' }` |
 | stdio | `serveStdio({ server, caller })` | none — the peer already owns the shell |
 
-The HTTP transport exports a route *descriptor*, not a mounted handler: `@ultimat3/http`
-owns the lifecycle, and the descriptor stays drivable from a bare `Request` in a test. It
-carries `rateLimitClass(body)` because all MCP traffic is one URL — a per-route bucket would
-charge `initialize` to the write bucket and throttle an agent on its handshake.
+The HTTP transport exports a route *descriptor*, not a mounted handler: a host owns the lifecycle,
+and the descriptor stays drivable from a bare `Request` in a test. It carries
+`rateLimitClass(body)` because all MCP traffic is one URL — a per-route bucket would charge
+`initialize` to the write bucket and throttle an agent on its handshake.
 
-Reads: 120/min. Writes: 20/min. Unresolvable calls bill the write bucket (fail-closed).
+Reads: 120/min per caller. Writes: 20/min. Unresolvable calls bill the write bucket (fail-closed).
+
+**`handle` enforces those numbers itself, `As of 2026-08-24`** — they were published on the
+descriptor and applied by no mount point before that, so the ceiling was really Bun's accept rate.
+It cannot be done from outside: `rateLimitClass(body)` takes an already-parsed body and `handle` is
+the only thing that parses one. The bucket is `@ultimat3/http`'s, keyed per actor per class; over
+the limit is `429` + `Retry-After` + `X_MCP_RATE_LIMITED`.
+
+| Knob | Where | Default |
+|---|---|---|
+| the numbers | `mcpHttpRoute({ rateLimits })` · `defineAppMcp({ rateLimits })` | `MCP_RATE_LIMITS` |
+| where they are counted | `mcpHttpRoute({ rateLimitStore })` · `defineAppMcp({ rateLimitStore })` | a per-**process** memory store — N replicas behind one URL each enforce the full allowance, so a fleet passes `postgresRateLimitStore({ executor })` |
 
 ## Resources
 
@@ -214,3 +225,4 @@ inside their own handler.
 | `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
 | `X_MCP_NOT_BRANCH_DB` | `db.migrate` aimed at a production or otherwise non-branch database |
 | `X_MCP_RESOURCE_DUPLICATE` | two resources claim one `ultimate://` URI — refused at registration, as a duplicate tool name is |
+| `X_MCP_RATE_LIMITED` | the caller spent its per-minute allowance for this request's class. Its own code rather than `@ultimat3/http`'s `X_RATE_LIMITED` because the KNOB differs — `rateLimits` on the route, never `rateLimit.buckets` in `app.config.ts` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "11.3.0",
-  "description": "MCP server, dev tools, and the action-to-tool projection — one authz system, two surfaces",
+  "version": "12.0.0",
+  "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -31,12 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "11.3.0",
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/entity": "11.3.0",
-    "@ultimat3/jobs": "11.3.0",
-    "@ultimat3/policy": "11.3.0",
-    "@ultimat3/query": "11.3.0",
-    "@ultimat3/schema": "11.3.0"
+    "@ultimat3/action": "12.0.0",
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/entity": "12.0.0",
+    "@ultimat3/http": "12.0.0",
+    "@ultimat3/jobs": "12.0.0",
+    "@ultimat3/policy": "12.0.0",
+    "@ultimat3/query": "12.0.0",
+    "@ultimat3/schema": "12.0.0"
   }
 }

package/src/app-tools.ts

@@ -8,6 +8,7 @@
 // Deliberately one function: an app author should never have to know that `ToolRegistry`,
 // `frameworkResources` and `mcpHttpRoute` exist.
 
+import type { RateLimitStore } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { AnyAppToolDefinition, AppTools } from './app-tool';
 import { appToolPrimitives } from './app-tool';
@@ -16,7 +17,7 @@ import { exposedPrimitives } from './exposed';
 import { toolsFrom, toolsListed } from './from-action';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
-import type { AnyMcpTool } from './registry';
+import type { AnyMcpTool, McpVerbClass } from './registry';
 import type { McpPrompt, McpResource } from './resources';
 import { toPrompts } from './resources';
 import type { McpScopes } from './scopes';
@@ -77,6 +78,18 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
   resolveToken?(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Mount path. Defaults to `/mcp`. */
   readonly path?: string;
+  /**
+   * Requests per minute per caller, by class. Defaults to `MCP_RATE_LIMITS` and is ENFORCED by the
+   * route, so this is the app's one knob over what an agent may spend here.
+   */
+  readonly rateLimits?: Readonly<Record<McpVerbClass, number>> | undefined;
+  /**
+   * Where those buckets are counted. Forwarded rather than left to the route's per-process default
+   * because an app behind N replicas has no other way to reach it — and N processes each holding
+   * their own counters enforce N x every number above, silently and only in production. The same
+   * `postgresRateLimitStore({ executor })` the web role takes.
+   */
+  readonly rateLimitStore?: RateLimitStore | undefined;
 }
 
 export interface AppMcp {
@@ -155,6 +168,8 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
           server,
           resolveToken,
           ...(input.path !== undefined ? { path: input.path } : {}),
+          ...(input.rateLimits !== undefined ? { rateLimits: input.rateLimits } : {}),
+          ...(input.rateLimitStore !== undefined ? { rateLimitStore: input.rateLimitStore } : {}),
         });
 
   return { server, tools: projected, route };

package/src/errors.ts

@@ -16,6 +16,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_RESOURCE_DUPLICATE',
   'X_MCP_SCOPE_UNKNOWN',
   'X_MCP_SCOPE_CONFLICT',
+  'X_MCP_RATE_LIMITED',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -33,6 +34,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_RESOURCE_DUPLICATE: 'two resources claim one MCP resource URI',
   X_MCP_SCOPE_UNKNOWN: 'defineAppMcp scopes a tool this server does not project',
   X_MCP_SCOPE_CONFLICT: 'two scopes claim one MCP tool',
+  X_MCP_RATE_LIMITED: "the caller has spent its allowance for this request's class",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -292,3 +294,32 @@ export class McpNotBranchDbError extends UltimateError {
     });
   }
 }
+
+/**
+ * The transport's own throttle, and its own CODE rather than `@ultimat3/http`'s `X_RATE_LIMITED`
+ * — not because the maths differ (they are the same `Bucket`, the same store and the same
+ * `rateLimitDecision`) but because the KNOB does. `X_RATE_LIMITED` tells an operator to raise
+ * `rateLimit.buckets` through `configureHttp()`, which governs the HTTP pipeline and not this route: all
+ * MCP traffic is one URL and the class comes from the parsed body, so `mcpHttpRoute` meters itself.
+ * A fix line that runs and changes nothing is worse than none — the same rule
+ * `@ultimat3/realtime`'s `SubscriptionLimitError` follows when it names the knob over the default.
+ *
+ * The bucket key names the ACTOR and never reaches the caller: a 429 is provokable by anyone
+ * holding a valid token, and an org id or an actor id in the body of one is a leak wearing a
+ * throttle's clothes.
+ */
+export class McpRateLimitedError extends UltimateError {
+  constructor(input: { verbClass: string; limit: number; retryAfterSeconds: number }) {
+    super({
+      code: 'X_MCP_RATE_LIMITED',
+      cause: `this caller has spent its ${input.limit} ${input.verbClass} requests per minute; the bucket refills in ${input.retryAfterSeconds}s`,
+      fix: `wait ${input.retryAfterSeconds}s — the Retry-After header carries the same number — or raise it where the route is built: mcpHttpRoute({ rateLimits: { ${input.verbClass}: <n> } }), or defineAppMcp({ rateLimits })`,
+      // why `meta` and not only the sentence: `transport-http.ts` writes `Retry-After` by hand, so
+      // this route is correct today. `@ultimat3/http`'s `retryAfterOf` reads the header off
+      // `meta.retryAfterSeconds` — so the day an MCP host is mounted inside that pipeline, an error
+      // carrying the number only in its prose sheds a caller with no delay to honour, which is the
+      // stampede `admit` exists to spread.
+      meta: { retryAfterSeconds: input.retryAfterSeconds },
+    });
+  }
+}

package/src/index.ts

@@ -37,6 +37,7 @@ export {
   McpNotBranchDbError,
   McpProtocolError,
   McpQueryRejectedError,
+  McpRateLimitedError,
   McpResourceDuplicateError,
   McpScopeConflictError,
   McpScopeDeniedError,
@@ -111,6 +112,7 @@ export {
   bearerToken,
   DEFAULT_MCP_BODY_LIMIT_BYTES,
   isAgentActor,
+  MCP_RATE_LIMIT_WINDOW_MS,
   MCP_RATE_LIMITS,
   mcpHttpRoute,
 } from './transport-http';

package/src/transport-http.ts

@@ -1,19 +1,29 @@
 // `POST /mcp` — the HTTP transport.
 //
-// Exported as a route DESCRIPTOR rather than a mounted handler: `@ultimat3/http` owns the
-// lifecycle (ALS context, tracing, rate limiting) and mounts this, while the descriptor
-// stays drivable from a bare `Request` in a test. Two things travel with it that a generic
-// route table cannot infer:
+// Exported as a route DESCRIPTOR rather than a mounted handler: a host owns the lifecycle (ALS
+// context, tracing) and mounts this, while the descriptor stays drivable from a bare `Request` in
+// a test. Three things travel with it that a generic route table cannot infer:
 //
 //  1. `rateLimitClass(body)` — all MCP traffic is one URL, so a per-route bucket would
 //     charge `initialize` and every read to the write bucket and throttle an agent on its
 //     handshake. The server classifies each body instead.
-//  2. `authenticate` — a bearer token resolves to an Actor of kind 'agent'. An agent is
+//  2. `limits`, ENFORCED HERE since 2026-08-24 and by nothing before it. The two above were
+//     published on the descriptor and read by no mount point: `x mcp serve` runs `handle` in a
+//     bare `Bun.serve` and `defineAppMcp` returns the route to the app, so the type promised 20
+//     writes a minute and the real ceiling was Bun's accept rate. It cannot be enforced from
+//     OUTSIDE either: `rateLimitClass(body)` takes an already-parsed body and `handle` is the only
+//     thing that parses one, so a limiter above it would have to consume the request stream first.
+//     The maths, the `Bucket` and the store are `@ultimat3/http`'s — tier 2, a downward import,
+//     and never a second token bucket written here.
+//  3. `authenticate` — a bearer token resolves to an Actor of kind 'agent'. An agent is
 //     never silently upgraded to the user behind the token; policies see 'agent' and can
 //     refuse what a human would be allowed.
 
-import type { Actor } from '@ultimat3/core';
-import { readWithinLimit } from '@ultimat3/core';
+import type { Actor, Clock } from '@ultimat3/core';
+import { readWithinLimit, systemClock } from '@ultimat3/core';
+import type { RateLimitStore } from '@ultimat3/http';
+import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
+import { McpRateLimitedError } from './errors';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
 import type { JsonRpcResponse } from './wire';
@@ -27,7 +37,10 @@ import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
  */
 export const DEFAULT_MCP_BODY_LIMIT_BYTES = 1_048_576;
 
-/** Requests per minute per token, by class. Reads are cheap; a write may run migrations. */
+/** The window every number in `MCP_RATE_LIMITS` is spent over. One minute, per class, per actor. */
+export const MCP_RATE_LIMIT_WINDOW_MS = 60_000;
+
+/** Requests per minute per caller, by class. Reads are cheap; a write may run migrations. */
 export const MCP_RATE_LIMITS: Readonly<Record<McpVerbClass, number>> = {
   read: 120,
   write: 20,
@@ -51,6 +64,17 @@ export interface McpHttpTransportInput {
   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;
+  /**
+   * 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
+   * full allowance on its own. A fleet passes `postgresRateLimitStore({ executor })` from
+   * `@ultimat3/http`, the same store the web role's limiter takes.
+   */
+  readonly rateLimitStore?: RateLimitStore | undefined;
+  /** The one clock the buckets refill on. Defaulted, never read inline, so a test can freeze it. */
+  readonly clock?: Clock | undefined;
 }
 
 export interface McpRouteDescriptor {
@@ -58,6 +82,7 @@ export interface McpRouteDescriptor {
   readonly path: string;
   /** 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>>;
   handle(request: Request): Promise<Response>;
 }
@@ -67,11 +92,25 @@ const JSON_HEADERS = { 'content-type': 'application/json' } as const;
 export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   const { server } = input;
   const bodyLimitBytes = input.bodyLimitBytes ?? DEFAULT_MCP_BODY_LIMIT_BYTES;
+  const limits = 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
+  // a number that cannot be enforced must fail where an author can act on it rather than on the
+  // first request an agent makes.
+  const readBucket = toBucket('mcpHttpRoute rateLimits.read', {
+    limit: limits.read,
+    windowMs: MCP_RATE_LIMIT_WINDOW_MS,
+  });
+  const writeBucket = toBucket('mcpHttpRoute rateLimits.write', {
+    limit: limits.write,
+    windowMs: MCP_RATE_LIMIT_WINDOW_MS,
+  });
 
   return {
     method: 'POST',
     path: input.path ?? '/mcp',
-    limits: MCP_RATE_LIMITS,
+    limits,
     rateLimitClass: (body) => server.classify(body),
 
     async handle(request: Request): Promise<Response> {
@@ -109,6 +148,27 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
         return json(errorResponse(null, PARSE_ERROR, 'request body is not valid JSON'), 400);
       }
 
+      // Metered AFTER the class is known and BEFORE the tool runs. It cannot move above the
+      // parse — the class comes out of the body — and an unauthenticated caller never reaches it,
+      // so a token nobody issued cannot spend an actor's allowance.
+      const verbClass = server.classify(body);
+      const bucket = verbClass === 'write' ? writeBucket : readBucket;
+      const decision = await store.take(
+        // `<route>|<subject>`, the shape `@ultimat3/http`'s own keys take, spelled here rather
+        // than borrowed: that package's key builder answers "actor, else org, else the connection
+        // address", a precedence with nothing to decide on this route — an unauthenticated caller
+        // was answered 401 four lines up, so there is ALWAYS an actor and never an address. The
+        // route half carries the CLASS because `read` and `write` are two allowances, and charging
+        // both to one key would let a handshake burst close the writes behind it.
+        `mcp:${verbClass}|actor:${resolved.actor.id}`,
+        bucket,
+        1,
+        clock.now().getTime(),
+      );
+      if (!decision.allowed) {
+        return throttled(verbClass, bucket.capacity, decision.retryAfterSeconds);
+      }
+
       const caller: McpCaller = {
         actor: resolved.actor,
         scopes: resolved.scopes,
@@ -143,6 +203,20 @@ export function isAgentActor(actor: Actor): boolean {
   return (actor as { kind?: unknown }).kind === 'agent';
 }
 
+/**
+ * The refusal, rendered the way this file's 401 and 403 already are: `{ code, cause, fix }` and an
+ * HTTP status, never a JSON-RPC envelope — the transport refused before dispatch, so there is no
+ * 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 {
+  const error = new McpRateLimitedError({ verbClass, limit, retryAfterSeconds });
+  return new Response(JSON.stringify({ code: error.code, cause: error.cause, fix: error.fix }), {
+    status: 429,
+    headers: { ...JSON_HEADERS, 'retry-after': String(retryAfterSeconds) },
+  });
+}
+
 function notAnAgent(): Response {
   return new Response(
     JSON.stringify({

package/src/validate-args.ts

@@ -6,6 +6,7 @@
 // still re-parse authoritatively inside their own handler; this pass exists so a wrong
 // call comes back as a structured issue list instead of a round trip.
 
+import { charCount } from '@ultimat3/schema';
 import type { JsonSchema } from './wire';
 
 export interface ArgIssue {
@@ -130,10 +131,19 @@ function string(schema: JsonSchema, input: unknown, path: string, issues: ArgIss
     issues.push({ path, message: 'must be a string' });
     return input;
   }
-  if (schema.minLength !== undefined && input.length < schema.minLength) {
+  // `charCount`, never `input.length`: JSON Schema defines these two over CODE POINTS, which is
+  // the unit `@ultimat3/schema`'s `char-count.ts` mints them in and the unit the action's own
+  // re-parse applies. In code units both directions were wrong on any astral value — `'👍a'` is
+  // 3 units and 2 points, so `min(3)` passed here and then answered `X_INPUT_INVALID` inside the
+  // handler (the silent pass this file exists to prevent), and `'👍👍'` is 4 units and 2 points,
+  // so `max(3)` refused a call the tool would have served, quoting a bound the agent obeyed with
+  // no re-parse behind it to disagree. One import rather than a second count: this package is
+  // tier 4 and `@ultimat3/schema` is tier 0, so the excuse core's private twin has is not ours.
+  const length = charCount(input);
+  if (schema.minLength !== undefined && length < schema.minLength) {
     issues.push({ path, message: `must be at least ${schema.minLength} characters` });
   }
-  if (schema.maxLength !== undefined && input.length > schema.maxLength) {
+  if (schema.maxLength !== undefined && length > schema.maxLength) {
     issues.push({ path, message: `must be at most ${schema.maxLength} characters` });
   }
   if (schema.pattern !== undefined) matchesPattern(schema, schema.pattern, input, path, issues);