fastmcp 4.24.4 → 4.25.0

package/dist/openapi/index.js

@@ -2,630 +2,739 @@ import {
   FastMCP,
   UserError,
   jsonSchemaAdapter
-} from "../chunk-D2CVYAA5.js";
-import "../chunk-CAQLTSJ5.js";
+} from "../chunk-PU3JOW7T.js";
+import "../chunk-JFHOYU3S.js";
 import "../chunk-OKKFL2M4.js";
 
 // src/openapi/loadSpec.ts
 import SwaggerParser from "@apidevtools/swagger-parser";
-async function loadSpec(spec) {
-  const document = await SwaggerParser.bundle(
-    spec
+
+// src/openapi/schemas.ts
+var SCHEMA_MAP_KEYS = /* @__PURE__ */ new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties"
+]);
+var DATA_KEYS = /* @__PURE__ */ new Set([
+  "const",
+  "default",
+  "enum",
+  "example",
+  "examples"
+]);
+var STRIP_KEYS = /* @__PURE__ */ new Set(["example", "examples"]);
+function buildFlatSchema(route, sharedDefs) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const param of route.parameters) {
+    const list = byName.get(param.name) ?? [];
+    list.push(param);
+    byName.set(param.name, list);
+  }
+  const {
+    bodyEncoding,
+    properties: bodyProperties,
+    unsupportedBodyContentType,
+    wholeBodyKey
+  } = extractBodyProperties(
+    route.method === "get" ? void 0 : route.requestBody,
+    sharedDefs
   );
-  if (!document.openapi?.startsWith("3.")) {
-    throw new Error(
-      `fromOpenAPI only supports OpenAPI 3.x documents (found ${document.openapi ?? document.swagger ?? "an unrecognized version"}). Swagger 2.0 is not supported.`
-    );
+  const properties = /* @__PURE__ */ Object.create(null);
+  const required = [];
+  const parameterMap = /* @__PURE__ */ Object.create(null);
+  const used = new Set(bodyProperties.keys());
+  for (const [name, occurrences] of byName) {
+    if (occurrences.length === 1 && !bodyProperties.has(name)) {
+      used.add(name);
+    }
+  }
+  const allocateAlias = (base) => {
+    let key = base;
+    let suffix = 1;
+    while (used.has(key)) {
+      suffix += 1;
+      key = `${base}_${suffix}`;
+    }
+    used.add(key);
+    return key;
+  };
+  for (const [name, occurrences] of byName) {
+    const collides = name === "__proto__" || occurrences.length > 1 || bodyProperties.has(name);
+    for (const param of occurrences) {
+      const base = collides ? `${name}__${param.in}` : name;
+      const key = collides ? allocateAlias(base) : name;
+      properties[key] = rewriteComponentRefs(
+        param.schema ?? { type: "string" }
+      );
+      parameterMap[key] = {
+        allowReserved: param.allowReserved,
+        explode: param.explode,
+        in: param.in,
+        name,
+        style: param.style
+      };
+      if (param.in === "path" || param.required) {
+        required.push(key);
+      }
+    }
+  }
+  const bodyKeys = [];
+  const requiredBodyKeys = [];
+  for (const [name, { required: isRequired, schema }] of bodyProperties) {
+    const key = name === "__proto__" ? allocateAlias(`${name}__body`) : name;
+    properties[key] = rewriteComponentRefs(schema);
+    parameterMap[key] = { in: "body", name };
+    bodyKeys.push(key);
+    if (isRequired) {
+      requiredBodyKeys.push(key);
+    }
+  }
+  if (route.requestBody?.required) {
+    required.push(...requiredBodyKeys);
+  }
+  const flatSchema = {
+    additionalProperties: false,
+    properties,
+    type: "object",
+    ...required.length > 0 ? { required } : {}
+  };
+  if (!route.requestBody?.required && requiredBodyKeys.length > 0) {
+    flatSchema.if = { anyOf: bodyKeys.map((key) => ({ required: [key] })) };
+    flatSchema.then = { required: requiredBodyKeys };
+  }
+  const usedDefs = sharedDefs && filterReferencedDefs(properties, sharedDefs);
+  if (usedDefs) {
+    flatSchema.$defs = usedDefs;
   }
   return {
-    document,
-    origin: typeof spec === "string" && isHttpUrl(spec) ? spec : void 0
+    bodyEncoding,
+    flatSchema,
+    parameterMap,
+    unsupportedBodyContentType,
+    wholeBodyKey
   };
 }
