@ultimat3/mcp 1.0.0

package/src/resources.ts

@@ -0,0 +1,166 @@
+// MCP resources and prompts: the read-only documents an agent pulls once and keeps.
+//
+// Resources are what stops an agent guessing. Rather than teaching it the framework in a
+// prompt, hand it the generated facts at a stable URI and let it read them. Providers are
+// injected as thunks because `@ultimat3/manifest` and `@ultimat3/render` sit in this same
+// tier — the CLI wires them, this package only defines the shape and the URIs.
+
+import type { JsonSchema } from './wire';
+
+/** Stable URIs. These are quoted in AGENTS.md files, so treat them as public API. */
+export const RESOURCE_URIS = {
+  manifest: 'ultimate://manifest',
+  openapi: 'ultimate://openapi.json',
+  routes: 'ultimate://routes',
+  schema: 'ultimate://schema',
+} as const;
+
+export interface McpResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly description: string;
+  readonly mimeType: string;
+  /** Read on demand — a resource is never eagerly materialised at boot. */
+  read(): Promise<string> | string;
+}
+
+/** `resources/list` row (the MCP shape, minus the body). */
+export interface ResourceListEntry {
+  readonly uri: string;
+  readonly name: string;
+  readonly description: string;
+  readonly mimeType: string;
+}
+
+/** `resources/read` contents entry. */
+export interface ResourceContents {
+  readonly uri: string;
+  readonly mimeType: string;
+  readonly text: string;
+}
+
+/** A versioned prompt the server offers to clients (`prompts/list`). */
+export interface McpPrompt {
+  readonly name: string;
+  readonly description: string;
+  readonly arguments?: readonly McpPromptArgument[];
+}
+
+export interface McpPromptArgument {
+  readonly name: string;
+  readonly description: string;
+  readonly required?: boolean;
+}
+
+/**
+ * A prompt may be authored as a path to a versioned prompt artifact
+ * (`apps/web/app/posts/prompts/summarize.v3.md`). The file IS the contract, so restating its
+ * name and description in a second place is exactly the duplication that goes stale — the name
+ * comes from the filename, version suffix included, because `summarize.v2` and `summarize.v3`
+ * are two different prompts and an agent must be able to say which one it read.
+ */
+export function promptFromPath(path: string): McpPrompt {
+  const file = path.split('/').pop() ?? path;
+  const name = file.replace(/\.(md|markdown|txt|prompt)$/i, '');
+  return { name, description: `Versioned prompt artifact: ${path}` };
+}
+
+/** Accepts either authoring form; an object is already the wire shape and passes through. */
+export function toPrompts(prompts: readonly (string | McpPrompt)[]): readonly McpPrompt[] {
+  return prompts.map((prompt) => (typeof prompt === 'string' ? promptFromPath(prompt) : prompt));
+}
+
+/** The four documents every Ultimate app publishes. Any provider may be omitted. */
+export interface FrameworkResourceProviders {
+  /** `x.manifest.json` contents — the generated facts. */
+  readonly manifest?: () => Promise<string> | string;
+  /** The OpenAPI document projected from actions and queries. */
+  readonly openapi?: () => Promise<string> | string;
+  /** The route table: URL, render mode, offline strategy, budget. */
+  readonly routes?: () => Promise<string> | string;
+  /** Entity/column/invariant description — the DB shape as JSON. */
+  readonly schema?: () => Promise<string> | string;
+}
+
+export function frameworkResources(providers: FrameworkResourceProviders): readonly McpResource[] {
+  const out: McpResource[] = [];
+  if (providers.manifest !== undefined) {
+    out.push({
+      uri: RESOURCE_URIS.manifest,
+      name: 'x.manifest.json',
+      description: 'Generated facts: routes, entities, actions, queries, jobs, policies.',
+      mimeType: 'application/json',
+      read: providers.manifest,
+    });
+  }
+  if (providers.openapi !== undefined) {
+    out.push({
+      uri: RESOURCE_URIS.openapi,
+      name: 'openapi.json',
+      description: 'OpenAPI 3.1 document projected from every action and query.',
+      mimeType: 'application/json',
+      read: providers.openapi,
+    });
+  }
+  if (providers.routes !== undefined) {
+    out.push({
+      uri: RESOURCE_URIS.routes,
+      name: 'routes',
+      description: 'Route table: url, render mode, offline strategy, hydrate, budget.',
+      mimeType: 'application/json',
+      read: providers.routes,
+    });
+  }
+  if (providers.schema !== undefined) {
+    out.push({
+      uri: RESOURCE_URIS.schema,
+      name: 'schema',
+      description: 'Entities with columns, types and invariants.',
+      mimeType: 'application/json',
+      read: providers.schema,
+    });
+  }
+  return out;
+}
+
+export class ResourceRegistry {
+  private readonly resources = new Map<string, McpResource>();
+
+  register(resource: McpResource): this {
+    this.resources.set(resource.uri, resource);
+    return this;
+  }
+
+  registerAll(resources: readonly McpResource[]): this {
+    for (const r of resources) this.register(r);
+    return this;
+  }
+
+  /** Sorted by URI: a stable list is diffable between two boots. */
+  list(): readonly ResourceListEntry[] {
+    return [...this.resources.values()]
+      .map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType,
+      }))
+      .sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+  }
+
+  async read(uri: string): Promise<ResourceContents | undefined> {
+    const resource = this.resources.get(uri);
+    if (resource === undefined) return undefined;
+    return { uri, mimeType: resource.mimeType, text: await resource.read() };
+  }
+}
+
+/** JSON Schema for a tool that takes one resource URI — reused by app surfaces. */
+export const URI_ARG_SCHEMA: JsonSchema = {
+  type: 'object',
+  properties: {
+    uri: { type: 'string', description: `Resource URI, e.g. ${RESOURCE_URIS.manifest}` },
+  },
+  required: ['uri'],
+  additionalProperties: false,
+};

