@ultimat3/mcp 22.9.1 → 22.10.0

package/src/meta-surface.ts

@@ -50,6 +50,7 @@ export const META_TOOL_NAMES: readonly string[] = [
 export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
   {
     name: DESCRIBE_RESOURCE,
+    title: 'Describe resources',
     description:
       "Full input schemas for the actions of one or more resources (batched). Call it before manage_resource when list_resources' one-line params are not enough. Read-only.",
     inputSchema: {
@@ -58,15 +59,19 @@ export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
       required: ['resources'],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true, openWorldHint: false },
   },
   {
     name: LIST_RESOURCES,
+    title: 'List resources',
     description:
       'The catalog: every resource this caller may use, each with its actions (query or action), a one-line parameter hint and whether a write waits for a human to confirm. Read-only.',
     inputSchema: NO_ARGS,
+    annotations: { readOnlyHint: true, openWorldHint: false },
   },
   {
     name: MANAGE_RESOURCE,
+    title: 'Manage a resource',
     description:
       'Run one action of one resource: { resource, action, params }. Same policies, scopes and audit as calling the action directly. Writes may change state or send mail — read the action first.',
     inputSchema: {
@@ -79,6 +84,9 @@ export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
       required: ['resource', 'action'],
       additionalProperties: false,
     },
+    // The door to every grouped tool, reads and writes alike: a client has to assume the worst of
+    // it. `list_resources` says per action which is which.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   },
 ];
 
@@ -254,6 +262,40 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
     : listParamsSchema(tool.listParams, tool.inputSchema);
 }
 
