@12-apps/mcp 1.19.0 → 2.0.0

package/scripts/sync-mcp-schema.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/* global console, process */
+/**
+ * Copy this package's Prisma model PARTIAL into the host's schema folder.
+ *
+ *   node scripts/sync-mcp-schema.mjs [--check] [<host-schema-dir>]
+ *
+ * The partial is COPIED, never symlinked (the entity-lifecycle doctrine, and
+ * the prisma-partials-are-copied-never-symlinked memory): `turbo prune` copies
+ * only what the dependency graph reaches, so a committed symlink dangles the
+ * moment the owning package is not a declared workspace dependency — and a
+ * SYMLINKED MIGRATION is silently skipped by Prisma (`readdir` +
+ * `isDirectory()` is false for a link), so a green deploy applies no schema.
+ *
+ * Only the schema partial. MIGRATIONS ARE NOT HANDLED HERE — the host
+ * discovers and copies them structurally, by looking for a `prisma/migrations`
+ * directory inside every installed `@12-apps/*` package (see future-pay's
+ * packages/prisma/scripts/sync-prisma-plugins.mjs).
+ *
+ * The host package that owns the schema folder MUST also declare this package
+ * as a dependency, so the source of the copy is present in every build
+ * context.
+ *
+ * Default host path follows the future-pay layout
+ * (`packages/prisma/prisma/schema/`); another repo passes its own schema
+ * folder as the positional argument, or sets MCP_HOST_SCHEMA_DIR.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LABEL = '[mcp-schema]';
+const RESYNC = 'pnpm --filter @12-apps/mcp prisma:sync';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SOURCE = join(HERE, '../prisma/mcp.prisma');
+
+const args = process.argv.slice(2).filter((arg) => arg !== '--check');
+const check = process.argv.includes('--check');
+const hostSchemaDir =
+  args[0] ??
+  process.env.MCP_HOST_SCHEMA_DIR ??
+  join(HERE, '../../prisma/prisma/schema');
+const TARGET = join(hostSchemaDir, 'mcp.prisma');
+
+const source = readFileSync(SOURCE, 'utf8');
+const target = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : null;
+
+if (source === target) {
+  console.log(`${LABEL} in sync.`);
+} else if (check) {
+  console.error(
+    `${LABEL} DRIFT: ${TARGET} does not match the @12-apps/mcp partial. ` +
+      `Run "${RESYNC}" and commit the result.`,
+  );
+  process.exit(1);
+} else {
+  mkdirSync(hostSchemaDir, { recursive: true });
+  copyFileSync(SOURCE, TARGET);
+  console.log(`${LABEL} copied ${SOURCE} -> ${TARGET}.`);
+}

package/src/auth/authorization-server-metadata.ts

@@ -21,6 +21,22 @@ export interface AuthorizationServerMetadataInput {
    * public PKCE clients (`none`) plus HTTP Basic client-secret auth.
    */
   tokenEndpointAuthMethods?: string[];
+  /**
+   * Where the endpoints are actually mounted, if not at the defaults below. A
+   * host that moves an endpoint MUST move it here too: this document is the only
+   * thing a connector reads before its first request, so a path that lies here is
+   * a flow that fails at the first hop (12-23 — `createApiMcpOauth` passes its
+   * resolved paths, so the two cannot disagree).
+   */
+  paths?: Partial<AuthorizationServerPaths>;
+}
+
+/** The endpoint paths this document advertises, relative to the issuer origin. */
+export interface AuthorizationServerPaths {
+  authorize: string;
+  token: string;
+  register: string;
+  jwks: string;
 }
 
 /** The RFC 8414 document served at `/.well-known/oauth-authorization-server`. */
@@ -37,10 +53,12 @@ export interface AuthorizationServerMetadata {
   token_endpoint_auth_methods_supported: string[];
 }
 
