stitchkit 0.36.1 → 0.38.0

package/dist/tools.js

@@ -2,42 +2,46 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-bx49hskg.js";
+} from "./index-bgdd42pt.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-czmqks7r.js";
 import {
   assertToolName,
   assertUniqueToolName,
+  buildToolPresentationSchema,
   coerceJsonArgs,
   collectTools,
   createCli,
   createToolRunner,
+  executeToolMethod,
   fetchGuarded,
-  flattenDiscriminatedUnion,
-  flattenUnionsDeep,
+  flattenToolJsonSchema,
   formatToolError,
+  isObjectPresentationSchema,
   pollUntil,
+  presentationMetadata,
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-82gncajj.js";
+} from "./index-n5t4gnfz.js";
 import {
   toJsonSchema
-} from "./index-0ed3bx43.js";
+} from "./index-frfyw9fa.js";
 import {
   isWithinDir
 } from "./index-x3fcszf8.js";
 import {
   AppError,
+  formatZodError,
   getTraceId,
   isRecord,
   mergeMeta,
   typedEntries
-} from "./index-17rdjw68.js";
+} from "./index-mzx0an0s.js";
 
 // src/tools/agent.ts
-import { tool, zodSchema } from "ai";
+import { jsonSchema, tool } from "ai";
 function mountAgent(services, config = {}) {
   const serviceList = Array.isArray(services) ? services : [services];
   const tools = {};
@@ -59,7 +63,9 @@ function mountAgent(services, config = {}) {
       assertUniqueToolName(mountable.name, Object.hasOwn(tools, mountable.name), "agent tool name");
       tools[mountable.name] = tool({
         description: mountable.method.desc,
-        inputSchema: zodSchema(mountable.schema),
+        inputSchema: jsonSchema(mountable.presentationSchema, {
+          validate: async (value) => isRecord(value) ? { success: true, value } : { success: false, error: new Error("Tool arguments must be an object") }
+        }),
         execute: async (rawArgs) => {
           const args = isRecord(rawArgs) ? rawArgs : {};
           try {
@@ -102,19 +108,15 @@ function listToolNames(services) {
 }
 // src/tools/manifest.ts
 function buildToolManifest(tools) {
-  return tools.map((t) => {
-    let inputSchema;
-    try {
-      inputSchema = toJsonSchema(t.schema, "input");
-    } catch {
-      inputSchema = {};
-    }
-    return { name: t.name, description: t.method.desc, inputSchema };
-  });
+  return tools.map((tool2) => ({
+    name: tool2.name,
+    description: tool2.method.desc,
+    inputSchema: tool2.presentationSchema
+  }));
 }
 // src/tools/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/tools/mcp-app.ts
 import { readFileSync } from "node:fs";
@@ -137,6 +139,192 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/native-mcp.ts
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+function operationIdentity(definition) {
+  return {
+    method: definition.identity.method,
+    desc: definition.description,
+    serviceName: definition.identity.serviceName,
+    key: definition.identity.action,
+    toolName: definition.name,
+    scope: definition.identity.scope,
+    meta: definition.identity.meta,
+    annotations: definition.annotations,
+    ui: definition.ui
+  };
+}
+function isCallToolResult(value) {
+  return CallToolResultSchema.safeParse(value).success;
+}
+function nativeResultSchema(output) {
+  const envelope = z.custom(isCallToolResult, {
+    error: "Native MCP handler must return a valid CallToolResult"
+  });
+  if (!output)
+    return envelope;
+  return envelope.transform((result, context) => {
+    const parsed = output.safeParse(result.structuredContent);
+    if (!parsed.success) {
+      context.addIssue({
+        code: "custom",
+        message: `Invalid structuredContent: ${formatZodError(parsed.error)}`
+      });
+      return z.NEVER;
+    }
+    return { ...result, structuredContent: parsed.data };
+  });
+}
+function createNativeMcpRegistrar(server, config) {
+  return {
+    rawServer: server,
+    registerTool: (definition) => {
+      const identity = operationIdentity(definition);
+      const advertisedOperation = {
+        ...identity,
+        inputSchema: definition.input,
+        outputSchema: definition.output,
+        handler: () => {
+          return;
+        }
+      };
+      const mountable = {
+        method: advertisedOperation,
+        name: definition.name,
+        argumentSchema: definition.input,
+        presentationSchema: buildToolPresentationSchema({
+          inputSchema: definition.input,
+          unrepresentable: "any"
+        }),
+        shouldExtend: false
+      };
+      const [prepared] = config.prepare(mountable);
+      if (!prepared)
+        return;
+      const executionOperation = {
+        ...identity,
+        inputSchema: definition.input,
+        outputSchema: nativeResultSchema(definition.output),
+        handler: definition.handler
+      };
+      const toolConfig = {
+        description: definition.description,
+        inputSchema: z.looseObject({}).meta(presentationMetadata(prepared.inputSchema))
+      };
+      if (prepared.outputSchema)
+        toolConfig.outputSchema = prepared.outputSchema;
+      if (definition.annotations)
+        toolConfig.annotations = definition.annotations;
+      if (definition.ui) {
+        toolConfig._meta = {
+          ui: definition.ui,
+          "ui/resourceUri": definition.ui.resourceUri
+        };
+      }
+      server.registerTool(definition.name, toolConfig, async (rawArgs) => {
+        const args = isRecord(rawArgs) ? rawArgs : {};
+        const result = await executeToolMethod(executionOperation, definition.name, args, { ...config.context, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
+        if (!result.ok)
+          return config.formatError(result, definition.name);
+        if (isCallToolResult(result.data))
+          return result.data;
+        return config.formatError({
+          ok: false,
+          code: "INTERNAL_SERVER_ERROR",
+          details: { message: "Native MCP handler returned an invalid result" }
+        }, definition.name);
+      });
+    }
+  };
+}
+
+// src/tools/portable-formats.ts
+var PORTABLE_JSON_SCHEMA_FORMATS = new Set([
+  "date",
+  "time",
+  "date-time",
+  "duration",
+  "uri",
+  "uri-reference",
+  "uri-template",
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "regex",
+  "uuid",
+  "json-pointer",
+  "relative-json-pointer"
+]);
+function propertyPath(prefix, property) {
+  return prefix ? `${prefix}.${property}` : property;
+}
+function keywordPath(prefix, keyword) {
+  if (prefix && keyword.startsWith("["))
+    return `${prefix}${keyword}`;
+  return prefix ? `${prefix}.${keyword}` : keyword;
+}
+function findNonPortableFormats(schema, allowFormats = []) {
+  const allowed = new Set([...PORTABLE_JSON_SCHEMA_FORMATS, ...allowFormats]);
+  const found = [];
+  const pending = [{ value: schema, path: "" }];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current || !isRecord(current.value))
+      continue;
+    const format = current.value.format;
+    if (typeof format === "string" && !allowed.has(format)) {
+      found.push({ path: current.path || "(root)", format });
+    }
+    const properties = current.value.properties;
+    if (isRecord(properties)) {
+      for (const [key, value] of Object.entries(properties)) {
+        pending.push({ value, path: propertyPath(current.path, key) });
+      }
+    }
+    for (const mapKey of ["$defs", "definitions", "patternProperties", "dependentSchemas"]) {
+      const entries = current.value[mapKey];
+      if (!isRecord(entries))
+        continue;
+      for (const [key, value] of Object.entries(entries)) {
+        pending.push({ value, path: keywordPath(current.path, `${mapKey}.${key}`) });
+      }
+    }
+    const directChildren = [
+      ["items", "[]"],
+      ["contains", "contains"],
+      ["additionalProperties", "*"],
+      ["unevaluatedProperties", "*"],
+      ["propertyNames", "propertyNames"],
+      ["not", "not"],
+      ["if", "if"],
+      ["then", "then"],
+      ["else", "else"]
+    ];
+    for (const [keyword, segment] of directChildren) {
+      const child = current.value[keyword];
+      if (isRecord(child)) {
+        pending.push({ value: child, path: keywordPath(current.path, segment) });
+      }
+      if (Array.isArray(child)) {
+        child.forEach((value, index) => {
+          pending.push({ value, path: keywordPath(current.path, `${segment}[${index}]`) });
+        });
+      }
+    }
+    for (const keyword of ["prefixItems", "allOf", "anyOf", "oneOf"]) {
+      const branches = current.value[keyword];
+      if (!Array.isArray(branches))
+        continue;
+      branches.forEach((value, index) => {
+        pending.push({ value, path: keywordPath(current.path, `${keyword}[${index}]`) });
+      });
+    }
+  }
+  return found.sort((left, right) => left.path.localeCompare(right.path) || left.format.localeCompare(right.format));
+}
+
 // src/tools/untyped-properties.ts
 var TYPE_KEYWORDS = ["type", "enum", "const", "anyOf", "oneOf", "allOf", "$ref", "not"];
 function saysWhatItIs(schema) {
@@ -239,10 +427,10 @@ function probeSchema(schema, io) {
 function resolveOutputSchema(outputSchema) {
   if (!outputSchema)
     return null;
-  if (outputSchema instanceof z.ZodObject) {
+  if (outputSchema instanceof z2.ZodObject) {
     return { schema: outputSchema, mode: "direct" };
   }
-  return { schema: z.object({ result: outputSchema }), mode: "wrapped" };
+  return { schema: z2.object({ result: outputSchema }), mode: "wrapped" };
 }
 function reportIncompatible(message, policy, logger, failures) {
   if (policy === "throw") {
@@ -261,51 +449,99 @@ function throwIfFailures(failures) {
  - `)}`);
   }
 }
-function prepareMcpTool(mountable, policy, logger, failures, seen) {
+function prepareMcpTool(mountable, config, validation, logger, failures, seen) {
+  const policy = validation.policy ?? "throw";
   assertUniqueToolName(mountable.name, seen.has(mountable.name), "MCP tool name");
   seen.add(mountable.name);
-  if (!(mountable.schema instanceof z.ZodObject)) {
-    reportIncompatible(`MCP tool "${mountable.name}" — input must be an object schema; a union, discriminated union or scalar cannot be an MCP tool input (flatten it in the contract, or drop MCP from \`expose\`)`, policy, logger, failures);
+  let inputJsonSchema;
+  try {
+    inputJsonSchema = buildToolPresentationSchema({
+      paramsSchema: mountable.method.paramsSchema,
+      inputSchema: mountable.method.inputSchema,
+      extendSchema: mountable.shouldExtend && config.extend ? config.extend.schema : undefined,
+      flattenUnionInput: config.flattenUnionInput,
+      unrepresentable: "throw"
+    });
+  } catch (err) {
+    reportIncompatible(`MCP tool "${mountable.name}" — input schema is not JSON Schema-compatible: ${err instanceof Error ? err.message : String(err)}`, policy, logger, failures);
     return null;
   }
-  const inputError = probeSchema(mountable.schema, "input");
-  if (inputError) {
-    reportIncompatible(`MCP tool "${mountable.name}" — input schema is not JSON Schema-compatible: ${inputError}`, policy, logger, failures);
+  if (!isObjectPresentationSchema(inputJsonSchema)) {
+    reportIncompatible(`MCP tool "${mountable.name}" — input must be an object schema; a union, discriminated union or scalar cannot be an MCP tool input (flatten it in the contract, or drop MCP from \`expose\`)`, policy, logger, failures);
     return null;
   }
+  if (validation.requireTypedProperties) {
+    const allowed = new Set(validation.allowUntyped ?? []);
+    for (const untyped of findUntypedProperties(inputJsonSchema)) {
+      const path = `${mountable.name}.${untyped.path}`;
+      if (allowed.has(path))
+        continue;
+      const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
+      reportIncompatible(`MCP tool "${mountable.name}" — input property "${untyped.path}" carries no type, enum or $ref${clue}. ` + "A model is given no way to know what to send. Widen the contract, or list it in `allowUntyped` if it is deliberately free-form.", policy === "skip" ? "warn" : policy, logger, failures);
+    }
+  }
+  if (validation.requirePortableFormats) {
+    for (const finding of findNonPortableFormats(inputJsonSchema, validation.allowFormats)) {
+      reportIncompatible(`MCP tool "${mountable.name}" — input property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". ` + "Use a portable pattern/schema, or list the format in `allowFormats` only when every MCP client supports it.", policy === "skip" ? "warn" : policy, logger, failures);
+    }
+  }
   const resolved = resolveOutputSchema(mountable.method.outputSchema);
   if (!resolved)
-    return { outputMode: "none" };
+    return { mountable, inputSchema: inputJsonSchema, outputMode: "none" };
   const outputError = probeSchema(resolved.schema, "output");
   if (outputError) {
     reportIncompatible(`MCP tool "${mountable.name}" — output schema is not JSON Schema-compatible: ${outputError}`, policy, logger, failures);
-    return { outputMode: "none" };
+    return { mountable, inputSchema: inputJsonSchema, outputMode: "none" };
+  }
+  if (validation.requirePortableFormats) {
+    for (const finding of findNonPortableFormats(toJsonSchema(resolved.schema, "output"), validation.allowFormats)) {
+      reportIncompatible(`MCP tool "${mountable.name}" — output property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". ` + "Use a portable pattern/schema, or list the format in `allowFormats` only when every MCP client supports it.", policy === "skip" ? "warn" : policy, logger, failures);
+    }
   }
-  return { outputSchema: resolved.schema, outputMode: resolved.mode };
+  return {
+    mountable,
+    inputSchema: inputJsonSchema,
+    outputSchema: resolved.schema,
+    outputMode: resolved.mode
+  };
+}
+function prepareMcpSurface(services, config = {}) {
+  const serviceList = Array.isArray(services) ? services : [services];
+  const tools = serviceList.flatMap((service) => collectTools(service, "MCP", config));
+  return prepareMcpTools(tools, config);
 }
-function validateMcpSchemas(services, onIncompatibleSchema = "throw", logger, options) {
+function prepareMcpTools(tools, config = {}) {
   const seen = new Set;
   const failures = [];
-  const allowed = new Set(options?.allowUntyped ?? []);
-  for (const service of services) {
-    for (const mountable of collectTools(service, "MCP", options)) {
-      const prepared = prepareMcpTool(mountable, onIncompatibleSchema, logger, failures, seen);
-      if (!prepared || !options?.requireTypedProperties)
-        continue;
-      for (const untyped of findUntypedProperties(toJsonSchema(mountable.schema, "input"))) {
-        const path = `${mountable.name}.${untyped.path}`;
-        if (allowed.has(path))
-          continue;
-        const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
-        reportIncompatible(`MCP tool "${mountable.name}" — property "${untyped.path}" carries no type, enum or $ref${clue}. ` + "A model is given no way to know what to send. Widen the contract, or list it in `allowUntyped` if it is deliberately free-form.", onIncompatibleSchema === "skip" ? "warn" : onIncompatibleSchema, logger, failures);
-      }
+  const prepared = [];
+  for (const mountable of tools) {
+    const tool2 = prepareMcpTool(mountable, config, config.schemaValidation ?? {}, config.logger, failures, seen);
+    if (tool2) {
+      Object.freeze(tool2.mountable);
+      prepared.push(Object.freeze(tool2));
     }
   }
   throwIfFailures(failures);
+  return Object.freeze(prepared);
+}
+function validateMcpSchemas(config) {
+  prepareMcpSurface(config.services, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config,
+    logger: config.logger
+  });
 }
 function mountMcp(mcpServer, services, config = {}) {
-  const serviceList = Array.isArray(services) ? services : [services];
-  const policy = config.onIncompatibleSchema ?? "throw";
+  const prepared = prepareMcpSurface(services, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation,
+    logger: config.logger
+  });
+  mountPreparedMcp(mcpServer, prepared, config);
+}
+function mountPreparedMcp(mcpServer, prepared, config = {}) {
   const runTool = createToolRunner({
     source: "mcp",
     extend: config.extend,
@@ -316,57 +552,74 @@ function mountMcp(mcpServer, services, config = {}) {
     coerceJsonArgs: config.coerceJsonArgs,
     onOutputStrip: config.onOutputStrip
   });
-  const seen = new Set;
-  const failures = [];
-  for (const service of serviceList) {
-    for (const mountable of collectTools(service, "MCP", {
-      extend: config.extend,
-      flattenUnionInput: config.flattenUnionInput
-    })) {
-      const prepared = prepareMcpTool(mountable, policy, config.logger, failures, seen);
-      if (!prepared)
-        continue;
-      const toolConfig = { description: mountable.method.desc, inputSchema: mountable.schema };
-      if (prepared.outputSchema)
-        toolConfig.outputSchema = prepared.outputSchema;
-      if (mountable.method.annotations) {
-        toolConfig.annotations = mountable.method.annotations;
-      }
-      if (mountable.method.ui) {
-        toolConfig._meta = {
-          ui: mountable.method.ui,
-          "ui/resourceUri": mountable.method.ui.resourceUri
-        };
-      }
-      mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs) => {
-        const args = isRecord(rawArgs) ? rawArgs : {};
-        try {
-          const result = await runTool(mountable, args);
-          return formatMcpResult(result, prepared.outputMode, mountable.name, config.errorHint);
-        } catch (err) {
-          return formatMcpResult(toolResultFromError(err), "none", mountable.name, config.errorHint);
-        }
-      });
+  for (const descriptor of prepared) {
+    const { mountable } = descriptor;
+    const toolConfig = {
+      description: mountable.method.desc,
+      inputSchema: z2.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+    };
+    if (descriptor.outputSchema)
+      toolConfig.outputSchema = descriptor.outputSchema;
+    if (mountable.method.annotations) {
+      toolConfig.annotations = mountable.method.annotations;
     }
+    if (mountable.method.ui) {
+      toolConfig._meta = {
+        ui: mountable.method.ui,
+        "ui/resourceUri": mountable.method.ui.resourceUri
+      };
+    }
+    mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs) => {
+      const args = isRecord(rawArgs) ? rawArgs : {};
+      try {
+        const result = await runTool(mountable, args);
+        return formatMcpResult(result, descriptor.outputMode, mountable.name, config.errorHint);
+      } catch (err) {
+        return formatMcpResult(toolResultFromError(err), "none", mountable.name, config.errorHint);
+      }
+    });
   }
-  throwIfFailures(failures);
 }
 function buildMcpServer(config, auth) {
-  const server = new McpServer(config.serverInfo, config.instructions ? { instructions: config.instructions } : undefined);
   const services = typeof config.services === "function" ? config.services(auth) : config.services;
+  const prepared = prepareMcpSurface(services, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation,
+    logger: config.logger
+  });
+  return buildMcpServerFromPrepared(config, auth, prepared);
+}
+function buildMcpServerFromPrepared(config, auth, prepared) {
+  const server = new McpServer(config.serverInfo, config.instructions ? { instructions: config.instructions } : undefined);
   const context = config.context?.(auth);
-  mountMcp(server, services, {
+  mountPreparedMcp(server, prepared, {
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     extend: config.extend,
-    onIncompatibleSchema: config.onIncompatibleSchema,
+    schemaValidation: config.schemaValidation,
     logger: config.logger,
     coerceJsonArgs: config.coerceJsonArgs,
     flattenUnionInput: config.flattenUnionInput,
-    errorHint: config.errorHint
+    errorHint: config.errorHint,
+    onOutputStrip: config.onOutputStrip
   });
-  config.nativeTools?.(server, auth);
+  if (config.nativeTools) {
+    const registrar = createNativeMcpRegistrar(server, {
+      context,
+      hooks: config.hooks,
+      lifecycle: config.lifecycle,
+      coerceJsonArgs: config.coerceJsonArgs,
+      onOutputStrip: config.onOutputStrip,
+      prepare: (tool2) => prepareMcpTools([tool2], {
+        schemaValidation: config.schemaValidation,
+        logger: config.logger
+      }),
+      formatError: (result, toolName) => formatMcpResult(result, "none", toolName, config.errorHint)
+    });
+    config.nativeTools(registrar, auth);
+  }
   for (const resource of config.resources ?? []) {
     mountMcpResource(server, resource);
   }
@@ -477,17 +730,23 @@ function jsonRpcError(code, message, status, headers) {
   return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
 }
 function createMcpHandler(config) {
+  let buildServer;
   if (Array.isArray(config.services)) {
-    validateMcpSchemas(config.services, config.onIncompatibleSchema, config.logger, {
+    const prepared = prepareMcpSurface(config.services, {
+      logger: config.logger,
       extend: config.extend,
-      flattenUnionInput: config.flattenUnionInput
+      flattenUnionInput: config.flattenUnionInput,
+      schemaValidation: config.schemaValidation
     });
+    buildServer = (auth) => buildMcpServerFromPrepared(config, auth, prepared);
+  } else {
+    buildServer = (auth) => buildMcpServer(config, auth);
   }
   const unauthorized = () => {
     const headers = config.protectedResource ? { "WWW-Authenticate": wwwAuthenticateHeader(config.protectedResource.resource) } : undefined;
     return jsonRpcError(-32001, "Authorization required", 401, headers);
   };
-  if (config.stateless) {
+  if ((config.sessionMode ?? "stateless") === "stateless") {
     return async (req) => {
       const auth = await config.auth(req);
       if (!auth)
@@ -496,7 +755,7 @@ function createMcpHandler(config) {
         sessionIdGenerator: undefined,
         enableJsonResponse: true
       });
-      const server = buildMcpServer(config, auth);
+      const server = buildServer(auth);
       await server.connect(transport);
       return transport.handleRequest(req);
     };
@@ -555,7 +814,7 @@ function createMcpHandler(config) {
       sessionIdGenerator: () => newSessionId,
       eventStore
     });
-    const server = buildMcpServer(config, auth);
+    const server = buildServer(auth);
     sessions.set(newSessionId, { transport, server, lastSeen: Date.now() });
     transport.onclose = () => {
       sessions.delete(newSessionId);
@@ -644,13 +903,13 @@ function mountDownload(server, config) {
   });
 }
 // src/tools/mount-upload.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function mountUpload(server, config) {
   const name = config.name ?? "upload";
   assertToolName(name, "<native>", "upload");
   server.registerTool(name, {
     description: config.description,
-    inputSchema: { path: z2.string().describe("Path to a local file on this machine") }
+    inputSchema: { path: z3.string().describe("Path to a local file on this machine") }
   }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     const path = typeof args.path === "string" ? args.path : "";
@@ -976,6 +1235,117 @@ function appendFormFields(formData, values, skipKeys) {
   }
 }
 
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+}
+function collectQueryParams(args, endpoint) {
+  const params = {};
+  let hasParams = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
+      params[key] = value;
+      hasParams = true;
+      continue;
+    }
+    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
+    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+  }
+  return hasParams ? params : undefined;
+}
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function resolvePathPrefix(config, args) {
+  if (!config?.pathPrefix)
+    return "";
+  if (typeof config.pathPrefix === "string")
+    return config.pathPrefix;
+  const keys = config.stripPrefixKeys ?? [];
+  if (!hasStringKeys(args, keys)) {
+    const missing = keys.find((key) => typeof args[key] !== "string");
+    throw new Error(`Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
+}
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  if (path.endsWith("/*"))
+    names.push("*");
+  return names;
+}
+function fillPathParams(path, args) {
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw new Error(`Missing path param: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (!filled.endsWith("/*"))
+    return filled;
+  const wildcard = args["*"];
+  if (wildcard === undefined || wildcard === null) {
+    throw new Error("Missing path param: *");
+  }
+  const remainder = String(wildcard).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -1)}${remainder}`;
+  return filled;
+}
+function stripConsumedArgs(args, path, scopeKeys) {
+  const consumed = new Set(scopeKeys);
+  for (const name of extractParamNames(path))
+    consumed.add(name);
+  const remaining = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key) && value !== undefined)
+      remaining[key] = value;
+  }
+  return remaining;
+}
+function appendQuery(relativeUrl, params) {
+  if (!params)
+    return relativeUrl;
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, String(item));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search.size > 0 ? `${relativeUrl}?${search}` : relativeUrl;
+}
+function planClientRequest(endpoint, contractPrefix, args, config) {
+  let pathPrefix = resolvePathPrefix(config, args);
+  if (pathPrefix && !pathPrefix.endsWith("/"))
+    pathPrefix += "/";
+  if (pathPrefix.startsWith("/"))
+    pathPrefix = pathPrefix.slice(1);
+  const endpointPath = endpoint.path === "/" ? "" : endpoint.path;
+  let relativeUrl = fillPathParams(`${pathPrefix}${contractPrefix}${endpointPath}`, args);
+  if (relativeUrl.endsWith("/"))
+    relativeUrl = relativeUrl.slice(0, -1);
+  const remainingArgs = stripConsumedArgs(args, endpoint.path, config?.stripPrefixKeys ?? []);
+  if (inputIsQuery(endpoint.method)) {
+    relativeUrl = appendQuery(relativeUrl, collectQueryParams(remainingArgs, endpoint));
+  }
+  return { relativeUrl, remainingArgs };
+}
+function joinClientBaseUrl(baseUrl, relativeUrl) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
+  return `${base}${path}`;
+}
+
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 class ApiError extends Error {
@@ -1026,25 +1396,6 @@ function withOutput(endpoint, result) {
     return result;
   return result.then((value) => value === undefined ? undefined : schema.parse(value));
 }
-function isParamArray(value) {
-  return Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number");
-}
-function collectQueryParams(args, skipKeys, endpoint) {
-  const params = {};
-  let hasParams = false;
-  for (const [key, value] of Object.entries(args)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
-      params[key] = value;
-      hasParams = true;
-      continue;
-    }
-    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
-    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
-  }
-  return hasParams ? params : undefined;
-}
 function createClient(contract, configOrClient, contractConfig) {
   const client = {};
   const makeMethod = isHttpAdapter(configOrClient) ? (endpoint) => createHttpMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig);
@@ -1063,27 +1414,9 @@ function setClientMethod(target, key, method) {
 }
 function createHttpMethod(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
-  const isGet = httpMethod === "get";
-  const paramNames = extractParamNames(endpoint.path);
-  const prefixKeys = new Set([...config?.stripPrefixKeys ?? [], ...paramNames]);
   return (...args) => {
     const firstArg = args[0] ?? {};
-    let pathPrefixStr = "";
-    if (config?.pathPrefix) {
-      pathPrefixStr = typeof config.pathPrefix === "function" ? config.pathPrefix(firstArg) : config.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = `${pathPrefixStr}${prefix}${endpoint.path}`;
-    for (const name of paramNames) {
-      const value = firstArg[name];
-      if (value === undefined || value === null) {
-        throw new Error(`Missing path param: ${name}`);
-      }
-      url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-    }
-    if (url.endsWith("/"))
-      url = url.slice(0, -1);
+    const plan = planClientRequest(endpoint, prefix, firstArg, config);
     if (endpoint.multipart) {
       const file = firstArg[endpoint.multipart];
       if (!isMultipartFile(file)) {
@@ -1094,59 +1427,28 @@ function createHttpMethod(endpoint, prefix, client, config) {
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint)));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(undefined, endpoint)));
     }
-    if (isGet) {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint)));
+    if (httpMethod === "get") {
+      return withOutput(endpoint, client.get(plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
     if (httpMethod === "delete") {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint)));
-    }
-    const payload = {};
-    for (const [key, value] of Object.entries(firstArg)) {
-      if (!prefixKeys.has(key) && value !== undefined) {
-        payload[key] = value;
-      }
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
-    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint)));
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(undefined, endpoint)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
-  const prefixKeys = new Set(contractConfig?.stripPrefixKeys ?? []);
   return async (args) => {
-    let pathPrefixStr = "";
-    if (contractConfig?.pathPrefix) {
-      pathPrefixStr = typeof contractConfig.pathPrefix === "function" ? contractConfig.pathPrefix(args ?? {}) : contractConfig.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = buildFetchUrl(config.baseUrl, prefix, endpoint.path, args, pathPrefixStr);
+    const plan = planClientRequest(endpoint, prefix, args ?? {}, contractConfig);
+    const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
     const headers = {
       Accept: "application/json",
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
     const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
-    const isQuery = inputIsQuery(endpoint.method);
-    const hasBody = !isQuery && !endpoint.multipart && endpoint.input && args;
-    if (isQuery && args) {
-      const remaining = stripParams(args, endpoint.path, prefixKeys);
-      const params = collectQueryParams(remaining, new Set, endpoint);
-      if (params) {
-        const searchParams = new URLSearchParams;
-        for (const [k, v] of Object.entries(params)) {
-          if (Array.isArray(v)) {
-            for (const item of v)
-              searchParams.append(k, String(item));
-          } else {
-            searchParams.set(k, String(v));
-          }
-        }
-        url += `?${searchParams}`;
-      }
-    }
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
     if (hasBody)
       headers["Content-Type"] = "application/json";
     if (endpoint.multipart && args) {
@@ -1156,7 +1458,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, stripParams(args, endpoint.path, prefixKeys), new Set([endpoint.multipart]));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
       const res2 = await fetch(url, {
         method: endpoint.method,
         headers,
@@ -1180,7 +1482,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       credentials: config.credentials,
       signal,
       ...hasBody && {
-        body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
+        body: JSON.stringify(plan.remainingArgs)
       }
     });
     if (!res.ok) {
@@ -1203,36 +1505,6 @@ async function throwForErrorResponse(res, config, fallbackBody) {
   }
   throw new ApiError("HTTP_ERROR", res.status, { body });
 }
-function extractParamNames(path) {
-  const matches = path.match(/:(\w+)/g);
-  return matches ? matches.map((m) => m.slice(1)) : [];
-}
-function buildFetchUrl(baseUrl, prefix, path, args, pathPrefix = "") {
-  let fullPath = `/${pathPrefix}${prefix}${path === "/" ? "" : path}`;
-  if (args) {
-    fullPath = fullPath.replace(/:(\w+)/g, (_, key) => {
-      const val = args[key];
-      if (val === undefined || val === null) {
-        throw new Error(`Missing path param: ${key}`);
-      }
-      return encodeURIComponent(String(val));
-    });
-  }
-  return `${baseUrl}${fullPath}`;
-}
-function stripParams(args, path, extra) {
-  const skip = new Set(extra);
-  for (const match of path.matchAll(/:(\w+)/g)) {
-    if (match[1])
-      skip.add(match[1]);
-  }
-  const result = {};
-  for (const [k, v] of Object.entries(args)) {
-    if (!skip.has(k))
-      result[k] = v;
-  }
-  return result;
-}
 
 // src/tools/remote.ts
 var HTTP_ONLY = Object.freeze(["HTTP"]);
@@ -1255,7 +1527,7 @@ function implementRemote(contract, http, options) {
       serviceName: contract.meta.prefix,
       key,
       toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
-      expose: endpoint.rawResponse ? HTTP_ONLY : endpoint.expose,
+      expose: endpoint.rawResponse || endpoint.rawBody || endpoint.responseMeta ? HTTP_ONLY : endpoint.expose,
       ui: "ui" in endpoint ? endpoint.ui : undefined,
       annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
       meta: mergeMeta(contract.meta.meta, endpoint.meta),
@@ -1264,8 +1536,11 @@ function implementRemote(contract, http, options) {
       inputSchema: endpoint.input,
       outputSchema: endpoint.output,
       multipart: endpoint.multipart,
+      maxJsonBodyBytes: endpoint.maxJsonBodyBytes,
       idempotent: endpoint.idempotent,
       rawResponse: endpoint.rawResponse,
+      rawBody: endpoint.rawBody,
+      responseMeta: endpoint.responseMeta,
       contentType: "contentType" in endpoint ? endpoint.contentType : undefined,
       handler: async (ctx) => {
         const call = client[key];
@@ -1296,7 +1571,7 @@ function implementRemote(contract, http, options) {
 function createToolLogger(config = {}) {
   const log = config.log ?? ((line) => console.info(line));
   return {
-    afterToolCall: (toolName, _args, result, durationMs, context, endpoint) => {
+    afterToolCall: ({ toolName, result, durationMs, context, endpoint }) => {
       const record = {
         tool: toolName,
         service: endpoint.serviceName,
@@ -1350,7 +1625,7 @@ function summarizeTransports(services) {
 // src/tools/view-file.ts
 import { readFile, realpath, stat } from "node:fs/promises";
 import { extname as extname2, resolve } from "node:path";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var MAX_INLINE_BYTES = 20 * 1024 * 1024;
 var EXT_MIME = {
   ".png": "image/png",
@@ -1450,7 +1725,7 @@ function mountViewFile(server, options = {}) {
   server.registerTool("view_file", {
     description: "View media (image, audio, video) by URL or local path — returns it as content you can SEE / HEAR. Pass several paths to view multiple files at once. Use it on a generation `output` url to inspect the result.",
     inputSchema: {
-      paths: z3.union([z3.string(), z3.array(z3.string())]).describe("Media URL(s) or file path(s) to view")
+      paths: z4.union([z4.string(), z4.array(z4.string())]).describe("Media URL(s) or file path(s) to view")
     },
     annotations: { title: "View Media", readOnlyHint: true, idempotentHint: true }
   }, async (args) => {
@@ -1487,9 +1762,9 @@ export {
   listToolNames,
   inlineMcpAppBundle,
   implementRemote,
-  flattenUnionsDeep,
-  flattenDiscriminatedUnion,
+  flattenToolJsonSchema,
   findUntypedProperties,
+  findNonPortableFormats,
   createToolkit,
   createToolLogger,
   createStdioMcpServer,
@@ -1501,5 +1776,6 @@ export {
   buildMcpServer,
   RESOURCE_MIME_TYPE,
   PROTECTED_RESOURCE_PATH,
+  PORTABLE_JSON_SCHEMA_FORMATS,
   EXT_APPS_BUNDLE_PLACEHOLDER
 };