@nanobpm/urban 0.87.0 → 0.87.1

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, toolInputSchema, } 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";
@@ -257,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)
         : "";
@@ -277,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) {
@@ -716,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.87.0",
+	"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

@@ -19,6 +19,11 @@
 #                                          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
@@ -93,3 +98,25 @@ paths:
       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

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

@@ -64,5 +64,36 @@
       "type": "object",
       "properties": {}
     }
+  },
+  {
+    "operationId": "bulkCreateWidgets",
+    "method": "post",
+    "mutating": true,
+    "excluded": false,
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "body": {
+          "type": "object",
+          "required": [
+            "items"
+          ],
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "dryRun": {
+              "type": "boolean"
+            }
+          }
+        }
+      },
+      "required": [
+        "body"
+      ]
+    }
   }
 ]

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

@@ -356,6 +356,130 @@ test("a $ref-bodied tool projects a self-contained body schema (no $ref, explici
   assert.ok(!JSON.stringify(schema).includes("$ref"), "projected body schema must not leak a $ref");
 });
 
+test("an object body reaches the door as an object; a pre-encoded JSON-string body is parsed, not double-encoded; a malformed string body is a clear error", async () => {
+  // `createInvoice`'s requestBody is `{ $ref: "#/components/schemas/Invoice" }` — an object body
+  // whose concrete `type` is only visible after the projection resolver inlines the component. The
+  // transport must classify it as an object body FROM THE RESOLVED SCHEMA (not the raw `$ref`) so the
+  // string-parse path triggers for exactly this motivating shape, not merely an inline-`type` body.
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    modules: {
+      "/app/operations/createInvoice": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine object argument reaches the door (the reused delegate) AS AN OBJECT.
+  const objCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: { id: "7", amount: 3 } },
+  });
+  assert.notEqual(objCall.result?.isError, true, `object body call must succeed: ${toolContentText(objCall.result)}`);
+  assert.deepEqual(seenBody, { id: "7", amount: 3 }, "an object body argument must reach the door as an object");
+
+  // 2. A PRE-ENCODED JSON-string body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected object, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: JSON.stringify({ id: "9", amount: 5 }) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, { id: "9", amount: 5 }, "a pre-encoded JSON-string body must be parsed to an object at the door");
+
+  // 3. A malformed string body is a CLEAR tool error naming the expected shape — never a silent 4xx
+  //    from a forwarded double-encoded body, and the delegate must not run.
+  seenBody = "unset";
+  const badCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "{not valid json" },
+  });
+  assert.equal(badCall.result?.isError, true, "a malformed string body must return an isError result");
+  assert.match(toolContentText(badCall.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a malformed string body");
+
+  // 4. A string that parses to the WRONG shape (a scalar) is likewise a clear error, not a
+  //    double-encoded forward — the object body path fails loudly on a non-object.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "42" },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to a scalar must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string body");
+});
+
+test("an array body reaches the door as an array; a pre-encoded JSON-string array body is parsed, not double-encoded; a wrong-shape string is a clear error", async () => {
+  // Mirror of the object-body transport test for the ARRAY branch: `structuredBodyKind` can return
+  // "array" and `normalizeBodyArg` has an `Array.isArray(parsed)` path, so a regression in array
+  // handling must be caught here. `createBatch`'s requestBody declares a `type: array` body — the
+  // transport must classify it as an array body and parse a pre-encoded JSON-string array once so it
+  // round-trips as an array rather than being double-encoded into a quoted string the door rejects.
+  const arraySpec = JSON.stringify({
+    openapi: "3.0.0",
+    paths: {
+      "/batch": {
+        post: {
+          operationId: "createBatch",
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "array", items: { type: "string" } } } },
+          },
+          responses: { "201": {} },
+        },
+      },
+    },
+  });
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    spec: arraySpec,
+    modules: {
+      "/app/operations/createBatch": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine array argument reaches the door (the reused delegate) AS AN ARRAY.
+  const arrCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: ["a", "b"] },
+  });
+  assert.notEqual(arrCall.result?.isError, true, `array body call must succeed: ${toolContentText(arrCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "an array body argument must reach the door as an array");
+
+  // 2. A PRE-ENCODED JSON-string array body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected array, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify(["a", "b"]) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string array body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "a pre-encoded JSON-string array body must be parsed to an array at the door");
+
+  // 3. A string that parses to the WRONG shape (an object) is a clear error naming the expected
+  //    array shape, not a double-encoded forward — and the delegate must not run.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify({ not: "an array" }) },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to an object must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /array/i, "the error must name the expected array shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string array body");
+});
+
 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

@@ -50,9 +50,13 @@ import {
   collectOperations,
   evaluateSecurity,
   isMutatingMethod,
+  isObjectSchema,
   type OpenApiDoc,
+  type OpenApiSchema,
   type OperationInfo,
   parseSpec,
+  resolveSchema,
+  schemaHasType,
   type SecurityDecision,
   sharedSecretSchemeName,
   toolInputSchema,
@@ -336,6 +340,10 @@ function toHttpRequest(
   args: Record<string, unknown>,
   forwardHeaders: Record<string, string | string[] | undefined>,
 ): HttpRequest {
+  // `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)
     : "";
@@ -354,6 +362,76 @@ function toHttpRequest(
   };
 }
 
+/** 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: OperationInfo,
+  doc: OpenApiDoc | undefined,
+): OpenApiSchema | undefined {
+  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: OpenApiSchema | undefined): "object" | "array" | undefined {
+  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: OperationInfo,
+  args: Record<string, unknown>,
+  doc: OpenApiDoc | undefined,
+): { ok: true; args: Record<string, unknown> } | { ok: false; error: string } {
+  const body = args.body;
+  const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+  if (body === undefined || kind === undefined || typeof body !== "string") {
+    return { ok: true, args };
+  }
+  let parsed: unknown;
+  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: unknown, isError = false): {
@@ -838,10 +916,16 @@ export function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]):
         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);
   };