-const AUTHORIZE_PATH = "/api/oauth/authorize";
-const TOKEN_PATH = "/api/oauth/token";
-const REGISTRATION_PATH = "/api/oauth/register";
-const JWKS_PATH = "/.well-known/jwks.json";
+const DEFAULT_PATHS: AuthorizationServerPaths = {
+  authorize: "/api/oauth/authorize",
+  token: "/api/oauth/token",
+  register: "/api/oauth/register",
+  jwks: "/.well-known/jwks.json",
+};
 
 const DEFAULT_TOKEN_ENDPOINT_AUTH_METHODS = [
   "none",
@@ -57,12 +75,13 @@ export function buildAuthorizationServerMetadata(
   input: AuthorizationServerMetadataInput,
 ): AuthorizationServerMetadata {
   const origin = input.issuer;
+  const paths = { ...DEFAULT_PATHS, ...input.paths };
   return {
     issuer: origin,
-    authorization_endpoint: `${origin}${AUTHORIZE_PATH}`,
-    token_endpoint: `${origin}${TOKEN_PATH}`,
-    registration_endpoint: `${origin}${REGISTRATION_PATH}`,
-    jwks_uri: `${origin}${JWKS_PATH}`,
+    authorization_endpoint: `${origin}${paths.authorize}`,
+    token_endpoint: `${origin}${paths.token}`,
+    registration_endpoint: `${origin}${paths.register}`,
+    jwks_uri: `${origin}${paths.jwks}`,
     scopes_supported: input.scopesSupported,
     response_types_supported: ["code"],
     grant_types_supported: ["authorization_code", "refresh_token"],

package/src/coverage-gate/index.ts

@@ -0,0 +1,243 @@
+import { readFileSync } from "node:fs";
+
+import { exportedActionsOf, segmentPrefixMatch, walkActionFiles } from "@12-apps/rbac/coverage";
+
+import { collectRouteMethods } from "./route-methods";
+
+/**
+ * `@12-apps/mcp/coverage` — the MCP route/action coverage gate (12-23), moved out
+ * of future-pay's `apps/web/scripts/mcp/coverage.ts` so a host's own script is a
+ * one-line re-export and the CI workflow that shells out to the consumer's
+ * `mcp:coverage` package script (`12-apps/ci`'s `mcp-contract.yml`) keeps working
+ * unchanged.
+ *
+ * `mcp:check` only proves the REGISTRY matches the committed manifest; nothing
+ * stops a new route file, or a new server action, from shipping outside the
+ * agent-exposable surface. This gate closes both:
+ *
+ *  1. **Route coverage** — every HTTP method exported by a route file must be
+ *     registered in the host's MCP registry (or its path listed under `routes` in
+ *     the exclusions file), and every registry entry must map back to a real route
+ *     file exporting that method. A tool the manifest advertises but no route
+ *     serves is a promise an agent cannot cash.
+ *  2. **Action coverage** — every exported server action must be mapped to a
+ *     registry operationId in the action map, or listed under `actions` in the
+ *     exclusions file with a reason. New actions fail until mapped; stale entries
+ *     fail until pruned, so neither file can rot.
+ *
+ * The exclusions file is the ONLY escape hatch, and keeping it a separate,
+ * human-protected file is the point: an agent cannot silently exclude a new
+ * route/action — it has to justify to a human why the capability is not exposed.
+ */
+
+/** One registry entry, as the host's MCP registry describes an endpoint. */
+export interface McpRegistryEndpoint {
+  method: string;
+  /** URL path in `{param}` form — the same shape the scan produces. */
+  path: string;
+  operationId: string;
+}
+
+/** The protected exclusions file: every deliberate gate escape hatch. */
+export interface McpCoverageExclusions {
+  /** Server actions kept off the surface, name → reason. */
+  actions: Record<string, string>;
+  /** Route path prefixes kept off the surface, prefix → reason. */
+  routes: Record<string, string>;
+}
+
+/** The action map: server action name → registry operationId. */
+export interface McpActionMap {
+  mapped: Record<string, string>;
+}
+
+export interface McpCoverageOptions {
+  /** The framework routes folder (the WHOLE `app`, never `app/api`). */
+  appDir: string;
+  /** Root for relative paths in failure messages. Default: `appDir`. */
+  webRoot?: string;
+  /** The host's registry entries (its `endpoints` array). */
+  endpoints: readonly McpRegistryEndpoint[];
+  /** Path to the exclusions JSON ({@link McpCoverageExclusions}). */
+  exclusionsPath: string;
+  /**
+   * Path to the action-map JSON ({@link McpActionMap}). Omit for a host with no
+   * server actions at all — action coverage is then vacuous rather than a crash on
+   * a file that was never written.
+   */
+  actionMapPath?: string;
+}
+
+export interface McpCoverageResult {
+  failures: string[];
+  routeMethodCount: number;
+  actionCount: number;
+}
+
+interface GateContext {
+  appDir: string;
+  webRoot: string;
+  endpoints: readonly McpRegistryEndpoint[];
+  exclusions: McpCoverageExclusions;
+  actionMap: McpActionMap | null;
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+/** Route coverage — every served method registered, every registry entry served. */
+function routeFailures(ctx: GateContext): { failures: string[]; routeMethodCount: number } {
+  const failures: string[] = [];
+  const infraPrefixes = Object.keys(ctx.exclusions.routes);
+  const routeMethods = collectRouteMethods(ctx.appDir, ctx.webRoot);
+  const registered = new Set(
+    ctx.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()} ${endpoint.path}`),
+  );
+
+  // NOTE which way this loop fails, because it is the opposite of the instinct a
+  // gate invites: a method the SCAN misses is simply absent from `covered`, so no
+  // violation is raised at all and that route ships unregistered. Under-detection
+  // here is fail-OPEN — which is why `exportedNamesOf` blanks comments and strings
+  // before it looks for an export head instead of trusting raw source. (The loop
+  // after this one is the merely noisy half: a REGISTERED entry whose route was
+  // missed reports `registry entry without a route`.)
+  const covered = routeMethods.filter(({ urlPath }) => !segmentPrefixMatch(urlPath, infraPrefixes));
+  for (const { urlPath, method, file } of covered) {
+    if (!registered.has(`${method} ${urlPath}`)) {
+      failures.push(
+        `unregistered route: ${method} ${urlPath} (${file}) — add a registry entry, or ` +
+          `(human-authorized, for infra only) a routes prefix in the exclusions file`,
+      );
+    }
+  }
+
+  const served = new Set(
+    routeMethods.map(({ method, urlPath }) => `${method} ${urlPath}`),
+  );
+  for (const endpoint of ctx.endpoints) {
+    if (!served.has(`${endpoint.method.toUpperCase()} ${endpoint.path}`)) {
+      failures.push(
+        `registry entry without a route: ${endpoint.operationId} ` +
+          `(${endpoint.method.toUpperCase()} ${endpoint.path}) — the manifest advertises a tool no route serves`,
+      );
+    }
+  }
+
+  return { failures, routeMethodCount: covered.length };
+}
+
+/**
+ * Every action the host actually exports must be accounted for — mapped to a
+ * registry operationId, or excluded with a reason. Neither silently.
+ */
+function unaccountedActions(
+  ctx: GateContext,
+  actions: Set<string>,
+  mapped: Record<string, string>,
+): string[] {
+  const failures: string[] = [];
+  for (const action of actions) {
+    const isMapped = action in mapped;
+    const isExcluded = action in ctx.exclusions.actions;
+    if (!isMapped && !isExcluded) {
+      failures.push(
+        `unmapped server action: ${action} — map it to a registry operationId in the action ` +
+          `map, or (human-authorized) add it to the exclusions file with a reason`,
+      );
+    }
+    if (isMapped && isExcluded) {
+      failures.push(
+        `action both mapped and excluded: ${action} — remove it from one of the two files`,
+      );
+    }
+  }
+  return failures;
+}
+
+/**
+ * The other direction, and the one that keeps both files from rotting: an entry
+ * naming an action that no longer exists, or an operationId the registry does not
+ * have. Adding the mapping is never enough — a stale line must go.
+ */
+function staleActionEntries(
+  ctx: GateContext,
+  actions: Set<string>,
+  mapped: Record<string, string>,
+): string[] {
+  const failures: string[] = [];
+  const operationIds = new Set(ctx.endpoints.map((endpoint) => endpoint.operationId));
+  for (const [action, operationId] of Object.entries(mapped)) {
+    if (!actions.has(action)) {
+      failures.push(`stale action-map entry: ${action} — the action no longer exists`);
+    }
+    if (!operationIds.has(operationId)) {
+      failures.push(`action-map points at unknown operationId: ${action} → ${operationId}`);
+    }
+  }
+  for (const action of Object.keys(ctx.exclusions.actions)) {
+    if (!actions.has(action)) {
+      failures.push(`stale action exclusion: ${action} — the action no longer exists`);
+    }
+  }
+  return failures;
+}
+
+/** Action coverage — every action mapped or excluded, and neither file stale. */
+function actionFailures(ctx: GateContext): { failures: string[]; actionCount: number } {
+  const mapped = ctx.actionMap?.mapped ?? {};
+  const actions = new Set(
+    walkActionFiles(ctx.appDir).flatMap((file) => exportedActionsOf(readFileSync(file, "utf8"))),
+  );
+
+  return {
+    failures: [
+      ...unaccountedActions(ctx, actions, mapped),
+      ...staleActionEntries(ctx, actions, mapped),
+    ],
+    actionCount: actions.size,
+  };
+}
+
+/** Run the gate and return every violation (empty = green). */
+export function runMcpCoverage(options: McpCoverageOptions): McpCoverageResult {
+  const ctx: GateContext = {
+    appDir: options.appDir,
+    webRoot: options.webRoot ?? options.appDir,
+    endpoints: options.endpoints,
+    exclusions: readJson<McpCoverageExclusions>(options.exclusionsPath),
+    actionMap: options.actionMapPath ? readJson<McpActionMap>(options.actionMapPath) : null,
+  };
+  const routes = routeFailures(ctx);
+  const actions = actionFailures(ctx);
+  return {
+    failures: [...routes.failures, ...actions.failures],
+    routeMethodCount: routes.routeMethodCount,
+    actionCount: actions.actionCount,
+  };
+}
+
+/**
+ * The CLI face: print the verdict and exit non-zero on violations. A host's
+ * `scripts/mcp/coverage.ts` is then one import + one call, and the CI workflow that
+ * runs `pnpm mcp:coverage` needs no change at all.
+ */
+export function mcpCoverageCli(options: McpCoverageOptions): void {
+  const { failures, routeMethodCount, actionCount } = runMcpCoverage(options);
+  if (failures.length > 0) {
+    console.error(`[mcp:coverage] ${failures.length} violation(s):`);
+    for (const failure of failures) console.error(`  ✗ ${failure}`);
+    process.exit(1);
+  }
+  console.log(
+    `[mcp:coverage] OK — ${routeMethodCount} route method(s) registered, ` +
+      `${actionCount} action(s) mapped/excluded.`,
+  );
+}
+
+export {
+  collectRouteMethods,
+  exportedMethodsOf,
+  HTTP_METHODS,
+  type RouteMethod,
+} from "./route-methods";

package/src/coverage-gate/route-methods.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+
+import { exportedNamesOf, urlPathOf, walkRouteFiles } from "@12-apps/rbac/coverage";
+
+/**
+ * The route-METHOD half of the surface scan (12-23) — what `mcp:coverage` needs
+ * on top of what `rbac:coverage` already ships.
+ *
+ * The WALK is imported from `@12-apps/rbac/coverage` rather than copied — the file
+ * walk (`walkRouteFiles`), the URL mapping (`urlPathOf`) AND the export-head
+ * parser (`exportedNamesOf`) — and that is deliberate: both gates assert a
+ * COMPLETENESS property over the same two surfaces (`app/**` route files and
+ * `*actions.ts` modules), and future-pay's own comment on the shared scanner says
+ * why they must share it — "so the two gates can never disagree about what the
+ * surface is". Two copies would agree on the day they were written and drift
+ * silently after, in the direction of not looking. What is left here is the one
+ * thing that genuinely differs: the GRAMMAR (see {@link exportedMethodsOf}).
+ *
+ * THE SCAN ROOT IS THE WHOLE `app` FOLDER, never `app/api`: a completeness gate
+ * rooted below the surface it claims to cover does not fail when it misses
+ * something, it simply never looks. Three OAuth/JWKS discovery routes shipped
+ * unregistered for exactly as long as the walk was rooted at `app/api`.
+ *
+ * Detection is over SOURCE, with no TS compiler: fast, dependency-free, and it
+ * matches how the framework itself keys routes off file paths plus exported names.
+ */
+
+/** Every method a route file can serve — the scan must see them all. */
+export const HTTP_METHODS = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+] as const;
+
+/** One exported HTTP handler discovered on a route file. */
+export interface RouteMethod {
+  /** URL path with `[param]` → `{param}` (e.g. `/api/checkout/{id}`). */
+  urlPath: string;
+  /** The HTTP method exported (GET/POST/…). */
+  method: string;
+  /** The route file, relative to the web root. */
+  file: string;
+}
+
+/**
+ * Exported HTTP methods, across every form the app router serves:
+ * `export const GET`, `export function GET`, `export async function GET`,
+ * `export const { GET, POST } = handlers`, `export { handler as GET }`. For brace
+ * lists the exported name is the last identifier of each item (after `as`, or
+ * after `:` for destructuring renames). `export type { … }` never matches — a type
+ * is never a handler.
+ *
+ * The two grammar knobs are the whole difference from `exportedActionsOf`, and both
+ * are load-bearing: a route handler may be a SYNC `export function` (a server
+ * action may not — it must be async), and only the seven HTTP methods count, where
+ * every runtime export of a use-server module is an action.
+ *
+ * The shared walk is a linear hand-parse, not a regex: the `\s+`-joined patterns
+ * this gate first shipped with backtracked polynomially on adversarial input
+ * (CodeQL js/polynomial-redos), and a COMPLETENESS gate must stay O(n) on whatever
+ * source it is pointed at — it is run over files a contributor supplies.
+ */
+export function exportedMethodsOf(source: string): string[] {
+  return exportedNamesOf(source, { syncFunctions: true, accept: isHttpMethod });
+}
+
+function isHttpMethod(name: string): boolean {
+  return (HTTP_METHODS as readonly string[]).includes(name);
+}
+
+/** Every exported HTTP handler across all route files under `appDir`. */
+export function collectRouteMethods(appDir: string, webRoot: string): RouteMethod[] {
+  return walkRouteFiles(appDir).flatMap((file) => {
+    const urlPath = urlPathOf(file, appDir);
+    return exportedMethodsOf(readFileSync(file, "utf8")).map((method) => ({
+      urlPath,
+      method,
+      file: relative(webRoot, file),
+    }));
+  });
+}

package/src/generate/index.ts

@@ -0,0 +1,197 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { generateTools, type OpenApiDocument } from "../openapi/generate";
+import { buildManifest, serializeManifest } from "../server/manifest";
+import {
+  serializeSurfaceLock,
+  surfaceDigest,
+  surfaceLockProblem,
+  type SurfaceLock,
+} from "../server/surface-lock";
+import type { ToolManifest } from "../types";
+
+/**
+ * `@12-apps/mcp/generate` — the `mcp:generate` / `mcp:check` gate (12-23), moved
+ * out of future-pay's `apps/web/scripts/mcp/generate.ts` so a host's own script is
+ * a one-line call and `12-apps/ci`'s `mcp-contract.yml`, which shells out to the
+ * consumer's `mcp:check` package script, keeps working unchanged.
+ *
+ * It renders the committed surface artifacts from the host's OpenAPI document:
+ *
+ *   openapi.json      — the document itself, canonicalized
+ *   manifest.json     — the MCP tool manifest generated from it
+ *   surface-lock.json — which surface the current version stands for
+ *
+ * With `check: true` it regenerates IN MEMORY and fails on any drift — the same
+ * command CI runs, so a forgotten regeneration is a red build rather than a tool
+ * list that silently disagrees with the endpoints.
+ *
+ * It ALSO refuses, in both modes, to emit a tool surface that changed while the
+ * advertised VERSION did not. That version is the only signal a connected host has
+ * that `tools/list` is worth re-reading, so a shipped tool behind an unmoved
+ * version is invisible to every client that already cached it — and "remember to
+ * bump it" as a comment is not a rule (see `server/surface-lock.ts`).
+ */
+
+/** One extra artifact a host renders from the same manifest, e.g. a store submission. */
+export interface McpExtraArtifact {
+  /** Absolute path of the committed file. */
+  path: string;
+  /** Rendered text, INCLUDING its trailing newline (compared byte for byte). */
+  render: (manifest: ToolManifest) => string;
+}
+
+export interface McpGenerateOptions {
+  /**
+   * The host's OpenAPI document, or a thunk producing it. A thunk is the useful
+   * form: building it usually evaluates a Zod registry, and `--check` should pay
+   * that cost once, when it runs.
+   */
+  document: OpenApiDocument | (() => OpenApiDocument);
+  /**
+   * The advertised surface version — the number a client is handed on `initialize`
+   * and caches `tools/list` against.
+   */
+  version: number;
+  /** Human label for the spec the tools were generated from. */
+  source: string;
+  /**
+   * Where the host's version constant lives, repo-relative — quoted verbatim in
+   * the surface-lock failure, so the fix is a path and a value rather than a hunt.
+   */
+  versionLocation: string;
+  /** The constant's name, if the host does not call it `MCP_SURFACE_VERSION`. */
+  versionName?: string;
+  /** Where the three artifacts are committed. */
+  outputs: {
+    openapi: string;
+    manifest: string;
+    surfaceLock: string;
+  };
+  /** Anything else the host commits from the same manifest. */
+  extraArtifacts?: readonly McpExtraArtifact[];
+}
+
+/** The rendered text of every artifact, keyed by its committed path. */
+export type RenderedArtifacts = Map<string, string>;
+
+export interface McpGenerateResult {
+  artifacts: RenderedArtifacts;
+  /** Non-null when the surface moved without a version bump — the message to print. */
+  surfaceProblem: string | null;
+}
+
+function readOrEmpty(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function readSurfaceLock(path: string): SurfaceLock | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as SurfaceLock;
+  } catch {
+    // No lock committed yet — there is nothing to contradict.
+    return null;
+  }
+}
+
+/**
+ * Render every artifact from the document. Pure: nothing is written and nothing is
+ * compared, so a caller can diff, print or discard the result.
+ */
+export function renderMcpArtifacts(options: McpGenerateOptions): McpGenerateResult {
+  const document =
+    typeof options.document === "function" ? options.document() : options.document;
+  const tools = generateTools(document);
+
+  // Before anything is written or compared: does this version still stand for this
+  // surface? The digest is of what `tools/list` would actually return, which is
+  // neither over- nor under-sensitive the way a paths filter on the registry's
+  // source tree is in both directions.
+  const digest = surfaceDigest(tools, options.source);
+  const surfaceProblem = surfaceLockProblem({
+    previous: readSurfaceLock(options.outputs.surfaceLock),
+    version: options.version,
+    digest,
+    versionLocation: options.versionLocation,
+    ...(options.versionName ? { versionName: options.versionName } : {}),
+  });
+
+  const manifestValue = buildManifest(tools, {
+    version: options.version,
+    source: options.source,
+  });
+
+  const artifacts: RenderedArtifacts = new Map([
+    [options.outputs.openapi, `${JSON.stringify(document, null, 2)}\n`],
+    [options.outputs.manifest, serializeManifest(manifestValue)],
+    [
+      options.outputs.surfaceLock,
+      serializeSurfaceLock({ version: options.version, digest }),
+    ],
+  ]);
+  for (const extra of options.extraArtifacts ?? []) {
+    artifacts.set(extra.path, extra.render(manifestValue));
+  }
+
+  return { artifacts, surfaceProblem };
+}
+
+/** Every artifact whose committed text differs from a fresh render. */
+export function mcpArtifactDrift(artifacts: RenderedArtifacts): string[] {
+  return [...artifacts.entries()]
+    .filter(([path, rendered]) => readOrEmpty(path) !== rendered)
+    .map(([path]) => path);
+}
+
+/** Write every artifact, creating directories as needed. */
+export function writeMcpArtifacts(artifacts: RenderedArtifacts): void {
+  for (const [path, contents] of artifacts) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents);
+  }
+}
+
+export interface McpGenerateCliOptions extends McpGenerateOptions {
+  /** `true` for `mcp:check` (verify only), `false` for `mcp:generate` (write). */
+  check: boolean;
+  /** The command to suggest on drift. Default: `pnpm mcp:generate`. */
+  regenerateCommand?: string;
+}
+
+/**
+ * The CLI face: render, then either verify or write, printing the verdict and
+ * exiting non-zero on any failure. A host's `scripts/mcp/generate.ts` becomes an
+ * import, its document builder, and one call.
+ */
+export function mcpGenerateCli(options: McpGenerateCliOptions): void {
+  const { artifacts, surfaceProblem } = renderMcpArtifacts(options);
+
+  if (surfaceProblem) {
+    // Exits rather than throws so the message IS the whole output — it names the
+    // number to change and where, which is the entire point of failing here
+    // instead of leaving it to review.
+    console.error(`[mcp:surface] ${surfaceProblem}`);
+    process.exit(1);
+  }
+
+  if (options.check) {
+    const drift = mcpArtifactDrift(artifacts);
+    if (drift.length > 0) {
+      console.error(
+        `[mcp:check] drift in: ${drift.join(", ")}.\n` +
+          `Run \`${options.regenerateCommand ?? "pnpm mcp:generate"}\` and commit the result.`,
+      );
+      process.exit(1);
+    }
+    console.log("[mcp:check] MCP surface is in sync with the OpenAPI registry.");
+    return;
+  }
+
+  writeMcpArtifacts(artifacts);
+  console.log(`[mcp:generate] wrote ${[...artifacts.keys()].join(", ")}`);
+}