@ultimat3/mcp 19.3.1 → 19.3.2

package/CLAUDE.md

@@ -39,6 +39,11 @@ import. The CLI wires it.
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineAppMcp` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
   every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
+- **Every refusal carries its instruction** (`As of 2026-09-07`). The 413 and the batch refusal
+  were bare `-32600`s; both now carry `data: { code, fix }` built by the error class that owns the
+  wording (`McpBodyTooLargeError`, shared with the stdio line cap; `McpProtocolError`). The
+  `-32601` for a tool carries no `data` — see the next rule — so its instruction rides in the
+  MESSAGE, and it is `TOOL_UNKNOWN_FIX`, the same sentence on the absent and the hidden branch.
 - Three outcomes, never blurred: role-hidden → `-32601` ToolNotFound with no `data`;
   scope → `-32600` `X_MCP_SCOPE_DENIED` naming the scope; policy → an `isError` result
   carrying `X_FORBIDDEN`. Swapping any two is an enumeration oracle.

package/README.md

@@ -198,8 +198,16 @@ It cannot be done from outside: `rateLimitClass(body)` takes an already-parsed b
 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`.
 
+The body is capped WHILE it is read, and over the cap is `413` on a JSON-RPC `-32600` (`id: null`)
+carrying `data: { code: 'X_MCP_BODY_TOO_LARGE', cause, fix, limit }` — the stdio transport answers
+an over-long line with the same code. A JSON-RPC batch (an array) is refused `-32600` by name with
+`data: { code: 'X_MCP_PROTOCOL', fix }`: one request per `POST`, never walked. Every refusal on
+this surface carries its instruction, `As of 2026-09-07` — the 413 and the batch were the two that
+did not.
+
 | Knob | Where | Default |
 |---|---|---|
