@ultimat3/mcp 22.9.1 → 22.11.0

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 { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
+import type { ErrorAudience } from '@ultimat3/core';
+import { fixFor } from '@ultimat3/core';
+import { auditResourceRead, auditToolCall, outcomeForResult } from './audit';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
-import { asFrameworkError, renderFrameworkError } from './framework-error';
+import { asFrameworkError } 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,9 @@ 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 { admitted, thrownResponse } from './tool-thrown';
 import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
 import {
   defaultServerInfo,
@@ -64,6 +68,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 +110,7 @@ export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
     input.prompts ?? [],
     input.serverInfo ?? defaultServerInfo(),
     meta,
+    { instructions: input.instructions, errorAudience: input.errorAudience ?? 'developer' },
   );
 }
 
@@ -102,6 +121,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 +129,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 +173,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 +183,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 +219,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 +305,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 +335,20 @@ 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': {
+        // The policy's actor half outranks the argument check: a caller the tool refuses whatever
+        // 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);
+        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;
     }
@@ -319,25 +357,7 @@ export class McpServer {
     try {
       result = await resolved.tool.handle(resolved.args, caller);
     } catch (error) {
-      // OUTCOME 3 arrives here: the tool ran its policy through `guard()` and the policy
-      // said no. An UltimateError is an EXPECTED outcome the model can act on, so it comes
-      // back as an `isError` result carrying code/cause/fix — the same three lines an HTTP
-      // caller gets for the same call — rather than an opaque transport failure.
-      const framework = asFrameworkError(error);
-      if (framework !== undefined) {
-        auditToolCall({
-          tool: name,
-          outcome: outcomeForCode(framework.code),
-          caller,
-          code: framework.code,
-        });
-        return resultResponse(id, {
-          content: [{ type: 'text', text: renderFrameworkError(framework) }],
-          isError: true,
-        });
-      }
-      auditToolCall({ tool: name, outcome: 'failed', caller });
-      return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
+      return thrownResponse(id, name, error, caller, audience);
     }
 
     // A tool may answer `isError` itself (admin renders its own denial). Outcome 3 unless it
@@ -351,6 +371,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 +424,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 +454,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;
+}

package/src/tool-thrown.ts

@@ -0,0 +1,51 @@
+// What a `tools/call` answers when the tool threw — or its `admit` refused the caller before the
+// arguments were read. One renderer for both, so a policy denial reads the same whichever gate
+// 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 { asFrameworkError, renderFrameworkError } from './framework-error';
+import type { AnyMcpTool, McpCaller } from './registry';
+import type { JsonRpcId, JsonRpcResponse } from './wire';
+import { errorResponse, INTERNAL_ERROR, resultResponse } from './wire';
+
+/**
+ * OUTCOME 3 arrives here: the tool ran its policy through `guard()` and the policy said no. An
+ * UltimateError is an EXPECTED outcome the model can act on, so it comes back as an `isError`
+ * result carrying code/cause/fix — the same three lines an HTTP caller gets for the same call —
+ * rather than an opaque transport failure.
+ */
+export function thrownResponse(
+  id: JsonRpcId,
+  name: string,
+  error: unknown,
+  caller: McpCaller,
+  audience: ErrorAudience,
+): JsonRpcResponse {
+  const framework = asFrameworkError(error);
+  if (framework !== undefined) {
+    auditToolCall({
+      tool: name,
+      outcome: outcomeForCode(framework.code),
+      caller,
+      code: framework.code,
+    });
+    return resultResponse(id, {
+      content: [{ type: 'text', text: renderFrameworkError(framework, audience) }],
+      isError: true,
+    });
+  }
+  auditToolCall({ tool: name, outcome: 'failed', caller });
+  return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
+}
+
+/** What the tool's `admit` threw for this caller, or `undefined` when it let them through. */
+export function admitted(tool: AnyMcpTool | undefined, caller: McpCaller): unknown {
+  if (tool?.admit === undefined) return undefined;
+  try {
+    tool.admit(caller);
+    return undefined;
+  } catch (error) {
+    return error;
+  }
+}