package/src/scopes.ts

@@ -0,0 +1,71 @@
+// `defineAppMcp`'s `scopes:` map — OUTCOME 2's declaration surface.
+//
+// Visibility and the policy are declared ON the primitive: one is the tool's audience, the
+// other is its authz rule, and both belong beside the code they guard. A SCOPE is neither.
+// It is a capability of the CONNECTION — what the token was issued to do — so it is grouped
+// here, once per scope, naming the tools that capability covers. That is also why
+// `toolFromAction` never invents one: a projection cannot know what a token means.
+//
+// Without this map the second outcome is unreachable for a generated app. `ToolRegistry`
+// enforces `scope`, the framework's own dev tools declare one, and until 2026-08 nothing an
+// app could write ever set the field — an enforced gate no app declaration could engage.
+
+import { McpScopeConflictError, McpScopeUnknownError } from './errors';
+import type { AnyMcpTool } from './registry';
+
+/**
+ * Scope name → the tools it covers, BY TOOL NAME. A name, not an object reference: it is the
+ * one identifier every tool in the catalog has, whichever way it got there — a projected
+ * action or query, a key in the `tools` record, a ready `McpTool` from a programmatic surface.
+ * It is also what the wire and a token grant both talk about, so `x token grant orders:write`
+ * and this map name the same thing. A typo cannot survive boot — see `withScopes`.
+ */
+export type McpScopes = Readonly<Record<string, readonly string[]>>;
+
+/**
+ * Attach each declared scope to the tool it covers, refusing anything ambiguous at BOOT.
+ *
+ * Two refusals, because both silently ship an ungated tool otherwise:
+ *
+ *  - a name no tool in the catalog answers to (`X_MCP_SCOPE_UNKNOWN`) — a typo, or a primitive
+ *    that was renamed or never listed. Skipping it leaves the tool reachable with no scope at
+ *    all, which is the opposite of what the author wrote;
+ *  - one tool claimed by two scopes (`X_MCP_SCOPE_CONFLICT`) — a tool carries ONE scope, so
+ *    the second claim would either overwrite the first or be dropped, and which one wins would
+ *    be decided by object key order.
+ *
+ * Runs AFTER duplicate names are refused, so a name resolves to exactly one tool.
+ */
+export function withScopes(
+  tools: readonly AnyMcpTool[],
+  scopes: McpScopes | undefined,
+): readonly AnyMcpTool[] {
+  if (scopes === undefined) return tools;
+
+  const catalog = new Map(tools.map((tool) => [tool.name, tool]));
+  const required = new Map<string, string>();
+
+  for (const [scope, names] of Object.entries(scopes)) {
+    for (const name of names) {
+      if (!catalog.has(name)) {
+        throw new McpScopeUnknownError({ scope, name, projected: [...catalog.keys()].sort() });
+      }
+      const claimed = required.get(name);
+      if (claimed !== undefined && claimed !== scope) {
+        throw new McpScopeConflictError({ name, scopes: [claimed, scope] });
+      }
+      // A tool that arrived with its own `scope` (a ready `McpTool` from a programmatic
+      // surface) is claimed too: two sources for one gate is the same ambiguity.
+      const declared = catalog.get(name)?.scope;
+      if (declared !== undefined && declared !== scope) {
+        throw new McpScopeConflictError({ name, scopes: [declared, scope] });
+      }
+      required.set(name, scope);
+    }
+  }
+
+  return tools.map((tool) => {
+    const scope = required.get(tool.name);
+    return scope === undefined ? tool : { ...tool, scope };
+  });
+}

