@nanobpm/urban 0.86.1 → 0.87.0

package/dist/openapi/spec.d.ts

@@ -53,6 +53,11 @@ export interface OpenApiParameter {
     in: "path" | "query" | "header" | "cookie";
     required?: boolean;
     schema?: OpenApiSchema;
+    /** The parameter's schema with every local component `$ref` inlined (via {@link resolveSchemaDeep}),
+     *  so a consumer that cannot resolve `#/components/...` — e.g. an MCP client reading the projected
+     *  tool `inputSchema` — sees a self-contained schema. Absent when the parameter declares no schema.
+     *  The raw {@link schema} is retained for the type deriver, which maps a `$ref` to its named type. */
+    resolvedSchema?: OpenApiSchema;
 }
 export interface OpenApiMediaType {
     schema?: OpenApiSchema;
@@ -119,6 +124,16 @@ export interface OperationInfo {
     path: string;
     parameters: OpenApiParameter[];
     requestBodySchema?: OpenApiSchema;
+    /** The request-body schema with every local component `$ref` deeply inlined (via
+     *  {@link resolveSchemaDeep}), so it is self-contained: no `$ref`, and an explicit `type` where the
+     *  referenced component declared one. This is what the MCP tool projection copies into a tool's
+     *  `inputSchema.properties.body` — an MCP client cannot resolve `#/components/...` outside the
+     *  original document, so the projected schema must carry the concrete shape. The raw
+     *  {@link requestBodySchema} is retained alongside it for the type deriver (which maps a `$ref` to
+     *  its named TypeScript type) and for `sharedRequestBodySchemas` (which fingerprints shared refs).
+     *  Absent exactly when {@link requestBodySchema} is absent. Downstream slices (ADR 0067) read the
+     *  resolved body `type` from here rather than re-resolving a possibly-`$ref` raw schema. */
+    requestBodySchemaResolved?: OpenApiSchema;
     requestBodyRequired: boolean;
     /** Every documented JSON response, keyed by status code ("200","400",…,"default"), in a stable
      *  order. The type layer unions these into the operation's response type; the runtime validates a
@@ -144,6 +159,20 @@ export declare function parseSpec(text: string): OpenApiDoc;
 export declare function refName(ref: string): string | undefined;
 /** Follow local component `$ref`s to the concrete schema (guarding cycles). Non-local refs → undefined. */
 export declare function resolveSchema(doc: OpenApiDoc, schema: OpenApiSchema | undefined): OpenApiSchema | undefined;
+/** Deeply inline every local component `$ref` in a schema, returning a self-contained schema with no
+ *  `$ref` anywhere in its tree (top-level chain plus nested `properties`/`items`/
+ *  `additionalProperties`/`allOf`/`oneOf`/`anyOf`). This is the resolver the MCP tool projection uses
+ *  so a tool's `inputSchema` carries the concrete shape rather than an opaque `#/components/...`
+ *  pointer an MCP client cannot follow (ADR 0067). It reuses the same local-ref semantics as
+ *  {@link resolveSchema}, extended to recurse into subschemas.
+ *
+ *  Cycles and unresolvable refs FAIL LOUDLY rather than leak a `$ref`:
+ *   - a `$ref` that reappears on its own resolution path (an irreducible cycle — a schema that
+ *     cannot be finitely inlined) throws;
+ *   - a `$ref` that is non-local or dangles (no matching `#/components/schemas/*`) throws.
+ *  `seenRefs` tracks refs on the CURRENT path only, so a component referenced twice in sibling
+ *  branches (a diamond) inlines fine — only genuine self-reference is rejected. */
+export declare function resolveSchemaDeep(doc: OpenApiDoc, schema: OpenApiSchema | undefined, seenRefs?: ReadonlySet<string>): OpenApiSchema | undefined;
 /** Walk the document's paths and return every operation that carries an operationId, in a stable
  *  (path, method) order. Operations without an operationId are skipped here; the runtime mount logs
  *  them at `warn` and skips them too — this keeps the pure collector total. */
@@ -164,15 +193,44 @@ export declare function isMcpExcluded(ext: unknown): boolean;
 /** Whether an operation's HTTP method mutates state — anything other than a safe read verb. Drives
  *  the MCP read/mutate split: read tools are unguarded on loopback, mutating tools are gated. */
 export declare function isMutatingMethod(method: HttpMethodLower): boolean;
-/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, and whether
- *  `x-mcp` excludes it from projection. This is the shared unit the runtime MCP surface AND the CI
- *  spec↔tool parity guard both read — a single derivation of "which operations become tools", never
- *  a second walker (ADR 0053). */
+/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
+ *  path/query parameters and its request-body schema. It is the SINGLE derivation both the runtime
+ *  MCP surface (`tools/list`) and the CI parity guard read, so a tool's advertised input schema and
+ *  the HTTP validation it dispatches to can never drift (ADR 0053/0067).
+ *
+ *  Every property schema is taken from the operation's resolved (`$ref`-free) metadata — the
+ *  parameters' `resolvedSchema` and the body's `requestBodySchemaResolved`, both produced by
+ *  {@link resolveSchemaDeep} in {@link collectOperations} — so the emitted schema is self-contained:
+ *  an MCP client, which cannot follow a `#/components/...` pointer outside the original document,
+ *  sees the concrete shape (and an explicit `type` on the body). */
+export declare function toolInputSchema(op: OperationInfo): Record<string, unknown>;
+/** Walk a JSON value (a projected tool schema) and return a pointer for every `$ref` still present.
+ *  Empty means the schema is self-contained — no `#/components/...` an MCP client cannot resolve. The
+ *  path is a dotted trail to each leak (e.g. `properties.body.properties.foo`). Pure/total. */
+export declare function findSchemaRefLeaks(value: unknown, path?: string): string[];
+/** Self-containment violations in one projected tool's `inputSchema`: any surviving `$ref` (an
+ *  MCP client cannot resolve `#/components/...`), and — when the tool has a `body` property — a
+ *  `body` that carries no explicit `type` (so the client cannot tell it is an object/array and
+ *  mis-encodes the argument). Empty means the schema is a usable, self-contained input contract.
+ *  This is the pure assertion the `check:mcp` guard runs over every projected tool (ADR 0067). */
+export declare function findToolSchemaViolations(operationId: string, inputSchema: Record<string, unknown>): string[];
+/** Every self-containment violation across all projected (non-excluded) tools for a document — the
+ *  aggregate the `check:mcp` guard fails on. Excluded operations are skipped: they are withheld from
+ *  the live tool surface, so their schema is never advertised to a client. */
+export declare function findAllToolSchemaViolations(doc: OpenApiDoc): string[];
+/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, whether
+ *  `x-mcp` excludes it from projection, and its self-contained input schema. This is the shared unit
+ *  the runtime MCP surface AND the CI spec↔tool parity guard both read — a single derivation of
+ *  "which operations become tools and what each accepts", never a second walker (ADR 0053). */
 export interface McpToolProjection {
     operationId: string;
     method: HttpMethodLower;
     mutating: boolean;
     excluded: boolean;
+    /** The tool's `inputSchema` as advertised to an MCP client (absent for an excluded op, which is
+     *  never advertised). Captured in the snapshot so a projection change — including a body `$ref`
+     *  that stops being resolved — is caught by `check:mcp` drift, not discovered by a client. */
+    inputSchema?: Record<string, unknown>;
 }
 /**
  * Project every operationId-bearing operation to its MCP-tool facts, in the stable
@@ -180,7 +238,7 @@ export interface McpToolProjection {
  * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
  * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
  * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
- * `mountApi` routes.
+ * `mountApi` routes. A non-excluded op also carries its self-contained {@link toolInputSchema}.
  */
 export declare function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[];
 /**

package/dist/openapi/spec.js

@@ -115,6 +115,54 @@ export function resolveSchema(doc, schema) {
     }
     return current;
 }
+/** Deeply inline every local component `$ref` in a schema, returning a self-contained schema with no
+ *  `$ref` anywhere in its tree (top-level chain plus nested `properties`/`items`/
+ *  `additionalProperties`/`allOf`/`oneOf`/`anyOf`). This is the resolver the MCP tool projection uses
+ *  so a tool's `inputSchema` carries the concrete shape rather than an opaque `#/components/...`
+ *  pointer an MCP client cannot follow (ADR 0067). It reuses the same local-ref semantics as
+ *  {@link resolveSchema}, extended to recurse into subschemas.
+ *
+ *  Cycles and unresolvable refs FAIL LOUDLY rather than leak a `$ref`:
+ *   - a `$ref` that reappears on its own resolution path (an irreducible cycle — a schema that
+ *     cannot be finitely inlined) throws;
+ *   - a `$ref` that is non-local or dangles (no matching `#/components/schemas/*`) throws.
+ *  `seenRefs` tracks refs on the CURRENT path only, so a component referenced twice in sibling
+ *  branches (a diamond) inlines fine — only genuine self-reference is rejected. */
+export function resolveSchemaDeep(doc, schema, seenRefs = new Set()) {
+    if (!schema)
+        return undefined;
+    let current = schema;
+    let seen = seenRefs;
+    while (current.$ref) {
+        const ref = current.$ref;
+        if (seen.has(ref)) {
+            throw new Error(`OpenAPI schema $ref cycle: ${[...seen, ref].join(" -> ")} cannot be inlined into a self-contained schema`);
+        }
+        const name = refName(ref);
+        const next = name ? doc.components?.schemas?.[name] : undefined;
+        if (!next) {
+            throw new Error(`OpenAPI schema $ref "${ref}" does not resolve to a local component — a self-contained schema cannot contain an unresolvable $ref`);
+        }
+        seen = new Set(seen).add(ref);
+        current = next;
+    }
+    const out = { ...current };
+    delete out.$ref;
+    if (current.properties) {
+        out.properties = Object.fromEntries(Object.entries(current.properties).map(([k, v]) => [k, resolveSchemaDeep(doc, v, seen) ?? {}]));
+    }
+    if (current.items)
+        out.items = resolveSchemaDeep(doc, current.items, seen);
+    if (current.additionalProperties && typeof current.additionalProperties === "object") {
+        out.additionalProperties = resolveSchemaDeep(doc, current.additionalProperties, seen);
+    }
+    for (const key of ["allOf", "oneOf", "anyOf"]) {
+        const arr = current[key];
+        if (arr)
+            out[key] = arr.map((s) => resolveSchemaDeep(doc, s, seen) ?? {});
+    }
+    return out;
+}
 function firstJsonSchema(content) {
     if (!content)
         return undefined;
@@ -151,10 +199,29 @@ export function collectOperations(doc) {
             const operationId = typeof opRaw.operationId === "string" ? opRaw.operationId : undefined;
             if (!operationId || !isSafeOperationId(operationId))
                 continue;
+            // Resolve exclusion BEFORE any deep `$ref` inlining. An `x-mcp`-excluded operation is never
+            // advertised as a tool, so its schema is never projected or self-containment-guarded; doing
+            // its (throwing) deep resolution eagerly would let a dangling/cyclic `$ref` on an EXCLUDED
+            // door crash projection/guards for the whole document — even though that door is withheld.
+            // Excluded ops therefore carry no `resolvedSchema`/`requestBodySchemaResolved` (unused).
+            const mcpExcluded = isMcpExcluded(opRaw["x-mcp"]);
             const opParams = Array.isArray(opRaw.parameters) ? opRaw.parameters : [];
-            const parameters = normalizeParameters([...pathParams, ...opParams]);
+            const parameters = normalizeParameters([...pathParams, ...opParams]).map((p) => ({
+                ...p,
+                // Inline any local component `$ref` so the projected MCP tool schema is self-contained. The
+                // raw `p.schema` is kept for the type deriver; the tool projection reads `resolvedSchema`.
+                resolvedSchema: mcpExcluded ? undefined : resolveSchemaDeep(doc, p.schema),
+            }));
             const requestBody = isRecord(opRaw.requestBody) ? opRaw.requestBody : undefined;
             const requestBodySchema = firstJsonSchema(isRecord(requestBody?.content) ? requestBody.content : undefined);
+            // Deeply inline component `$ref`s so downstream consumers (the MCP tool projection, ADR 0067)
+            // get a self-contained, explicitly-typed body schema — never an opaque `#/components/...`
+            // pointer. Raw `requestBodySchema` is retained (deriver + shared-ref fingerprinting). A cyclic
+            // or unresolvable body ref fails loudly here rather than leaking a `$ref` — but only for a
+            // projected (non-excluded) op; an excluded op skips this throwing work (see above).
+            const requestBodySchemaResolved = mcpExcluded
+                ? undefined
+                : resolveSchemaDeep(doc, requestBodySchema);
             const responses = isRecord(opRaw.responses) ? opRaw.responses : {};
             // Effective security: an operation's own `security` (even an explicit `[]`, which opts out of
             // a document-level default) wins; otherwise inherit the document-level default; otherwise open.
@@ -168,11 +235,12 @@ export function collectOperations(doc) {
                 path,
                 parameters,
                 requestBodySchema,
+                requestBodySchemaResolved,
                 requestBodyRequired: requestBody?.required === true,
                 responseSchemas: collectResponseSchemas(responses),
                 security,
                 eject: opRaw["x-urban-eject"] === true,
-                mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
+                mcpExcluded,
                 summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
             });
         }
@@ -206,13 +274,107 @@ const READ_ONLY_METHODS = ["get", "head", "options"];
 export function isMutatingMethod(method) {
     return !READ_ONLY_METHODS.includes(method);
 }
+/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
+ *  path/query parameters and its request-body schema. It is the SINGLE derivation both the runtime
+ *  MCP surface (`tools/list`) and the CI parity guard read, so a tool's advertised input schema and
+ *  the HTTP validation it dispatches to can never drift (ADR 0053/0067).
+ *
+ *  Every property schema is taken from the operation's resolved (`$ref`-free) metadata — the
+ *  parameters' `resolvedSchema` and the body's `requestBodySchemaResolved`, both produced by
+ *  {@link resolveSchemaDeep} in {@link collectOperations} — so the emitted schema is self-contained:
+ *  an MCP client, which cannot follow a `#/components/...` pointer outside the original document,
+ *  sees the concrete shape (and an explicit `type` on the body). */
+export function toolInputSchema(op) {
+    const properties = {};
+    const required = [];
+    for (const p of op.parameters) {
+        if (p.in === "path" || p.in === "query") {
+            properties[p.name] = p.resolvedSchema ?? p.schema ?? {};
+            if (p.required)
+                required.push(p.name);
+        }
+    }
+    const body = op.requestBodySchemaResolved;
+    if (body) {
+        properties.body = body;
+        if (op.requestBodyRequired)
+            required.push("body");
+    }
+    const schema = { type: "object", properties };
+    if (required.length > 0)
+        schema.required = required;
+    return schema;
+}
+/** Walk a JSON value (a projected tool schema) and return a pointer for every `$ref` still present.
+ *  Empty means the schema is self-contained — no `#/components/...` an MCP client cannot resolve. The
+ *  path is a dotted trail to each leak (e.g. `properties.body.properties.foo`). Pure/total. */
+export function findSchemaRefLeaks(value, path = "") {
+    const leaks = [];
+    const visit = (v, p) => {
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => visit(item, `${p}[${i}]`));
+            return;
+        }
+        if (v && typeof v === "object") {
+            for (const [k, child] of Object.entries(v)) {
+                // A JSON-Schema `$ref` is a *string* pointer; only that form is an unresolvable leak. A
+                // property literally named `$ref` with a non-string value is an ordinary schema key, so
+                // recurse into it (real leaks can still hide nested beneath such a property).
+                if (k === "$ref" && typeof child === "string")
+                    leaks.push(p || "<root>");
+                else
+                    visit(child, p ? `${p}.${k}` : k);
+            }
+        }
+    };
+    visit(value, path);
+    return leaks;
+}
+/** Whether a (record-typed) schema declares an explicit JSON-Schema `type` — a non-empty string or a
+ *  non-empty array of types. Operates on a raw record (not a typed {@link OpenApiSchema}) so it can
+ *  vet a projected tool schema's `body` property without an unchecked cast. */
+function hasExplicitType(schema) {
+    const t = schema.type;
+    if (typeof t === "string")
+        return t.length > 0;
+    return Array.isArray(t) && t.length > 0;
+}
+/** Self-containment violations in one projected tool's `inputSchema`: any surviving `$ref` (an
+ *  MCP client cannot resolve `#/components/...`), and — when the tool has a `body` property — a
+ *  `body` that carries no explicit `type` (so the client cannot tell it is an object/array and
+ *  mis-encodes the argument). Empty means the schema is a usable, self-contained input contract.
+ *  This is the pure assertion the `check:mcp` guard runs over every projected tool (ADR 0067). */
+export function findToolSchemaViolations(operationId, inputSchema) {
+    const violations = [];
+    for (const leak of findSchemaRefLeaks(inputSchema)) {
+        violations.push(`${operationId}: inputSchema leaks an unresolved $ref at ${leak}`);
+    }
+    const properties = isRecord(inputSchema.properties) ? inputSchema.properties : undefined;
+    const body = properties && isRecord(properties.body) ? properties.body : undefined;
+    if (body && !hasExplicitType(body)) {
+        violations.push(`${operationId}: inputSchema.properties.body has no explicit \`type\``);
+    }
+    return violations;
+}
+/** Every self-containment violation across all projected (non-excluded) tools for a document — the
+ *  aggregate the `check:mcp` guard fails on. Excluded operations are skipped: they are withheld from
+ *  the live tool surface, so their schema is never advertised to a client. */
+export function findAllToolSchemaViolations(doc) {
+    const violations = [];
+    for (const op of collectOperations(doc)) {
+        if (op.mcpExcluded)
+            continue;
+        violations.push(...findToolSchemaViolations(op.operationId, toolInputSchema(op)));
+    }
+    return violations;
+}
 /**
  * Project every operationId-bearing operation to its MCP-tool facts, in the stable
  * `collectOperations` (path, method) order. Excluded operations are RETAINED here (flagged
  * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
  * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
  * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
- * `mountApi` routes.
+ * `mountApi` routes. A non-excluded op also carries its self-contained {@link toolInputSchema}.
  */
 export function collectMcpToolProjection(doc) {
     return collectOperations(doc).map((op) => ({
@@ -220,6 +382,7 @@ export function collectMcpToolProjection(doc) {
         method: op.method,
         mutating: isMutatingMethod(op.method),
         excluded: op.mcpExcluded,
+        ...(op.mcpExcluded ? {} : { inputSchema: toolInputSchema(op) }),
     }));
 }
 /**
@@ -247,6 +410,12 @@ export function diffMcpToolProjection(snapshot, current) {
                 `excluded:${snap.excluded}} vs spec {method:${cur.method}, mutating:${cur.mutating}, ` +
                 `excluded:${cur.excluded}}`);
         }
+        if (JSON.stringify(snap.inputSchema ?? null) !== JSON.stringify(cur.inputSchema ?? null)) {
+            // Emit a concise, constant-size line rather than inlining both full `inputSchema` payloads:
+            // for a non-trivial schema that would explode CI logs and bury the signal. The committed
+            // snapshot's own diff carries the exact field-level detail; this line just names the drift.
+            drift.push(`~ ${id}: inputSchema changed (regenerate the snapshot to see the field-level diff)`);
+        }
     }
     for (const id of snapshotById.keys()) {
         if (!currentById.has(id)) {

package/dist/runtime/core/modules/mcp.js

@@ -34,7 +34,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, isInitializeRequest, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { GENERATED_DIR } from "../../../toolkit/artifact.js";
 import { SYSTEM_BRIEF_JSON } from "../../../toolkit/derivers/system-brief.js";
-import { collectOperations, evaluateSecurity, isMutatingMethod, parseSpec, sharedSecretSchemeName, } from "../../../openapi/spec.js";
+import { collectOperations, evaluateSecurity, isMutatingMethod, parseSpec, sharedSecretSchemeName, toolInputSchema, } from "../../../openapi/spec.js";
 import { errorMessage } from "../guards.js";
 import { presentFormIdentifier } from "../host.js";
 import { resolveBindMode } from "../manifest.js";
@@ -173,29 +173,10 @@ export function readHeader(headers, name) {
 function isMutatingOperation(op) {
     return isMutatingMethod(op.method);
 }
-/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
- *  path/query parameters and its request-body schema. Keeping the property schemas verbatim from the
- *  spec means the tool input schema and the HTTP validation share one source of truth. */
-function toolInputSchema(op) {
-    const properties = {};
-    const required = [];
-    for (const p of op.parameters) {
-        if (p.in === "path" || p.in === "query") {
-            properties[p.name] = p.schema ?? {};
-            if (p.required)
-                required.push(p.name);
-        }
-    }
-    if (op.requestBodySchema) {
-        properties.body = op.requestBodySchema;
-        if (op.requestBodyRequired)
-            required.push("body");
-    }
-    const schema = { type: "object", properties };
-    if (required.length > 0)
-        schema.required = required;
-    return schema;
-}
+/** A JSON Schema (OpenAPI object subset) describing a tool's input is derived once, in
+ *  `openapi/spec.ts`'s {@link toolInputSchema}, from an operation's resolved (`$ref`-free) parameter
+ *  and request-body metadata — so the tool input schema the runtime advertises and the schema the CI
+ *  parity guard pins are the SAME derivation (one source of truth, ADR 0053/0067). */
 /** Substitute an operation's `{param}` path-template segments with the supplied arguments, building
  *  the request path under the shared `/app/api` base so dispatch hits the exact `mountApi` route. */
 function fillPath(op, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.86.1",
+	"version": "0.87.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/openapi/mcp-parity.fixture.yaml

@@ -10,6 +10,15 @@
 #   - an `x-mcp`-EXCLUDED operation      → present in the doc but withheld from the
 #                                          agent-facing tool surface (the security-
 #                                          relevant opt-out, `x-mcp: false`)
+#   - a `$ref`-BODIED operation (POST)   → its request body is a bare
+#                                          `{ $ref: #/components/schemas/... }` with
+#                                          no inline `type`, whose referenced
+#                                          component itself nests another `$ref`.
+#                                          The projection must inline both so the
+#                                          tool's `inputSchema.properties.body` is
+#                                          self-contained (no `$ref`, explicit
+#                                          `type`) — an MCP client cannot resolve
+#                                          `#/components/...` outside this document.
 #
 # Edit this fixture ONLY together with a reviewed `npm run gen:mcp-tools`.
 openapi: 3.1.0
@@ -23,6 +32,30 @@ components:
       in: header
       name: X-Nano-Key
       x-nano-secret-env: NANO_WEBHOOK_KEY
+  schemas:
+    # A request-body schema declared as a bare `$ref` with NO inline `type` — the exact shape that
+    # leaked an unresolved `#/components/...` pointer into a tool's inputSchema before it was resolved
+    # on the projection path (the motivating real op `previewDeliveryGraph`). It also NESTS another
+    # `$ref` (`root`) so deep resolution is exercised, not just a single top-level hop.
+    DeliveryGraphSubmit:
+      type: object
+      required:
+        - root
+      properties:
+        root:
+          $ref: "#/components/schemas/DeliveryNode"
+        note:
+          type: string
+    DeliveryNode:
+      type: object
+      required:
+        - id
+      properties:
+        id:
+          type: string
+        weight:
+          type: integer
+          minimum: 0
 paths:
   /widgets:
     get:
@@ -47,3 +80,16 @@ paths:
       responses:
         "202":
           description: accepted
+  /delivery-graph/preview:
+    post:
+      operationId: previewDeliveryGraph
+      summary: Preview a delivery graph (mutating — `$ref`-bodied, body must resolve to a self-contained schema).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphSubmit"
+      responses:
+        "200":
+          description: ok

package/src/openapi/mcp-tools.snapshot.json

@@ -1,4 +1,44 @@
 [
+  {
+    "operationId": "previewDeliveryGraph",
+    "method": "post",
+    "mutating": true,
+    "excluded": false,
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "body": {
+          "type": "object",
+          "required": [
+            "root"
+          ],
+          "properties": {
+            "root": {
+              "type": "object",
+              "required": [
+                "id"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "weight": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "note": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "required": [
+        "body"
+      ]
+    }
+  },
   {
     "operationId": "reindexWidgets",
     "method": "post",
@@ -9,12 +49,20 @@
     "operationId": "listWidgets",
     "method": "get",
     "mutating": false,
-    "excluded": false
+    "excluded": false,
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
   },
   {
     "operationId": "createWidget",
     "method": "post",
     "mutating": true,
-    "excluded": false
+    "excluded": false,
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
   }
 ]

package/src/openapi/spec.test.ts

@@ -2,7 +2,12 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   collectOperations,
+  collectMcpToolProjection,
+  diffMcpToolProjection,
   evaluateSecurity,
+  findAllToolSchemaViolations,
+  findSchemaRefLeaks,
+  findToolSchemaViolations,
   isObjectSchema,
   isSafeOperationId,
   isMutatingMethod,
@@ -12,10 +17,12 @@ import {
   operationsWithUnsafeId,
   parseSpec,
   resolveSchema,
+  resolveSchemaDeep,
   responseSchemaForStatus,
   sharedRequestBodySchemas,
   sharedSecretSchemeName,
   sharedSecretSchemeNames,
+  toolInputSchema,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -179,6 +186,220 @@ test("resolveSchema follows a local $ref and guards cycles", () => {
   assert.equal(resolveSchema(cyclic, { $ref: "#/components/schemas/A" }), undefined);
 });
 
+test("resolveSchemaDeep inlines nested $refs into a self-contained, $ref-free schema", () => {
+  const nestedDoc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: {
+        Submit: {
+          type: "object",
+          required: ["root"],
+          properties: { root: { $ref: "#/components/schemas/Node" }, note: { type: "string" } },
+        },
+        Node: {
+          type: "object",
+          required: ["id"],
+          properties: { id: { type: "string" }, meta: { $ref: "#/components/schemas/Meta" } },
+        },
+        Meta: { type: "object", properties: { label: { type: "string" } } },
+      },
+    },
+    paths: {},
+  };
+  const resolved = resolveSchemaDeep(nestedDoc, { $ref: "#/components/schemas/Submit" });
+  // A bare `$ref` body with no inline `type` resolves to an explicit `type: object`, and the nested
+  // `Node` ref inside `root` (and the deeper `Meta` ref inside `Node`) are inlined too — no `$ref`
+  // survives at any depth.
+  assert.equal(resolved?.type, "object");
+  assert.ok(!JSON.stringify(resolved).includes("$ref"));
+  const root = resolved?.properties?.root;
+  assert.equal(root?.type, "object");
+  assert.equal(root?.properties?.id?.type, "string");
+  assert.equal(root?.properties?.meta?.type, "object");
+  assert.equal(root?.properties?.meta?.properties?.label?.type, "string");
+});
+
+test("resolveSchemaDeep inlines a diamond (same component in sibling branches) without a false cycle", () => {
+  const diamond: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: {
+        Pair: {
+          type: "object",
+          properties: { left: { $ref: "#/components/schemas/Leaf" }, right: { $ref: "#/components/schemas/Leaf" } },
+        },
+        Leaf: { type: "object", properties: { v: { type: "integer" } } },
+      },
+    },
+    paths: {},
+  };
+  const resolved = resolveSchemaDeep(diamond, { $ref: "#/components/schemas/Pair" });
+  assert.equal(resolved?.properties?.left?.properties?.v?.type, "integer");
+  assert.equal(resolved?.properties?.right?.properties?.v?.type, "integer");
+});
+
+test("resolveSchemaDeep fails loudly on an irreducible cycle rather than leaking a $ref", () => {
+  const cyclic: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: { schemas: { A: { type: "object", properties: { self: { $ref: "#/components/schemas/A" } } } } },
+    paths: {},
+  };
+  assert.throws(
+    () => resolveSchemaDeep(cyclic, { $ref: "#/components/schemas/A" }),
+    /\$ref cycle/,
+  );
+});
+
+test("resolveSchemaDeep fails loudly on a dangling/non-local $ref rather than leaking it", () => {
+  assert.throws(
+    () => resolveSchemaDeep(doc, { $ref: "#/components/schemas/Missing" }),
+    /does not resolve to a local component/,
+  );
+  assert.throws(
+    () => resolveSchemaDeep(doc, { $ref: "https://example.com/external.json#/X" }),
+    /does not resolve to a local component/,
+  );
+});
+
+test("collectOperations exposes the resolved request-body schema as operation metadata", () => {
+  // Downstream consumers (ADR 0067 P1) read the resolved body type from `requestBodySchemaResolved`;
+  // the raw `requestBodySchema` keeps its `$ref` for the type deriver + shared-ref fingerprinting.
+  const create = collectOperations(doc).find((o) => o.operationId === "createInvoice");
+  assert.equal(create?.requestBodySchema?.$ref, "#/components/schemas/Invoice");
+  assert.equal(create?.requestBodySchemaResolved?.type, "object");
+  assert.ok(!JSON.stringify(create?.requestBodySchemaResolved).includes("$ref"));
+});
+
+test("toolInputSchema resolves a $ref body to a self-contained typed schema", () => {
+  const create = collectOperations(doc).find((o) => o.operationId === "createInvoice");
+  assert.ok(create);
+  const schema = toolInputSchema(create);
+  assert.ok(!JSON.stringify(schema).includes("$ref"));
+  assert.deepEqual(schema, {
+    type: "object",
+    properties: {
+      body: {
+        type: "object",
+        properties: { id: { type: "string" }, amount: { type: "integer", minimum: 1 } },
+        required: ["id", "amount"],
+        additionalProperties: false,
+      },
+    },
+    required: ["body"],
+  });
+});
+
+test("findSchemaRefLeaks reports every surviving $ref path, empty when self-contained", () => {
+  assert.deepEqual(findSchemaRefLeaks({ type: "object", properties: { a: { type: "string" } } }), []);
+  assert.deepEqual(
+    findSchemaRefLeaks({ properties: { body: { $ref: "#/components/schemas/X" } } }),
+    ["properties.body"],
+  );
+  // A property literally named `$ref` whose value is NOT a string is an ordinary schema key, not a
+  // JSON-Schema reference — it must not be reported as a leak, and real leaks nested beneath it are
+  // still caught.
+  assert.deepEqual(
+    findSchemaRefLeaks({ type: "object", properties: { $ref: { type: "string" } } }),
+    [],
+  );
+  assert.deepEqual(
+    findSchemaRefLeaks({ properties: { $ref: { body: { $ref: "#/components/schemas/X" } } } }),
+    ["properties.$ref.body"],
+  );
+});
+
+test("findToolSchemaViolations flags a leaked $ref and a body missing an explicit type", () => {
+  assert.deepEqual(findToolSchemaViolations("ok", { type: "object", properties: { body: { type: "object" } } }), []);
+  const leak = findToolSchemaViolations("leaky", { type: "object", properties: { body: { $ref: "#/components/schemas/X" } } });
+  assert.equal(leak.length, 2); // both the $ref leak AND the missing body type
+  assert.ok(leak.some((m) => /leaks an unresolved \$ref/.test(m)));
+  assert.ok(leak.some((m) => /body has no explicit `type`/.test(m)));
+  const untyped = findToolSchemaViolations("untyped", { type: "object", properties: { body: { properties: {} } } });
+  assert.deepEqual(untyped, ["untyped: inputSchema.properties.body has no explicit `type`"]);
+});
+
+test("findAllToolSchemaViolations passes a resolved-body doc and catches a would-be $ref leak", () => {
+  // The real doc (a $ref body) is self-contained AFTER projection resolution — no violations.
+  assert.deepEqual(findAllToolSchemaViolations(doc), []);
+  // Excluded ops are never advertised, so their schema is not asserted.
+  const excludedDoc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: { schemas: { Invoice: { type: "object", properties: { id: { type: "string" } } } } },
+    paths: {
+      "/x": {
+        post: {
+          operationId: "hiddenOp",
+          "x-mcp": false,
+          requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  assert.deepEqual(findAllToolSchemaViolations(excludedDoc), []);
+});
+
+test("an x-mcp-excluded op with a dangling/cyclic $ref never crashes projection or guards", () => {
+  // An EXCLUDED door is withheld from the tool surface, so its schema is never advertised — a
+  // broken `$ref` on it must not make the whole document's projection/guards throw. Regression:
+  // deep resolution used to run eagerly, before the exclusion check.
+  const excludedBrokenDoc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: { schemas: { Cyclic: { $ref: "#/components/schemas/Cyclic" } } },
+    paths: {
+      "/hidden": {
+        post: {
+          operationId: "hiddenBroken",
+          "x-mcp": false,
+          parameters: [{ name: "q", in: "query", schema: { $ref: "#/components/schemas/Missing" } }],
+          requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Cyclic" } } } },
+          responses: { "200": {} },
+        },
+      },
+      "/shown": {
+        post: {
+          operationId: "shownOp",
+          requestBody: { content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" } } } } } },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const ops = collectOperations(excludedBrokenDoc);
+  const hidden = ops.find((o) => o.operationId === "hiddenBroken");
+  assert.equal(hidden?.mcpExcluded, true);
+  assert.equal(hidden?.requestBodySchemaResolved, undefined);
+  assert.deepEqual(findAllToolSchemaViolations(excludedBrokenDoc), []);
+  const projection = collectMcpToolProjection(excludedBrokenDoc);
+  assert.equal(projection.find((p) => p.operationId === "hiddenBroken")?.excluded, true);
+  assert.equal(projection.find((p) => p.operationId === "shownOp")?.inputSchema?.type, "object");
+});
+
+test("diffMcpToolProjection reports an inputSchema skew concisely, not by inlining payloads", () => {
+  const projection = collectMcpToolProjection(doc);
+  const big = { type: "object", properties: { body: { type: "object", properties: { huge: { type: "string" } } } }, required: ["body"] };
+  const stale = projection.map((p) => (p.operationId === "createInvoice" ? { ...p, inputSchema: big } : p));
+  const drift = diffMcpToolProjection(stale, projection);
+  const line = drift.find((l) => /createInvoice: inputSchema changed/.test(l));
+  assert.ok(line, "expected an inputSchema-changed drift line for createInvoice");
+  assert.ok(!line?.includes("huge"), "drift line must not inline the full schema payload");
+});
+
+test("collectMcpToolProjection carries a self-contained inputSchema; diff catches an inputSchema skew", () => {
+  const projection = collectMcpToolProjection(doc);
+  const create = projection.find((p) => p.operationId === "createInvoice");
+  assert.equal(create?.inputSchema?.type, "object");
+  assert.ok(!JSON.stringify(create?.inputSchema).includes("$ref"));
+  // A snapshot whose body schema regressed to a $ref (or otherwise differs) is reported as drift.
+  const stale = projection.map((p) =>
+    p.operationId === "createInvoice"
+      ? { ...p, inputSchema: { type: "object", properties: { body: { $ref: "#/components/schemas/Invoice" } }, required: ["body"] } }
+      : p,
+  );
+  const drift = diffMcpToolProjection(stale, projection);
+  assert.ok(drift.some((line) => /createInvoice: inputSchema changed/.test(line)));
+});
+
 test("validateValue enforces the JSON-Schema subset via $ref", () => {
   const schema = { $ref: "#/components/schemas/Invoice" };
   assert.deepEqual(validateValue(doc, schema, { id: "i1", amount: 5 }, "body"), []);

package/src/openapi/spec.ts

@@ -106,6 +106,11 @@ export interface OpenApiParameter {
   in: "path" | "query" | "header" | "cookie";
   required?: boolean;
   schema?: OpenApiSchema;
+  /** The parameter's schema with every local component `$ref` inlined (via {@link resolveSchemaDeep}),
+   *  so a consumer that cannot resolve `#/components/...` — e.g. an MCP client reading the projected
+   *  tool `inputSchema` — sees a self-contained schema. Absent when the parameter declares no schema.
+   *  The raw {@link schema} is retained for the type deriver, which maps a `$ref` to its named type. */
+  resolvedSchema?: OpenApiSchema;
 }
 
 export interface OpenApiMediaType {
@@ -178,6 +183,16 @@ export interface OperationInfo {
   path: string;
   parameters: OpenApiParameter[];
   requestBodySchema?: OpenApiSchema;
+  /** The request-body schema with every local component `$ref` deeply inlined (via
+   *  {@link resolveSchemaDeep}), so it is self-contained: no `$ref`, and an explicit `type` where the
+   *  referenced component declared one. This is what the MCP tool projection copies into a tool's
+   *  `inputSchema.properties.body` — an MCP client cannot resolve `#/components/...` outside the
+   *  original document, so the projected schema must carry the concrete shape. The raw
+   *  {@link requestBodySchema} is retained alongside it for the type deriver (which maps a `$ref` to
+   *  its named TypeScript type) and for `sharedRequestBodySchemas` (which fingerprints shared refs).
+   *  Absent exactly when {@link requestBodySchema} is absent. Downstream slices (ADR 0067) read the
+   *  resolved body `type` from here rather than re-resolving a possibly-`$ref` raw schema. */
+  requestBodySchemaResolved?: OpenApiSchema;
   requestBodyRequired: boolean;
   /** Every documented JSON response, keyed by status code ("200","400",…,"default"), in a stable
    *  order. The type layer unions these into the operation's response type; the runtime validates a
@@ -254,6 +269,62 @@ export function resolveSchema(
   return current;
 }
 
+/** Deeply inline every local component `$ref` in a schema, returning a self-contained schema with no
+ *  `$ref` anywhere in its tree (top-level chain plus nested `properties`/`items`/
+ *  `additionalProperties`/`allOf`/`oneOf`/`anyOf`). This is the resolver the MCP tool projection uses
+ *  so a tool's `inputSchema` carries the concrete shape rather than an opaque `#/components/...`
+ *  pointer an MCP client cannot follow (ADR 0067). It reuses the same local-ref semantics as
+ *  {@link resolveSchema}, extended to recurse into subschemas.
+ *
+ *  Cycles and unresolvable refs FAIL LOUDLY rather than leak a `$ref`:
+ *   - a `$ref` that reappears on its own resolution path (an irreducible cycle — a schema that
+ *     cannot be finitely inlined) throws;
+ *   - a `$ref` that is non-local or dangles (no matching `#/components/schemas/*`) throws.
+ *  `seenRefs` tracks refs on the CURRENT path only, so a component referenced twice in sibling
+ *  branches (a diamond) inlines fine — only genuine self-reference is rejected. */
+export function resolveSchemaDeep(
+  doc: OpenApiDoc,
+  schema: OpenApiSchema | undefined,
+  seenRefs: ReadonlySet<string> = new Set(),
+): OpenApiSchema | undefined {
+  if (!schema) return undefined;
+  let current: OpenApiSchema = schema;
+  let seen = seenRefs;
+  while (current.$ref) {
+    const ref = current.$ref;
+    if (seen.has(ref)) {
+      throw new Error(
+        `OpenAPI schema $ref cycle: ${[...seen, ref].join(" -> ")} cannot be inlined into a self-contained schema`,
+      );
+    }
+    const name = refName(ref);
+    const next = name ? doc.components?.schemas?.[name] : undefined;
+    if (!next) {
+      throw new Error(
+        `OpenAPI schema $ref "${ref}" does not resolve to a local component — a self-contained schema cannot contain an unresolvable $ref`,
+      );
+    }
+    seen = new Set(seen).add(ref);
+    current = next;
+  }
+  const out: OpenApiSchema = { ...current };
+  delete out.$ref;
+  if (current.properties) {
+    out.properties = Object.fromEntries(
+      Object.entries(current.properties).map(([k, v]) => [k, resolveSchemaDeep(doc, v, seen) ?? {}]),
+    );
+  }
+  if (current.items) out.items = resolveSchemaDeep(doc, current.items, seen);
+  if (current.additionalProperties && typeof current.additionalProperties === "object") {
+    out.additionalProperties = resolveSchemaDeep(doc, current.additionalProperties, seen);
+  }
+  for (const key of ["allOf", "oneOf", "anyOf"] as const) {
+    const arr = current[key];
+    if (arr) out[key] = arr.map((s) => resolveSchemaDeep(doc, s, seen) ?? {});
+  }
+  return out;
+}
+
 function firstJsonSchema(
   content: Record<string, unknown> | undefined,
 ): OpenApiSchema | undefined {
@@ -289,12 +360,31 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
       if (!isRecord(opRaw)) continue;
       const operationId = typeof opRaw.operationId === "string" ? opRaw.operationId : undefined;
       if (!operationId || !isSafeOperationId(operationId)) continue;
+      // Resolve exclusion BEFORE any deep `$ref` inlining. An `x-mcp`-excluded operation is never
+      // advertised as a tool, so its schema is never projected or self-containment-guarded; doing
+      // its (throwing) deep resolution eagerly would let a dangling/cyclic `$ref` on an EXCLUDED
+      // door crash projection/guards for the whole document — even though that door is withheld.
+      // Excluded ops therefore carry no `resolvedSchema`/`requestBodySchemaResolved` (unused).
+      const mcpExcluded = isMcpExcluded(opRaw["x-mcp"]);
       const opParams = Array.isArray(opRaw.parameters) ? opRaw.parameters : [];
-      const parameters = normalizeParameters([...pathParams, ...opParams]);
+      const parameters = normalizeParameters([...pathParams, ...opParams]).map((p) => ({
+        ...p,
+        // Inline any local component `$ref` so the projected MCP tool schema is self-contained. The
+        // raw `p.schema` is kept for the type deriver; the tool projection reads `resolvedSchema`.
+        resolvedSchema: mcpExcluded ? undefined : resolveSchemaDeep(doc, p.schema),
+      }));
       const requestBody = isRecord(opRaw.requestBody) ? opRaw.requestBody : undefined;
       const requestBodySchema = firstJsonSchema(
         isRecord(requestBody?.content) ? requestBody.content : undefined,
       );
+      // Deeply inline component `$ref`s so downstream consumers (the MCP tool projection, ADR 0067)
+      // get a self-contained, explicitly-typed body schema — never an opaque `#/components/...`
+      // pointer. Raw `requestBodySchema` is retained (deriver + shared-ref fingerprinting). A cyclic
+      // or unresolvable body ref fails loudly here rather than leaking a `$ref` — but only for a
+      // projected (non-excluded) op; an excluded op skips this throwing work (see above).
+      const requestBodySchemaResolved = mcpExcluded
+        ? undefined
+        : resolveSchemaDeep(doc, requestBodySchema);
       const responses = isRecord(opRaw.responses) ? opRaw.responses : {};
       // Effective security: an operation's own `security` (even an explicit `[]`, which opts out of
       // a document-level default) wins; otherwise inherit the document-level default; otherwise open.
@@ -308,11 +398,12 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         path,
         parameters,
         requestBodySchema,
+        requestBodySchemaResolved,
         requestBodyRequired: requestBody?.required === true,
         responseSchemas: collectResponseSchemas(responses),
         security,
         eject: opRaw["x-urban-eject"] === true,
-        mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
+        mcpExcluded,
         summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
       });
     }
@@ -349,15 +440,114 @@ export function isMutatingMethod(method: HttpMethodLower): boolean {
   return !READ_ONLY_METHODS.includes(method);
 }
 
-/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, and whether
- *  `x-mcp` excludes it from projection. This is the shared unit the runtime MCP surface AND the CI
- *  spec↔tool parity guard both read — a single derivation of "which operations become tools", never
- *  a second walker (ADR 0053). */
+/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
+ *  path/query parameters and its request-body schema. It is the SINGLE derivation both the runtime
+ *  MCP surface (`tools/list`) and the CI parity guard read, so a tool's advertised input schema and
+ *  the HTTP validation it dispatches to can never drift (ADR 0053/0067).
+ *
+ *  Every property schema is taken from the operation's resolved (`$ref`-free) metadata — the
+ *  parameters' `resolvedSchema` and the body's `requestBodySchemaResolved`, both produced by
+ *  {@link resolveSchemaDeep} in {@link collectOperations} — so the emitted schema is self-contained:
+ *  an MCP client, which cannot follow a `#/components/...` pointer outside the original document,
+ *  sees the concrete shape (and an explicit `type` on the body). */
+export function toolInputSchema(op: OperationInfo): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const p of op.parameters) {
+    if (p.in === "path" || p.in === "query") {
+      properties[p.name] = p.resolvedSchema ?? p.schema ?? {};
+      if (p.required) required.push(p.name);
+    }
+  }
+  const body = op.requestBodySchemaResolved;
+  if (body) {
+    properties.body = body;
+    if (op.requestBodyRequired) required.push("body");
+  }
+  const schema: Record<string, unknown> = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+/** Walk a JSON value (a projected tool schema) and return a pointer for every `$ref` still present.
+ *  Empty means the schema is self-contained — no `#/components/...` an MCP client cannot resolve. The
+ *  path is a dotted trail to each leak (e.g. `properties.body.properties.foo`). Pure/total. */
+export function findSchemaRefLeaks(value: unknown, path = ""): string[] {
+  const leaks: string[] = [];
+  const visit = (v: unknown, p: string): void => {
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => visit(item, `${p}[${i}]`));
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const [k, child] of Object.entries(v)) {
+        // A JSON-Schema `$ref` is a *string* pointer; only that form is an unresolvable leak. A
+        // property literally named `$ref` with a non-string value is an ordinary schema key, so
+        // recurse into it (real leaks can still hide nested beneath such a property).
+        if (k === "$ref" && typeof child === "string") leaks.push(p || "<root>");
+        else visit(child, p ? `${p}.${k}` : k);
+      }
+    }
+  };
+  visit(value, path);
+  return leaks;
+}
+
+/** Whether a (record-typed) schema declares an explicit JSON-Schema `type` — a non-empty string or a
+ *  non-empty array of types. Operates on a raw record (not a typed {@link OpenApiSchema}) so it can
+ *  vet a projected tool schema's `body` property without an unchecked cast. */
+function hasExplicitType(schema: Record<string, unknown>): boolean {
+  const t = schema.type;
+  if (typeof t === "string") return t.length > 0;
+  return Array.isArray(t) && t.length > 0;
+}
+
+/** Self-containment violations in one projected tool's `inputSchema`: any surviving `$ref` (an
+ *  MCP client cannot resolve `#/components/...`), and — when the tool has a `body` property — a
+ *  `body` that carries no explicit `type` (so the client cannot tell it is an object/array and
+ *  mis-encodes the argument). Empty means the schema is a usable, self-contained input contract.
+ *  This is the pure assertion the `check:mcp` guard runs over every projected tool (ADR 0067). */
+export function findToolSchemaViolations(
+  operationId: string,
+  inputSchema: Record<string, unknown>,
+): string[] {
+  const violations: string[] = [];
+  for (const leak of findSchemaRefLeaks(inputSchema)) {
+    violations.push(`${operationId}: inputSchema leaks an unresolved $ref at ${leak}`);
+  }
+  const properties = isRecord(inputSchema.properties) ? inputSchema.properties : undefined;
+  const body = properties && isRecord(properties.body) ? properties.body : undefined;
+  if (body && !hasExplicitType(body)) {
+    violations.push(`${operationId}: inputSchema.properties.body has no explicit \`type\``);
+  }
+  return violations;
+}
+
+/** Every self-containment violation across all projected (non-excluded) tools for a document — the
+ *  aggregate the `check:mcp` guard fails on. Excluded operations are skipped: they are withheld from
+ *  the live tool surface, so their schema is never advertised to a client. */
+export function findAllToolSchemaViolations(doc: OpenApiDoc): string[] {
+  const violations: string[] = [];
+  for (const op of collectOperations(doc)) {
+    if (op.mcpExcluded) continue;
+    violations.push(...findToolSchemaViolations(op.operationId, toolInputSchema(op)));
+  }
+  return violations;
+}
+
+/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, whether
+ *  `x-mcp` excludes it from projection, and its self-contained input schema. This is the shared unit
+ *  the runtime MCP surface AND the CI spec↔tool parity guard both read — a single derivation of
+ *  "which operations become tools and what each accepts", never a second walker (ADR 0053). */
 export interface McpToolProjection {
   operationId: string;
   method: HttpMethodLower;
   mutating: boolean;
   excluded: boolean;
+  /** The tool's `inputSchema` as advertised to an MCP client (absent for an excluded op, which is
+   *  never advertised). Captured in the snapshot so a projection change — including a body `$ref`
+   *  that stops being resolved — is caught by `check:mcp` drift, not discovered by a client. */
+  inputSchema?: Record<string, unknown>;
 }
 
 /**
@@ -366,7 +556,7 @@ export interface McpToolProjection {
  * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
  * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
  * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
- * `mountApi` routes.
+ * `mountApi` routes. A non-excluded op also carries its self-contained {@link toolInputSchema}.
  */
 export function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[] {
   return collectOperations(doc).map((op) => ({
@@ -374,6 +564,7 @@ export function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[] {
     method: op.method,
     mutating: isMutatingMethod(op.method),
     excluded: op.mcpExcluded,
+    ...(op.mcpExcluded ? {} : { inputSchema: toolInputSchema(op) }),
   }));
 }
 
@@ -408,6 +599,12 @@ export function diffMcpToolProjection(
           `excluded:${cur.excluded}}`,
       );
     }
+    if (JSON.stringify(snap.inputSchema ?? null) !== JSON.stringify(cur.inputSchema ?? null)) {
+      // Emit a concise, constant-size line rather than inlining both full `inputSchema` payloads:
+      // for a non-trivial schema that would explode CI logs and bury the signal. The committed
+      // snapshot's own diff carries the exact field-level detail; this line just names the drift.
+      drift.push(`~ ${id}: inputSchema changed (regenerate the snapshot to see the field-level diff)`);
+    }
   }
   for (const id of snapshotById.keys()) {
     if (!currentById.has(id)) {

package/src/runtime/core/modules/mcp.test.ts

@@ -327,6 +327,35 @@ test("a projected tool's input schema matches the spec's params", async () => {
   });
 });
 
+test("a $ref-bodied tool projects a self-contained body schema (no $ref, explicit type)", async () => {
+  // createInvoice's requestBody is `{ $ref: "#/components/schemas/Invoice" }` — a bare $ref with no
+  // inline `type`. An MCP client cannot resolve `#/components/...` outside the document, so the
+  // projected tool schema MUST inline the concrete Invoice shape (ADR 0067). Regression guard for the
+  // leak that shipped an opaque `#/components/...` pointer into `inputSchema.properties.body`.
+  const { router } = buildHarness();
+  const session = await connect(router);
+  const list = await rpc(router, session, "tools/list", {});
+  const tools = list.result?.tools;
+  assert.ok(Array.isArray(tools));
+  const createInvoice = tools.find((t) => Reflect.get(t, "name") === "createInvoice");
+  assert.ok(createInvoice, "createInvoice must be present in tools/list before checking its schema");
+  const schema = Reflect.get(createInvoice, "inputSchema");
+  assert.deepEqual(schema, {
+    type: "object",
+    properties: {
+      body: {
+        type: "object",
+        properties: { id: { type: "string" }, amount: { type: "integer", minimum: 1 } },
+        required: ["id", "amount"],
+        additionalProperties: false,
+      },
+    },
+    required: ["body"],
+  });
+  // Self-containment holds structurally: the serialized schema carries no `$ref` token at all.
+  assert.ok(!JSON.stringify(schema).includes("$ref"), "projected body schema must not leak a $ref");
+});
+
 test("a tool call routes through the SAME mountApi delegate as the HTTP call", async () => {
   let seenParams: Record<string, unknown> | undefined;
   const { router, imported } = buildHarness({

package/src/runtime/core/modules/mcp.ts

@@ -55,6 +55,7 @@ import {
   parseSpec,
   type SecurityDecision,
   sharedSecretSchemeName,
+  toolInputSchema,
 } from "../../../openapi/spec.ts";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
@@ -250,26 +251,10 @@ function isMutatingOperation(op: OperationInfo): boolean {
   return isMutatingMethod(op.method);
 }
 
-/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
- *  path/query parameters and its request-body schema. Keeping the property schemas verbatim from the
- *  spec means the tool input schema and the HTTP validation share one source of truth. */
-function toolInputSchema(op: OperationInfo): Record<string, unknown> {
-  const properties: Record<string, unknown> = {};
-  const required: string[] = [];
-  for (const p of op.parameters) {
-    if (p.in === "path" || p.in === "query") {
-      properties[p.name] = p.schema ?? {};
-      if (p.required) required.push(p.name);
-    }
-  }
-  if (op.requestBodySchema) {
-    properties.body = op.requestBodySchema;
-    if (op.requestBodyRequired) required.push("body");
-  }
-  const schema: Record<string, unknown> = { type: "object", properties };
-  if (required.length > 0) schema.required = required;
-  return schema;
-}
+/** A JSON Schema (OpenAPI object subset) describing a tool's input is derived once, in
+ *  `openapi/spec.ts`'s {@link toolInputSchema}, from an operation's resolved (`$ref`-free) parameter
+ *  and request-body metadata — so the tool input schema the runtime advertises and the schema the CI
+ *  parity guard pins are the SAME derivation (one source of truth, ADR 0053/0067). */
 
 /** Substitute an operation's `{param}` path-template segments with the supplied arguments, building
  *  the request path under the shared `/app/api` base so dispatch hits the exact `mountApi` route. */