@nanobpm/urban 0.86.1 → 0.87.1

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, isObjectSchema, parseSpec, resolveSchema, schemaHasType, 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) {
@@ -276,6 +257,10 @@ export function missingRequiredArgs(inputSchema, args) {
  *  read-only) app operation is then guarded exactly as its HTTP route is — the app operation tools
  *  inherit the OpenAPI `security` contract rather than a bespoke MCP gate (ADR 0067 §4). */
 function toHttpRequest(op, args, forwardHeaders) {
+    // `args.body` is expected to already be the structured value the operation declares — a
+    // pre-encoded JSON-string body is normalized upstream by `normalizeBodyArg` (called in
+    // `dispatchOperationTool`) so `JSON.stringify` here serializes an object/array ONCE rather than
+    // double-encoding a quoted string the door would reject (ADR 0067).
     const bodyText = op.requestBodySchema !== undefined && args.body !== undefined
         ? JSON.stringify(args.body)
         : "";
@@ -296,6 +281,69 @@ function toHttpRequest(op, args, forwardHeaders) {
         text: () => Promise.resolve(bodyText),
     };
 }
+/** The operation's effective request-body schema for classifying a tool-call `body`: P0's resolved,
+ *  `$ref`-free schema ({@link OperationInfo.requestBodySchemaResolved}, produced by
+ *  `collectOperations`). As defence in depth, if that metadata is somehow still a bare `$ref` (it
+ *  should never be after resolution), re-resolve it via {@link resolveSchema} against `doc` so the
+ *  classification below never keys off an opaque `#/components/...` pointer. */
+function effectiveRequestBodySchema(op, doc) {
+    const schema = op.requestBodySchemaResolved ?? op.requestBodySchema;
+    if (schema?.$ref)
+        return doc ? resolveSchema(doc, schema) : undefined;
+    return schema;
+}
+/** Whether the operation declares a STRUCTURED (object/array) request body — the shapes the app door
+ *  expects as a JSON object/array rather than a bare scalar. Classified from the RESOLVED schema so a
+ *  `$ref`-bodied op (e.g. `previewDeliveryGraph`, whose object `type` is only visible after P0's
+ *  resolution) is recognized, not merely an inline-`type` object body. */
+function structuredBodyKind(schema) {
+    if (!schema)
+        return undefined;
+    if (isObjectSchema(schema))
+        return "object";
+    if (schemaHasType(schema, "array"))
+        return "array";
+    return undefined;
+}
+/** Normalize a tool-call `body` argument for FAITHFUL transport (ADR 0067). A client that saw an
+ *  opaque input schema — or that coerces non-primitive args — may send `body` as a pre-encoded JSON
+ *  *string* instead of the object/array the operation declares. Left as-is, `toHttpRequest`'s
+ *  `JSON.stringify` would DOUBLE-encode it into a quoted string and the door would reject it with
+ *  "expected object, got string". So when the op declares an object/array body and `body` arrives as
+ *  a string, parse it once so it round-trips as the structured value. A genuine object/array argument
+ *  passes through untouched (still serialized by the transport). A string that does not parse to the
+ *  declared shape is a CLEAR tool error naming the expected shape — never a silently double-encoded
+ *  (and 4xx-rejected) request. */
+function normalizeBodyArg(op, args, doc) {
+    const body = args.body;
+    const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+    if (body === undefined || kind === undefined || typeof body !== "string") {
+        return { ok: true, args };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {
+            ok: false,
+            error: `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; the string is not valid JSON`,
+        };
+    }
+    const parsedKind = Array.isArray(parsed)
+        ? "array"
+        : parsed !== null && typeof parsed === "object"
+            ? "object"
+            : undefined;
+    if (parsedKind !== kind) {
+        const got = parsedKind ?? (parsed === null ? "null" : typeof parsed);
+        return {
+            ok: false,
+            error: `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; it parsed to a ${got}`,
+        };
+    }
+    return { ok: true, args: { ...args, body: parsed } };
+}
 /** Wrap a value as an MCP tool text result. A JSON payload is stringified; `isError` flags a
  *  non-2xx dispatch so the client sees the failure (carrying the delegate's own error body). */
 function textResult(value, isError = false) {
@@ -735,10 +783,17 @@ export function mountMcp(ctx, app, apiRoutes) {
             // empty-string substitution — the calling agent sees exactly which required params it omitted.
             return textResult({ error: `validation failed: missing required path parameter(s): ${missing.join(", ")}` }, true);
         }
+        // Faithful body transport (ADR 0067): a client may send an object/array `body` pre-encoded as a
+        // JSON string. Normalize it to the structured value from the operation's RESOLVED body schema so
+        // it is not double-encoded by `toHttpRequest`; a string that cannot parse to the declared shape
+        // is a clear tool error rather than a silent 4xx from a double-encoded body.
+        const normalized = normalizeBodyArg(op, args, (await loadSpecDoc()).doc);
+        if (!normalized.ok)
+            return textResult({ error: normalized.error }, true);
         // Forward the MCP connection's headers so the reused router enforces the operation's own
         // OpenAPI `security` (a mutating — or secured read — app op is guarded exactly as its HTTP
         // route). A `401`/`403`/`500` from that enforcement flows back as an error tool result.
-        const res = await apiRouter(toHttpRequest(op, args, headers));
+        const res = await apiRouter(toHttpRequest(op, normalized.args, headers));
         const status = res.status ?? 200;
         return textResult(res.body ?? "", status >= 400);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.86.1",
+	"version": "0.87.1",
 	"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,20 @@
 #   - 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.
+#   - an INLINE object-body op (POST)    → its request body declares `type: object`
+#                                          inline, exercising the faithful object-body
+#                                          transport path (object arg → door receives
+#                                          an object; a pre-encoded JSON string is
+#                                          parsed, not double-encoded).
 #
 # Edit this fixture ONLY together with a reviewed `npm run gen:mcp-tools`.
 openapi: 3.1.0
@@ -23,6 +37,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 +85,38 @@ 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
+  /widgets/bulk:
+    post:
+      operationId: bulkCreateWidgets
+      summary: "Bulk create widgets (mutating — inline `type: object` request body, object-arg round-trip case)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - items
+              properties:
+                items:
+                  type: array
+                  items:
+                    type: string
+                dryRun:
+                  type: boolean
+      responses:
+        "201":
+          description: created