package/src/server.ts

@@ -0,0 +1,268 @@
+// The MCP server: JSON-RPC dispatch over a tool registry, a resource registry and a
+// prompt list. Transport-independent — `handle(body, caller)` takes an already-parsed body
+// 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 { auditToolCall, outcomeForCode } from './audit';
+import { McpScopeDeniedError } from './errors';
+import type { AnyMcpTool, McpCaller, McpToolResult, McpVerbClass, ToolListEntry } from './registry';
+import { ToolRegistry } from './registry';
+import type { McpPrompt, McpResource } from './resources';
+import { ResourceRegistry } from './resources';
+import type { JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
+import {
+  DEFAULT_SERVER_INFO,
+  errorResponse,
+  INTERNAL_ERROR,
+  INVALID_PARAMS,
+  INVALID_REQUEST,
+  isJsonRpcRequest,
+  isNotification,
+  MCP_PROTOCOL_VERSION,
+  METHOD_NOT_FOUND,
+  paramsOf,
+  resultResponse,
+} from './wire';
+
+export interface CreateMcpServerInput {
+  readonly tools?: readonly AnyMcpTool[];
+  readonly resources?: readonly McpResource[];
+  readonly prompts?: readonly McpPrompt[];
+  readonly serverInfo?: ServerInfo;
+}
+
+/** The set of JSON-RPC methods this server answers. Kept in sync with `classify`. */
+const METHODS = [
+  'initialize',
+  'tools/list',
+  'tools/call',
+  'resources/list',
+  'resources/read',
+  'prompts/list',
+] as const;
+
+export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
+  const tools = new ToolRegistry().registerAll(input.tools ?? []);
+  const resources = new ResourceRegistry().registerAll(input.resources ?? []);
+  return new McpServer(
+    tools,
+    resources,
+    input.prompts ?? [],
+    input.serverInfo ?? DEFAULT_SERVER_INFO,
+  );
+}
+
+export class McpServer {
+  readonly tools: ToolRegistry;
+  readonly resources: ResourceRegistry;
+  private readonly prompts: readonly McpPrompt[];
+  private readonly serverInfo: ServerInfo;
+
+  constructor(
+    tools: ToolRegistry,
+    resources: ResourceRegistry,
+    prompts: readonly McpPrompt[],
+    serverInfo: ServerInfo,
+  ) {
+    this.tools = tools;
+    this.resources = resources;
+    this.prompts = prompts;
+    this.serverInfo = serverInfo;
+  }
+
+  async handle(body: unknown, caller: McpCaller): Promise<JsonRpcResponse | null> {
+    if (!isJsonRpcRequest(body)) {
+      return errorResponse(null, INVALID_REQUEST, '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;
+    const id = body.id ?? null;
+
+    switch (body.method) {
+      case 'initialize':
+        return resultResponse(id, {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: {
+            tools: { listChanged: false },
+            resources: { subscribe: false, listChanged: false },
+            prompts: { listChanged: false },
+          },
+          serverInfo: this.serverInfo,
+        });
+      case 'tools/list':
+        return resultResponse(id, { tools: this.list(caller) });
+      case 'tools/call':
+        return this.toolsCall(body, caller);
+      case 'resources/list':
+        return resultResponse(id, { resources: this.resources.list() });
+      case 'resources/read':
+        return this.resourcesRead(body);
+      case 'prompts/list':
+        return resultResponse(id, { prompts: this.prompts });
+      default:
+        return errorResponse(id, METHOD_NOT_FOUND, `method not found: ${body.method}`, {
+          supported: METHODS,
+        });
+    }
+  }
+
+  /** Role-filtered catalog. Exposed so a transport can answer a cheap capability probe. */
+  list(caller: McpCaller): readonly ToolListEntry[] {
+    return this.tools.list(caller);
+  }
+
+  /**
+   * Rate-limit class of a body WITHOUT executing it, and WITHOUT a caller — bucket
+   * selection is metering, not authorization. All MCP traffic is one `POST /mcp`, so a
+   * coarse per-route rule would charge `initialize` and every read to the write bucket and
+   * throttle an agent on its handshake.
+   *
+   * KEEP IN SYNC with `handle`: only `tools/call` can reach a tool, so every other method
+   * is protocol chatter that structurally cannot mutate.
+   */
+  classify(body: unknown): McpVerbClass {
+    if (!isJsonRpcRequest(body) || body.method !== 'tools/call') return 'read';
+    const name = paramsOf(body)?.['name'];
+    // An unresolvable call is refused before it runs, so charging it the strict bucket
+    // only costs a broken client — it never hands an unproven verb the cheap one.
+    if (typeof name !== 'string') return 'write';
+    return this.tools.verbClass(name);
+  }
+
+  private async toolsCall(req: JsonRpcRequest, caller: McpCaller): Promise<JsonRpcResponse> {
+    const id = req.id ?? null;
+    const params = paramsOf(req);
+    if (params === null) return errorResponse(id, INVALID_PARAMS, 'tools/call requires params');
+    const name = params['name'];
+    if (typeof name !== 'string') {
+      return errorResponse(id, INVALID_PARAMS, 'tools/call params.name must be a string');
+    }
+
+    // Three outcomes, deliberately different — and every one of them audited, including the
+    // one that tells the caller nothing. See `audit.ts`.
+    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.
+      case 'not-found':
+        auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
+        return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name}`);
+      // 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': {
+        const denial = new McpScopeDeniedError({ name, scope: resolved.scope });
+        auditToolCall({
+          tool: name,
+          outcome: 'scope-denied',
+          caller,
+          scope: resolved.scope,
+          code: denial.code,
+        });
+        return errorResponse(id, INVALID_REQUEST, `missing scope: ${resolved.scope}`, {
+          code: denial.code,
+          scope: resolved.scope,
+          fix: denial.fix,
+          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 'ok':
+        break;
+    }
+
+    let result: McpToolResult;
+    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`);
+    }
+
+    // A tool may answer `isError` itself (admin renders its own denial): still outcome 3.
+    auditToolCall({
+      tool: name,
+      outcome: result.isError === true ? 'policy-denied' : 'ok',
+      caller,
+    });
+    const payload: Record<string, unknown> = { content: result.content };
+    if (result.isError === true) payload['isError'] = true;
+    return resultResponse(id, payload);
+  }
+
+  private async resourcesRead(req: JsonRpcRequest): Promise<JsonRpcResponse> {
+    const id = req.id ?? null;
+    const uri = paramsOf(req)?.['uri'];
+    if (typeof uri !== 'string') {
+      return errorResponse(id, INVALID_PARAMS, 'resources/read params.uri must be a string');
+    }
+    const contents = await this.resources.read(uri);
+    if (contents === undefined) {
+      return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`, {
+        available: this.resources.list().map((r) => r.uri),
+      });
+    }
+    return resultResponse(id, { contents: [contents] });
+  }
+}
+
+interface FrameworkError {
+  readonly code: string;
+  /** `''` for a foreign thrown object that carries no title. See `renderFrameworkError`. */
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/**
+ * Read a thrown framework error, or `undefined` when it is not one (a genuine bug, which
+ * becomes `-32603` with no internals leaked). Structural rather than `instanceof`: the
+ * transport must stay independent of which package threw.
+ */
+function asFrameworkError(error: unknown): FrameworkError | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const e = error as { code?: unknown; title?: unknown; cause?: unknown; fix?: unknown };
+  if (typeof e.code !== 'string' || !e.code.startsWith('X_')) return undefined;
+  return {
+    code: e.code,
+    title: typeof e.title === 'string' ? e.title : '',
+    cause: typeof e.cause === 'string' ? e.cause : 'unknown',
+    fix: typeof e.fix === 'string' ? e.fix : 'see docs',
+  };
+}
+
+/**
+ * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format()` — one denial reads the
+ * same over MCP as it does in the terminal, so an agent that learned the shape from `x` does
+ * not have to learn a second one here. Dropping the title would be a second rendering of the
+ * same contract, and the two would drift.
+ *
+ * The bare-`code` head is the fallback for a foreign thrown object that carries `code`/`cause`
+ * but no title; a real `UltimateError` always has one.
+ */
+function renderFrameworkError(error: FrameworkError): string {
+  const head = error.title === '' ? error.code : `${error.code}: ${error.title}`;
+  return `${head}\n  cause: ${error.cause}\n  fix:   ${error.fix}`;
+}

package/src/transport-http.ts

@@ -0,0 +1,145 @@
+// `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:
+//
+//  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
+//     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 type { McpCaller, McpRole, McpVerbClass } from './registry';
+import type { McpServer } from './server';
+import type { JsonRpcResponse } from './wire';
+import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
+
+/** Requests per minute per token, by class. Reads are cheap; a write may run migrations. */
+export const MCP_RATE_LIMITS: Readonly<Record<McpVerbClass, number>> = {
+  read: 120,
+  write: 20,
+};
+
+/** What a token resolves to. `null` = unauthenticated, answered 401 with no catalog. */
+export interface ResolvedToken {
+  readonly actor: Actor;
+  readonly scopes: ReadonlySet<string>;
+  readonly role?: McpRole;
+}
+
+export interface McpHttpTransportInput {
+  readonly server: McpServer;
+  /**
+   * Resolve an OAuth bearer / personal token to a caller. The framework supplies the token
+   * string only — credential storage belongs to `@ultimat3/policy` and the app, never here.
+   */
+  resolveToken(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
+  /** Route path. Overridable so an app can mount a second, app-scoped surface. */
+  readonly path?: string;
+}
+
+export interface McpRouteDescriptor {
+  readonly method: 'POST';
+  readonly path: string;
+  /** Bucket for one already-parsed body. Metering only — never an authz decision. */
+  rateLimitClass(body: unknown): McpVerbClass;
+  readonly limits: Readonly<Record<McpVerbClass, number>>;
+  handle(request: Request): Promise<Response>;
+}
+
+const JSON_HEADERS = { 'content-type': 'application/json' } as const;
+
+export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
+  const { server } = input;
+
+  return {
+    method: 'POST',
+    path: input.path ?? '/mcp',
+    limits: MCP_RATE_LIMITS,
+    rateLimitClass: (body) => server.classify(body),
+
+    async handle(request: Request): Promise<Response> {
+      const token = bearerToken(request);
+      if (token === null) {
+        // 401 before parsing: an unauthenticated caller learns nothing about the catalog,
+        // not even whether its JSON was well formed.
+        return unauthorized();
+      }
+
+      let body: unknown;
+      try {
+        body = await request.json();
+      } catch {
+        return json(errorResponse(null, PARSE_ERROR, 'request body is not valid JSON'), 400);
+      }
+
+      const resolved = await input.resolveToken(token);
+      if (resolved === null) return unauthorized();
+      if (!isAgentActor(resolved.actor)) return notAnAgent();
+
+      const caller: McpCaller = {
+        actor: resolved.actor,
+        scopes: resolved.scopes,
+        ...(resolved.role !== undefined ? { role: resolved.role } : {}),
+      };
+
+      const response = await server.handle(body, caller);
+      // 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
+      // malformed envelope (below) is an HTTP-level failure.
+      const status = response.error?.code === INVALID_REQUEST && response.id === null ? 400 : 200;
+      return json(response, status);
+    },
+  };
+}
+
+/** `Authorization: Bearer <token>`, the only accepted form. No query-string tokens. */
+export function bearerToken(request: Request): string | null {
+  const header = request.headers.get('authorization');
+  if (header === null) return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  return match?.[1] ?? null;
+}
+
+/**
+ * A token-authenticated MCP caller is ALWAYS `kind: 'agent'`, never the human the token
+ * belongs to. Enforced here rather than trusted from `resolveToken`, so a policy that says
+ * "agents may not do this" cannot be bypassed by an app handing back a user actor.
+ */
+export function isAgentActor(actor: Actor): boolean {
+  return (actor as { kind?: unknown }).kind === 'agent';
+}
+
+function notAnAgent(): Response {
+  return new Response(
+    JSON.stringify({
+      code: 'X_MCP_PROTOCOL',
+      cause: 'resolveToken returned an actor whose kind is not "agent"',
+      fix: 'return { kind: "agent", ... } from resolveToken; MCP callers are agents, not users',
+    }),
+    { status: 403, headers: JSON_HEADERS },
+  );
+}
+
+function unauthorized(): Response {
+  return new Response(
+    JSON.stringify({
+      code: 'X_MCP_PROTOCOL',
+      cause: 'missing or unrecognised bearer token',
+      fix: 'x token create --scopes dev:read, then send Authorization: Bearer <token>',
+    }),
+    {
+      status: 401,
+      headers: { ...JSON_HEADERS, 'www-authenticate': 'Bearer realm="ultimate-mcp"' },
+    },
+  );
+}
+
+function json(response: JsonRpcResponse, status: number): Response {
+  return new Response(JSON.stringify(response), { status, headers: JSON_HEADERS });
+}