-function isHttpUrl(value) {
-  return /^https?:\/\//i.test(value);
+function buildSharedDefs(document) {
+  const schemas = document.components?.schemas;
+  if (!schemas || Object.keys(schemas).length === 0) {
+    return void 0;
+  }
+  return rewriteNode(schemas, "schemaMap");
 }
-
-// src/openapi/naming.ts
-var MAX_NAME_LENGTH = 56;
-var MAX_BASE_LENGTH = MAX_NAME_LENGTH - 5;
-function generateNames(routes, mcpNames) {
-  const names = /* @__PURE__ */ new Map();
-  const used = /* @__PURE__ */ new Set();
-  for (const route of routes) {
-    const base = slugify(baseNameFor(route, mcpNames));
-    let candidate = base;
-    let suffix = 1;
-    while (used.has(candidate)) {
-      suffix += 1;
-      candidate = `${base}_${suffix}`;
-    }
-    used.add(candidate);
-    names.set(route, candidate);
+var SUCCESS_STATUS_PATTERN = /^2\d\d$/;
+var MAX_OUTPUT_SCHEMA_DEFS = 50;
+function buildOutputSchema(route, sharedDefs) {
+  const successEntry = Object.entries(route.responses ?? {}).find(
+    ([code]) => SUCCESS_STATUS_PATTERN.test(code)
+  );
+  const declaredSchema = findMediaType(
+    successEntry?.[1].content,
+    "application/json"
+  )?.schema;
+  if (!declaredSchema) {
+    return void 0;
   }
-  return names;
+  const schema = resolveComponentRef(declaredSchema, sharedDefs);
+  const rewritten = rewriteComponentRefs(schema, true);
+  const { type } = rewritten;
+  const isObjectShaped = type === "object" || Array.isArray(type) && type.includes("object");
+  if (!isObjectShaped) {
+    return void 0;
+  }
+  const normalized = { ...rewritten, type: "object" };
+  const usedDefs = sharedDefs && filterReferencedDefs(normalized, sharedDefs);
+  if (usedDefs && Object.keys(usedDefs).length > MAX_OUTPUT_SCHEMA_DEFS) {
+    return void 0;
+  }
+  return {
+    ...normalized,
+    ...usedDefs ? {
+      $defs: rewriteNode(usedDefs, "schemaMap", true)
+    } : {}
+  };
 }
-function baseNameFor(route, mcpNames) {
-  if (route.operationId) {
-    const override = mcpNames && Object.hasOwn(mcpNames, route.operationId) ? mcpNames[route.operationId] : void 0;
-    return override ?? route.operationId.split("__")[0];
+function resolveComponentRef(schema, sharedDefs) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = schema;
+  let ref = current.$ref;
+  while (typeof ref === "string") {
+    const name = componentSchemaName(ref);
+    const target = name === void 0 ? void 0 : sharedDefs?.[name];
+    if (name === void 0 || target === void 0 || seen.has(name)) {
+      break;
+    }
+    seen.add(name);
+    current = target;
+    ref = current.$ref;
   }
-  return route.summary || `${route.method}_${route.path}`;
+  return current;
 }
-function slugify(value) {
-  const slug = value.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, MAX_BASE_LENGTH);
-  return slug || "operation";
+function rewriteComponentRefs(value, stripExamples = false) {
+  return rewriteNode(value, "schema", stripExamples);
 }
-
-// src/openapi/requestBuilder.ts
-async function executeRequest(options) {
-  const baseUrl = resolveBaseUrl(
-    options.servers,
-    options.origin,
-    options.baseUrlOverride
-  );
-  const pathParams = /* @__PURE__ */ Object.create(null);
-  const queryParts = [];
-  const headers = new Headers(await resolveHeaders(options.headers));
-  const bodyProps = /* @__PURE__ */ Object.create(null);
-  for (const [key, value] of Object.entries(options.args)) {
-    const mapping = options.parameterMap[key];
-    if (!mapping || value === void 0) {
-      continue;
+function childMode(key) {
+  if (DATA_KEYS.has(key)) {
+    return "data";
+  }
+  return SCHEMA_MAP_KEYS.has(key) ? "schemaMap" : "schema";
+}
+function componentSchemaName(ref) {
+  for (const prefix of ["#/components/schemas/", "#/$defs/"]) {
+    if (ref.startsWith(prefix)) {
+      return ref.slice(prefix.length).replaceAll("~1", "/").replaceAll("~0", "~");
     }
-    switch (mapping.in) {
-      case "body":
-        bodyProps[mapping.name] = value;
-        break;
-      case "cookie": {
-        const pair = `${mapping.name}=${encodeCookieValue(mapping, value)}`;
-        const existing = headers.get("cookie");
-        headers.set("cookie", existing ? `${existing}; ${pair}` : pair);
-        break;
-      }
-      case "header":
-        headers.set(mapping.name, String(value));
-        break;
-      case "path":
-        pathParams[mapping.name] = encodePathValue(
-          value,
-          mapping.style,
-          mapping.explode
-        );
-        break;
-      case "query": {
-        const query = new URLSearchParams();
-        appendQueryValue(
-          query,
-          mapping.name,
-          mapping.style,
-          value,
-          mapping.explode
-        );
-        if (query.size > 0) {
-          queryParts.push(serializeQuery(query, mapping.allowReserved));
-        }
-        break;
-      }
+  }
+  return void 0;
+}
+function extractBodyProperties(requestBody, sharedDefs) {
+  const properties = /* @__PURE__ */ new Map();
+  const content = requestBody?.content;
+  if (!content) {
+    return { properties };
+  }
+  const json = findMediaType(content, "application/json");
+  const form = findMediaType(content, "application/x-www-form-urlencoded");
+  if (json === void 0 && form === void 0) {
+    const contentTypes = Object.keys(content);
+    return contentTypes.length > 0 ? { properties, unsupportedBodyContentType: contentTypes[0] } : { properties };
+  }
+  const bodyEncoding = json === void 0 ? "form" : "json";
+  const declaredSchema = bodyEncoding === "json" ? json?.schema : form?.schema;
+  if (!declaredSchema) {
+    return { bodyEncoding, properties };
+  }
+  const schema = bodyEncoding === "form" ? resolveComponentRef(declaredSchema, sharedDefs) : declaredSchema;
+  const schemaProperties = schema.properties;
+  if (schema.type === "object" && schemaProperties && (bodyEncoding === "form" || schema.additionalProperties === false || Object.keys(schemaProperties).length > 0)) {
+    const requiredNames = new Set(
+      schema.required ?? []
+    );
+    for (const [name, propertySchema] of Object.entries(schemaProperties)) {
+      properties.set(name, {
+        required: requiredNames.has(name),
+        schema: propertySchema
+      });
     }
+    return { bodyEncoding, properties };
   }
-  let path = options.route.path;
-  for (const [name, value] of Object.entries(pathParams)) {
-    path = path.replaceAll(`{${name}}`, value);
+  if (bodyEncoding === "form") {
+    return {
+      properties,
+      unsupportedBodyContentType: "application/x-www-form-urlencoded"
+    };
   }
-  assertNoSubstitutedDotSegments(options.route, path);
-  const url = new URL(baseUrl.replace(/\/$/, "") + path);
-  url.search = queryParts.join("&");
-  let body;
-  const requiredJsonBody = options.bodyEncoding === "json" && options.route.requestBody?.required === true && !options.wholeBodyKey;
-  if (Object.keys(bodyProps).length > 0 || requiredJsonBody) {
-    const payload = options.wholeBodyKey ? bodyProps[options.wholeBodyKey] : bodyProps;
-    if (options.bodyEncoding === "form") {
-      if (!headers.has("content-type")) {
-        headers.set("content-type", "application/x-www-form-urlencoded");
-      }
-      body = encodeFormBody(payload);
-    } else {
-      if (!headers.has("content-type")) {
-        headers.set("content-type", "application/json");
+  properties.set("body", {
+    required: requestBody?.required ?? false,
+    schema
+  });
+  return { bodyEncoding, properties, wholeBodyKey: "body" };
+}
+function filterReferencedDefs(node, allDefs) {
+  const referenced = /* @__PURE__ */ new Set();
+  const stack = [node];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (Array.isArray(current)) {
+      stack.push(...current);
+      continue;
+    }
+    if (!current || typeof current !== "object") {
+      continue;
+    }
+    for (const [key, value] of Object.entries(
+      current
+    )) {
+      if (key === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
+        const [first = ""] = value.slice("#/$defs/".length).split("/");
+        const name = first.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (allDefs[name] && !referenced.has(name)) {
+          referenced.add(name);
+          stack.push(allDefs[name]);
+        }
+        continue;
       }
-      body = JSON.stringify(payload);
+      stack.push(value);
     }
   }
-  const response = await options.fetchImpl(url.toString(), {
-    body,
-    headers,
-    method: options.route.method.toUpperCase(),
-    signal: options.signal
-  });
-  const text = await response.text();
-  if (!response.ok) {
-    throw new UserError(
-      `${options.route.method.toUpperCase()} ${path} failed with ${response.status}: ${text.slice(0, 2e3)}`
-    );
+  if (referenced.size === 0) {
+    return void 0;
   }
-  const mediaType = response.headers.get("content-type")?.split(";")[0];
-  if (mediaType?.toLowerCase().includes("json")) {
-    try {
-      const json = JSON.parse(text);
-      return { json, text: JSON.stringify(json, null, 2) };
-    } catch {
-      return { text };
-    }
+  return Object.fromEntries(
+    [...referenced].map((name) => [name, allDefs[name]])
+  );
+}
+function findMediaType(content, mediaType) {
+  if (!content) {
+    return void 0;
   }
-  return { text };
+  const key = Object.hasOwn(content, mediaType) ? mediaType : Object.keys(content).find(
+    (candidate) => candidate.split(";")[0].trim().toLowerCase() === mediaType
+  );
+  return key === void 0 ? void 0 : content[key];
 }
-function resolveBaseUrl(servers, origin, overrideUrl) {
-  if (overrideUrl) {
-    return overrideUrl.replace(/\/$/, "");
+function normalizeExclusiveBound(schema, exclusiveKey, boundKey) {
+  const { [exclusiveKey]: exclusive, ...rest } = schema;
+  if (typeof exclusive !== "boolean") {
+    return schema;
   }
-  const server = servers?.[0];
-  if (!server) {
-    throw new Error(
-      "The OpenAPI document has no `servers` entry. Pass `baseUrl` to fromOpenAPI() explicitly."
-    );
+  if (!exclusive || typeof rest[boundKey] !== "number") {
+    return rest;
   }
-  let url = server.url;
-  for (const [name, variable] of Object.entries(server.variables ?? {})) {
-    url = url.replaceAll(`{${name}}`, () => variable.default);
+  const { [boundKey]: bound, ...unbounded } = rest;
+  return { ...unbounded, [exclusiveKey]: bound };
+}
+function normalizeExclusiveBounds(schema) {
+  return normalizeExclusiveBound(
+    normalizeExclusiveBound(schema, "exclusiveMinimum", "minimum"),
+    "exclusiveMaximum",
+    "maximum"
+  );
+}
+function normalizeNullable(schema) {
+  if (!("nullable" in schema)) {
+    return schema;
   }
-  try {
-    return new URL(url).toString().replace(/\/$/, "");
-  } catch {
-    if (!origin) {
-      throw new Error(
-        `The OpenAPI document's servers[0].url ("${url}") is relative, and the spec was not loaded from an http(s) URL, so it cannot be resolved to an absolute address. Pass \`baseUrl\` to fromOpenAPI() explicitly.`
-      );
-    }
-    return new URL(url, origin).toString().replace(/\/$/, "");
+  const { nullable, ...rest } = schema;
+  if (nullable !== true) {
+    return rest;
   }
-}
-function appendBracketPairs(params, key, value) {
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      if (item !== null && typeof item === "object") {
-        appendBracketPairs(params, `${key}[]`, item);
-      } else {
-        params.append(key, String(item));
-      }
-    }
-    return;
+  const { type } = rest;
+  if (typeof type === "string") {
+    return { ...rest, type: [type, "null"] };
   }
-  if (value !== null && typeof value === "object") {
-    for (const [subKey, subValue] of Object.entries(
-      value
-    )) {
-      if (subValue !== void 0) {
-        appendBracketPairs(params, `${key}[${subKey}]`, subValue);
-      }
-    }
-    return;
+  if (Array.isArray(type)) {
+    return { ...rest, type: [.../* @__PURE__ */ new Set(["null", ...type])] };
   }
-  params.append(key, String(value));
+  return rest;
 }
-function appendQueryValue(query, name, style, value, explode) {
-  if (style === "deepObject") {
-    appendBracketPairs(query, name, value);
-    return;
-  }
-  if (style === "spaceDelimited" || style === "pipeDelimited") {
-    const items = Array.isArray(value) ? value : [value];
-    const separator = style === "spaceDelimited" ? " " : "|";
-    query.append(name, items.map(String).join(separator));
-    return;
+function rewriteNode(value, mode, stripExamples = false) {
+  if (mode === "data") {
+    return value;
   }
-  if ((style === void 0 || style === "form") && value !== null && typeof value === "object" && !Array.isArray(value)) {
-    const entries = Object.entries(value);
-    if (explode === false) {
-      if (entries.length > 0) {
-        query.append(
-          name,
-          entries.flatMap(([key, item]) => [key, String(item)]).join(",")
-        );
-      }
-    } else {
-      for (const [key, item] of entries) {
-        query.append(key, String(item));
-      }
-    }
-    return;
+  if (Array.isArray(value)) {
+    return value.map((item) => rewriteNode(item, "schema", stripExamples));
   }
-  if ((style === void 0 || style === "form") && explode === false && Array.isArray(value) && value.length > 0) {
-    query.append(name, value.map(String).join(","));
-    return;
+  if (!value || typeof value !== "object") {
+    return value;
   }
-  for (const item of Array.isArray(value) ? value : [value]) {
-    query.append(name, String(item));
+  const entries = Object.entries(value).filter(
+    ([key]) => !stripExamples || mode !== "schema" || !STRIP_KEYS.has(key)
+  ).map(([key, entryValue]) => {
+    if (mode === "schemaMap") {
+      return [key, rewriteNode(entryValue, "schema", stripExamples)];
+    }
+    if (key === "$ref" && typeof entryValue === "string" && entryValue.startsWith("#/components/schemas/")) {
+      return [key, entryValue.replace("#/components/schemas/", "#/$defs/")];
+    }
+    return [key, rewriteNode(entryValue, childMode(key), stripExamples)];
+  });
+  const rewritten = Object.fromEntries(entries);
+  return mode === "schemaMap" ? rewritten : normalizeExclusiveBounds(normalizeNullable(rewritten));
+}
+
+// src/openapi/loadSpec.ts
+async function loadSpec(spec) {
+  const document = await SwaggerParser.bundle(
+    spec
+  );
+  if (!document.openapi?.startsWith("3.")) {
+    throw new Error(
+      `fromOpenAPI only supports OpenAPI 3.x documents (found ${document.openapi ?? document.swagger ?? "an unrecognized version"}). Swagger 2.0 is not supported.`
+    );
   }
+  resolveBundledPointerRefs(document);
+  return {
+    document,
+    origin: typeof spec === "string" && isHttpUrl(spec) ? spec : void 0
+  };
 }
-function assertNoSubstitutedDotSegments(route, resolvedPath) {
-  const templateSegments = new Set(route.path.split("/"));
-  for (const segment of resolvedPath.split("/")) {
-    if ((segment === "." || segment === "..") && !templateSegments.has(segment)) {
-      throw new UserError(
-        `${route.method.toUpperCase()} ${route.path}: path parameter values must not produce a "${segment}" path segment.`
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(value);
+}
+function resolveBundledPointerRefs(document) {
+  const hoisted = /* @__PURE__ */ new Map();
+  let counter = 0;
+  const resolvePointer = (pointer) => {
+    let segments;
+    try {
+      segments = pointer.slice(2).split("/").map(
+        (segment) => decodeURIComponent(
+          segment.replaceAll("~1", "/").replaceAll("~0", "~")
+        )
       );
+    } catch {
+      return void 0;
     }
-  }
-}
-function encodeCookieValue(mapping, value) {
-  return (Array.isArray(value) ? value : [value]).map((item) => {
-    const text = String(item);
-    if (mapping.style !== "cookie") {
-      return encodePathComponent(text);
+    let node = document;
+    for (const segment of segments) {
+      if (!node || typeof node !== "object" || !Object.hasOwn(node, segment)) {
+        return void 0;
+      }
+      node = node[segment];
     }
-    if (/[;,]/.test(text)) {
-      throw new UserError(
-        `Cookie parameter "${mapping.name}" uses style "cookie" and its value contains ";" or ","`
-      );
+    return node;
+  };
+  const hoist = (ref) => {
+    const existing = hoisted.get(ref);
+    if (existing !== void 0) {
+      return existing;
     }
-    return text;
-  }).join(",");
-}
-function encodeFormBody(payload) {
-  const params = new URLSearchParams();
-  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
-    for (const [key, value] of Object.entries(
-      payload
-    )) {
-      if (value === void 0) {
-        continue;
+    const target = resolvePointer(ref);
+    if (!target || typeof target !== "object") {
+      return void 0;
+    }
+    const schemas = (document.components ??= {}).schemas ??= {};
+    let name;
+    do {
+      name = `__bundle_${counter++}`;
+    } while (Object.hasOwn(schemas, name));
+    hoisted.set(ref, name);
+    schemas[name] = target;
+    walk(target, "schema");
+    return name;
+  };
+  const rewriteRef = (record) => {
+    const ref = record.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#/") || ref.startsWith("#/components/schemas/") || ref.startsWith("#/$defs/")) {
+      return;
+    }
+    const name = hoist(ref);
+    if (name !== void 0) {
+      record.$ref = `#/components/schemas/${name}`;
+    }
+  };
+  const childMode2 = (key, mode) => {
+    if (mode === "schemaMap") {
+      return "schema";
+    }
+    if (mode === "schema") {
+      return SCHEMA_MAP_KEYS.has(key) ? "schemaMap" : "schema";
+    }
+    if (key === "schema") {
+      return "schema";
+    }
+    if (mode === "document" && key === "components") {
+      return "components";
+    }
+    return mode === "components" && key === "schemas" ? "schemaMap" : "document";
+  };
+  const walk = (value, mode) => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        walk(item, mode);
       }
-      appendBracketPairs(params, key, value);
+      return;
     }
-  }
-  return params.toString();
-}
-function encodePathComponent(value) {
-  return encodeURIComponent(value).replace(
-    /[!'()*]/g,
-    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
-  );
+    if (!value || typeof value !== "object") {
+      return;
+    }
+    const record = value;
+    for (const [key, entryValue] of Object.entries(record)) {
+      if (mode === "schema" && key === "$ref") {
+        rewriteRef(record);
+      } else if (mode !== "schema" || !DATA_KEYS.has(key)) {
+        walk(entryValue, childMode2(key, mode));
+      }
+    }
+  };
+  walk(document, "document");
 }
-function encodePathValue(value, style, explode) {
-  if ((style === void 0 || style === "simple") && Array.isArray(value) && value.every((item) => item === null || typeof item !== "object")) {
-    return value.map((item) => encodePathComponent(String(item))).join(",");
-  }
-  if ((style === void 0 || style === "simple") && value !== null && typeof value === "object" && !Array.isArray(value)) {
-    const entries = Object.entries(value);
-    if (entries.every(([, item]) => item === null || typeof item !== "object")) {
-      return entries.map(([key, item]) => {
-        const encodedKey = encodePathComponent(key);
-        const encodedValue = encodePathComponent(String(item));
-        return explode === true ? `${encodedKey}=${encodedValue}` : `${encodedKey},${encodedValue}`;
-      }).join(",");
+
+// src/openapi/naming.ts
+var MAX_NAME_LENGTH = 56;
+var MAX_BASE_LENGTH = MAX_NAME_LENGTH - 5;
+function generateNames(routes, mcpNames) {
+  const names = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    const base = slugify(baseNameFor(route, mcpNames));
+    let candidate = base;
+    let suffix = 1;
+    while (used.has(candidate)) {
+      suffix += 1;
+      candidate = `${base}_${suffix}`;
     }
+    used.add(candidate);
+    names.set(route, candidate);
   }
-  return encodeURIComponent(String(value));
+  return names;
 }
-async function resolveHeaders(headers) {
-  if (!headers) {
-    return {};
+function baseNameFor(route, mcpNames) {
+  if (route.operationId) {
+    const override = mcpNames && Object.hasOwn(mcpNames, route.operationId) ? mcpNames[route.operationId] : void 0;
+    return override ?? route.operationId.split("__")[0];
   }
-  return typeof headers === "function" ? await headers() : { ...headers };
+  return route.summary || `${route.method}_${route.path}`;
 }
-function serializeQuery(query, allowReserved) {
-  const encoded = query.toString();
-  if (!allowReserved) {
-    return encoded;
-  }
-  return encoded.split("&").map((pair) => {
-    const [name, value] = pair.split("=");
-    const expanded = value.replace(
-      /\+|%25([\da-f]{2})|%(21|24|27|28|29|2c|2f|3a|3b|3f|40|7e)/gi,
-      (match, triple) => triple ? `%${triple}` : match === "+" ? "%20" : decodeURIComponent(match)
-    );
-    return `${name}=${expanded}`;
-  }).join("&");
+function slugify(value) {
+  const slug = value.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, MAX_BASE_LENGTH);
+  return slug || "operation";
 }
 
-// src/openapi/schemas.ts
-var SCHEMA_MAP_KEYS = /* @__PURE__ */ new Set([
-  "$defs",
-  "definitions",
-  "dependentSchemas",
-  "patternProperties",
-  "properties"
-]);
-var DATA_KEYS = /* @__PURE__ */ new Set(["const", "default", "enum", "example", "examples"]);
-var STRIP_KEYS = /* @__PURE__ */ new Set(["example", "examples"]);
-function buildFlatSchema(route, sharedDefs) {
-  const byName = /* @__PURE__ */ new Map();
-  for (const param of route.parameters) {
-    const list = byName.get(param.name) ?? [];
-    list.push(param);
-    byName.set(param.name, list);
-  }
-  const {
-    bodyEncoding,
-    properties: bodyProperties,
-    unsupportedBodyContentType,
-    wholeBodyKey
-  } = extractBodyProperties(
-    route.method === "get" ? void 0 : route.requestBody,
-    sharedDefs
+// src/openapi/requestBuilder.ts
+async function executeRequest(options) {
+  const baseUrl = resolveBaseUrl(
+    options.servers,
+    options.origin,
+    options.baseUrlOverride
   );
-  const properties = /* @__PURE__ */ Object.create(null);
-  const required = [];
-  const parameterMap = /* @__PURE__ */ Object.create(null);
-  const used = new Set(bodyProperties.keys());
-  for (const [name, occurrences] of byName) {
-    if (occurrences.length === 1 && !bodyProperties.has(name)) {
-      used.add(name);
-    }
-  }
-  const allocateAlias = (base) => {
-    let key = base;
-    let suffix = 1;
-    while (used.has(key)) {
-      suffix += 1;
-      key = `${base}_${suffix}`;
+  const pathParams = /* @__PURE__ */ Object.create(null);
+  const queryParts = [];
+  const headers = new Headers(
+    await resolveHeaders(options.headers, options.context)
+  );
+  const bodyProps = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(options.args)) {
+    const mapping = options.parameterMap[key];
+    if (!mapping || value === void 0) {
+      continue;
     }
-    used.add(key);
-    return key;
-  };
-  for (const [name, occurrences] of byName) {
-    const collides = name === "__proto__" || occurrences.length > 1 || bodyProperties.has(name);
-    for (const param of occurrences) {
-      const base = collides ? `${name}__${param.in}` : name;
-      const key = collides ? allocateAlias(base) : name;
-      properties[key] = rewriteComponentRefs(
-        param.schema ?? { type: "string" }
-      );
-      parameterMap[key] = {
-        allowReserved: param.allowReserved,
-        explode: param.explode,
-        in: param.in,
-        name,
-        style: param.style
-      };
-      if (param.in === "path" || param.required) {
-        required.push(key);
+    switch (mapping.in) {
+      case "body":
+        bodyProps[mapping.name] = value;
+        break;
+      case "cookie": {
+        const pair = `${mapping.name}=${encodeCookieValue(mapping, value)}`;
+        const existing = headers.get("cookie");
+        headers.set("cookie", existing ? `${existing}; ${pair}` : pair);
+        break;
+      }
+      case "header":
+        headers.set(mapping.name, String(value));
+        break;
+      case "path":
+        pathParams[mapping.name] = encodePathValue(
+          value,
+          mapping.style,
+          mapping.explode
+        );
+        break;
+      case "query": {
+        const query = new URLSearchParams();
+        appendQueryValue(
+          query,
+          mapping.name,
+          mapping.style,
+          value,
+          mapping.explode
+        );
+        if (query.size > 0) {
+          queryParts.push(serializeQuery(query, mapping.allowReserved));
+        }
+        break;
       }
     }
   }
-  for (const [name, { required: isRequired, schema }] of bodyProperties) {
-    const key = name === "__proto__" ? allocateAlias(`${name}__body`) : name;
-    properties[key] = rewriteComponentRefs(schema);
-    parameterMap[key] = { in: "body", name };
-    if (isRequired) {
-      required.push(key);
+  let path = options.route.path;
+  for (const [name, value] of Object.entries(pathParams)) {
+    path = path.replaceAll(`{${name}}`, value);
+  }
+  assertNoSubstitutedDotSegments(options.route, path);
+  const url = new URL(baseUrl.replace(/\/$/, "") + path);
+  url.search = queryParts.join("&");
+  let body;
+  const requiredJsonBody = options.bodyEncoding === "json" && options.route.requestBody?.required === true && !options.wholeBodyKey;
+  if (Object.keys(bodyProps).length > 0 || requiredJsonBody) {
+    const payload = options.wholeBodyKey ? bodyProps[options.wholeBodyKey] : bodyProps;
+    if (options.bodyEncoding === "form") {
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/x-www-form-urlencoded");
+      }
+      body = encodeFormBody(payload);
+    } else {
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+      body = JSON.stringify(payload);
     }
   }
-  const flatSchema = {
-    additionalProperties: false,
-    properties,
-    type: "object",
-    ...required.length > 0 ? { required } : {}
-  };
-  const usedDefs = sharedDefs && filterReferencedDefs(properties, sharedDefs);
-  if (usedDefs) {
-    flatSchema.$defs = usedDefs;
+  const response = await options.fetchImpl(url.toString(), {
+    body,
+    headers,
+    method: options.route.method.toUpperCase(),
+    signal: options.signal
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new UserError(
+      `${options.route.method.toUpperCase()} ${path} failed with ${response.status}: ${text.slice(0, 2e3)}`
+    );
   }
-  return {
-    bodyEncoding,
-    flatSchema,
-    parameterMap,
-    unsupportedBodyContentType,
-    wholeBodyKey
-  };
-}
-function buildSharedDefs(document) {
-  const schemas = document.components?.schemas;
-  if (!schemas || Object.keys(schemas).length === 0) {
-    return void 0;
+  const mediaType = response.headers.get("content-type")?.split(";")[0];
+  if (mediaType?.toLowerCase().includes("json")) {
+    try {
+      const json = JSON.parse(text);
+      return { json, text: JSON.stringify(json, null, 2) };
+    } catch {
+      return { text };
+    }
   }
-  return rewriteNode(schemas, "schemaMap");
+  return { text };
 }
-var SUCCESS_STATUS_PATTERN = /^2\d\d$/;
-var MAX_OUTPUT_SCHEMA_DEFS = 50;
-function buildOutputSchema(route, sharedDefs) {
-  const successEntry = Object.entries(route.responses ?? {}).find(
-    ([code]) => SUCCESS_STATUS_PATTERN.test(code)
-  );
-  const declaredSchema = findMediaType(
-    successEntry?.[1].content,
-    "application/json"
-  )?.schema;
-  if (!declaredSchema) {
-    return void 0;
-  }
-  const schema = resolveComponentRef(declaredSchema, sharedDefs);
-  const rewritten = rewriteComponentRefs(schema, true);
-  const { type } = rewritten;
-  const isObjectShaped = type === "object" || Array.isArray(type) && type.includes("object");
-  if (!isObjectShaped) {
-    return void 0;
+function resolveBaseUrl(servers, origin, overrideUrl) {
+  if (overrideUrl) {
+    return overrideUrl.replace(/\/$/, "");
   }
-  const normalized = { ...rewritten, type: "object" };
-  const usedDefs = sharedDefs && filterReferencedDefs(normalized, sharedDefs);
-  if (usedDefs && Object.keys(usedDefs).length > MAX_OUTPUT_SCHEMA_DEFS) {
-    return void 0;
+  const server = servers?.[0];
+  if (!server) {
+    throw new Error(
+      "The OpenAPI document has no `servers` entry. Pass `baseUrl` to fromOpenAPI() explicitly."
+    );
   }
-  return {
-    ...normalized,
-    ...usedDefs ? {
-      $defs: rewriteNode(usedDefs, "schemaMap", true)
-    } : {}
-  };
-}
-function resolveComponentRef(schema, sharedDefs) {
-  const seen = /* @__PURE__ */ new Set();
-  let current = schema;
-  let ref = current.$ref;
-  while (typeof ref === "string") {
-    const name = componentSchemaName(ref);
-    const target = name === void 0 ? void 0 : sharedDefs?.[name];
-    if (name === void 0 || target === void 0 || seen.has(name)) {
-      break;
+  let url = server.url;
+  for (const [name, variable] of Object.entries(server.variables ?? {})) {
+    url = url.replaceAll(`{${name}}`, () => variable.default);
+  }
+  try {
+    return new URL(url).toString().replace(/\/$/, "");
+  } catch {
+    if (!origin) {
+      throw new Error(
+        `The OpenAPI document's servers[0].url ("${url}") is relative, and the spec was not loaded from an http(s) URL, so it cannot be resolved to an absolute address. Pass \`baseUrl\` to fromOpenAPI() explicitly.`
+      );
     }
-    seen.add(name);
-    current = target;
-    ref = current.$ref;
+    return new URL(url, origin).toString().replace(/\/$/, "");
   }
-  return current;
-}
-function rewriteComponentRefs(value, stripExamples = false) {
-  return rewriteNode(value, "schema", stripExamples);
 }
-function childMode(key) {
-  if (DATA_KEYS.has(key)) {
-    return "data";
+function appendBracketPairs(params, key, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (item !== null && typeof item === "object") {
+        appendBracketPairs(params, `${key}[]`, item);
+      } else {
+        params.append(key, String(item));
+      }
+    }
+    return;
   }
-  return SCHEMA_MAP_KEYS.has(key) ? "schemaMap" : "schema";
-}
-function componentSchemaName(ref) {
-  for (const prefix of ["#/components/schemas/", "#/$defs/"]) {
-    if (ref.startsWith(prefix)) {
-      return ref.slice(prefix.length).replaceAll("~1", "/").replaceAll("~0", "~");
+  if (value !== null && typeof value === "object") {
+    for (const [subKey, subValue] of Object.entries(
+      value
+    )) {
+      if (subValue !== void 0) {
+        appendBracketPairs(params, `${key}[${subKey}]`, subValue);
+      }
     }
+    return;
   }
-  return void 0;
+  params.append(key, String(value));
 }
-function extractBodyProperties(requestBody, sharedDefs) {
-  const properties = /* @__PURE__ */ new Map();
-  const content = requestBody?.content;
-  if (!content) {
-    return { properties };
-  }
-  const json = findMediaType(content, "application/json");
-  const form = findMediaType(content, "application/x-www-form-urlencoded");
-  if (json === void 0 && form === void 0) {
-    const contentTypes = Object.keys(content);
-    return contentTypes.length > 0 ? { properties, unsupportedBodyContentType: contentTypes[0] } : { properties };
+function appendQueryValue(query, name, style, value, explode) {
+  if (style === "deepObject") {
+    appendBracketPairs(query, name, value);
+    return;
   }
-  const bodyEncoding = json === void 0 ? "form" : "json";
-  const declaredSchema = bodyEncoding === "json" ? json?.schema : form?.schema;
-  if (!declaredSchema) {
-    return { bodyEncoding, properties };
+  if (style === "spaceDelimited" || style === "pipeDelimited") {
+    const items = Array.isArray(value) ? value : [value];
+    const separator = style === "spaceDelimited" ? " " : "|";
+    query.append(name, items.map(String).join(separator));
+    return;
   }
-  const schema = bodyEncoding === "form" ? resolveComponentRef(declaredSchema, sharedDefs) : declaredSchema;
-  const schemaProperties = schema.properties;
-  if (schema.type === "object" && schemaProperties && (bodyEncoding === "form" || schema.additionalProperties === false || Object.keys(schemaProperties).length > 0)) {
-    const requiredNames = new Set(
-      schema.required ?? []
-    );
-    for (const [name, propertySchema] of Object.entries(schemaProperties)) {
-      properties.set(name, {
-        required: requiredNames.has(name),
-        schema: propertySchema
-      });
+  if ((style === void 0 || style === "form") && value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const entries = Object.entries(value);
+    if (explode === false) {
+      if (entries.length > 0) {
+        query.append(
+          name,
+          entries.flatMap(([key, item]) => [key, String(item)]).join(",")
+        );
+      }
+    } else {
+      for (const [key, item] of entries) {
+        query.append(key, String(item));
+      }
     }
-    return { bodyEncoding, properties };
+    return;
   }
-  if (bodyEncoding === "form") {
-    return {
-      properties,
-      unsupportedBodyContentType: "application/x-www-form-urlencoded"
-    };
+  if ((style === void 0 || style === "form") && explode === false && Array.isArray(value) && value.length > 0) {
+    query.append(name, value.map(String).join(","));
+    return;
+  }
+  for (const item of Array.isArray(value) ? value : [value]) {
+    query.append(name, String(item));
   }
-  properties.set("body", {
-    required: requestBody?.required ?? false,
-    schema
-  });
-  return { bodyEncoding, properties, wholeBodyKey: "body" };
 }
-function filterReferencedDefs(node, allDefs) {
-  const referenced = /* @__PURE__ */ new Set();
-  const stack = [node];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    if (Array.isArray(current)) {
-      stack.push(...current);
-      continue;
+function assertNoSubstitutedDotSegments(route, resolvedPath) {
+  const templateSegments = new Set(route.path.split("/"));
+  for (const segment of resolvedPath.split("/")) {
+    if ((segment === "." || segment === "..") && !templateSegments.has(segment)) {
+      throw new UserError(
+        `${route.method.toUpperCase()} ${route.path}: path parameter values must not produce a "${segment}" path segment.`
+      );
     }
-    if (!current || typeof current !== "object") {
-      continue;
+  }
+}
+function encodeCookieValue(mapping, value) {
+  return (Array.isArray(value) ? value : [value]).map((item) => {
+    const text = String(item);
+    if (mapping.style !== "cookie") {
+      return encodePathComponent(text);
     }
+    if (/[;,]/.test(text)) {
+      throw new UserError(
+        `Cookie parameter "${mapping.name}" uses style "cookie" and its value contains ";" or ","`
+      );
+    }
+    return text;
+  }).join(",");
+}
+function encodeFormBody(payload) {
+  const params = new URLSearchParams();
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
     for (const [key, value] of Object.entries(
-      current
+      payload
     )) {
-      if (key === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
-        const [first = ""] = value.slice("#/$defs/".length).split("/");
-        const name = first.replaceAll("~1", "/").replaceAll("~0", "~");
-        if (allDefs[name] && !referenced.has(name)) {
-          referenced.add(name);
-          stack.push(allDefs[name]);
-        }
+      if (value === void 0) {
         continue;
       }
-      stack.push(value);
+      appendBracketPairs(params, key, value);
     }
   }
-  if (referenced.size === 0) {
-    return void 0;
-  }
-  return Object.fromEntries(
-    [...referenced].map((name) => [name, allDefs[name]])
-  );
+  return params.toString();
 }
-function findMediaType(content, mediaType) {
-  if (!content) {
-    return void 0;
-  }
-  const key = Object.hasOwn(content, mediaType) ? mediaType : Object.keys(content).find(
-    (candidate) => candidate.split(";")[0].trim().toLowerCase() === mediaType
+function encodePathComponent(value) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
   );
-  return key === void 0 ? void 0 : content[key];
 }
-function normalizeExclusiveBound(schema, exclusiveKey, boundKey) {
-  const { [exclusiveKey]: exclusive, ...rest } = schema;
-  if (typeof exclusive !== "boolean") {
-    return schema;
+function encodePathValue(value, style, explode) {
+  if ((style === void 0 || style === "simple") && Array.isArray(value) && value.every((item) => item === null || typeof item !== "object")) {
+    return value.map((item) => encodePathComponent(String(item))).join(",");
   }
-  if (!exclusive || typeof rest[boundKey] !== "number") {
-    return rest;
+  if ((style === void 0 || style === "simple") && value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const entries = Object.entries(value);
+    if (entries.every(([, item]) => item === null || typeof item !== "object")) {
+      return entries.map(([key, item]) => {
+        const encodedKey = encodePathComponent(key);
+        const encodedValue = encodePathComponent(String(item));
+        return explode === true ? `${encodedKey}=${encodedValue}` : `${encodedKey},${encodedValue}`;
+      }).join(",");
+    }
   }
-  const { [boundKey]: bound, ...unbounded } = rest;
-  return { ...unbounded, [exclusiveKey]: bound };
-}
-function normalizeExclusiveBounds(schema) {
-  return normalizeExclusiveBound(
-    normalizeExclusiveBound(schema, "exclusiveMinimum", "minimum"),
-    "exclusiveMaximum",
-    "maximum"
-  );
+  return encodeURIComponent(String(value));
 }
-function normalizeNullable(schema) {
-  if (!("nullable" in schema)) {
-    return schema;
-  }
-  const { nullable, ...rest } = schema;
-  if (nullable !== true) {
-    return rest;
-  }
-  const { type } = rest;
-  if (typeof type === "string") {
-    return { ...rest, type: [type, "null"] };
-  }
-  if (Array.isArray(type)) {
-    return { ...rest, type: [.../* @__PURE__ */ new Set(["null", ...type])] };
+async function resolveHeaders(headers, context) {
+  if (!headers) {
+    return {};
   }
-  return rest;
+  return typeof headers === "function" ? await headers(context) : { ...headers };
 }
-function rewriteNode(value, mode, stripExamples = false) {
-  if (mode === "data") {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => rewriteNode(item, "schema", stripExamples));
-  }
-  if (!value || typeof value !== "object") {
-    return value;
+function serializeQuery(query, allowReserved) {
+  const encoded = query.toString();
+  if (!allowReserved) {
+    return encoded;
   }
-  const entries = Object.entries(value).filter(
-    ([key]) => !stripExamples || mode !== "schema" || !STRIP_KEYS.has(key)
-  ).map(([key, entryValue]) => {
-    if (mode === "schemaMap") {
-      return [key, rewriteNode(entryValue, "schema", stripExamples)];
-    }
-    if (key === "$ref" && typeof entryValue === "string" && entryValue.startsWith("#/components/schemas/")) {
-      return [key, entryValue.replace("#/components/schemas/", "#/$defs/")];
-    }
-    return [key, rewriteNode(entryValue, childMode(key), stripExamples)];
-  });
-  const rewritten = Object.fromEntries(entries);
-  return mode === "schemaMap" ? rewritten : normalizeExclusiveBounds(normalizeNullable(rewritten));
+  return encoded.split("&").map((pair) => {
+    const [name, value] = pair.split("=");
+    const expanded = value.replace(
+      /\+|%25([\da-f]{2})|%(21|24|27|28|29|2c|2f|3a|3b|3f|40|7e)/gi,
+      (match, triple) => triple ? `%${triple}` : match === "+" ? "%20" : decodeURIComponent(match)
+    );
+    return `${name}=${expanded}`;
+  }).join("&");
 }
 
 // src/openapi/resourceMapping.ts
@@ -857,12 +966,13 @@ async function fromOpenAPI(options) {
     const outputSchema = outputSchemaJson ? jsonSchemaAdapter(outputSchemaJson) : void 0;
     server.addTool({
       description: route.summary ?? `${route.method.toUpperCase()} ${route.path}`,
-      execute: async (args, { signal }) => {
+      execute: async (args, context) => {
         const result = await executeRequest({
           ...execOptions,
           args,
           bodyEncoding,
-          signal,
+          context,
+          signal: context.signal,
           wholeBodyKey
         });
         return resolveToolResult(result, outputSchema);
@@ -887,8 +997,8 @@ function registerResource(server, route, name, parameterMap, requiredKeys, execO
   if (mapping.kind === "resource") {
     server.addResource({
       description,
-      load: async () => wrapAsResourceResult(
-        await executeRequest({ ...execOptions, args: {} })
+      load: async (_auth, context) => wrapAsResourceResult(
+        await executeRequest({ ...execOptions, args: {}, context })
       ),
       name,
       uri: mapping.uri
@@ -898,10 +1008,11 @@ function registerResource(server, route, name, parameterMap, requiredKeys, execO
   server.addResourceTemplate({
     arguments: mapping.args,
     description,
-    load: async (args) => wrapAsResourceResult(
+    load: async (args, _auth, context) => wrapAsResourceResult(
       await executeRequest({
         ...execOptions,
-        args
+        args,
+        context
       })
     ),
     name,