+| the body cap | `mcpHttpRoute({ bodyLimitBytes })` · `defineAppMcp({ bodyLimitBytes })` | `DEFAULT_MCP_BODY_LIMIT_BYTES`, 1 MiB |
 | 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 })` |
 

package/package.json

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

package/src/app-tools.ts

@@ -78,6 +78,13 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
   resolveToken?(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Mount path. Defaults to `/mcp`. */
   readonly path?: string;
+  /**
+   * Bytes the route holds for one request. Defaults to `DEFAULT_MCP_BODY_LIMIT_BYTES` (1 MiB).
+   * Forwarded since 2026-09-07: `mcpHttpRoute` took it and this — the one path an app builds the
+   * route through — never passed it on, so `X_MCP_BODY_TOO_LARGE`'s fix line named a knob the app
+   * could not reach.
+   */
+  readonly bodyLimitBytes?: number | undefined;
   /**
    * 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.
@@ -168,6 +175,7 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
           server,
           resolveToken,
           ...(input.path !== undefined ? { path: input.path } : {}),
+          ...(input.bodyLimitBytes !== undefined ? { bodyLimitBytes: input.bodyLimitBytes } : {}),
           ...(input.rateLimits !== undefined ? { rateLimits: input.rateLimits } : {}),
           ...(input.rateLimitStore !== undefined ? { rateLimitStore: input.rateLimitStore } : {}),
         });

package/src/errors.ts

@@ -18,6 +18,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_SCOPE_CONFLICT',
   'X_MCP_RATE_LIMITED',
   'X_MCP_APP_UNMOUNTED',
+  'X_MCP_BODY_TOO_LARGE',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -37,6 +38,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   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",
   X_MCP_APP_UNMOUNTED: "the app's MCP endpoint is exposed in config and nothing can be mounted",
+  X_MCP_BODY_TOO_LARGE: 'one MCP message is larger than the transport holds',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -53,6 +55,15 @@ registerErrorCodes(
 // answered 404, host included, on every error it has ever thrown; restating the replacement here
 // would be the same constant in eight places waiting to drift again.
 
+/**
+ * The one instruction that is SAFE on both of outcome 1's branches. `server.ts` appends it to the
+ * wire message for a hidden tool and for an absent one alike, and `McpToolUnknownError` is its
+ * in-process twin — one constant, so the sentence an agent reads over `-32601` and the one it
+ * reads from a thrown error cannot drift. It names `tools/list` and nothing about the name it was
+ * given: whether that name exists is exactly what the answer must not say.
+ */
+export const TOOL_UNKNOWN_FIX = 'call tools/list to read the catalog this caller may use';
+
 /**
  * OUTCOME 1 of three: a tool name reached the dispatcher that no VISIBLE tool answers to —
  * the tool is absent, or it exists and this caller's role may never invoke it. One error for
@@ -67,7 +78,7 @@ export class McpToolUnknownError extends UltimateError {
       cause: `no MCP tool named "${input.name}" is visible to this caller (visible: ${
         input.visible.length > 0 ? input.visible.join(', ') : 'none'
       })`,
-      fix: 'call tools/list to read the catalog this caller may use',
+      fix: TOOL_UNKNOWN_FIX,
     });
   }
 }
@@ -324,6 +335,52 @@ export class McpNotBranchDbError extends UltimateError {
   }
 }
 
+/**
+ * One message larger than the transport holds. Its own code, for the reason `X_MCP_RATE_LIMITED`
+ * below is not `X_RATE_LIMITED`: `@ultimat3/http`'s `X_BODY_INVALID` names `bodyLimitBytes` on the
+ * HTTP pipeline, and this route never passes through it — the knob is `mcpHttpRoute`'s (or
+ * `defineAppMcp`'s, which forwards it), and over stdio it is `serveStdio({ lineLimitBytes })`, a
+ * ceiling in characters rather than bytes. One class for both transports, because the condition is
+ * one: the peer sent more in one message than this end agreed to hold, and the two answers must
+ * name the same code so an agent learns it once.
+ *
+ * Measured through ai-maxxing's `POST /mcp` on 2026-09-07: the 413 was a bare `-32600` reading
+ * `request body is at least N bytes, limit is M` — two numbers and no next step, while the 401,
+ * 403 and 429 beside it all carried `{ code, cause, fix }`. A box agent sending a large
+ * `promptSession` had nothing to act on. The fix names both moves, send less or raise the cap,
+ * because which one is right is the author's call: a prompt can be split, a paged result cannot
+ * always be, and a cap set by default was never a decision anyone made about this app.
+ */
+export class McpBodyTooLargeError extends UltimateError {
+  readonly limit: number;
+
+  constructor(input: { transport: 'http' | 'stdio'; limit: number; over?: number | undefined }) {
+    const http = input.transport === 'http';
+    // A NUMBER in the fix, never a `<n>`: the contract is a one-line edit that runs as written. The
+    // cap itself would run and change nothing; twice the larger of the cap and what arrived is a
+    // value that admits this message, whichever of the two was the shorter measure. Both are
+    // finite non-negative integers by the transports' own screens, so the product is too.
+    const raised = 2 * Math.max(input.limit, input.over ?? 0);
+    super({
+      code: 'X_MCP_BODY_TOO_LARGE',
+      cause: http
+        ? `request body is at least ${input.over ?? input.limit} bytes, limit is ${input.limit}`
+        : `one message exceeded ${input.limit} characters and was dropped`,
+      fix: http
+        ? `send less in one request — page a large read, split a long prompt across calls — or raise the cap where the route is built: mcpHttpRoute({ bodyLimitBytes: ${raised} }) or defineAppMcp({ bodyLimitBytes: ${raised} })`
+        : `send one JSON-RPC message per line, each under the cap — split a large tool result into paged calls — or raise it where the transport is started: serveStdio({ lineLimitBytes: ${raised} })`,
+      // The numbers as FIELDS, not only prose: a `--json` reader and the wire's `data` both want
+      // the limit without re-parsing a sentence.
+      meta: {
+        transport: input.transport,
+        limit: input.limit,
+        ...(input.over === undefined ? {} : { over: input.over }),
+      },
+    });
+    this.limit = input.limit;
+  }
+}
+
 /**
  * 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

package/src/index.ts

@@ -35,6 +35,7 @@ export {
   MCP_ERROR_TITLES,
   McpAppUnmountedError,
   McpArgsInvalidError,
+  McpBodyTooLargeError,
   McpNotBranchDbError,
   McpProtocolError,
   McpQueryRejectedError,
@@ -102,7 +103,7 @@ export {
 } from './resources';
 export type { McpScopes } from './scopes';
 export { withScopes } from './scopes';
-export type { CreateMcpServerInput } from './server';
+export type { CreateMcpServerInput, McpWire } from './server';
 export { createMcpServer, McpServer } from './server';
 export type {
   McpHttpTransportInput,

package/src/server.ts

@@ -6,7 +6,7 @@
 import { FRAMEWORK_CODE, singleLine, stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
 import { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
-import { McpScopeDeniedError } from './errors';
+import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
 import type { AnyMcpTool, McpCaller, McpToolResult, McpVerbClass, ToolListEntry } from './registry';
 import { ToolRegistry } from './registry';
 import type { McpPrompt, McpResource } from './resources';
@@ -26,6 +26,23 @@ import {
   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 interface CreateMcpServerInput {
   readonly tools?: readonly AnyMcpTool[];
   readonly resources?: readonly McpResource[];
@@ -72,9 +89,34 @@ export class McpServer {
     this.serverInfo = serverInfo;
   }
 
-  async handle(body: unknown, caller: McpCaller): Promise<JsonRpcResponse | null> {
+  async handle(
+    body: unknown,
+    caller: McpCaller,
+    wire?: McpWire | undefined,
+  ): Promise<JsonRpcResponse | null> {
+    // A batch is legal JSON-RPC 2.0 and this server does not walk one: one call, one answer, one
+    // rate-limit class. Refused BY NAME rather than falling through to the envelope check below —
+    // an array is not an envelope, so it did, and a client sending a batch got the same bare
+    // `-32600` as `{ not: 'jsonrpc' }` with no word that batching was the problem. Measured
+    // through ai-maxxing's `POST /mcp` on 2026-09-07. The `message` is the same on every wire;
+    // only the fix names the unit — `POST <path>` as mounted, or a line — and only when the
+    // transport said which it is.
+    if (Array.isArray(body)) {
+      return protocolRefusal(
+        'a JSON-RPC batch (an array of requests) is not supported: send one request per message',
+        new McpProtocolError({
+          cause: 'the body is a JSON-RPC batch, and this server answers one request per message',
+          fix: `send one request per ${messageUnitOf(wire)} — a batch is never walked, so its calls did not run`,
+        }),
+      );
+    }
     if (!isJsonRpcRequest(body)) {
-      return errorResponse(null, INVALID_REQUEST, 'not a JSON-RPC 2.0 request envelope');
+      return protocolRefusal(
+        'not a JSON-RPC 2.0 request envelope',
+        new McpProtocolError({
+          cause: 'the body is not a JSON-RPC 2.0 request envelope',
+        }),
+      );
     }
     // Notifications get no answer at all; the transport replies 202 with an empty body.
     if (isNotification(body)) return null;
@@ -145,10 +187,13 @@ export class McpServer {
     const resolved = this.tools.resolve(name, params['arguments'] ?? {}, caller);
     switch (resolved.kind) {
       // OUTCOME 1. Absent AND role-hidden collapse to the same answer, with no `data` at
-      // all: any extra field would be the difference a prober is looking for.
+      // all: any extra field would be the difference a prober is looking for. The message
+      // carries the one instruction that holds on both branches — read `tools/list` — and
+      // nothing about whether the name exists: the same sentence for a stale name and for a
+      // tool this role may never see, so the hint is not a second oracle.
       case 'not-found':
         auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
-        return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name}`);
+        return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name} — ${TOOL_UNKNOWN_FIX}`);
       // OUTCOME 2. The caller can already see this tool, so naming the missing scope leaks
       // nothing — and the fix travels with it, built by the error that owns the wording.
       case 'scope-denied': {
@@ -302,6 +347,20 @@ export class McpServer {
   }
 }
 
+/**
+ * The envelope refusals — no id to answer on, so `null` — rendered the way the scope refusal
+ * already is: a `message` a client library surfaces verbatim, and `data: { code, fix, docs }`
+ * built by the error class that owns the wording. Every other refusal on this surface carried its
+ * instruction; these two answered a bare `-32600` and left the caller to guess.
+ */
+function protocolRefusal(message: string, error: McpProtocolError): JsonRpcResponse {
+  return errorResponse(null, INVALID_REQUEST, message, {
+    code: error.code,
+    fix: error.fix,
+    docs: error.docs,
+  });
+}
+
 interface FrameworkError {
   readonly code: string;
   /** `''` for a foreign thrown object that carries no title. See `renderFrameworkError`. */

package/src/transport-http.ts

@@ -23,11 +23,11 @@ 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 { McpRateLimitedError } from './errors';
+import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
 import type { JsonRpcResponse } from './wire';
-import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
+import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './wire';
 
 /**
  * The same 1 MiB `@ultimat3/http`'s `bodyLimitBytes` defaults to. This descriptor is driven from a
@@ -117,9 +117,11 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     windowMs: MCP_RATE_LIMIT_WINDOW_MS,
   });
 
+  const path = input.path ?? '/mcp';
+
   return {
     method: 'POST',
-    path: input.path ?? '/mcp',
+    path,
     limits,
     rateLimitClass: (body) => server.classify(body),
 
@@ -141,12 +143,23 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // cannot drift.
       const read = await readWithinLimit(request.body, bodyLimitBytes);
       if ('over' in read) {
+        // Still the JSON-RPC envelope on `id: null` — a client library parses that and a consumer
+        // has pinned it — and the stdio transport answers the same condition the same way. What
+        // travels now is the refusal: the code, both numbers, and the two moves that end it,
+        // built by the error that owns the wording so the two transports cannot drift.
+        const refusal = new McpBodyTooLargeError({
+          transport: 'http',
+          limit: bodyLimitBytes,
+          over: read.over,
+        });
         return json(
-          errorResponse(
-            null,
-            INVALID_REQUEST,
-            `request body is at least ${read.over} bytes, limit is ${bodyLimitBytes}`,
-          ),
+          errorResponse(null, INVALID_REQUEST, refusalMessage(refusal), {
+            code: refusal.code,
+            cause: refusal.cause,
+            fix: refusal.fix,
+            docs: refusal.docs,
+            limit: bodyLimitBytes,
+          }),
           413,
         );
       }
@@ -185,7 +198,9 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
         ...(resolved.role !== undefined ? { role: resolved.role } : {}),
       };
 
-      const response = await server.handle(body, caller);
+      // The wire named, so a refusal that tells the client where to resend names THIS mount and
+      // not a spelled `/mcp`.
+      const response = await server.handle(body, caller, { transport: 'http', path });
       // A notification has no response. 202 with an empty body is the MCP-correct answer.
       if (response === null) return new Response(null, { status: 202 });
       // JSON-RPC errors are 200s: the transport succeeded, the call did not. Only a

package/src/transport-stdio.ts

@@ -9,9 +9,10 @@
 // stderr and this file never calls `console.log`.
 
 import { finiteCount } from '@ultimat3/core';
+import { McpBodyTooLargeError } from './errors';
 import type { McpCaller } from './registry';
 import type { McpServer } from './server';
-import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
+import { errorResponse, INVALID_REQUEST, PARSE_ERROR, refusalMessage } from './wire';
 
 /**
  * Characters held for ONE message that has not ended yet. `transport-http.ts` caps the same wire at
@@ -92,17 +93,22 @@ export async function serveStdio(config: StdioTransportInput): Promise<void> {
   }
 }
 
-/** Answered once per over-long message, and the `fix` is what the peer has to change. */
+/**
+ * Answered once per over-long message, and the `fix` is what the peer has to change. The same
+ * `X_MCP_BODY_TOO_LARGE` the HTTP transport's 413 carries: one condition, one code, on both wires.
+ */
 function overLimit(limit: number): ReturnType<typeof errorResponse> {
-  return errorResponse(
-    null,
-    INVALID_REQUEST,
-    `a single message exceeded ${limit} characters and was dropped`,
-    {
-      limit,
-      fix: `send one JSON-RPC message per line, each under ${limit} characters — split a large tool result into paged calls`,
-    },
-  );
+  const refusal = new McpBodyTooLargeError({ transport: 'stdio', limit });
+  // `message` carries the fix as the HTTP 413's does: a peer reading nothing but `message` still
+  // learns the next move. The two transports' words differ — a line is not a body — and the SHAPE
+  // is the one `refusalMessage` owns.
+  return errorResponse(null, INVALID_REQUEST, refusalMessage(refusal), {
+    code: refusal.code,
+    cause: refusal.cause,
+    fix: refusal.fix,
+    docs: refusal.docs,
+    limit,
+  });
 }
 
 async function handleLine(
@@ -122,7 +128,7 @@ async function handleLine(
     return;
   }
 
-  const response = await server.handle(body, caller);
+  const response = await server.handle(body, caller, { transport: 'stdio' });
   // `null` means notification: emit nothing at all, or the peer sees a phantom reply.
   if (response === null) return;
   await write(`${JSON.stringify(response)}\n`);

package/src/wire.ts

@@ -111,6 +111,16 @@ export function resultResponse(id: JsonRpcId, result: unknown): JsonRpcResponse
   return { jsonrpc: '2.0', id, result };
 }
 
+/**
+ * The `message` a coded refusal travels under: the cause AND the fix, in one sentence. `data`
+ * carries both as fields; `message` is the ONE thing a client that reads nothing else prints, so a
+ * consumer of `message` alone still gets the recovery step. Both transports build theirs here —
+ * the HTTP 413 and the stdio over-long frame carry transport-specific wording, and this keeps the
+ * SHAPE shared without forcing the text to be identical.
+ */
+export const refusalMessage = (refusal: { readonly cause: string; readonly fix: string }): string =>
+  `${refusal.cause} — ${refusal.fix}`;
+
 export function errorResponse(
   id: JsonRpcId,
   code: number,