+/**
+ * `list_resources` as the model reads it: PLAIN TEXT, one line per action under one line per
+ * resource. The JSON form it answered until 22.10 repeated every key on every action and escaped
+ * every quote — a staff catalog measured 32.5k characters — and `JSON.parse` was never its reader's
+ * job: the model's is. Same facts, same order; `describe_resource` stays JSON because a schema is.
+ *
+ * ```text
+ * cases — Court cases of the account.
+ *   listCases (query) {radicado?: string} — List the account's cases.
+ *   closeCase (action; confirms; scope cases:write) {id: string} — Close a case.
+ * ```
+ */
+export function renderCatalog(resources: readonly MetaResource[]): string {
+  if (resources.length === 0) return 'No resources are available to this caller.';
+  const lines = [
+    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas.`,
+  ];
+  for (const resource of resources) {
+    lines.push('', `${resource.name} — ${oneLine(resource.description)}`);
+    for (const action of resource.actions) {
+      const tags = [
+        action.kind,
+        ...(action.confirms === true ? ['confirms'] : []),
+        ...(action.scope === undefined ? [] : [`scope ${action.scope}`]),
+      ].join('; ');
+      lines.push(`  ${action.name} (${tags}) {${action.params}} — ${oneLine(action.description)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** A description authored across lines is still one catalog line. */
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
+
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
   return {
     name: tool.name,

package/src/projectable.ts

@@ -11,8 +11,9 @@ import { isQuery, queryName, sourceFor } from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
-import { toWireSchema } from './input-schema';
+import { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
 import type { McpListParams } from './list-params';
+import type { McpToolAnnotations } from './registry';
 
 /**
  * What `defineAppMcp`'s `actions:`/`queries:` accept.
@@ -48,12 +49,15 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
   // `idempotent: true` is honoured on this surface exactly as over HTTP: the caller's key reaches
   // `invoke`, which files it under the action, the caller and the key (`idempotencyKeyFor`).
   const keyed = target.describe().idempotent;
+  const output = toOutputSchema(target.output);
   return {
     name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: keyed ? withIdempotencyKeyArg(name, wire) : wire,
+    ...(output === undefined ? {} : { outputJsonSchema: output }),
     mutates: true,
+    idempotent: keyed,
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
     run: keyed
       ? ({ input: args, actor }) => {
@@ -66,11 +70,16 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
 
 export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
+  // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape; the tool
+  // answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent` is an
+  // object by the spec.
+  const output = toRowsOutputSchema(target.rows);
   return {
     name: queryName(target),
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: toWireSchema(target.input),
+    ...(output === undefined ? {} : { outputJsonSchema: output, outputWrap: 'rows' }),
     mutates: false,
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
@@ -103,6 +112,8 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     ...(declared.description === undefined ? {} : { description: declared.description }),
     ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
     ...(declared.listParams === undefined ? {} : { listParams: declared.listParams }),
+    ...(declared.title === undefined ? {} : { title: declared.title }),
+    ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };
 }
 
@@ -113,4 +124,6 @@ interface DeclaredMcp {
   readonly visibleTo?: readonly string[];
   /** `QueryMcp` only; an action has no list to compose. */
   readonly listParams?: McpListParams;
+  readonly title?: string;
+  readonly annotations?: McpToolAnnotations;
 }

package/src/registry.ts

@@ -67,6 +67,12 @@ export type ContentBlock =
 export interface McpToolResult {
   readonly content: readonly ContentBlock[];
   readonly isError?: boolean;
+  /**
+   * The same answer as a JSON object, for a client that consumes it programmatically (MCP
+   * 2025-06-18). Set by the projection only when the tool publishes an `outputSchema`, and then it
+   * conforms to it; the text block above still carries the serialized JSON for every other client.
+   */
+  readonly structuredContent?: Readonly<Record<string, unknown>>;
   /**
    * The `X_*` code an `isError` result refused with. AUDIT ONLY — never written to the wire,
    * because the code is already in the rendered body the model reads.
@@ -81,11 +87,45 @@ export interface McpToolResult {
 
 export type ToolArgs = Record<string, unknown>;
 
+/**
+ * MCP's tool annotations (2025-06-18), spelled as the spec spells them. HINTS for a client — which
+ * calls to confirm with a human, which to retry — never a security boundary: the policy, the scope
+ * and the visibility gate decide every call whatever these say.
+ *
+ * The projection derives them from the primitive (`from-action.ts`); an action or query overrides
+ * any of them in its `mcp: { annotations }` block.
+ */
+export interface McpToolAnnotations {
+  /** `true`: the tool changes nothing. A query's default. */
+  readonly readOnlyHint?: boolean;
+  /**
+   * Meaningful only when `readOnlyHint` is false. `true`: it may delete or overwrite. An action's
+   * default is `true` — the spec's own default and the safe one: the framework cannot tell an
+   * additive write from a destructive one, so a client is told to confirm until the author says
+   * otherwise (`annotations: { destructiveHint: false }`).
+   */
+  readonly destructiveHint?: boolean;
+  /** Meaningful only when `readOnlyHint` is false. `true`: a repeat with the same args is a no-op. */
+  readonly idempotentHint?: boolean;
+  /** `true`: it reaches entities outside this app (mail, a payment provider, the web). */
+  readonly openWorldHint?: boolean;
+}
+
 export interface McpTool<A extends ToolArgs = ToolArgs> {
   readonly name: string;
+  /** Display name for a client's UI (MCP 2025-06-18). Absent: the client shows `name`. */
+  readonly title?: string;
   readonly description: string;
   /** The only argument contract. Handed verbatim to the agent by `tools/list`. */
   readonly inputSchema: JsonSchema;
+  /**
+   * The shape of `structuredContent` (MCP 2025-06-18) — a JSON Schema whose root is an object.
+   * Published by `tools/list` only when present; a tool that declares it answers
+   * `structuredContent` conforming to it on every successful call.
+   */
+  readonly outputSchema?: JsonSchema;
+  /** See `McpToolAnnotations`. Published by `tools/list` when present. */
+  readonly annotations?: McpToolAnnotations;
   /** Required scope. Absent = no scope gate (the tool's own policy is the gate). */
   readonly scope?: string;
   /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
@@ -116,8 +156,26 @@ export type AnyMcpTool = McpTool<ToolArgs>;
 /** One `tools/list` row — complete and standalone, no follow-up fetch required. */
 export interface ToolListEntry {
   readonly name: string;
+  readonly title?: string;
   readonly description: string;
   readonly inputSchema: JsonSchema;
+  readonly outputSchema?: JsonSchema;
+  readonly annotations?: McpToolAnnotations;
+}
+
+/**
+ * The `tools/list` row of one tool: every optional member attached only when the tool carries it,
+ * so a tool declaring none of them lists exactly the three keys it always did.
+ */
+export function toolListEntry(tool: AnyMcpTool): ToolListEntry {
+  return {
+    name: tool.name,
+    ...(tool.title === undefined ? {} : { title: tool.title }),
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+    ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+  };
 }
 
 /** Rate-limit class of a call. Derived from `destructive`, never declared twice. */
@@ -198,7 +256,7 @@ export class ToolRegistry {
     const all = [...this.#tools.values()];
     const visible = caller === undefined ? all : all.filter((t) => visibleToCaller(t, caller));
     return visible
-      .map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+      .map(toolListEntry)
       .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   }
 
@@ -248,7 +306,10 @@ export function textResult(text: string, isError = false): McpToolResult {
 }
 
 /**
- * JSON payload as a text block — stable 2-space form so an agent can diff two calls.
+ * JSON payload as a text block — COMPACT, one line. Every byte of it lands in the caller's context
+ * window and stays there for the rest of the session; the 2-space form this printed until 22.10
+ * spent a third of a large answer on indentation (a staff catalog measured 32.5k characters).
+ * `JSON.stringify` is deterministic for one value, so two calls still diff.
  *
  * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
  * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
@@ -258,14 +319,44 @@ export function textResult(text: string, isError = false): McpToolResult {
  * three-line shape every other expected failure comes back as, and one an agent can act on.
  */
 export function jsonResult(value: unknown): McpToolResult {
-  let text: string | undefined;
+  const text = serialize(value);
+  return text === undefined ? UNSERIALIZABLE : textResult(text);
+}
+
+/**
+ * `jsonResult` plus `structuredContent`, for a tool that publishes an `outputSchema`. The structured
+ * copy is the SERIALIZED value read back — never the value itself — so a `Date` is the string the
+ * text block carries and a class instance is its JSON, exactly what a client validating against the
+ * schema is handed. `wrap` names the key an array answer is published under (`rows` for a query),
+ * because MCP's `structuredContent` is an object.
+ *
+ * An answer whose JSON is not an object (after `wrap`) gets no structured copy: the schema said
+ * object, and a structured copy that contradicts its schema is refused by a validating client.
+ */
+export function structuredResult(value: unknown, wrap?: string): McpToolResult {
+  const text = serialize(value);
+  if (text === undefined) return UNSERIALIZABLE;
+  const parsed: unknown = JSON.parse(text);
+  const structured = wrap === undefined ? parsed : { [wrap]: parsed };
+  if (typeof structured !== 'object' || structured === null || Array.isArray(structured)) {
+    return textResult(text);
+  }
+  return {
+    content: [{ type: 'text', text }],
+    structuredContent: structured as Record<string, unknown>,
+  };
+}
+
+const UNSERIALIZABLE: McpToolResult = textResult(
+  'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
+  true,
+);
+
+/** Compact JSON, `'null'` for a value with no JSON form, `undefined` when serializing threw. */
+function serialize(value: unknown): string | undefined {
   try {
-    text = JSON.stringify(value, null, 2);
+    return JSON.stringify(value) ?? 'null';
   } catch {
-    return textResult(
-      'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
-      true,
-    );
+    return undefined;
   }
-  return textResult(text ?? 'null');
 }

package/src/server-voice.ts

@@ -0,0 +1,64 @@
+// What the server SAYS, per caller, as opposed to what it decides: `initialize`'s `instructions`,
+// the audience every `fix:` line is written for, and the tool result a mistyped argument earns.
+// Split from `server.ts` for the size ceiling; it holds no gate — dispatch stays there.
+
+import { InputInvalidError } from '@ultimat3/action';
+import type { ErrorAudience } from '@ultimat3/core';
+import { formatIssues } from '@ultimat3/schema';
+import type { McpCaller, McpToolResult } from './registry';
+import type { ArgIssue } from './validate-args';
+
+/** See `CreateMcpServerInput.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. */
+export interface McpServerVoice {
+  readonly instructions?: McpInstructions | undefined;
+  readonly errorAudience: ErrorAudience;
+}
+
+/** The instructions THIS caller is handed, or `undefined`. Fail-closed to none, never a throw. */
+export function instructionsFor(
+  instructions: McpInstructions | undefined,
+  caller: McpCaller,
+): string | undefined {
+  if (instructions === undefined) return undefined;
+  let text: unknown;
+  try {
+    text = typeof instructions === 'function' ? instructions(caller) : instructions;
+  } catch {
+    // The handshake is the one call every client makes; advice that failed to render must not
+    // take the connection down with it.
+    return undefined;
+  }
+  return typeof text === 'string' && text.trim() !== '' ? text : undefined;
+}
+
+/**
+ * A tool RESULT for arguments that failed the published schema — not a JSON-RPC error, since
+ * 22.10. Clients surface a protocol error to the human and hide it from the model, so the `-32602`
+ * this answered left the agent nothing to correct and it retried blind. `isError` reaches the
+ * model carrying the same `X_INPUT_INVALID` an HTTP caller gets for the same input, each issue
+ * addressed by path. `-32602` stays for what is not a call at all (no params, a non-string name).
+ */
+export function invalidArgsResult(
+  name: string,
+  issues: readonly ArgIssue[],
+  audience: ErrorAudience,
+): { readonly code: string; readonly result: McpToolResult } {
+  const invalid = new InputInvalidError(
+    name,
+    formatIssues(issues).join('; '),
+    issues.map((issue) => ({
+      path: issue.path,
+      expected: issue.message,
+      received: '',
+      message: issue.message,
+    })),
+    'tool',
+  );
+  return {
+    code: invalid.code,
+    result: { content: [{ type: 'text', text: invalid.format({ audience }) }], isError: true },
+  };
+}

package/src/server.ts

@@ -3,13 +3,14 @@
 // 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 { formatIssues } from '@ultimat3/schema';
+import type { ErrorAudience } from '@ultimat3/core';
+import { fixFor } from '@ultimat3/core';
 import { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
 import { asFrameworkError, renderFrameworkError } from './framework-error';
 import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
-import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
+import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
 import { MANAGE_RESOURCE, META_TOOL_ENTRIES, META_TOOL_NAMES, MetaSurface } from './meta-surface';
 import { promptListEntry, promptsGet } from './prompts-get';
 import type {
@@ -23,6 +24,8 @@ import type {
 import { ToolRegistry } from './registry';
 import type { McpPrompt, McpResource } from './resources';
 import { ResourceRegistry } from './resources';
+import type { McpInstructions, McpServerVoice } from './server-voice';
+import { instructionsFor, invalidArgsResult } from './server-voice';
 import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
 import {
   defaultServerInfo,
@@ -64,6 +67,20 @@ export interface CreateMcpServerInput {
   readonly surface?: McpSurfaceOption | undefined;
   /** The meta catalog's resources. Required with a surface that can be `'meta'`. */
   readonly groups?: McpResourceGroups | undefined;
+  /**
+   * `initialize`'s `instructions`: how to use this server, for a client that injects it into the
+   * model's context (Claude Code does; many clients do not — never load-bear on it). A function
+   * answers per caller population — a staff surface and a customer one read different advice —
+   * and a function that throws or answers anything but a non-empty string sends none.
+   */
+  readonly instructions?: McpInstructions | undefined;
+  /**
+   * Whose `fix:` line a refusal carries. `'developer'` (the default, and the dev server's): the
+   * fix the author wrote — `x policy explain …`, a declaration to edit. `'caller'`: the error's
+   * `callerFix` where it declares one — what a REMOTE agent can do about it. `defineAppMcp`
+   * serves `'caller'`.
+   */
+  readonly errorAudience?: ErrorAudience | undefined;
 }
 
 /** The set of JSON-RPC methods this server answers. Kept in sync with `classify`. */
@@ -92,6 +109,7 @@ export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
     input.prompts ?? [],
     input.serverInfo ?? defaultServerInfo(),
     meta,
+    { instructions: input.instructions, errorAudience: input.errorAudience ?? 'developer' },
   );
 }
 
@@ -102,6 +120,7 @@ export class McpServer {
   private readonly serverInfo: ServerInfo;
   /** `undefined` for a flat-only server — every existing app, byte for byte. */
   private readonly meta: MetaSurface | undefined;
+  private readonly voice: McpServerVoice;
 
   constructor(
     tools: ToolRegistry,
@@ -109,12 +128,14 @@ export class McpServer {
     prompts: readonly McpPrompt[],
     serverInfo: ServerInfo,
     meta?: MetaSurface,
+    voice: McpServerVoice = { errorAudience: 'developer' },
   ) {
     this.tools = tools;
     this.resources = resources;
     this.prompts = prompts;
     this.serverInfo = serverInfo;
     this.meta = meta;
+    this.voice = voice;
   }
 
   async handle(
@@ -151,7 +172,8 @@ export class McpServer {
     const id = body.id ?? null;
 
     switch (body.method) {
-      case 'initialize':
+      case 'initialize': {
+        const instructions = instructionsFor(this.voice.instructions, caller);
         return resultResponse(id, {
           protocolVersion: MCP_PROTOCOL_VERSION,
           capabilities: {
@@ -160,7 +182,9 @@ export class McpServer {
             prompts: { listChanged: false },
           },
           serverInfo: this.serverInfo,
+          ...(instructions === undefined ? {} : { instructions }),
         });
+      }
       case 'tools/list':
         return resultResponse(id, { tools: this.list(caller) });
       case 'tools/call':
@@ -194,6 +218,14 @@ export class McpServer {
     );
   }
 
+  /**
+   * The meta catalog THIS caller would read from `list_resources`, as data — `undefined` for a caller
+   * served the flat surface. For a test or a tool asserting on the catalog: the wire form is text.
+   */
+  catalog(caller: McpCaller): readonly MetaResource[] | undefined {
+    return this.metaFor(caller)?.listResources(caller);
+  }
+
   /** The meta surface when THIS caller is served it, else `undefined`. */
   private metaFor(caller: McpCaller): MetaSurface | undefined {
     const meta = this.meta;
@@ -272,6 +304,7 @@ export class McpServer {
     resolved: ToolResolution,
     caller: McpCaller,
   ): Promise<JsonRpcResponse> {
+    const audience = this.voice.errorAudience;
     // Three outcomes, deliberately different — and every one of them audited, including the
     // one that tells the caller nothing. See `audit.ts`.
     switch (resolved.kind) {
@@ -301,16 +334,15 @@ export class McpServer {
         return errorResponse(id, INVALID_REQUEST, `missing scope: ${resolved.scope}`, {
           code: denial.code,
           scope: resolved.scope,
-          fix: denial.fix,
+          fix: fixFor(denial, audience),
           docs: denial.docs,
         });
       }
-      case 'invalid-args':
-        auditToolCall({ tool: name, outcome: 'invalid-args', caller, code: 'X_MCP_ARGS_INVALID' });
-        return errorResponse(id, INVALID_PARAMS, `invalid arguments for ${name}`, {
-          code: 'X_MCP_ARGS_INVALID',
-          issues: formatIssues(resolved.issues),
-        });
+      case 'invalid-args': {
+        const invalid = invalidArgsResult(name, resolved.issues, audience);
+        auditToolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
+        return resultResponse(id, invalid.result);
+      }
       case 'ok':
         break;
     }
@@ -332,7 +364,7 @@ export class McpServer {
           code: framework.code,
         });
         return resultResponse(id, {
-          content: [{ type: 'text', text: renderFrameworkError(framework) }],
+          content: [{ type: 'text', text: renderFrameworkError(framework, audience) }],
           isError: true,
         });
       }
@@ -351,6 +383,11 @@ export class McpServer {
     });
     // `code` is audit-only and never reaches the wire: it is already inside the rendered body.
     const payload: Record<string, unknown> = { content: result.content };
+    // Through `manage_resource` too, byte for byte: the meta door answers what the flat one does,
+    // and MCP allows `structuredContent` beside a tool (the dispatcher) that publishes no schema.
+    if (result.structuredContent !== undefined && result.isError !== true) {
+      payload['structuredContent'] = result.structuredContent;
+    }
     if (result.isError === true) payload['isError'] = true;
     return resultResponse(id, payload);
   }
@@ -399,7 +436,7 @@ export class McpServer {
         return errorResponse(id, INVALID_REQUEST, `missing scope: ${resolved.scope}`, {
           code: denial.code,
           scope: resolved.scope,
-          fix: denial.fix,
+          fix: fixFor(denial, this.voice.errorAudience),
           docs: denial.docs,
         });
       }
@@ -429,7 +466,8 @@ export class McpServer {
         return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
           code: framework.code,
           cause: framework.cause,
-          fix: framework.fix,
+          fix: fixFor(framework, this.voice.errorAudience),
+          ...(framework.docs === undefined ? {} : { docs: framework.docs }),
         });
       }
       // No internals: a provider's own message names a path, a query or a host the caller has no

package/src/surface-budget.ts

@@ -0,0 +1,113 @@
+// The size of what an agent READS from this server, measured off the wire, and a budget an app's
+// test holds it to. `tools/list` is re-sent with every step of every turn and `list_resources` is
+// read once a session and then sits in the transcript — both are standing context the model pays
+// for whether or not it uses them, so a number with a test beside it is the only way they stay
+// small (gold standard: context-budget.md, "guard the numbers with tests").
+
+import { McpSurfaceOverBudgetError } from './errors';
+import { LIST_RESOURCES } from './meta-surface';
+import type { McpCaller } from './registry';
+import type { McpServer } from './server';
+
+/** Characters, as serialized on the wire — what a client hands its model. */
+export interface McpSurfaceSize {
+  /** `JSON.stringify` of the `tools/list` result this caller gets. */
+  readonly toolsList: number;
+  /** The text of `list_resources({})`, or `undefined` for a caller served the flat surface. */
+  readonly listResources: number | undefined;
+  /** `initialize`'s `instructions`; `0` when none are sent to this caller. */
+  readonly instructions: number;
+}
+
+/** A ceiling per surface, in characters. An omitted surface is measured and not judged. */
+export interface McpSurfaceBudget {
+  readonly toolsList?: number;
+  readonly listResources?: number;
+  readonly instructions?: number;
+}
+
+/** Measure the three surfaces for ONE caller — a per-population server answers each differently. */
+export async function measureMcpSurface(
+  server: McpServer,
+  caller: McpCaller,
+): Promise<McpSurfaceSize> {
+  const init = resultOf(
+    await server.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, caller),
+  );
+  const instructions = init?.['instructions'];
+  const list = resultOf(
+    await server.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list' }, caller),
+  );
+  const tools = Array.isArray(list?.['tools'])
+    ? (list['tools'] as readonly { name?: unknown }[])
+    : [];
+  let listResources: number | undefined;
+  if (tools.some((tool) => tool.name === LIST_RESOURCES)) {
+    const called = resultOf(
+      await server.handle(
+        {
+          jsonrpc: '2.0',
+          id: 3,
+          method: 'tools/call',
+          params: { name: LIST_RESOURCES, arguments: {} },
+        },
+        caller,
+      ),
+    );
+    listResources = textLength(called?.['content']);
+  }
+  return {
+    toolsList: JSON.stringify(list ?? {}).length,
+    listResources,
+    instructions: typeof instructions === 'string' ? instructions.length : 0,
+  };
+}
+
+/**
+ * Measure, then refuse any surface over its budget with `X_MCP_SURFACE_OVER_BUDGET` naming every
+ * one. Returns the measurement so a test can print it next to the number it chose.
+ *
+ * ```ts
+ * test('the staff surface stays small', async () => {
+ *   await assertMcpSurfaceBudget(mcp.server, staffCaller, { toolsList: 4_000, listResources: 12_000 });
+ * });
+ * ```
+ *
+ * Size a budget from the measured value times a margin, and write the derivation beside it.
+ */
+export async function assertMcpSurfaceBudget(
+  server: McpServer,
+  caller: McpCaller,
+  budget: McpSurfaceBudget,
+): Promise<McpSurfaceSize> {
+  const size = await measureMcpSurface(server, caller);
+  const over: { surface: string; size: number; budget: number }[] = [];
+  const judge = (surface: string, measured: number | undefined, ceiling: number | undefined) => {
+    if (measured !== undefined && ceiling !== undefined && measured > ceiling) {
+      over.push({ surface, size: measured, budget: ceiling });
+    }
+  };
+  judge('tools/list', size.toolsList, budget.toolsList);
+  judge('list_resources', size.listResources, budget.listResources);
+  judge('instructions', size.instructions, budget.instructions);
+  if (over.length > 0) throw new McpSurfaceOverBudgetError({ over });
+  return size;
+}
+
+function resultOf(
+  response: { readonly result?: unknown } | null,
+): Record<string, unknown> | undefined {
+  const result = response?.result;
+  return typeof result === 'object' && result !== null
+    ? (result as Record<string, unknown>)
+    : undefined;
+}
+
+function textLength(content: unknown): number {
+  if (!Array.isArray(content)) return 0;
+  let total = 0;
+  for (const block of content as readonly { readonly text?: unknown }[]) {
+    if (typeof block.text === 'string') total += block.text.length;
+  }
+  return total;
+}