@12-apps/mcp 3.3.0 → 3.5.0

package/dist/coverage-gate/index.d.ts

@@ -96,6 +96,15 @@ interface McpCoverageExclusions {
 interface McpActionMap {
     mapped: Record<string, string>;
 }
+/**
+ * A route served WITHOUT a route file — declared by an adopted package's
+ * wiring manifest and registered wholesale from the assembled aggregate.
+ * `{param}`-form path, the same grammar the filesystem scan yields.
+ */
+interface DeclaredRouteMethod {
+    method: string;
+    path: string;
+}
 interface McpCoverageOptions {
     /** The framework routes folder (the WHOLE `app`, never `app/api`). */
     appDir: string;
@@ -103,6 +112,14 @@ interface McpCoverageOptions {
     webRoot?: string;
     /** The host's registry entries (its `endpoints` array). */
     endpoints: readonly McpRegistryEndpoint[];
+    /**
+     * Routes with no file behind them, declared by wiring manifests. Each
+     * feeds BOTH directions of the route check: it must be registered like
+     * any scanned method, and it lets a registry entry count as served. A
+     * declared method duplicating a scanned file's method is refused — one
+     * URL, one source of truth.
+     */
+    declaredRoutes?: readonly DeclaredRouteMethod[];
     /** Path to the exclusions JSON ({@link McpCoverageExclusions}). */
     exclusionsPath: string;
     /**
@@ -126,4 +143,4 @@ declare function runMcpCoverage(options: McpCoverageOptions): McpCoverageResult;
  */
 declare function mcpCoverageCli(options: McpCoverageOptions): void;
 
-export { HTTP_METHODS, type McpActionMap, type McpCoverageExclusions, type McpCoverageOptions, type McpCoverageResult, type McpRegistryEndpoint, type RouteMethod, collectRouteMethods, exportedMethodsOf, mcpCoverageCli, runMcpCoverage };
+export { type DeclaredRouteMethod, HTTP_METHODS, type McpActionMap, type McpCoverageExclusions, type McpCoverageOptions, type McpCoverageResult, type McpRegistryEndpoint, type RouteMethod, collectRouteMethods, exportedMethodsOf, mcpCoverageCli, runMcpCoverage };

package/dist/coverage-gate/index.js

@@ -47,7 +47,24 @@ __name(readJson, "readJson");
 function routeFailures(ctx) {
   const failures = [];
   const infraPrefixes = Object.keys(ctx.exclusions.routes);
-  const routeMethods = collectRouteMethods(ctx.appDir, ctx.webRoot);
+  const scanned = collectRouteMethods(ctx.appDir, ctx.webRoot);
+  const scannedKeys = new Set(scanned.map(({ method, urlPath }) => `${method} ${urlPath}`));
+  for (const declared of ctx.declaredRoutes) {
+    const key = `${declared.method.toUpperCase()} ${declared.path}`;
+    if (scannedKeys.has(key)) {
+      failures.push(
+        `declared route shadows a route file: ${key} \u2014 delete the file or drop the declaration`
+      );
+    }
+  }
+  const routeMethods = [
+    ...scanned,
+    ...ctx.declaredRoutes.map((declared) => ({
+      urlPath: declared.path,
+      method: declared.method.toUpperCase(),
+      file: "<declared by a wiring manifest>"
+    }))
+  ];
   const registered = new Set(
     ctx.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()} ${endpoint.path}`)
   );
@@ -130,7 +147,8 @@ function runMcpCoverage(options) {
     webRoot: options.webRoot ?? options.appDir,
     endpoints: options.endpoints,
     exclusions: readJson(options.exclusionsPath),
-    actionMap: options.actionMapPath ? readJson(options.actionMapPath) : null
+    actionMap: options.actionMapPath ? readJson(options.actionMapPath) : null,
+    declaredRoutes: options.declaredRoutes ?? []
   };
   const routes = routeFailures(ctx);
   const actions = actionFailures(ctx);

package/dist/coverage-gate/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/coverage-gate/index.ts","../../src/coverage-gate/route-methods.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\n\nimport { exportedActionsOf, segmentPrefixMatch, walkActionFiles } from \"@12-apps/rbac/coverage\";\n\nimport { collectRouteMethods } from \"./route-methods\";\n\n/**\n * `@12-apps/mcp/coverage` — the MCP route/action coverage gate (12-23), moved out\n * of the origin host's `apps/web/scripts/mcp/coverage.ts` so a host's own script is a\n * one-line re-export and the CI workflow that shells out to the consumer's\n * `mcp:coverage` package script (`12-apps/ci`'s `mcp-contract.yml`) keeps working\n * unchanged.\n *\n * `mcp:check` only proves the REGISTRY matches the committed manifest; nothing\n * stops a new route file, or a new server action, from shipping outside the\n * agent-exposable surface. This gate closes both:\n *\n *  1. **Route coverage** — every HTTP method exported by a route file must be\n *     registered in the host's MCP registry (or its path listed under `routes` in\n *     the exclusions file), and every registry entry must map back to a real route\n *     file exporting that method. A tool the manifest advertises but no route\n *     serves is a promise an agent cannot cash.\n *  2. **Action coverage** — every exported server action must be mapped to a\n *     registry operationId in the action map, or listed under `actions` in the\n *     exclusions file with a reason. New actions fail until mapped; stale entries\n *     fail until pruned, so neither file can rot.\n *\n * The exclusions file is the ONLY escape hatch, and keeping it a separate,\n * human-protected file is the point: an agent cannot silently exclude a new\n * route/action — it has to justify to a human why the capability is not exposed.\n */\n\n/** One registry entry, as the host's MCP registry describes an endpoint. */\nexport interface McpRegistryEndpoint {\n  method: string;\n  /** URL path in `{param}` form — the same shape the scan produces. */\n  path: string;\n  operationId: string;\n}\n\n/** The protected exclusions file: every deliberate gate escape hatch. */\nexport interface McpCoverageExclusions {\n  /** Server actions kept off the surface, name → reason. */\n  actions: Record<string, string>;\n  /** Route path prefixes kept off the surface, prefix → reason. */\n  routes: Record<string, string>;\n}\n\n/** The action map: server action name → registry operationId. */\nexport interface McpActionMap {\n  mapped: Record<string, string>;\n}\n\nexport interface McpCoverageOptions {\n  /** The framework routes folder (the WHOLE `app`, never `app/api`). */\n  appDir: string;\n  /** Root for relative paths in failure messages. Default: `appDir`. */\n  webRoot?: string;\n  /** The host's registry entries (its `endpoints` array). */\n  endpoints: readonly McpRegistryEndpoint[];\n  /** Path to the exclusions JSON ({@link McpCoverageExclusions}). */\n  exclusionsPath: string;\n  /**\n   * Path to the action-map JSON ({@link McpActionMap}). Omit for a host with no\n   * server actions at all — action coverage is then vacuous rather than a crash on\n   * a file that was never written.\n   */\n  actionMapPath?: string;\n}\n\nexport interface McpCoverageResult {\n  failures: string[];\n  routeMethodCount: number;\n  actionCount: number;\n}\n\ninterface GateContext {\n  appDir: string;\n  webRoot: string;\n  endpoints: readonly McpRegistryEndpoint[];\n  exclusions: McpCoverageExclusions;\n  actionMap: McpActionMap | null;\n}\n\nfunction readJson<T>(path: string): T {\n  return JSON.parse(readFileSync(path, \"utf8\")) as T;\n}\n\n/** Route coverage — every served method registered, every registry entry served. */\nfunction routeFailures(ctx: GateContext): { failures: string[]; routeMethodCount: number } {\n  const failures: string[] = [];\n  const infraPrefixes = Object.keys(ctx.exclusions.routes);\n  const routeMethods = collectRouteMethods(ctx.appDir, ctx.webRoot);\n  const registered = new Set(\n    ctx.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()} ${endpoint.path}`),\n  );\n\n  // NOTE which way this loop fails, because it is the opposite of the instinct a\n  // gate invites: a method the SCAN misses is simply absent from `covered`, so no\n  // violation is raised at all and that route ships unregistered. Under-detection\n  // here is fail-OPEN — which is why `exportedNamesOf` blanks comments and strings\n  // before it looks for an export head instead of trusting raw source. (The loop\n  // after this one is the merely noisy half: a REGISTERED entry whose route was\n  // missed reports `registry entry without a route`.)\n  const covered = routeMethods.filter(({ urlPath }) => !segmentPrefixMatch(urlPath, infraPrefixes));\n  for (const { urlPath, method, file } of covered) {\n    if (!registered.has(`${method} ${urlPath}`)) {\n      failures.push(\n        `unregistered route: ${method} ${urlPath} (${file}) — add a registry entry, or ` +\n          `(human-authorized, for infra only) a routes prefix in the exclusions file`,\n      );\n    }\n  }\n\n  const served = new Set(\n    routeMethods.map(({ method, urlPath }) => `${method} ${urlPath}`),\n  );\n  for (const endpoint of ctx.endpoints) {\n    if (!served.has(`${endpoint.method.toUpperCase()} ${endpoint.path}`)) {\n      failures.push(\n        `registry entry without a route: ${endpoint.operationId} ` +\n          `(${endpoint.method.toUpperCase()} ${endpoint.path}) — the manifest advertises a tool no route serves`,\n      );\n    }\n  }\n\n  return { failures, routeMethodCount: covered.length };\n}\n\n/**\n * Every action the host actually exports must be accounted for — mapped to a\n * registry operationId, or excluded with a reason. Neither silently.\n */\nfunction unaccountedActions(\n  ctx: GateContext,\n  actions: Set<string>,\n  mapped: Record<string, string>,\n): string[] {\n  const failures: string[] = [];\n  for (const action of actions) {\n    const isMapped = action in mapped;\n    const isExcluded = action in ctx.exclusions.actions;\n    if (!isMapped && !isExcluded) {\n      failures.push(\n        `unmapped server action: ${action} — map it to a registry operationId in the action ` +\n          `map, or (human-authorized) add it to the exclusions file with a reason`,\n      );\n    }\n    if (isMapped && isExcluded) {\n      failures.push(\n        `action both mapped and excluded: ${action} — remove it from one of the two files`,\n      );\n    }\n  }\n  return failures;\n}\n\n/**\n * The other direction, and the one that keeps both files from rotting: an entry\n * naming an action that no longer exists, or an operationId the registry does not\n * have. Adding the mapping is never enough — a stale line must go.\n */\nfunction staleActionEntries(\n  ctx: GateContext,\n  actions: Set<string>,\n  mapped: Record<string, string>,\n): string[] {\n  const failures: string[] = [];\n  const operationIds = new Set(ctx.endpoints.map((endpoint) => endpoint.operationId));\n  for (const [action, operationId] of Object.entries(mapped)) {\n    if (!actions.has(action)) {\n      failures.push(`stale action-map entry: ${action} — the action no longer exists`);\n    }\n    if (!operationIds.has(operationId)) {\n      failures.push(`action-map points at unknown operationId: ${action} → ${operationId}`);\n    }\n  }\n  for (const action of Object.keys(ctx.exclusions.actions)) {\n    if (!actions.has(action)) {\n      failures.push(`stale action exclusion: ${action} — the action no longer exists`);\n    }\n  }\n  return failures;\n}\n\n/** Action coverage — every action mapped or excluded, and neither file stale. */\nfunction actionFailures(ctx: GateContext): { failures: string[]; actionCount: number } {\n  const mapped = ctx.actionMap?.mapped ?? {};\n  const actions = new Set(\n    walkActionFiles(ctx.appDir).flatMap((file) => exportedActionsOf(readFileSync(file, \"utf8\"))),\n  );\n\n  return {\n    failures: [\n      ...unaccountedActions(ctx, actions, mapped),\n      ...staleActionEntries(ctx, actions, mapped),\n    ],\n    actionCount: actions.size,\n  };\n}\n\n/** Run the gate and return every violation (empty = green). */\nexport function runMcpCoverage(options: McpCoverageOptions): McpCoverageResult {\n  const ctx: GateContext = {\n    appDir: options.appDir,\n    webRoot: options.webRoot ?? options.appDir,\n    endpoints: options.endpoints,\n    exclusions: readJson<McpCoverageExclusions>(options.exclusionsPath),\n    actionMap: options.actionMapPath ? readJson<McpActionMap>(options.actionMapPath) : null,\n  };\n  const routes = routeFailures(ctx);\n  const actions = actionFailures(ctx);\n  return {\n    failures: [...routes.failures, ...actions.failures],\n    routeMethodCount: routes.routeMethodCount,\n    actionCount: actions.actionCount,\n  };\n}\n\n/**\n * The CLI face: print the verdict and exit non-zero on violations. A host's\n * `scripts/mcp/coverage.ts` is then one import + one call, and the CI workflow that\n * runs `pnpm mcp:coverage` needs no change at all.\n */\nexport function mcpCoverageCli(options: McpCoverageOptions): void {\n  const { failures, routeMethodCount, actionCount } = runMcpCoverage(options);\n  if (failures.length > 0) {\n    console.error(`[mcp:coverage] ${failures.length} violation(s):`);\n    for (const failure of failures) console.error(`  ✗ ${failure}`);\n    process.exit(1);\n  }\n  console.log(\n    `[mcp:coverage] OK — ${routeMethodCount} route method(s) registered, ` +\n      `${actionCount} action(s) mapped/excluded.`,\n  );\n}\n\nexport {\n  collectRouteMethods,\n  exportedMethodsOf,\n  HTTP_METHODS,\n  type RouteMethod,\n} from \"./route-methods\";\n","import { readFileSync } from \"node:fs\";\nimport { relative } from \"node:path\";\n\nimport { exportedNamesOf, urlPathOf, walkRouteFiles } from \"@12-apps/rbac/coverage\";\n\n/**\n * The route-METHOD half of the surface scan (12-23) — what `mcp:coverage` needs\n * on top of what `rbac:coverage` already ships.\n *\n * The WALK is imported from `@12-apps/rbac/coverage` rather than copied — the file\n * walk (`walkRouteFiles`), the URL mapping (`urlPathOf`) AND the export-head\n * parser (`exportedNamesOf`) — and that is deliberate: both gates assert a\n * COMPLETENESS property over the same two surfaces (`app/**` route files and\n * `*actions.ts` modules), and the origin host's own comment on the shared scanner says\n * why they must share it — \"so the two gates can never disagree about what the\n * surface is\". Two copies would agree on the day they were written and drift\n * silently after, in the direction of not looking. What is left here is the one\n * thing that genuinely differs: the GRAMMAR (see {@link exportedMethodsOf}).\n *\n * THE SCAN ROOT IS THE WHOLE `app` FOLDER, never `app/api`: a completeness gate\n * rooted below the surface it claims to cover does not fail when it misses\n * something, it simply never looks. Three OAuth/JWKS discovery routes shipped\n * unregistered for exactly as long as the walk was rooted at `app/api`.\n *\n * Detection is over SOURCE, with no TS compiler: fast, dependency-free, and it\n * matches how the framework itself keys routes off file paths plus exported names.\n */\n\n/** Every method a route file can serve — the scan must see them all. */\nexport const HTTP_METHODS = [\n  \"GET\",\n  \"HEAD\",\n  \"POST\",\n  \"PUT\",\n  \"PATCH\",\n  \"DELETE\",\n  \"OPTIONS\",\n] as const;\n\n/** One exported HTTP handler discovered on a route file. */\nexport interface RouteMethod {\n  /** URL path with `[param]` → `{param}` (e.g. `/api/checkout/{id}`). */\n  urlPath: string;\n  /** The HTTP method exported (GET/POST/…). */\n  method: string;\n  /** The route file, relative to the web root. */\n  file: string;\n}\n\n/**\n * Exported HTTP methods, across every form the app router serves:\n * `export const GET`, `export function GET`, `export async function GET`,\n * `export const { GET, POST } = handlers`, `export { handler as GET }`. For brace\n * lists the exported name is the last identifier of each item (after `as`, or\n * after `:` for destructuring renames). `export type { … }` never matches — a type\n * is never a handler.\n *\n * The two grammar knobs are the whole difference from `exportedActionsOf`, and both\n * are load-bearing: a route handler may be a SYNC `export function` (a server\n * action may not — it must be async), and only the seven HTTP methods count, where\n * every runtime export of a use-server module is an action.\n *\n * The shared walk is a linear hand-parse, not a regex: the `\\s+`-joined patterns\n * this gate first shipped with backtracked polynomially on adversarial input\n * (CodeQL js/polynomial-redos), and a COMPLETENESS gate must stay O(n) on whatever\n * source it is pointed at — it is run over files a contributor supplies.\n */\nexport function exportedMethodsOf(source: string): string[] {\n  return exportedNamesOf(source, { syncFunctions: true, accept: isHttpMethod });\n}\n\nfunction isHttpMethod(name: string): boolean {\n  return (HTTP_METHODS as readonly string[]).includes(name);\n}\n\n/** Every exported HTTP handler across all route files under `appDir`. */\nexport function collectRouteMethods(appDir: string, webRoot: string): RouteMethod[] {\n  return walkRouteFiles(appDir).flatMap((file) => {\n    const urlPath = urlPathOf(file, appDir);\n    return exportedMethodsOf(readFileSync(file, \"utf8\")).map((method) => ({\n      urlPath,\n      method,\n      file: relative(webRoot, file),\n    }));\n  });\n}\n"],"mappings":"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","names":["readFileSync","readFileSync"]}
+{"version":3,"sources":["../../src/coverage-gate/index.ts","../../src/coverage-gate/route-methods.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\n\nimport { exportedActionsOf, segmentPrefixMatch, walkActionFiles } from \"@12-apps/rbac/coverage\";\n\nimport { collectRouteMethods } from \"./route-methods\";\n\n/**\n * `@12-apps/mcp/coverage` — the MCP route/action coverage gate (12-23), moved out\n * of the origin host's `apps/web/scripts/mcp/coverage.ts` so a host's own script is a\n * one-line re-export and the CI workflow that shells out to the consumer's\n * `mcp:coverage` package script (`12-apps/ci`'s `mcp-contract.yml`) keeps working\n * unchanged.\n *\n * `mcp:check` only proves the REGISTRY matches the committed manifest; nothing\n * stops a new route file, or a new server action, from shipping outside the\n * agent-exposable surface. This gate closes both:\n *\n *  1. **Route coverage** — every HTTP method exported by a route file must be\n *     registered in the host's MCP registry (or its path listed under `routes` in\n *     the exclusions file), and every registry entry must map back to a real route\n *     file exporting that method. A tool the manifest advertises but no route\n *     serves is a promise an agent cannot cash.\n *  2. **Action coverage** — every exported server action must be mapped to a\n *     registry operationId in the action map, or listed under `actions` in the\n *     exclusions file with a reason. New actions fail until mapped; stale entries\n *     fail until pruned, so neither file can rot.\n *\n * The exclusions file is the ONLY escape hatch, and keeping it a separate,\n * human-protected file is the point: an agent cannot silently exclude a new\n * route/action — it has to justify to a human why the capability is not exposed.\n */\n\n/** One registry entry, as the host's MCP registry describes an endpoint. */\nexport interface McpRegistryEndpoint {\n  method: string;\n  /** URL path in `{param}` form — the same shape the scan produces. */\n  path: string;\n  operationId: string;\n}\n\n/** The protected exclusions file: every deliberate gate escape hatch. */\nexport interface McpCoverageExclusions {\n  /** Server actions kept off the surface, name → reason. */\n  actions: Record<string, string>;\n  /** Route path prefixes kept off the surface, prefix → reason. */\n  routes: Record<string, string>;\n}\n\n/** The action map: server action name → registry operationId. */\nexport interface McpActionMap {\n  mapped: Record<string, string>;\n}\n\n/**\n * A route served WITHOUT a route file — declared by an adopted package's\n * wiring manifest and registered wholesale from the assembled aggregate.\n * `{param}`-form path, the same grammar the filesystem scan yields.\n */\nexport interface DeclaredRouteMethod {\n  method: string;\n  path: string;\n}\n\nexport interface McpCoverageOptions {\n  /** The framework routes folder (the WHOLE `app`, never `app/api`). */\n  appDir: string;\n  /** Root for relative paths in failure messages. Default: `appDir`. */\n  webRoot?: string;\n  /** The host's registry entries (its `endpoints` array). */\n  endpoints: readonly McpRegistryEndpoint[];\n  /**\n   * Routes with no file behind them, declared by wiring manifests. Each\n   * feeds BOTH directions of the route check: it must be registered like\n   * any scanned method, and it lets a registry entry count as served. A\n   * declared method duplicating a scanned file's method is refused — one\n   * URL, one source of truth.\n   */\n  declaredRoutes?: readonly DeclaredRouteMethod[];\n  /** Path to the exclusions JSON ({@link McpCoverageExclusions}). */\n  exclusionsPath: string;\n  /**\n   * Path to the action-map JSON ({@link McpActionMap}). Omit for a host with no\n   * server actions at all — action coverage is then vacuous rather than a crash on\n   * a file that was never written.\n   */\n  actionMapPath?: string;\n}\n\nexport interface McpCoverageResult {\n  failures: string[];\n  routeMethodCount: number;\n  actionCount: number;\n}\n\ninterface GateContext {\n  appDir: string;\n  webRoot: string;\n  endpoints: readonly McpRegistryEndpoint[];\n  exclusions: McpCoverageExclusions;\n  actionMap: McpActionMap | null;\n  declaredRoutes: readonly DeclaredRouteMethod[];\n}\n\nfunction readJson<T>(path: string): T {\n  return JSON.parse(readFileSync(path, \"utf8\")) as T;\n}\n\n/** Route coverage — every served method registered, every registry entry served. */\nfunction routeFailures(ctx: GateContext): { failures: string[]; routeMethodCount: number } {\n  const failures: string[] = [];\n  const infraPrefixes = Object.keys(ctx.exclusions.routes);\n  const scanned = collectRouteMethods(ctx.appDir, ctx.webRoot);\n  // Declared routes join the scanned set on equal footing: registered like\n  // any method (direction 1), serving their registry entries (direction 2).\n  // A declaration duplicating a scanned method is two sources of truth for\n  // one URL — refused here, not silently deduplicated.\n  const scannedKeys = new Set(scanned.map(({ method, urlPath }) => `${method} ${urlPath}`));\n  for (const declared of ctx.declaredRoutes) {\n    const key = `${declared.method.toUpperCase()} ${declared.path}`;\n    if (scannedKeys.has(key)) {\n      failures.push(\n        `declared route shadows a route file: ${key} — delete the file or drop the declaration`,\n      );\n    }\n  }\n  const routeMethods = [\n    ...scanned,\n    ...ctx.declaredRoutes.map((declared) => ({\n      urlPath: declared.path,\n      method: declared.method.toUpperCase(),\n      file: \"<declared by a wiring manifest>\",\n    })),\n  ];\n  const registered = new Set(\n    ctx.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()} ${endpoint.path}`),\n  );\n\n  // NOTE which way this loop fails, because it is the opposite of the instinct a\n  // gate invites: a method the SCAN misses is simply absent from `covered`, so no\n  // violation is raised at all and that route ships unregistered. Under-detection\n  // here is fail-OPEN — which is why `exportedNamesOf` blanks comments and strings\n  // before it looks for an export head instead of trusting raw source. (The loop\n  // after this one is the merely noisy half: a REGISTERED entry whose route was\n  // missed reports `registry entry without a route`.)\n  const covered = routeMethods.filter(({ urlPath }) => !segmentPrefixMatch(urlPath, infraPrefixes));\n  for (const { urlPath, method, file } of covered) {\n    if (!registered.has(`${method} ${urlPath}`)) {\n      failures.push(\n        `unregistered route: ${method} ${urlPath} (${file}) — add a registry entry, or ` +\n          `(human-authorized, for infra only) a routes prefix in the exclusions file`,\n      );\n    }\n  }\n\n  const served = new Set(\n    routeMethods.map(({ method, urlPath }) => `${method} ${urlPath}`),\n  );\n  for (const endpoint of ctx.endpoints) {\n    if (!served.has(`${endpoint.method.toUpperCase()} ${endpoint.path}`)) {\n      failures.push(\n        `registry entry without a route: ${endpoint.operationId} ` +\n          `(${endpoint.method.toUpperCase()} ${endpoint.path}) — the manifest advertises a tool no route serves`,\n      );\n    }\n  }\n\n  return { failures, routeMethodCount: covered.length };\n}\n\n/**\n * Every action the host actually exports must be accounted for — mapped to a\n * registry operationId, or excluded with a reason. Neither silently.\n */\nfunction unaccountedActions(\n  ctx: GateContext,\n  actions: Set<string>,\n  mapped: Record<string, string>,\n): string[] {\n  const failures: string[] = [];\n  for (const action of actions) {\n    const isMapped = action in mapped;\n    const isExcluded = action in ctx.exclusions.actions;\n    if (!isMapped && !isExcluded) {\n      failures.push(\n        `unmapped server action: ${action} — map it to a registry operationId in the action ` +\n          `map, or (human-authorized) add it to the exclusions file with a reason`,\n      );\n    }\n    if (isMapped && isExcluded) {\n      failures.push(\n        `action both mapped and excluded: ${action} — remove it from one of the two files`,\n      );\n    }\n  }\n  return failures;\n}\n\n/**\n * The other direction, and the one that keeps both files from rotting: an entry\n * naming an action that no longer exists, or an operationId the registry does not\n * have. Adding the mapping is never enough — a stale line must go.\n */\nfunction staleActionEntries(\n  ctx: GateContext,\n  actions: Set<string>,\n  mapped: Record<string, string>,\n): string[] {\n  const failures: string[] = [];\n  const operationIds = new Set(ctx.endpoints.map((endpoint) => endpoint.operationId));\n  for (const [action, operationId] of Object.entries(mapped)) {\n    if (!actions.has(action)) {\n      failures.push(`stale action-map entry: ${action} — the action no longer exists`);\n    }\n    if (!operationIds.has(operationId)) {\n      failures.push(`action-map points at unknown operationId: ${action} → ${operationId}`);\n    }\n  }\n  for (const action of Object.keys(ctx.exclusions.actions)) {\n    if (!actions.has(action)) {\n      failures.push(`stale action exclusion: ${action} — the action no longer exists`);\n    }\n  }\n  return failures;\n}\n\n/** Action coverage — every action mapped or excluded, and neither file stale. */\nfunction actionFailures(ctx: GateContext): { failures: string[]; actionCount: number } {\n  const mapped = ctx.actionMap?.mapped ?? {};\n  const actions = new Set(\n    walkActionFiles(ctx.appDir).flatMap((file) => exportedActionsOf(readFileSync(file, \"utf8\"))),\n  );\n\n  return {\n    failures: [\n      ...unaccountedActions(ctx, actions, mapped),\n      ...staleActionEntries(ctx, actions, mapped),\n    ],\n    actionCount: actions.size,\n  };\n}\n\n/** Run the gate and return every violation (empty = green). */\nexport function runMcpCoverage(options: McpCoverageOptions): McpCoverageResult {\n  const ctx: GateContext = {\n    appDir: options.appDir,\n    webRoot: options.webRoot ?? options.appDir,\n    endpoints: options.endpoints,\n    exclusions: readJson<McpCoverageExclusions>(options.exclusionsPath),\n    actionMap: options.actionMapPath ? readJson<McpActionMap>(options.actionMapPath) : null,\n    declaredRoutes: options.declaredRoutes ?? [],\n  };\n  const routes = routeFailures(ctx);\n  const actions = actionFailures(ctx);\n  return {\n    failures: [...routes.failures, ...actions.failures],\n    routeMethodCount: routes.routeMethodCount,\n    actionCount: actions.actionCount,\n  };\n}\n\n/**\n * The CLI face: print the verdict and exit non-zero on violations. A host's\n * `scripts/mcp/coverage.ts` is then one import + one call, and the CI workflow that\n * runs `pnpm mcp:coverage` needs no change at all.\n */\nexport function mcpCoverageCli(options: McpCoverageOptions): void {\n  const { failures, routeMethodCount, actionCount } = runMcpCoverage(options);\n  if (failures.length > 0) {\n    console.error(`[mcp:coverage] ${failures.length} violation(s):`);\n    for (const failure of failures) console.error(`  ✗ ${failure}`);\n    process.exit(1);\n  }\n  console.log(\n    `[mcp:coverage] OK — ${routeMethodCount} route method(s) registered, ` +\n      `${actionCount} action(s) mapped/excluded.`,\n  );\n}\n\nexport {\n  collectRouteMethods,\n  exportedMethodsOf,\n  HTTP_METHODS,\n  type RouteMethod,\n} from \"./route-methods\";\n","import { readFileSync } from \"node:fs\";\nimport { relative } from \"node:path\";\n\nimport { exportedNamesOf, urlPathOf, walkRouteFiles } from \"@12-apps/rbac/coverage\";\n\n/**\n * The route-METHOD half of the surface scan (12-23) — what `mcp:coverage` needs\n * on top of what `rbac:coverage` already ships.\n *\n * The WALK is imported from `@12-apps/rbac/coverage` rather than copied — the file\n * walk (`walkRouteFiles`), the URL mapping (`urlPathOf`) AND the export-head\n * parser (`exportedNamesOf`) — and that is deliberate: both gates assert a\n * COMPLETENESS property over the same two surfaces (`app/**` route files and\n * `*actions.ts` modules), and the origin host's own comment on the shared scanner says\n * why they must share it — \"so the two gates can never disagree about what the\n * surface is\". Two copies would agree on the day they were written and drift\n * silently after, in the direction of not looking. What is left here is the one\n * thing that genuinely differs: the GRAMMAR (see {@link exportedMethodsOf}).\n *\n * THE SCAN ROOT IS THE WHOLE `app` FOLDER, never `app/api`: a completeness gate\n * rooted below the surface it claims to cover does not fail when it misses\n * something, it simply never looks. Three OAuth/JWKS discovery routes shipped\n * unregistered for exactly as long as the walk was rooted at `app/api`.\n *\n * Detection is over SOURCE, with no TS compiler: fast, dependency-free, and it\n * matches how the framework itself keys routes off file paths plus exported names.\n */\n\n/** Every method a route file can serve — the scan must see them all. */\nexport const HTTP_METHODS = [\n  \"GET\",\n  \"HEAD\",\n  \"POST\",\n  \"PUT\",\n  \"PATCH\",\n  \"DELETE\",\n  \"OPTIONS\",\n] as const;\n\n/** One exported HTTP handler discovered on a route file. */\nexport interface RouteMethod {\n  /** URL path with `[param]` → `{param}` (e.g. `/api/checkout/{id}`). */\n  urlPath: string;\n  /** The HTTP method exported (GET/POST/…). */\n  method: string;\n  /** The route file, relative to the web root. */\n  file: string;\n}\n\n/**\n * Exported HTTP methods, across every form the app router serves:\n * `export const GET`, `export function GET`, `export async function GET`,\n * `export const { GET, POST } = handlers`, `export { handler as GET }`. For brace\n * lists the exported name is the last identifier of each item (after `as`, or\n * after `:` for destructuring renames). `export type { … }` never matches — a type\n * is never a handler.\n *\n * The two grammar knobs are the whole difference from `exportedActionsOf`, and both\n * are load-bearing: a route handler may be a SYNC `export function` (a server\n * action may not — it must be async), and only the seven HTTP methods count, where\n * every runtime export of a use-server module is an action.\n *\n * The shared walk is a linear hand-parse, not a regex: the `\\s+`-joined patterns\n * this gate first shipped with backtracked polynomially on adversarial input\n * (CodeQL js/polynomial-redos), and a COMPLETENESS gate must stay O(n) on whatever\n * source it is pointed at — it is run over files a contributor supplies.\n */\nexport function exportedMethodsOf(source: string): string[] {\n  return exportedNamesOf(source, { syncFunctions: true, accept: isHttpMethod });\n}\n\nfunction isHttpMethod(name: string): boolean {\n  return (HTTP_METHODS as readonly string[]).includes(name);\n}\n\n/** Every exported HTTP handler across all route files under `appDir`. */\nexport function collectRouteMethods(appDir: string, webRoot: string): RouteMethod[] {\n  return walkRouteFiles(appDir).flatMap((file) => {\n    const urlPath = urlPathOf(file, appDir);\n    return exportedMethodsOf(readFileSync(file, \"utf8\")).map((method) => ({\n      urlPath,\n      method,\n      file: relative(webRoot, file),\n    }));\n  });\n}\n"],"mappings":"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","names":["readFileSync","readFileSync"]}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { J as JsonSchema, G as GeneratedTool, D as DispatchConfig, a as DispatchResult, b as ToolAnnotations, R as RequestAuth, T as ToolManifest } from './generate-Dx3cK8th.js';
 export { A as AuthResolver, c as GenerateOptions, O as OpenApiDocument, d as OpenApiOperation, e as OpenApiParameter, f as OpenApiRequestBody, g as OpenApiResponse, P as ParameterLocation, h as ToolParameter, i as generateTools } from './generate-Dx3cK8th.js';
 export { A as AI_CAPABILITIES, a as AI_PERMISSION_MODEL, b as AiCapability, c as AiConnectPromptSpec, d as AiHostBrand, e as AiHostConfigureStage, f as AiHostGuide, g as AiHostLink, h as AiProvider, i as aiConnectPrompt, j as aiHostGuides, p as providerForHostId } from './guide-DV5MQbCg.js';
+import { z } from 'zod';
 
 /**
  * Raised when a JSON Schema cannot be turned into a flat, self-contained tool
@@ -23,6 +24,69 @@ declare class UnsupportedSchemaError extends Error {
  */
 declare function inlineSchemaRefs(schema: JsonSchema): JsonSchema;
 
+/**
+ * How a route is DECLARED, one step before it becomes an OpenAPI operation and
+ * two before it becomes a tool.
+ *
+ * This package already owns everything downstream of an OpenAPI document —
+ * `generateTools` turns operations into tools, `dispatchTool` proxies a call,
+ * `redactResponseSchema`/`redactResponseBody` narrow both halves. What it did
+ * not own was the shape a consumer writes its routes down in, so every consumer
+ * declared its own. That is fine for one app and wrong for several: a monorepo
+ * where the shift routes, the lifecycle routes and the audit routes are each
+ * packaged separately needs those packages to produce endpoint lists the HOST
+ * can concatenate, which they can only do if they all mean the same thing by
+ * "an endpoint".
+ *
+ * Deliberately zod-shaped rather than JSON-Schema-shaped. A route validates its
+ * input with zod at runtime; describing it a second time in JSON Schema is a
+ * copy that drifts, and the drift is invisible — the manifest keeps advertising
+ * the shape the route stopped accepting. Converting zod → JSON Schema at
+ * generate time makes the validator the single source of truth.
+ *
+ * zod is a PEER dependency: it is referenced here as a type only, so this
+ * package pulls no copy of its own and cannot end up type-checking against a
+ * different one than the consumer declares its schemas with.
+ */
+/** The methods an MCP-exposed route may use. */
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+interface McpEndpointBase {
+    /** Stable tool id — this becomes the MCP tool name, so renaming it is a
+     *  breaking change for every agent that has learned the old one. */
+    operationId: string;
+    method: HttpMethod;
+    /** OpenAPI path template, e.g. `/api/products/{id}`. */
+    path: string;
+    /** What the tool is FOR, in the words an agent reads when choosing it. */
+    summary: string;
+    tags?: string[];
+    /** Object schema whose properties become query parameters. */
+    query?: z.ZodType;
+    /** Object schema whose properties become path parameters. */
+    params?: z.ZodType;
+    /** Request body schema (writes only). */
+    body?: z.ZodType;
+}
+/**
+ * A declared endpoint either answers 200 with a schema'd JSON body (the
+ * default) or 204 No Content (fire-and-forget writes).
+ *
+ * The union is what makes the two mutually exclusive: a 204 entry cannot carry
+ * a response schema, so a manifest can never advertise a body its route will
+ * not send — a mismatch an agent experiences as a tool that returns nothing
+ * where its own schema promised an object.
+ */
+type McpEndpoint = McpEndpointBase & ({
+    /** Success status (defaults to 200 with a JSON body). */
+    status?: 200;
+    /** Success (200) response schema. */
+    response: z.ZodType;
+} | {
+    /** 204 No Content — no response schema. */
+    status: 204;
+    response?: never;
+});
+
 /** Raised when tool arguments cannot be routed onto the HTTP request. */
 declare class DispatchInputError extends Error {
     constructor(message: string);
@@ -404,4 +468,4 @@ interface AuthorizationServerMetadata {
  */
 declare function buildAuthorizationServerMetadata(input: AuthorizationServerMetadataInput): AuthorizationServerMetadata;
 
-export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, redactResponseBody, redactResponseSchema, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };
+export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type HttpMethod, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpEndpoint, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, redactResponseBody, redactResponseSchema, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
@@ -43,18 +43,19 @@
   },
   "dependencies": {
     "@12-apps/onboarding": "^2.0.1",
-    "@12-apps/rbac": "^4.0.2",
-    "@12-apps/ui": "^5.0.1",
+    "@12-apps/rbac": "^4.1.0",
+    "@12-apps/ui": "^6.0.1",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",
     "react": "^19.2.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
-    "hono": ">=4.0.0"
+    "hono": ">=4.0.0",
+    "zod": ">=4.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@mui/material": "^6.5.0",
     "@testing-library/react": "^16.1.0",
@@ -67,7 +68,8 @@
     "react-dom": "^19.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.3.5"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -103,6 +105,9 @@
   "peerDependenciesMeta": {
     "hono": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   }
 }

package/src/coverage-gate/index.ts

@@ -51,6 +51,16 @@ export interface McpActionMap {
   mapped: Record<string, string>;
 }
 
+/**
+ * A route served WITHOUT a route file — declared by an adopted package's
+ * wiring manifest and registered wholesale from the assembled aggregate.
+ * `{param}`-form path, the same grammar the filesystem scan yields.
+ */
+export interface DeclaredRouteMethod {
+  method: string;
+  path: string;
+}
+
 export interface McpCoverageOptions {
   /** The framework routes folder (the WHOLE `app`, never `app/api`). */
   appDir: string;
@@ -58,6 +68,14 @@ export interface McpCoverageOptions {
   webRoot?: string;
   /** The host's registry entries (its `endpoints` array). */
   endpoints: readonly McpRegistryEndpoint[];
+  /**
+   * Routes with no file behind them, declared by wiring manifests. Each
+   * feeds BOTH directions of the route check: it must be registered like
+   * any scanned method, and it lets a registry entry count as served. A
+   * declared method duplicating a scanned file's method is refused — one
+   * URL, one source of truth.
+   */
+  declaredRoutes?: readonly DeclaredRouteMethod[];
   /** Path to the exclusions JSON ({@link McpCoverageExclusions}). */
   exclusionsPath: string;
   /**
@@ -80,6 +98,7 @@ interface GateContext {
   endpoints: readonly McpRegistryEndpoint[];
   exclusions: McpCoverageExclusions;
   actionMap: McpActionMap | null;
+  declaredRoutes: readonly DeclaredRouteMethod[];
 }
 
 function readJson<T>(path: string): T {
@@ -90,7 +109,28 @@ function readJson<T>(path: string): T {
 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 scanned = collectRouteMethods(ctx.appDir, ctx.webRoot);
+  // Declared routes join the scanned set on equal footing: registered like
+  // any method (direction 1), serving their registry entries (direction 2).
+  // A declaration duplicating a scanned method is two sources of truth for
+  // one URL — refused here, not silently deduplicated.
+  const scannedKeys = new Set(scanned.map(({ method, urlPath }) => `${method} ${urlPath}`));
+  for (const declared of ctx.declaredRoutes) {
+    const key = `${declared.method.toUpperCase()} ${declared.path}`;
+    if (scannedKeys.has(key)) {
+      failures.push(
+        `declared route shadows a route file: ${key} — delete the file or drop the declaration`,
+      );
+    }
+  }
+  const routeMethods = [
+    ...scanned,
+    ...ctx.declaredRoutes.map((declared) => ({
+      urlPath: declared.path,
+      method: declared.method.toUpperCase(),
+      file: "<declared by a wiring manifest>",
+    })),
+  ];
   const registered = new Set(
     ctx.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()} ${endpoint.path}`),
   );
@@ -207,6 +247,7 @@ export function runMcpCoverage(options: McpCoverageOptions): McpCoverageResult {
     endpoints: options.endpoints,
     exclusions: readJson<McpCoverageExclusions>(options.exclusionsPath),
     actionMap: options.actionMapPath ? readJson<McpActionMap>(options.actionMapPath) : null,
+    declaredRoutes: options.declaredRoutes ?? [],
   };
   const routes = routeFailures(ctx);
   const actions = actionFailures(ctx);

package/src/index.ts

@@ -28,6 +28,11 @@ export {
 } from "./guide";
 export { generateTools } from "./openapi/generate";
 export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
+// The shape a route is DECLARED in, upstream of the OpenAPI document. It lives
+// here so that packages which own a domain can ship that domain's endpoints and
+// a host can concatenate them — which requires all of them to mean the same
+// thing by "an endpoint". See `openapi/endpoint.ts`.
+export type { McpEndpoint, HttpMethod } from "./openapi/endpoint";
 export type {
   OpenApiDocument,
   OpenApiOperation,

package/src/openapi/endpoint.ts

@@ -0,0 +1,71 @@
+import type { z } from "zod";
+
+/**
+ * How a route is DECLARED, one step before it becomes an OpenAPI operation and
+ * two before it becomes a tool.
+ *
+ * This package already owns everything downstream of an OpenAPI document —
+ * `generateTools` turns operations into tools, `dispatchTool` proxies a call,
+ * `redactResponseSchema`/`redactResponseBody` narrow both halves. What it did
+ * not own was the shape a consumer writes its routes down in, so every consumer
+ * declared its own. That is fine for one app and wrong for several: a monorepo
+ * where the shift routes, the lifecycle routes and the audit routes are each
+ * packaged separately needs those packages to produce endpoint lists the HOST
+ * can concatenate, which they can only do if they all mean the same thing by
+ * "an endpoint".
+ *
+ * Deliberately zod-shaped rather than JSON-Schema-shaped. A route validates its
+ * input with zod at runtime; describing it a second time in JSON Schema is a
+ * copy that drifts, and the drift is invisible — the manifest keeps advertising
+ * the shape the route stopped accepting. Converting zod → JSON Schema at
+ * generate time makes the validator the single source of truth.
+ *
+ * zod is a PEER dependency: it is referenced here as a type only, so this
+ * package pulls no copy of its own and cannot end up type-checking against a
+ * different one than the consumer declares its schemas with.
+ */
+
+/** The methods an MCP-exposed route may use. */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+
+interface McpEndpointBase {
+  /** Stable tool id — this becomes the MCP tool name, so renaming it is a
+   *  breaking change for every agent that has learned the old one. */
+  operationId: string;
+  method: HttpMethod;
+  /** OpenAPI path template, e.g. `/api/products/{id}`. */
+  path: string;
+  /** What the tool is FOR, in the words an agent reads when choosing it. */
+  summary: string;
+  tags?: string[];
+  /** Object schema whose properties become query parameters. */
+  query?: z.ZodType;
+  /** Object schema whose properties become path parameters. */
+  params?: z.ZodType;
+  /** Request body schema (writes only). */
+  body?: z.ZodType;
+}
+
+/**
+ * A declared endpoint either answers 200 with a schema'd JSON body (the
+ * default) or 204 No Content (fire-and-forget writes).
+ *
+ * The union is what makes the two mutually exclusive: a 204 entry cannot carry
+ * a response schema, so a manifest can never advertise a body its route will
+ * not send — a mismatch an agent experiences as a tool that returns nothing
+ * where its own schema promised an object.
+ */
+export type McpEndpoint = McpEndpointBase &
+  (
+    | {
+        /** Success status (defaults to 200 with a JSON body). */
+        status?: 200;
+        /** Success (200) response schema. */
+        response: z.ZodType;
+      }
+    | {
+        /** 204 No Content — no response schema. */
+        status: 204;
+        response?: never;
+      }
+  );