mcp-from-openapi 2.5.1 → 2.6.0

package/esm/index.mjs

@@ -10,7 +10,25 @@ function toJsonSchema(schema) {
     return { $ref: schema.$ref };
   }
   const { exclusiveMaximum, exclusiveMinimum, maximum, minimum, ...rest } = schema;
-  const result = { ...rest };
+  const { nullable, example, ...cleanRest } = rest;
+  const result = { ...cleanRest };
+  delete result["xml"];
+  let wrapNullable = false;
+  if (nullable === true) {
+    const type = result["type"];
+    if (type === void 0) {
+      wrapNullable = true;
+    } else if (Array.isArray(type)) {
+      if (!type.includes("null")) {
+        result["type"] = [...type, "null"];
+      }
+    } else if (type !== "null") {
+      result["type"] = [type, "null"];
+    }
+  }
+  if (example !== void 0 && !Array.isArray(result["examples"])) {
+    result["examples"] = [example];
+  }
   if (typeof exclusiveMaximum === "boolean") {
     if (exclusiveMaximum && maximum !== void 0) {
       result["exclusiveMaximum"] = maximum;
@@ -64,16 +82,57 @@ function toJsonSchema(schema) {
   if (result["not"]) {
     result["not"] = toJsonSchema(result["not"]);
   }
+  for (const key of ["patternProperties", "$defs", "definitions", "dependentSchemas"]) {
+    const value = result[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const mapped = {};
+      for (const [name, sub] of Object.entries(value)) {
+        mapped[name] = toJsonSchema(sub);
+      }
+      result[key] = mapped;
+    }
+  }
+  for (const key of [
+    "contains",
+    "propertyNames",
+    "if",
+    "then",
+    "else",
+    "contentSchema",
+    "unevaluatedItems",
+    "unevaluatedProperties"
+  ]) {
+    const value = result[key];
+    if (value && typeof value === "object") {
+      result[key] = toJsonSchema(value);
+    }
+  }
+  if (Array.isArray(result["prefixItems"])) {
+    result["prefixItems"] = result["prefixItems"].map(toJsonSchema);
+  }
+  if (wrapNullable) {
+    const wrapper = {};
+    for (const key of ["title", "description", "deprecated", "examples"]) {
+      if (result[key] !== void 0) {
+        wrapper[key] = result[key];
+        delete result[key];
+      }
+    }
+    wrapper["anyOf"] = [result, { type: "null" }];
+    return wrapper;
+  }
   return result;
 }
 
 // src/parameter-resolver.ts
 var ParameterResolver = class {
   namingStrategy;
-  constructor(namingStrategy) {
+  includeExamples;
+  constructor(namingStrategy, options) {
     this.namingStrategy = namingStrategy ?? {
       conflictResolver: this.defaultConflictResolver
     };
+    this.includeExamples = options?.includeExamples ?? false;
   }
   /**
    * Default conflict resolver: prefix with location
@@ -105,7 +164,8 @@ var ParameterResolver = class {
         style: param.style,
         explode: param.explode,
         allowReserved: param.allowReserved,
-        deprecated: param.deprecated
+        deprecated: param.deprecated,
+        examples: this.includeExamples ? collectExampleValues(param.example, param.examples) : void 0
       };
       if (!parametersByName.has(param.name)) {
         parametersByName.set(param.name, []);
@@ -116,7 +176,8 @@ var ParameterResolver = class {
       const contentType = this.selectContentType(requestBody.content);
       const mediaType = requestBody.content[contentType];
       if (mediaType?.schema) {
-        this.extractBodyParameters(mediaType.schema, parametersByName, requestBody.required ?? false, contentType);
+        const mediaExamples = this.includeExamples ? collectExampleValues(mediaType.example, mediaType.examples) : void 0;
+        this.extractBodyParameters(mediaType.schema, parametersByName, requestBody.required ?? false, contentType, mediaExamples, mediaType.encoding);
       }
     }
     const properties = {};
@@ -137,7 +198,9 @@ var ParameterResolver = class {
           required: param.required,
           style: param.style,
           explode: param.explode,
-          serialization: param.serialization
+          allowReserved: param.allowReserved,
+          serialization: param.serialization,
+          ...param.wholeBody && { wholeBody: true }
         });
       } else {
         params.forEach((param, index) => {
@@ -153,7 +216,9 @@ var ParameterResolver = class {
             required: param.required,
             style: param.style,
             explode: param.explode,
-            serialization: param.serialization
+            allowReserved: param.allowReserved,
+            serialization: param.serialization,
+            ...param.wholeBody && { wholeBody: true }
           });
         });
       }
@@ -178,23 +243,31 @@ var ParameterResolver = class {
   /**
    * Extract parameters from request body schema
    */
-  extractBodyParameters(schema, parametersByName, required, contentType, prefix = "") {
+  extractBodyParameters(schema, parametersByName, required, contentType, mediaExamples, encoding, prefix = "") {
     if (!schema || typeof schema !== "object") return;
     const jsonSchema = toJsonSchema(schema);
-    if (jsonSchema.type === "object" && jsonSchema.properties) {
-      const requiredFields = new Set(jsonSchema.required ?? []);
-      for (const [propName, propSchema] of Object.entries(jsonSchema.properties)) {
+    const flattened = flattenObjectBody(jsonSchema);
+    if (flattened) {
+      const requiredFields = flattened.required;
+      for (const [propName, propSchema] of Object.entries(flattened.properties)) {
         const fullName = prefix ? `${prefix}.${propName}` : propName;
         const isRequired = required && requiredFields.has(propName);
         if (typeof propSchema === "object") {
+          const propEncoding = encoding?.[propName];
+          const propExamples = mediaExamples?.map(
+            (ex) => ex !== null && typeof ex === "object" && !Array.isArray(ex) ? ex[propName] : void 0
+          ).filter((value) => value !== void 0);
           const info = {
             name: fullName,
             location: "body",
             required: isRequired,
             schema: propSchema,
             description: propSchema.description,
+            examples: propExamples && propExamples.length > 0 ? propExamples : void 0,
             serialization: {
-              contentType
+              contentType,
+              ...propEncoding && { encoding: { [propName]: propEncoding } },
+              ...isBinarySchema(propSchema) && { binary: true }
             }
           };
           if (!parametersByName.has(fullName)) {
@@ -209,9 +282,13 @@ var ParameterResolver = class {
         name: bodyParamName,
         location: "body",
         required,
-        schema,
+        schema: jsonSchema,
+        examples: mediaExamples,
+        wholeBody: true,
         serialization: {
-          contentType
+          contentType,
+          ...encoding && Object.keys(encoding).length > 0 && { encoding },
+          ...isBinarySchema(jsonSchema) && { binary: true }
         }
       };
       if (!parametersByName.has(bodyParamName)) {
@@ -228,6 +305,9 @@ var ParameterResolver = class {
     if (param.description) {
       schema.description = param.description;
     }
+    if (param.examples && param.examples.length > 0) {
+      schema.examples = param.examples;
+    }
     if (param.deprecated) {
       schema["deprecated"] = true;
     }
@@ -324,21 +404,68 @@ var ParameterResolver = class {
         required: true,
         security: securityInfo
       });
-      if (includeInInput) {
+      const schemeInInput = includeInInput === true || Array.isArray(includeInInput) && includeInInput.includes(scheme);
+      if (schemeInInput) {
         properties[inputKey] = schema;
         required.push(inputKey);
       }
     }
   }
 };
+function collectObjectMembers(schema) {
+  if (!schema || typeof schema !== "object") return { properties: {}, required: /* @__PURE__ */ new Set() };
+  if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) return "union";
+  const properties = {};
+  const required = /* @__PURE__ */ new Set();
+  if (Array.isArray(schema.allOf)) {
+    for (const member of schema.allOf) {
+      const collected = collectObjectMembers(member);
+      if (collected === "union") return "union";
+      Object.assign(properties, collected.properties);
+      collected.required.forEach((field) => required.add(field));
+    }
+  }
+  if (schema.properties && typeof schema.properties === "object") {
+    Object.assign(properties, schema.properties);
+  }
+  if (Array.isArray(schema.required)) {
+    schema.required.forEach((field) => required.add(field));
+  }
+  return { properties, required };
+}
+function flattenObjectBody(schema) {
+  const collected = collectObjectMembers(schema);
+  if (collected === "union") return void 0;
+  return Object.keys(collected.properties).length > 0 ? collected : void 0;
+}
+function isBinarySchema(schema) {
+  if (!schema || typeof schema !== "object") return false;
+  const record = schema;
+  if (record["format"] === "binary") return true;
+  return typeof record["contentMediaType"] === "string" && record["contentEncoding"] === void 0 && record["type"] === void 0;
+}
+function collectExampleValues(example, examples) {
+  if (examples && !Array.isArray(examples)) {
+    const values = Object.values(examples).filter((entry) => entry !== null && typeof entry === "object" && !isReferenceObject(entry)).map((entry) => entry.value).filter((value) => value !== void 0);
+    if (values.length > 0) {
+      return values;
+    }
+  }
+  if (example !== void 0) {
+    return [example];
+  }
+  return void 0;
+}
 
 // src/response-builder.ts
 var ResponseBuilder = class {
   preferredStatusCodes;
   includeAllResponses;
+  includeExamples;
   constructor(options = {}) {
     this.preferredStatusCodes = options.preferredStatusCodes ?? [200, 201, 204, 202, 203, 206];
     this.includeAllResponses = options.includeAllResponses ?? true;
+    this.includeExamples = options.includeExamples ?? false;
   }
   /**
    * Build output schema from responses
@@ -416,6 +543,12 @@ var ResponseBuilder = class {
     if (!schema.description && response.description) {
       schema.description = response.description;
     }
+    if (this.includeExamples) {
+      const mediaExamples = collectExampleValues(mediaType.example, mediaType.examples);
+      if (mediaExamples) {
+        schema.examples = mediaExamples;
+      }
+    }
     schema["x-content-type"] = contentType;
     return { statusCode, schema };
   }
@@ -452,1382 +585,2040 @@ var ResponseBuilder = class {
   }
 };
 
-// src/validator.ts
-var Validator = class {
+// src/schema-builder.ts
+var SchemaBuilder = class {
   /**
-   * Validate an OpenAPI document
+   * Merge multiple schemas into one
    */
-  async validate(document) {
-    const errors = [];
-    const warnings = [];
-    if (!document.openapi) {
-      errors.push({
-        message: "Missing required field: openapi",
-        path: "/openapi",
-        code: "MISSING_OPENAPI_VERSION"
-      });
-    } else if (!this.isValidOpenAPIVersion(document.openapi)) {
-      errors.push({
-        message: `Unsupported OpenAPI version: ${document.openapi}. Expected 3.0.x or 3.1.x`,
-        path: "/openapi",
-        code: "INVALID_OPENAPI_VERSION"
-      });
+  static merge(schemas) {
+    if (schemas.length === 0) {
+      return { type: "object" };
     }
-    if (!document.info) {
-      errors.push({
-        message: "Missing required field: info",
-        path: "/info",
-        code: "MISSING_INFO"
-      });
-    } else {
-      if (!document.info.title) {
-        errors.push({
-          message: "Missing required field: info.title",
-          path: "/info/title",
-          code: "MISSING_TITLE"
-        });
+    if (schemas.length === 1) {
+      return schemas[0];
+    }
+    const merged = {
+      type: "object",
+      properties: {},
+      required: []
+    };
+    const allRequired = /* @__PURE__ */ new Set();
+    for (const schema of schemas) {
+      if (schema.properties) {
+        merged.properties = {
+          ...merged.properties,
+          ...schema.properties
+        };
       }
-      if (!document.info.version) {
-        errors.push({
-          message: "Missing required field: info.version",
-          path: "/info/version",
-          code: "MISSING_VERSION"
-        });
+      if (schema.required) {
+        schema.required.forEach((field) => allRequired.add(field));
       }
     }
-    if (!document.paths || Object.keys(document.paths).length === 0) {
-      warnings.push({
-        message: "No paths defined in OpenAPI document",
-        path: "/paths",
-        code: "NO_PATHS"
-      });
-    } else {
-      this.validatePaths(document.paths, errors, warnings);
+    if (allRequired.size > 0) {
+      merged.required = Array.from(allRequired);
     }
-    if (!document.servers || document.servers.length === 0) {
-      warnings.push({
-        message: "No servers defined. You may need to provide a baseUrl option.",
-        path: "/servers",
-        code: "NO_SERVERS"
-      });
+    return merged;
+  }
+  /**
+   * Create a union schema (oneOf)
+   */
+  static union(schemas) {
+    if (schemas.length === 0) {
+      return {};
     }
-    if (document.security && !document.components?.securitySchemes) {
-      warnings.push({
-        message: "Security requirements defined but no security schemes found",
-        path: "/security",
-        code: "NO_SECURITY_SCHEMES"
-      });
+    if (schemas.length === 1) {
+      return schemas[0];
     }
     return {
-      valid: errors.length === 0,
-      errors: errors.length > 0 ? errors : void 0,
-      warnings: warnings.length > 0 ? warnings : void 0
+      oneOf: schemas
     };
   }
   /**
-   * Check if OpenAPI version is valid
+   * Deep clone a schema
    */
-  isValidOpenAPIVersion(version) {
-    return /^3\.[01]\.\d+$/.test(version);
+  static clone(schema) {
+    return JSON.parse(JSON.stringify(schema));
   }
   /**
-   * Validate paths
+   * Remove $ref from schema (assumes already dereferenced)
    */
-  validatePaths(paths, errors, warnings) {
-    for (const [path, pathItem] of Object.entries(paths)) {
-      if (!pathItem) continue;
-      if (!path.startsWith("/")) {
-        errors.push({
-          message: `Path must start with '/': ${path}`,
-          path: `/paths/${path}`,
-          code: "INVALID_PATH_FORMAT"
-        });
-      }
-      const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
-      let hasOperations = false;
-      for (const method of methods) {
-        const operation = pathItem[method];
-        if (operation) {
-          hasOperations = true;
-          this.validateOperation(operation, path, method, errors, warnings);
+  static removeRefs(schema) {
+    const cloned = this.clone(schema);
+    this.removeRefsRecursive(cloned);
+    return cloned;
+  }
+  static removeRefsRecursive(obj) {
+    if (!obj || typeof obj !== "object") return;
+    if (obj.$ref) {
+      delete obj.$ref;
+    }
+    for (const key in obj) {
+      if (key in obj) {
+        const value = obj[key];
+        if (value && typeof value === "object") {
+          this.removeRefsRecursive(value);
         }
       }
-      if (!hasOperations && !pathItem.$ref) {
-        warnings.push({
-          message: `Path has no operations: ${path}`,
-          path: `/paths/${path}`,
-          code: "NO_OPERATIONS"
-        });
-      }
     }
   }
   /**
-   * Validate an operation
+   * Add description to schema
    */
-  validateOperation(operation, path, method, errors, warnings) {
-    const basePath = `/paths/${path}/${method}`;
-    if (!operation.operationId) {
-      warnings.push({
-        message: `Operation missing operationId: ${method.toUpperCase()} ${path}`,
-        path: `${basePath}/operationId`,
-        code: "NO_OPERATION_ID"
-      });
-    }
-    if (!operation.responses || Object.keys(operation.responses).length === 0) {
-      errors.push({
-        message: `Operation missing responses: ${method.toUpperCase()} ${path}`,
-        path: `${basePath}/responses`,
-        code: "NO_RESPONSES"
-      });
-    }
-    if (operation.parameters) {
-      this.validateParameters(operation.parameters, path, method, errors, warnings);
-    }
-    const pathParams = path.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
-    const definedPathParams = new Set(
-      operation.parameters?.filter((p) => p.in === "path").map((p) => p.name) ?? []
-    );
-    for (const param of pathParams) {
-      if (!definedPathParams.has(param)) {
-        errors.push({
-          message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path}`,
-          path: `${basePath}/parameters`,
-          code: "MISSING_PATH_PARAMETER"
-        });
-      }
-    }
+  static withDescription(schema, description) {
+    return {
+      ...schema,
+      description
+    };
   }
   /**
-   * Validate parameters
+   * Add example to schema
    */
-  validateParameters(parameters, path, method, errors, warnings) {
-    const basePath = `/paths/${path}/${method}/parameters`;
-    for (let i = 0; i < parameters.length; i++) {
-      const param = parameters[i];
-      const paramPath = `${basePath}/${i}`;
-      if (!param.name) {
-        errors.push({
-          message: "Parameter missing name",
-          path: `${paramPath}/name`,
-          code: "MISSING_PARAMETER_NAME"
-        });
-      }
-      if (!param.in) {
-        errors.push({
-          message: 'Parameter missing "in" field',
-          path: `${paramPath}/in`,
-          code: "MISSING_PARAMETER_IN"
-        });
-      } else if (!["path", "query", "header", "cookie"].includes(param.in)) {
-        errors.push({
-          message: `Invalid parameter location: ${param.in}`,
-          path: `${paramPath}/in`,
-          code: "INVALID_PARAMETER_IN"
-        });
-      }
-      if (param.in === "path" && !param.required) {
-        errors.push({
-          message: `Path parameter '${param.name}' must be required`,
-          path: `${paramPath}/required`,
-          code: "PATH_PARAMETER_NOT_REQUIRED"
-        });
-      }
-      if (!param.schema && !param.content) {
-        errors.push({
-          message: `Parameter '${param.name}' missing schema or content`,
-          path: `${paramPath}`,
-          code: "MISSING_PARAMETER_SCHEMA"
-        });
-      }
-    }
+  static withExample(schema, example) {
+    const existingExamples = Array.isArray(schema.examples) ? schema.examples : [];
+    return {
+      ...schema,
+      examples: [...existingExamples, example]
+    };
   }
-};
-
-// src/errors.ts
-var OpenAPIToolError = class extends Error {
-  context;
-  constructor(message, context) {
-    super(message);
-    this.name = this.constructor.name;
-    this.context = context;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
+  /**
+   * Add default value to schema
+   */
+  static withDefault(schema, defaultValue) {
+    return {
+      ...schema,
+      default: defaultValue
+    };
   }
-};
-var LoadError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Add format to schema
+   */
+  static withFormat(schema, format) {
+    return {
+      ...schema,
+      format
+    };
   }
-};
-var SsrfError = class extends LoadError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Add pattern to schema
+   */
+  static withPattern(schema, pattern) {
+    return {
+      ...schema,
+      pattern
+    };
   }
-};
-var ParseError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Add enum to schema
+   */
+  static withEnum(schema, values) {
+    return {
+      ...schema,
+      enum: values
+    };
   }
-};
-var ValidationError = class extends OpenAPIToolError {
-  errors;
-  constructor(message, context) {
-    super(message, context);
-    this.errors = context?.["errors"];
+  /**
+   * Add minimum/maximum constraints
+   */
+  static withRange(schema, min, max, options = {}) {
+    const result = { ...schema };
+    if (min !== void 0) {
+      if (options.exclusive) {
+        result.exclusiveMinimum = min;
+      } else {
+        result.minimum = min;
+      }
+    }
+    if (max !== void 0) {
+      if (options.exclusive) {
+        result.exclusiveMaximum = max;
+      } else {
+        result.maximum = max;
+      }
+    }
+    return result;
   }
-};
-var GenerationError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Add minLength/maxLength constraints
+   */
+  static withLength(schema, minLength, maxLength) {
+    const result = { ...schema };
+    if (minLength !== void 0) {
+      result.minLength = minLength;
+    }
+    if (maxLength !== void 0) {
+      result.maxLength = maxLength;
+    }
+    return result;
   }
-};
-var SchemaError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Create object schema
+   */
+  static object(properties, required) {
+    return {
+      type: "object",
+      properties,
+      ...required && required.length > 0 && { required },
+      additionalProperties: false
+    };
   }
-};
-
-// src/format-resolver.ts
-var BUILTIN_FORMAT_RESOLVERS = {
-  // String formats
-  uuid: (schema) => ({
-    ...schema,
-    pattern: schema.pattern ?? "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
-    description: schema.description || "UUID string (RFC 4122)"
-  }),
-  "date-time": (schema) => ({
-    ...schema,
-    description: schema.description || "ISO 8601 date-time (e.g., 2024-01-15T09:30:00Z)"
-  }),
-  date: (schema) => ({
-    ...schema,
-    pattern: schema.pattern ?? "^\\d{4}-\\d{2}-\\d{2}$",
-    description: schema.description || "ISO 8601 date (e.g., 2024-01-15)"
-  }),
-  time: (schema) => ({
-    ...schema,
-    pattern: schema.pattern ?? "^\\d{2}:\\d{2}:\\d{2}",
-    description: schema.description || "ISO 8601 time (e.g., 09:30:00)"
-  }),
-  email: (schema) => ({
-    ...schema,
-    description: schema.description || "Email address (RFC 5322)"
-  }),
-  uri: (schema) => ({
-    ...schema,
-    description: schema.description || "URI (RFC 3986)"
-  }),
-  "uri-reference": (schema) => ({
-    ...schema,
-    description: schema.description || "URI reference (RFC 3986)"
-  }),
-  hostname: (schema) => ({
-    ...schema,
-    description: schema.description || "Internet hostname (RFC 1123)"
-  }),
-  ipv4: (schema) => ({
-    ...schema,
-    pattern: schema.pattern ?? "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$",
-    description: schema.description || "IPv4 address"
-  }),
-  ipv6: (schema) => ({
-    ...schema,
-    description: schema.description || "IPv6 address (RFC 4291)"
-  }),
-  // Integer formats
-  int32: (schema) => ({
-    ...schema,
-    minimum: schema.minimum ?? -2147483648,
-    maximum: schema.maximum ?? 2147483647
-  }),
-  int64: (schema) => ({
-    ...schema,
-    minimum: schema.minimum ?? Number.MIN_SAFE_INTEGER,
-    maximum: schema.maximum ?? Number.MAX_SAFE_INTEGER
-  }),
-  // Binary/encoding formats
-  byte: (schema) => ({
-    ...schema,
-    pattern: schema.pattern ?? "^[A-Za-z0-9+/]*={0,2}$",
-    description: schema.description || "Base64-encoded string (RFC 4648)"
-  }),
-  binary: (schema) => ({
-    ...schema,
-    description: schema.description || "Binary data"
-  }),
-  // Sensitive data formats
-  password: (schema) => ({
-    ...schema,
-    description: schema.description || "Password (sensitive, UI should mask input)"
-  })
-};
-function resolveSchemaFormats(schema, resolvers) {
-  if (!schema || typeof schema !== "object") return schema;
-  let result = { ...schema };
-  const format = result["format"];
-  if (format && resolvers[format]) {
-    result = { ...resolvers[format](result) };
+  /**
+   * Create array schema
+   */
+  static array(items, constraints) {
+    return {
+      type: "array",
+      items,
+      ...constraints
+    };
   }
-  if (result["properties"] && typeof result["properties"] === "object") {
-    const props = {};
-    for (const [key, value] of Object.entries(result["properties"])) {
-      props[key] = resolveSchemaFormats(value, resolvers);
-    }
-    result["properties"] = props;
+  /**
+   * Create string schema
+   */
+  static string(constraints) {
+    return {
+      type: "string",
+      ...constraints
+    };
   }
-  if (result["items"]) {
-    if (Array.isArray(result["items"])) {
-      result["items"] = result["items"].map((item) => resolveSchemaFormats(item, resolvers));
-    } else {
-      result["items"] = resolveSchemaFormats(result["items"], resolvers);
-    }
+  /**
+   * Create number schema
+   */
+  static number(constraints) {
+    return {
+      type: "number",
+      ...constraints
+    };
   }
-  if (result["additionalProperties"] && typeof result["additionalProperties"] === "object") {
-    result["additionalProperties"] = resolveSchemaFormats(result["additionalProperties"], resolvers);
+  /**
+   * Create integer schema
+   */
+  static integer(constraints) {
+    return {
+      type: "integer",
+      ...constraints
+    };
   }
-  for (const key of ["allOf", "anyOf", "oneOf"]) {
-    if (result[key] && Array.isArray(result[key])) {
-      result[key] = result[key].map((s) => resolveSchemaFormats(s, resolvers));
-    }
+  /**
+   * Create boolean schema
+   */
+  static boolean() {
+    return {
+      type: "boolean"
+    };
   }
-  if (result["not"] && typeof result["not"] === "object") {
-    result["not"] = resolveSchemaFormats(result["not"], resolvers);
+  /**
+   * Create null schema
+   */
+  static null() {
+    return {
+      type: "null"
+    };
   }
-  return result;
-}
-
-// src/ssrf.ts
-var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
-  "localhost",
-  "localhost.localdomain",
-  "ip6-localhost",
-  "ip6-loopback",
-  "metadata",
-  "metadata.google.internal",
-  "metadata.goog"
-]);
-function normalizeSsrfOptions(refResolution) {
-  return {
-    allowedHosts: refResolution?.allowedHosts ?? [],
-    blockedHosts: refResolution?.blockedHosts ?? [],
-    allowInternalIPs: refResolution?.allowInternalIPs ?? false
-  };
-}
-function decodeIpv4MappedIpv6(hostname) {
-  let h = hostname;
-  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
-  const lower = h.toLowerCase();
-  const marker = lower.lastIndexOf("::ffff:");
-  if (marker === -1) return null;
-  const tail = lower.slice(marker + "::ffff:".length);
-  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
-  const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-  if (hex) {
-    const hi = parseInt(hex[1], 16);
-    const lo = parseInt(hex[2], 16);
-    if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
-    return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+  /**
+   * Flatten nested oneOf/anyOf/allOf schemas
+   */
+  static flatten(schema, maxDepth = 10) {
+    if (maxDepth <= 0) return schema;
+    const cloned = this.clone(schema);
+    if (cloned.oneOf) {
+      const flattened = cloned.oneOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.oneOf ? sub.oneOf : [sub];
+      });
+      cloned.oneOf = flattened;
+    }
+    if (cloned.anyOf) {
+      const flattened = cloned.anyOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.anyOf ? sub.anyOf : [sub];
+      });
+      cloned.anyOf = flattened;
+    }
+    if (cloned.allOf) {
+      const flattened = cloned.allOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.allOf ? sub.allOf : [sub];
+      });
+      cloned.allOf = flattened;
+    }
+    return cloned;
+  }
+  /**
+   * Truncate a schema tree to a maximum nesting depth.
+   *
+   * The root sits at depth 0; descending into `properties` values, `items`,
+   * `additionalProperties`, composition members (`allOf`/`anyOf`/`oneOf`), or
+   * `not` increments the depth. Nodes at `maxDepth` keep their scalar keywords
+   * (type, description, format, ...) but have their child schemas stripped and
+   * a truncation note appended to the description.
+   */
+  static truncateDepth(schema, maxDepth) {
+    const bound = Number.isFinite(maxDepth) ? Math.max(0, Math.floor(maxDepth)) : 10;
+    return this.truncateDepthRecursive(schema, 0, bound);
+  }
+  /** Keys whose value is a map of schemas (JSON Schema 2020-12) */
+  static TRUNCATE_MAP_KEYS = [
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+    "dependentSchemas"
+  ];
+  /** Keys whose value is a single schema (or, for `items`, a tuple array) */
+  static TRUNCATE_SCHEMA_KEYS = [
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+    "contains",
+    "contentSchema",
+    "unevaluatedProperties",
+    "unevaluatedItems"
+  ];
+  /** Keys whose value is an array of schemas */
+  static TRUNCATE_LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+  // Copy-on-walk: never mutates the input, only copies nodes that have schema
+  // children, and — because the walk is depth-bounded — terminates even on
+  // circular schema graphs (which `clone()`'s JSON round-trip would reject).
+  static truncateDepthRecursive(node, depth, maxDepth) {
+    if (!node || typeof node !== "object") return node;
+    const record = node;
+    const childKeys = [...this.TRUNCATE_MAP_KEYS, ...this.TRUNCATE_SCHEMA_KEYS, ...this.TRUNCATE_LIST_KEYS];
+    const hasChildren = childKeys.some((key) => {
+      const value = record[key];
+      return value !== null && typeof value === "object";
+    });
+    if (!hasChildren) return node;
+    const copy = { ...node };
+    const copyRecord = copy;
+    if (depth >= maxDepth) {
+      for (const key of childKeys) {
+        const value = copyRecord[key];
+        if (value !== null && typeof value === "object") {
+          delete copyRecord[key];
+        }
+      }
+      delete copyRecord["required"];
+      const note = "[Truncated: nested schema exceeds maxSchemaDepth]";
+      copy.description = copy.description ? `${copy.description} ${note}` : note;
+      return copy;
+    }
+    for (const key of this.TRUNCATE_MAP_KEYS) {
+      const value = copyRecord[key];
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const mapped = {};
+        for (const [name, sub] of Object.entries(value)) {
+          mapped[name] = this.truncateDepthRecursive(sub, depth + 1, maxDepth);
+        }
+        copyRecord[key] = mapped;
+      }
+    }
+    for (const key of this.TRUNCATE_SCHEMA_KEYS) {
+      const value = copyRecord[key];
+      if (value !== null && typeof value === "object") {
+        copyRecord[key] = Array.isArray(value) ? value.map((item) => this.truncateDepthRecursive(item, depth + 1, maxDepth)) : this.truncateDepthRecursive(value, depth + 1, maxDepth);
+      }
+    }
+    for (const key of this.TRUNCATE_LIST_KEYS) {
+      const value = copyRecord[key];
+      if (Array.isArray(value)) {
+        copyRecord[key] = value.map((member) => this.truncateDepthRecursive(member, depth + 1, maxDepth));
+      }
+    }
+    return copy;
+  }
+  /**
+   * Simplify schema by removing unnecessary fields
+   */
+  static simplify(schema) {
+    const cloned = this.clone(schema);
+    if (Array.isArray(cloned.required) && cloned.required.length === 0) {
+      delete cloned.required;
+    }
+    if (cloned.properties && Object.keys(cloned.properties).length === 0) {
+      delete cloned.properties;
+    }
+    if (Array.isArray(cloned.examples) && cloned.examples.length === 0) {
+      delete cloned.examples;
+    }
+    if (cloned.title && cloned.description && cloned.title === cloned.description) {
+      delete cloned.title;
+    }
+    return cloned;
+  }
+};
+
+// src/annotations.ts
+function inferAnnotationsFromMethod(method) {
+  switch (method) {
+    case "get":
+    case "head":
+    case "options":
+    case "trace":
+      return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+    case "put":
+    case "delete":
+      return { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
+    case "post":
+    case "patch":
+      return { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
   }
-  return null;
 }
-function parseIpv4(host) {
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
-  if (!m) return null;
-  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
-  if (octets.some((n) => n > 255)) return null;
-  return octets;
+var ANNOTATION_KEYS = ["title", "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+function pickAnnotations(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const result = {};
+  for (const key of ANNOTATION_KEYS) {
+    const value = raw[key];
+    if (key === "title" ? typeof value === "string" : typeof value === "boolean") {
+      result[key] = value;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
 }
-function isBlockedIpv4(octets) {
-  const [a, b, c] = octets;
-  if (a === 0) return true;
-  if (a === 10) return true;
-  if (a === 127) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true;
-  if (a === 169 && b === 254) return true;
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && b === 0 && c === 0) return true;
-  if (a === 192 && b === 168) return true;
-  if (a === 198 && (b === 18 || b === 19)) return true;
-  if (a >= 224) return true;
-  return false;
+function mergeOverrides(base, layer) {
+  return {
+    ...base,
+    ...layer.disabled !== void 0 && { disabled: layer.disabled },
+    ...layer.name !== void 0 && { name: layer.name },
+    ...layer.title !== void 0 && { title: layer.title },
+    ...layer.description !== void 0 && { description: layer.description },
+    ...(base.annotations || layer.annotations) && {
+      annotations: { ...base.annotations, ...layer.annotations }
+    }
+  };
 }
-function isBlockedIpv6(host) {
-  let h = host;
-  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
-  const zone = h.indexOf("%");
-  if (zone !== -1) h = h.slice(0, zone);
-  const lower = h.toLowerCase();
-  if (lower === "::" || lower === "::0") return true;
-  if (lower === "::1") return true;
-  if (/^f[cd]/.test(lower)) return true;
-  if (/^fe[89a-f]/.test(lower)) return true;
-  if (/^ff/.test(lower)) return true;
-  return false;
+function readXMcp(node) {
+  return node["x-mcp"];
 }
-function isBlockedAddress(host) {
-  let h = host;
-  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
-  const mapped = decodeIpv4MappedIpv6(host);
-  if (mapped) {
-    const o = parseIpv4(mapped);
-    if (o) return isBlockedIpv4(o);
+function parseXMcpEnabled(ext) {
+  if (ext === false) return false;
+  if (ext === true) return true;
+  if (ext && typeof ext === "object" && typeof ext.enabled === "boolean") {
+    return ext.enabled;
   }
-  const v4 = parseIpv4(h);
-  if (v4) return isBlockedIpv4(v4);
-  if (h.includes(":")) return isBlockedIpv6(h);
-  return false;
-}
-function isIpLiteral(hostname) {
-  if (hostname.startsWith("[") && hostname.endsWith("]")) return true;
-  return parseIpv4(hostname) !== null;
+  return void 0;
 }
-function isBlockedHostname(hostname, ssrf) {
-  if (ssrf.allowInternalIPs) {
-    return ssrf.blockedHosts.includes(hostname);
-  }
-  if (ssrf.blockedHosts.includes(hostname)) return true;
-  const lower = hostname.toLowerCase();
-  const stripped = lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
-  if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
-  return isBlockedAddress(hostname);
+function resolveExtensionEnabled(document, pathItem, operation) {
+  let enabled = true;
+  const rootSetting = parseXMcpEnabled(readXMcp(document));
+  if (rootSetting !== void 0) enabled = rootSetting;
+  const pathSetting = parseXMcpEnabled(readXMcp(pathItem));
+  if (pathSetting !== void 0) enabled = pathSetting;
+  const operationDisabled = extractExtensionOverrides(operation).disabled;
+  if (operationDisabled !== void 0) enabled = !operationDisabled;
+  return enabled;
 }
-var SsrfResolverUnavailableError = class extends Error {
-};
-var defaultLookup = async (hostname) => {
-  let dns;
-  try {
-    dns = await import("node:dns");
-  } catch {
-    throw new SsrfResolverUnavailableError("DNS resolution is unavailable on this runtime");
-  }
-  return dns.promises.lookup(hostname, { all: true });
-};
-async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new SsrfError(`Invalid spec URL: ${url}`, { url });
+function extractExtensionOverrides(operation) {
+  const op = operation;
+  let result = {};
+  const speakeasy = op["x-speakeasy-mcp"];
+  if (speakeasy && typeof speakeasy === "object") {
+    const ext = speakeasy;
+    result = mergeOverrides(result, {
+      disabled: typeof ext["disabled"] === "boolean" ? ext["disabled"] : void 0,
+      name: typeof ext["name"] === "string" ? ext["name"] : void 0,
+      title: typeof ext["title"] === "string" ? ext["title"] : void 0,
+      description: typeof ext["description"] === "string" ? ext["description"] : void 0,
+      // Speakeasy's top-level `title` is the tool title, not an annotation slot
+      annotations: pickAnnotations({ ...ext, title: void 0 })
+    });
   }
-  const protocol = parsed.protocol.replace(/:$/, "");
-  if (protocol !== "http" && protocol !== "https") {
-    throw new SsrfError(`Protocol "${protocol}" is not allowed for network spec loading (only http/https)`, { url });
+  const xMcp = op["x-mcp"];
+  if (xMcp === false) {
+    result = mergeOverrides(result, { disabled: true });
+  } else if (xMcp === true) {
+    result = mergeOverrides(result, { disabled: false });
+  } else if (xMcp && typeof xMcp === "object") {
+    const ext = xMcp;
+    result = mergeOverrides(result, {
+      disabled: typeof ext["enabled"] === "boolean" ? !ext["enabled"] : void 0,
+      name: typeof ext["name"] === "string" ? ext["name"] : void 0,
+      title: typeof ext["title"] === "string" ? ext["title"] : void 0,
+      description: typeof ext["description"] === "string" ? ext["description"] : void 0,
+      annotations: pickAnnotations(ext["annotations"])
+    });
   }
-  const hostname = parsed.hostname;
-  if (ssrf.allowedHosts.length > 0 && !ssrf.allowedHosts.includes(hostname)) {
-    throw new SsrfError(`Host "${hostname}" is not in the allowed-hosts list`, { url });
+  const frontmcp = op["x-frontmcp"];
+  if (frontmcp && typeof frontmcp === "object" && frontmcp.annotations) {
+    const annotations = pickAnnotations(frontmcp.annotations);
+    result = mergeOverrides(result, {
+      annotations,
+      title: typeof frontmcp.annotations.title === "string" ? frontmcp.annotations.title : void 0
+    });
   }
-  if (ssrf.allowInternalIPs) {
-    if (ssrf.blockedHosts.includes(hostname)) {
-      throw new SsrfError(`Host "${hostname}" is blocked`, { url });
+  return result;
+}
+
+// src/client-targets.ts
+var MAP_KEYS = ["properties", "patternProperties", "dependentSchemas"];
+var SCHEMA_KEYS = [
+  "items",
+  "additionalProperties",
+  "not",
+  "if",
+  "then",
+  "else",
+  "propertyNames",
+  "contains",
+  "contentSchema",
+  "unevaluatedItems",
+  "unevaluatedProperties"
+];
+var LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+function isSchemaObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function walkSchema(node, visit) {
+  if (!isSchemaObject(node)) return node;
+  const visited = visit({ ...node });
+  for (const key of MAP_KEYS) {
+    const value = visited[key];
+    if (isSchemaObject(value)) {
+      const mapped = {};
+      for (const [name, sub] of Object.entries(value)) {
+        mapped[name] = walkSchema(sub, visit);
+      }
+      visited[key] = mapped;
     }
-    return [];
-  }
-  if (isBlockedHostname(hostname, ssrf)) {
-    throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
-  }
-  if (isIpLiteral(hostname)) {
-    return [];
   }
-  let addresses;
-  try {
-    addresses = await lookup(hostname);
-  } catch (error) {
-    if (error instanceof SsrfResolverUnavailableError) {
-      return [];
+  for (const key of SCHEMA_KEYS) {
+    const value = visited[key];
+    if (Array.isArray(value)) {
+      visited[key] = value.map((item) => walkSchema(item, visit));
+    } else if (isSchemaObject(value)) {
+      visited[key] = walkSchema(value, visit);
     }
-    const message = error instanceof Error ? error.message : String(error);
-    throw new SsrfError(`Host "${hostname}" could not be resolved for SSRF validation: ${message}`, { url });
   }
-  if (addresses.length === 0) {
-    throw new SsrfError(`Host "${hostname}" did not resolve to any address`, { url });
-  }
-  for (const { address } of addresses) {
-    if (isBlockedAddress(address)) {
-      throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
+  for (const key of LIST_KEYS) {
+    const value = visited[key];
+    if (Array.isArray(value)) {
+      visited[key] = value.map((member) => walkSchema(member, visit));
     }
   }
-  return addresses;
-}
-var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
-async function loadNodeHttpModules() {
-  try {
-    const [http, https] = await Promise.all([import("node:http"), import("node:https")]);
-    return { http, https };
-  } catch {
-    return null;
-  }
+  return visited;
 }
-function pickHttpModule(protocol, modules) {
-  return protocol === "https:" ? modules.https : modules.http;
-}
-function makePinnedLookup(pinned) {
-  return (_hostname, options, callback) => {
-    const done = typeof options === "function" ? options : callback;
-    const wantsAll = typeof options === "object" && options !== null && options.all === true;
-    if (wantsAll) {
-      done(
-        null,
-        pinned.map(({ address, family }) => ({ address, family }))
+function inlineLocalRefs(schema) {
+  if (!isSchemaObject(schema)) return schema;
+  const root = schema;
+  const resolvePointer = (pointer) => {
+    const parts = pointer.replace(/^#\/?/, "").split("/").filter((part) => part.length > 0).map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+    let current = root;
+    for (const part of parts) {
+      if (!isSchemaObject(current)) return void 0;
+      current = current[part];
+    }
+    return current;
+  };
+  const inline = (node, seenPointers) => {
+    if (!isSchemaObject(node)) return node;
+    const record = node;
+    const ref = record["$ref"];
+    if (typeof ref === "string" && !ref.startsWith("#")) {
+      const { $ref: _external, ...siblings } = record;
+      return inline(
+        { description: `[External $ref ${ref} removed for client compatibility]`, ...siblings },
+        seenPointers
       );
-    } else {
-      done(null, pinned[0].address, pinned[0].family);
     }
+    if (typeof ref === "string") {
+      const { $ref: _ref, ...siblings } = record;
+      if (seenPointers.has(ref)) {
+        return { description: "[Circular $ref removed for client compatibility]", ...siblings };
+      }
+      const resolved = resolvePointer(ref);
+      if (!isSchemaObject(resolved)) {
+        return { description: `[Unresolvable $ref ${ref} removed for client compatibility]`, ...siblings };
+      }
+      const inlined = inline(resolved, /* @__PURE__ */ new Set([...seenPointers, ref]));
+      if (!isSchemaObject(inlined)) return inlined;
+      return { ...inlined, ...siblings };
+    }
+    const copy = { ...record };
+    delete copy["$defs"];
+    delete copy["definitions"];
+    for (const key of MAP_KEYS) {
+      const value = copy[key];
+      if (isSchemaObject(value)) {
+        const mapped = {};
+        for (const [name, sub] of Object.entries(value)) {
+          mapped[name] = inline(sub, seenPointers);
+        }
+        copy[key] = mapped;
+      }
+    }
+    for (const key of SCHEMA_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((item) => inline(item, seenPointers));
+      } else if (isSchemaObject(value)) {
+        copy[key] = inline(value, seenPointers);
+      }
+    }
+    for (const key of LIST_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((member) => inline(member, seenPointers));
+      }
+    }
+    return copy;
   };
+  return inline(schema, /* @__PURE__ */ new Set());
 }
-var NULL_BODY_STATUS = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
-function nodePinnedTransport(modules) {
-  return (url, { headers, signal, pinned, maxBytes }) => new Promise((resolve, reject) => {
-    const limit = maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-    const lib = pickHttpModule(new URL(url).protocol, modules);
-    const requestOptions = {
-      method: "GET",
-      signal,
-      headers: { ...headers, "accept-encoding": "identity" }
-    };
-    if (pinned.length > 0) {
-      requestOptions["lookup"] = makePinnedLookup(pinned);
-    }
-    const request = lib.request(url, requestOptions, (response) => {
-      const chunks = [];
-      let received = 0;
-      response.on("data", (chunk) => {
-        received += chunk.length;
-        if (received > limit) {
-          request.destroy();
-          reject(new SsrfError(`Response body exceeds ${limit} bytes`, { url }));
-          return;
-        }
-        chunks.push(chunk);
-      });
-      response.on("end", () => {
-        const status = response.statusCode;
-        const responseHeaders = new Headers();
-        const entries = Object.entries(response.headers);
-        for (const [key, value] of entries) {
-          if (Array.isArray(value)) {
-            for (const item of value) responseHeaders.append(key, item);
-          } else {
-            responseHeaders.append(key, value);
-          }
-        }
-        const body = NULL_BODY_STATUS.has(status) ? null : Buffer.concat(chunks);
-        resolve(new Response(body, { status, statusText: response.statusMessage, headers: responseHeaders }));
-      });
-      response.on("error", reject);
-    });
-    request.on("error", reject);
-    request.end();
+function ensureArrayItems(schema) {
+  return walkSchema(schema, (node) => {
+    const type = node["type"];
+    const isArray = type === "array" || Array.isArray(type) && type.includes("array");
+    if (isArray && node["items"] === void 0) {
+      return { ...node, items: {} };
+    }
+    return node;
   });
 }
-function fetchTransport(fetchImpl) {
-  return (url, { headers, signal }) => fetchImpl(url, { headers, signal, redirect: "manual" });
+function mergeAllOf(node) {
+  const members = node["allOf"];
+  const merged = {};
+  const properties = {};
+  const required = /* @__PURE__ */ new Set();
+  for (const rawMember of members) {
+    if (!isSchemaObject(rawMember)) continue;
+    const member = Array.isArray(rawMember["allOf"]) ? mergeAllOf(rawMember) : rawMember;
+    const { properties: memberProps, required: memberRequired, ...scalars } = member;
+    Object.assign(merged, scalars);
+    if (isSchemaObject(memberProps)) Object.assign(properties, memberProps);
+    if (Array.isArray(memberRequired)) memberRequired.forEach((field) => required.add(String(field)));
+  }
+  const { allOf: _allOf, properties: ownProps, required: ownRequired, ...rest } = node;
+  Object.assign(merged, rest);
+  if (isSchemaObject(ownProps)) Object.assign(properties, ownProps);
+  if (Array.isArray(ownRequired)) ownRequired.forEach((field) => required.add(String(field)));
+  if (Object.keys(properties).length > 0) merged["properties"] = properties;
+  if (required.size > 0) merged["required"] = [...required];
+  return merged;
 }
-async function selectTransport(opts, url) {
-  if (opts.fetchImpl) {
-    return fetchTransport(opts.fetchImpl);
+function nullableWrapperMember(node) {
+  const anyOf = node["anyOf"];
+  if (!Array.isArray(anyOf) || anyOf.length !== 2) return void 0;
+  const nullIndex = anyOf.findIndex((m) => isSchemaObject(m) && m["type"] === "null");
+  if (nullIndex === -1) return void 0;
+  const other = anyOf[1 - nullIndex];
+  return isSchemaObject(other) ? other : void 0;
+}
+function describeVariants(members) {
+  return members.map((member, index) => {
+    if (!isSchemaObject(member)) return `variant ${index + 1}`;
+    const record = member;
+    return typeof record["title"] === "string" && record["title"] || typeof record["description"] === "string" && record["description"] || typeof record["type"] === "string" && `type ${record["type"]}` || `variant ${index + 1}`;
+  }).join("; ");
+}
+function collapseRootCompositions(schema) {
+  if (!isSchemaObject(schema)) return schema;
+  const node = { ...schema };
+  if (Array.isArray(node["allOf"])) {
+    return collapseRootCompositions(mergeAllOf(node));
+  }
+  const nullableMember = nullableWrapperMember(node);
+  if (nullableMember) {
+    const { anyOf: _anyOf, ...rest } = node;
+    const merged = { ...nullableMember, ...rest };
+    const note = "May be null.";
+    merged["description"] = merged["description"] ? `${merged["description"]} ${note}` : note;
+    return merged;
   }
-  const modules = await loadNodeHttpModules();
-  if (!modules) {
-    const platformFetch = globalThis.fetch;
-    if (typeof platformFetch === "function") {
-      return fetchTransport(platformFetch);
+  for (const key of ["oneOf", "anyOf"]) {
+    const members = node[key];
+    if (Array.isArray(members)) {
+      const { [key]: _members, ...rest } = node;
+      return {
+        ...rest,
+        description: `${typeof rest["description"] === "string" ? `${rest["description"]} ` : ""}Accepts one of ${members.length} variants: ${describeVariants(members)}.`,
+        "x-variants": members
+      };
     }
-    throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
   }
-  return nodePinnedTransport(modules);
+  return node;
 }
-async function safeFetch(url, opts) {
-  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
-  const transport = await selectTransport(opts, url);
-  let current = url;
-  for (let hop = 0; hop <= maxRedirects; hop++) {
-    const pinned = await assertUrlSafe(current, ssrf, lookup);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    let response;
-    try {
-      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
-    } finally {
-      clearTimeout(timer);
+function collapseNestedUnions(schema) {
+  return walkSchema(schema, (node) => {
+    let current = node;
+    for (; ; ) {
+      if (Array.isArray(current["allOf"])) {
+        current = mergeAllOf(current);
+        continue;
+      }
+      const type = current["type"];
+      if (Array.isArray(type)) {
+        const nonNull = type.filter((t) => t !== "null");
+        const notes = [];
+        if (nonNull.length > 1) notes.push(`Alternative types accepted: ${nonNull.slice(1).join(", ")}.`);
+        if (nonNull.length !== type.length) notes.push("May be null.");
+        current = { ...current, type: nonNull[0] ?? "null" };
+        if (notes.length > 0) {
+          const joined = notes.join(" ");
+          current["description"] = current["description"] ? `${current["description"]} ${joined}` : joined;
+        }
+        continue;
+      }
+      const nullableMember = nullableWrapperMember(current);
+      if (nullableMember) {
+        const { anyOf: _anyOf, ...rest } = current;
+        const merged = { ...nullableMember, ...rest };
+        const note = "May be null.";
+        merged["description"] = merged["description"] ? `${merged["description"]} ${note}` : note;
+        current = merged;
+        continue;
+      }
+      let collapsedUnion = false;
+      for (const key of ["oneOf", "anyOf"]) {
+        const members = current[key];
+        if (Array.isArray(members) && members.length > 0 && isSchemaObject(members[0])) {
+          const { [key]: _members, ...rest } = current;
+          const first = { ...members[0] };
+          const note = members.length > 1 ? `${members.length - 1} alternative schema variant(s) omitted for client compatibility: ${describeVariants(
+            members.slice(1)
+          )}.` : void 0;
+          const merged = { ...first, ...rest };
+          if (note) {
+            merged["description"] = merged["description"] ? `${merged["description"]} ${note}` : note;
+          }
+          current = merged;
+          collapsedUnion = true;
+          break;
+        }
+      }
+      if (collapsedUnion) continue;
+      return current;
     }
-    const status = typeof response.status === "number" ? response.status : 0;
-    const isRedirect = status >= 300 && status < 400 && status !== 304;
-    if (!isRedirect || !followRedirects) {
-      return response;
+  });
+}
+var GEMINI_SUPPORTED_FORMATS = /* @__PURE__ */ new Set(["date-time", "enum"]);
+var GEMINI_NUMERIC_FORMATS = /* @__PURE__ */ new Set(["int32", "int64", "float", "double"]);
+function isNumericNode(node) {
+  const type = node["type"];
+  return type === "integer" || type === "number" || Array.isArray(type) && (type.includes("integer") || type.includes("number"));
+}
+function demoteFormats(schema, supported = GEMINI_SUPPORTED_FORMATS) {
+  return walkSchema(schema, (node) => {
+    const format = node["format"];
+    if (typeof format !== "string" || supported.has(format)) return node;
+    if (GEMINI_NUMERIC_FORMATS.has(format) && isNumericNode(node)) return node;
+    const { format: _format, ...rest } = node;
+    const note = `(format: ${format})`;
+    rest["description"] = rest["description"] ? `${rest["description"]} ${note}` : note;
+    return rest;
+  });
+}
+function isObjectNode(node) {
+  const type = node["type"];
+  return type === "object" || Array.isArray(type) && type.includes("object") || type === void 0 && isSchemaObject(node["properties"]);
+}
+function enforceClosedObjects(schema) {
+  return walkSchema(schema, (node) => {
+    if (isObjectNode(node) && (node["additionalProperties"] === void 0 || node["additionalProperties"] === true)) {
+      return { ...node, additionalProperties: false };
     }
-    const location = response.headers?.get?.("location") ?? void 0;
-    if (!location) {
-      return response;
+    return node;
+  });
+}
+function requireAllProperties(schema) {
+  return walkSchema(schema, (node) => {
+    if (!isObjectNode(node) || !isSchemaObject(node["properties"])) return node;
+    const properties = node["properties"];
+    const originallyRequired = new Set(Array.isArray(node["required"]) ? node["required"].map(String) : []);
+    const rewritten = {};
+    for (const [name, propSchema] of Object.entries(properties)) {
+      if (originallyRequired.has(name) || !isSchemaObject(propSchema) || propSchema["const"] !== void 0) {
+        rewritten[name] = propSchema;
+        continue;
+      }
+      const prop = propSchema;
+      const withNullEnum = (next) => {
+        const enumValues = next["enum"];
+        if (Array.isArray(enumValues) && !enumValues.includes(null)) {
+          return { ...next, enum: [...enumValues, null] };
+        }
+        return next;
+      };
+      const type = prop["type"];
+      if (typeof type === "string" && type !== "null") {
+        rewritten[name] = withNullEnum({ ...prop, type: [type, "null"] });
+      } else if (Array.isArray(type) && !type.includes("null")) {
+        rewritten[name] = withNullEnum({ ...prop, type: [...type, "null"] });
+      } else {
+        rewritten[name] = withNullEnum(prop);
+      }
     }
-    current = new URL(location, current).toString();
+    return { ...node, properties: rewritten, required: Object.keys(properties) };
+  });
+}
+function applyClientTarget(schema, target) {
+  let result = inlineLocalRefs(schema);
+  result = ensureArrayItems(result);
+  if (target === "gemini") {
+    result = collapseNestedUnions(result);
+    result = demoteFormats(result);
+    return result;
   }
-  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
+  result = collapseRootCompositions(result);
+  if (target === "openai") {
+    result = enforceClosedObjects(result);
+    result = requireAllProperties(result);
+  }
+  return result;
 }
 
-// src/generator.ts
-var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
-  document;
-  dereferencedDocument;
-  options;
-  /**
-   * Private constructor - use static factory methods to create instances
-   */
-  constructor(document, options = {}) {
-    this.document = document;
-    this.options = {
-      dereference: options.dereference ?? true,
-      baseUrl: options.baseUrl ?? "",
-      headers: options.headers ?? {},
-      timeout: options.timeout ?? 3e4,
-      validate: options.validate ?? true,
-      followRedirects: options.followRedirects ?? true,
-      refResolution: options.refResolution ?? {}
-    };
-  }
+// src/validator.ts
+var Validator = class {
   /**
-   * Create generator from a URL
+   * Validate an OpenAPI document
    */
-  static async fromURL(url, options = {}) {
-    try {
-      const response = await safeFetch(url, {
-        headers: options.headers,
-        timeoutMs: options.timeout ?? 3e4,
-        followRedirects: options.followRedirects ?? true,
-        ssrf: normalizeSsrfOptions(options.refResolution)
+  async validate(document) {
+    const errors = [];
+    const warnings = [];
+    if (!document.openapi) {
+      errors.push({
+        message: "Missing required field: openapi",
+        path: "/openapi",
+        code: "MISSING_OPENAPI_VERSION"
       });
-      if (!response.ok) {
-        throw new LoadError(`Failed to fetch OpenAPI spec from URL: ${response.status} ${response.statusText}`, {
-          url,
-          status: response.status
+    } else if (!this.isValidOpenAPIVersion(document.openapi)) {
+      errors.push({
+        message: `Unsupported OpenAPI version: ${document.openapi}. Expected 3.0.x or 3.1.x`,
+        path: "/openapi",
+        code: "INVALID_OPENAPI_VERSION"
+      });
+    }
+    if (!document.info) {
+      errors.push({
+        message: "Missing required field: info",
+        path: "/info",
+        code: "MISSING_INFO"
+      });
+    } else {
+      if (!document.info.title) {
+        errors.push({
+          message: "Missing required field: info.title",
+          path: "/info/title",
+          code: "MISSING_TITLE"
         });
       }
-      const contentType = response.headers.get("content-type") || "";
-      const text = await response.text();
-      let document;
-      if (contentType.includes("yaml") || contentType.includes("yml") || url.match(/\.ya?ml$/i)) {
-        document = yaml.parse(text);
-      } else {
-        document = JSON.parse(text);
-      }
-      return new _OpenAPIToolGenerator(document, options);
-    } catch (error) {
-      if (error instanceof LoadError) {
-        throw error;
+      if (!document.info.version) {
+        errors.push({
+          message: "Missing required field: info.version",
+          path: "/info/version",
+          code: "MISSING_VERSION"
+        });
       }
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new LoadError(`Failed to load OpenAPI spec from URL: ${errorMessage}`, {
-        url,
-        originalError: error
+    }
+    if (!document.paths || Object.keys(document.paths).length === 0) {
+      warnings.push({
+        message: "No paths defined in OpenAPI document",
+        path: "/paths",
+        code: "NO_PATHS"
       });
+    } else {
+      this.validatePaths(document.paths, errors, warnings);
     }
-  }
-  /**
-   * Create generator from a file path
-   */
-  static async fromFile(filePath, options = {}) {
-    try {
-      const [path, fs] = await Promise.all([import("path"), import("fs/promises")]);
-      const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
-      const content = await fs.readFile(absolutePath, "utf-8");
-      const ext = path.extname(filePath).toLowerCase();
-      let document;
-      if (ext === ".yaml" || ext === ".yml") {
-        document = yaml.parse(content);
-      } else if (ext === ".json") {
-        document = JSON.parse(content);
-      } else {
-        try {
-          document = JSON.parse(content);
-        } catch {
-          document = yaml.parse(content);
-        }
-      }
-      return new _OpenAPIToolGenerator(document, options);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
-        filePath,
-        originalError: error
+    if (!document.servers || document.servers.length === 0) {
+      warnings.push({
+        message: "No servers defined. You may need to provide a baseUrl option.",
+        path: "/servers",
+        code: "NO_SERVERS"
       });
     }
-  }
-  /**
-   * Create generator from a YAML string
-   */
-  static async fromYAML(yamlString, options = {}) {
-    try {
-      const document = yaml.parse(yamlString);
-      return new _OpenAPIToolGenerator(document, options);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
-        originalError: error
+    if (document.security && !document.components?.securitySchemes) {
+      warnings.push({
+        message: "Security requirements defined but no security schemes found",
+        path: "/security",
+        code: "NO_SECURITY_SCHEMES"
       });
     }
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : void 0,
+      warnings: warnings.length > 0 ? warnings : void 0
+    };
   }
   /**
-   * Create generator from a JSON object
+   * Check if OpenAPI version is valid
    */
-  static async fromJSON(json, options = {}) {
-    const document = JSON.parse(JSON.stringify(json));
-    return new _OpenAPIToolGenerator(document, options);
+  isValidOpenAPIVersion(version) {
+    return /^3\.[01]\.\d+$/.test(version);
   }
   /**
-   * Get the OpenAPI document
+   * Validate paths
    */
-  getDocument() {
-    return this.dereferencedDocument ?? this.document;
-  }
-  /**
-   * Validate the OpenAPI document
-   */
-  async validate() {
-    const validator = new Validator();
-    return validator.validate(this.document);
-  }
-  // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
-  // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
-  // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
-  // augmented there with DNS resolution (closing the DNS-name-to-internal bypass)
-  // and per-hop redirect re-validation (`safeFetch`).
-  /**
-   * Build $RefParser options based on refResolution configuration.
-   * Defaults: allow http/https, block file://, block internal IPs.
-   */
-  buildRefParserOptions() {
-    const raw = this.options.refResolution;
-    const refOpts = {
-      allowedProtocols: raw.allowedProtocols ?? ["http", "https"],
-      allowedHosts: raw.allowedHosts ?? [],
-      blockedHosts: raw.blockedHosts ?? [],
-      allowInternalIPs: raw.allowInternalIPs ?? false
-    };
-    const allowedProtocols = new Set(refOpts.allowedProtocols);
-    const hasNetworkProtocol = allowedProtocols.size > 0 && !([...allowedProtocols].length === 1 && allowedProtocols.has("file"));
-    if (allowedProtocols.size === 0) {
-      return { resolve: { external: false } };
-    }
-    const resolveConfig = {
-      external: true,
-      file: allowedProtocols.has("file") ? void 0 : false
-    };
-    if (hasNetworkProtocol) {
-      const hasHostAllowlist = refOpts.allowedHosts.length > 0;
-      const hostAllowSet = new Set(refOpts.allowedHosts);
-      resolveConfig["http"] = {
-        // SECURITY: never auto-follow HTTP redirects when resolving external
-        // `$ref`s. `canRead` validates only the INITIAL URL; the resolver's
-        // default redirect-following (up to 5 hops) re-fetches the `Location`
-        // target WITHOUT re-invoking `canRead`, so an allowlisted host could
-        // 302 → `http://169.254.169.254/...` and smuggle a blocked target past
-        // the allow/deny lists. `redirects: 0` refuses the first redirect, and
-        // our custom `read` (below) additionally refuses redirects itself.
-        redirects: 0,
-        // Synchronous gate: protocol, host allow-list, and literal/known
-        // internal hosts. DNS names that *resolve* to internal addresses pass
-        // here (canRead cannot be async) and are caught in `read` via DNS
-        // resolution — closing the `127.0.0.1.nip.io` bypass for `$ref`s too.
-        canRead: (file) => {
-          try {
-            const parsed = new URL(file.url);
-            const protocol = parsed.protocol.replace(":", "");
-            if (!allowedProtocols.has(protocol)) {
-              return false;
-            }
-            if (hasHostAllowlist && !hostAllowSet.has(parsed.hostname)) {
-              return false;
-            }
-            if (isBlockedHostname(parsed.hostname, refOpts)) {
-              return false;
-            }
-            return true;
-          } catch {
-            return false;
-          }
-        },
-        // SSRF-safe fetch: resolves DNS and rejects names that map to internal
-        // addresses, and refuses redirects. NOTE: deliberately does NOT forward
-        // `this.options.headers` (the spec-load credentials) to third-party
-        // `$ref` hosts — that would leak the spec's auth token cross-origin.
-        read: async (file) => {
-          const response = await safeFetch(file.url, {
-            timeoutMs: this.options.timeout,
-            followRedirects: false,
-            ssrf: refOpts
-          });
-          if (!response.ok) {
-            throw new LoadError(
-              `Failed to resolve external $ref "${file.url}": ${response.status} ${response.statusText}`,
-              { url: file.url, status: response.status }
-            );
-          }
-          return response.text();
-        }
-      };
-    } else {
-      resolveConfig["http"] = false;
-    }
-    return { resolve: resolveConfig };
-  }
-  /**
-   * Does the document contain any EXTERNAL `$ref` (a ref that is not a local
-   * JSON-pointer beginning with `#`)? Only external refs require the full
-   * `$RefParser` (file/http resolvers, which pull Node builtins). A document
-   * with only internal refs can be dereferenced with the runtime-agnostic
-   * resolver below — so it works on V8 isolates (Cloudflare Workers) too.
-   */
-  static hasExternalRefs(node, seen = /* @__PURE__ */ new Set()) {
-    if (node === null || typeof node !== "object") return false;
-    if (seen.has(node)) return false;
-    seen.add(node);
-    if (Array.isArray(node)) return node.some((n) => _OpenAPIToolGenerator.hasExternalRefs(n, seen));
-    const ref = node.$ref;
-    if (typeof ref === "string" && !ref.startsWith("#")) return true;
-    return Object.values(node).some(
-      (v) => _OpenAPIToolGenerator.hasExternalRefs(v, seen)
-    );
-  }
-  /**
-   * Dereference local (`#/...`) `$ref`s without `$RefParser` — pure, dependency-
-   * free, runtime-agnostic. A pointer cache makes circular schemas resolve to a
-   * shared reference instead of recursing forever (same contract as `$RefParser`).
-   */
-  static dereferenceInternal(root) {
-    const cache = /* @__PURE__ */ new Map();
-    const resolvePointer = (ptr) => {
-      const parts = ptr.replace(/^#\/?/, "").split("/").filter((p) => p.length > 0).map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
-      let cur = root;
-      for (const p of parts) cur = cur?.[p];
-      return cur;
-    };
-    const walk = (node) => {
-      if (node === null || typeof node !== "object") return node;
-      if (Array.isArray(node)) return node.map(walk);
-      const ref = node.$ref;
-      if (typeof ref === "string" && ref.startsWith("#")) {
-        const cached = cache.get(ref);
-        if (cached !== void 0) return cached;
-        const placeholder = {};
-        cache.set(ref, placeholder);
-        const resolved = walk(resolvePointer(ref));
-        if (resolved && typeof resolved === "object") Object.assign(placeholder, resolved);
-        return placeholder;
-      }
-      const out = {};
-      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
-      return out;
-    };
-    return walk(root);
-  }
-  /**
-   * Initialize the generator (dereference if needed, then validate)
-   */
-  async initialize() {
-    if (this.options.dereference && !this.dereferencedDocument) {
-      const cloned = JSON.parse(JSON.stringify(this.document));
-      if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
-        this.dereferencedDocument = _OpenAPIToolGenerator.dereferenceInternal(cloned);
-      } else {
-        try {
-          const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
-          const refParserOptions = this.buildRefParserOptions();
-          this.dereferencedDocument = await $RefParser.dereference(cloned, refParserOptions);
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
-            originalError: error
-          });
-        }
-      }
-    }
-    if (this.options.validate) {
-      const validator = new Validator();
-      const documentToValidate = this.dereferencedDocument ?? this.document;
-      const result = await validator.validate(documentToValidate);
-      if (!result.valid) {
-        throw new ParseError("Invalid OpenAPI document", { errors: result.errors });
+  validatePaths(paths, errors, warnings) {
+    for (const [path, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue;
+      if (!path.startsWith("/")) {
+        errors.push({
+          message: `Path must start with '/': ${path}`,
+          path: `/paths/${path}`,
+          code: "INVALID_PATH_FORMAT"
+        });
       }
-    }
-  }
-  /**
-   * Generate all tools from the OpenAPI specification
-   */
-  async generateTools(options = {}) {
-    await this.initialize();
-    const document = this.getDocument();
-    const tools = [];
-    if (!document.paths) {
-      return tools;
-    }
-    for (const [pathStr, pathItem] of Object.entries(document.paths)) {
-      if (!pathItem || "$ref" in pathItem) continue;
       const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+      let hasOperations = false;
       for (const method of methods) {
         const operation = pathItem[method];
-        if (!operation) continue;
-        if (!this.shouldIncludeOperation(operation, pathStr, method, options)) {
-          continue;
-        }
-        try {
-          const tool = await this.generateTool(pathStr, method, options);
-          tools.push(tool);
-        } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          console.warn(`Failed to generate tool for ${method.toUpperCase()} ${pathStr}:`, errorMessage);
+        if (operation) {
+          hasOperations = true;
+          this.validateOperation(operation, path, method, errors, warnings);
         }
       }
+      if (!hasOperations && !pathItem.$ref) {
+        warnings.push({
+          message: `Path has no operations: ${path}`,
+          path: `/paths/${path}`,
+          code: "NO_OPERATIONS"
+        });
+      }
     }
-    return tools;
   }
   /**
-   * Generate a specific tool for a path and method
+   * Validate an operation
    */
-  async generateTool(pathStr, method, options = {}) {
-    await this.initialize();
-    const document = this.getDocument();
-    if (!document.paths) {
-      throw new Error("No paths defined in OpenAPI document");
-    }
-    const pathItem = document.paths[pathStr];
-    const operation = pathItem?.[method.toLowerCase()];
-    if (!operation) {
-      throw new Error(`Operation not found: ${method.toUpperCase()} ${pathStr}`);
+  validateOperation(operation, path, method, errors, warnings) {
+    const basePath = `/paths/${path}/${method}`;
+    if (!operation.operationId) {
+      warnings.push({
+        message: `Operation missing operationId: ${method.toUpperCase()} ${path}`,
+        path: `${basePath}/operationId`,
+        code: "NO_OPERATION_ID"
+      });
     }
-    const parameterResolver = new ParameterResolver(options.namingStrategy);
-    let pathParameters = void 0;
-    if (pathItem.parameters) {
-      pathParameters = pathItem.parameters.filter(
-        (p) => !isReferenceObject(p)
-      );
+    if (!operation.responses || Object.keys(operation.responses).length === 0) {
+      errors.push({
+        message: `Operation missing responses: ${method.toUpperCase()} ${path}`,
+        path: `${basePath}/responses`,
+        code: "NO_RESPONSES"
+      });
     }
-    let securityRequirements = void 0;
-    const securitySpec = operation.security ?? document.security;
-    if (securitySpec) {
-      securityRequirements = this.extractSecurityRequirements(securitySpec, document);
+    if (operation.parameters) {
+      this.validateParameters(operation.parameters, path, method, errors, warnings);
     }
-    const { inputSchema, mapper } = parameterResolver.resolve(
-      operation,
-      pathParameters,
-      securityRequirements,
-      options.includeSecurityInInput
+    const pathParams = path.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+    const definedPathParams = new Set(
+      operation.parameters?.filter((p) => p.in === "path").map((p) => p.name) ?? []
     );
-    const responseBuilder = new ResponseBuilder(options);
-    const outputSchema = responseBuilder.build(operation.responses);
-    const name = this.generateToolName(pathStr, method, operation.operationId, options);
-    const description = operation.summary || operation.description || `${method.toUpperCase()} ${pathStr}`;
-    const metadata = this.extractMetadata(pathStr, method, operation, document, outputSchema);
-    const formatResolvers = {
-      ...options.resolveFormats ? BUILTIN_FORMAT_RESOLVERS : {},
-      ...options.formatResolvers
-    };
-    const hasFormatResolvers = Object.keys(formatResolvers).length > 0;
-    const resolvedInputSchema = hasFormatResolvers ? resolveSchemaFormats(inputSchema, formatResolvers) : inputSchema;
-    const resolvedOutputSchema = hasFormatResolvers && outputSchema ? resolveSchemaFormats(outputSchema, formatResolvers) : outputSchema;
-    return {
-      name,
-      description,
-      inputSchema: resolvedInputSchema,
-      outputSchema: resolvedOutputSchema,
-      mapper,
-      metadata
-    };
+    for (const param of pathParams) {
+      if (!definedPathParams.has(param)) {
+        errors.push({
+          message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path}`,
+          path: `${basePath}/parameters`,
+          code: "MISSING_PATH_PARAMETER"
+        });
+      }
+    }
   }
   /**
-   * Check if an operation should be included
+   * Validate parameters
    */
-  shouldIncludeOperation(operation, path, method, options) {
-    if (operation.deprecated && !options.includeDeprecated) {
-      return false;
-    }
-    if (options.includeOperations && operation.operationId) {
-      if (!options.includeOperations.includes(operation.operationId)) {
-        return false;
+  validateParameters(parameters, path, method, errors, warnings) {
+    const basePath = `/paths/${path}/${method}/parameters`;
+    for (let i = 0; i < parameters.length; i++) {
+      const param = parameters[i];
+      const paramPath = `${basePath}/${i}`;
+      if (!param.name) {
+        errors.push({
+          message: "Parameter missing name",
+          path: `${paramPath}/name`,
+          code: "MISSING_PARAMETER_NAME"
+        });
       }
-    }
-    if (options.excludeOperations && operation.operationId) {
-      if (options.excludeOperations.includes(operation.operationId)) {
-        return false;
+      if (!param.in) {
+        errors.push({
+          message: 'Parameter missing "in" field',
+          path: `${paramPath}/in`,
+          code: "MISSING_PARAMETER_IN"
+        });
+      } else if (!["path", "query", "header", "cookie"].includes(param.in)) {
+        errors.push({
+          message: `Invalid parameter location: ${param.in}`,
+          path: `${paramPath}/in`,
+          code: "INVALID_PARAMETER_IN"
+        });
+      }
+      if (param.in === "path" && !param.required) {
+        errors.push({
+          message: `Path parameter '${param.name}' must be required`,
+          path: `${paramPath}/required`,
+          code: "PATH_PARAMETER_NOT_REQUIRED"
+        });
+      }
+      if (!param.schema && !param.content) {
+        errors.push({
+          message: `Parameter '${param.name}' missing schema or content`,
+          path: `${paramPath}`,
+          code: "MISSING_PARAMETER_SCHEMA"
+        });
       }
     }
-    if (options.filterFn) {
-      return options.filterFn({
-        ...operation,
-        path,
-        method
-      });
+  }
+};
+
+// src/errors.ts
+var OpenAPIToolError = class extends Error {
+  context;
+  constructor(message, context) {
+    super(message);
+    this.name = this.constructor.name;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
     }
-    return true;
   }
-  /**
-   * Generate a tool name
-   */
-  generateToolName(path, method, operationId, options = {}) {
-    if (options.namingStrategy?.toolNameGenerator) {
-      return options.namingStrategy.toolNameGenerator(path, method, operationId);
+};
+var LoadError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SsrfError = class extends LoadError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ParseError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ValidationError = class extends OpenAPIToolError {
+  errors;
+  constructor(message, context) {
+    super(message, context);
+    this.errors = context?.["errors"];
+  }
+};
+var GenerationError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var RequestBuildError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SchemaError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+
+// src/format-resolver.ts
+var BUILTIN_FORMAT_RESOLVERS = {
+  // String formats
+  uuid: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+    description: schema.description || "UUID string (RFC 4122)"
+  }),
+  "date-time": (schema) => ({
+    ...schema,
+    description: schema.description || "ISO 8601 date-time (e.g., 2024-01-15T09:30:00Z)"
+  }),
+  date: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^\\d{4}-\\d{2}-\\d{2}$",
+    description: schema.description || "ISO 8601 date (e.g., 2024-01-15)"
+  }),
+  time: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^\\d{2}:\\d{2}:\\d{2}",
+    description: schema.description || "ISO 8601 time (e.g., 09:30:00)"
+  }),
+  email: (schema) => ({
+    ...schema,
+    description: schema.description || "Email address (RFC 5322)"
+  }),
+  uri: (schema) => ({
+    ...schema,
+    description: schema.description || "URI (RFC 3986)"
+  }),
+  "uri-reference": (schema) => ({
+    ...schema,
+    description: schema.description || "URI reference (RFC 3986)"
+  }),
+  hostname: (schema) => ({
+    ...schema,
+    description: schema.description || "Internet hostname (RFC 1123)"
+  }),
+  ipv4: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$",
+    description: schema.description || "IPv4 address"
+  }),
+  ipv6: (schema) => ({
+    ...schema,
+    description: schema.description || "IPv6 address (RFC 4291)"
+  }),
+  // Integer formats
+  int32: (schema) => ({
+    ...schema,
+    minimum: schema.minimum ?? -2147483648,
+    maximum: schema.maximum ?? 2147483647
+  }),
+  int64: (schema) => ({
+    ...schema,
+    minimum: schema.minimum ?? Number.MIN_SAFE_INTEGER,
+    maximum: schema.maximum ?? Number.MAX_SAFE_INTEGER
+  }),
+  // Binary/encoding formats
+  byte: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^[A-Za-z0-9+/]*={0,2}$",
+    description: schema.description || "Base64-encoded string (RFC 4648)"
+  }),
+  binary: (schema) => ({
+    ...schema,
+    description: schema.description || "Binary data"
+  }),
+  // Sensitive data formats
+  password: (schema) => ({
+    ...schema,
+    description: schema.description || "Password (sensitive, UI should mask input)"
+  })
+};
+function resolveSchemaFormats(schema, resolvers) {
+  if (!schema || typeof schema !== "object") return schema;
+  let result = { ...schema };
+  const format = result["format"];
+  if (format && resolvers[format]) {
+    result = { ...resolvers[format](result) };
+  }
+  if (result["properties"] && typeof result["properties"] === "object") {
+    const props = {};
+    for (const [key, value] of Object.entries(result["properties"])) {
+      props[key] = resolveSchemaFormats(value, resolvers);
+    }
+    result["properties"] = props;
+  }
+  if (result["items"]) {
+    if (Array.isArray(result["items"])) {
+      result["items"] = result["items"].map((item) => resolveSchemaFormats(item, resolvers));
+    } else {
+      result["items"] = resolveSchemaFormats(result["items"], resolvers);
     }
-    if (operationId) {
-      return operationId;
+  }
+  if (result["additionalProperties"] && typeof result["additionalProperties"] === "object") {
+    result["additionalProperties"] = resolveSchemaFormats(result["additionalProperties"], resolvers);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    if (result[key] && Array.isArray(result[key])) {
+      result[key] = result[key].map((s) => resolveSchemaFormats(s, resolvers));
     }
-    const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
-    return `${method}_${sanitized}`;
   }
-  /**
-   * Extract metadata from operation
-   */
-  extractMetadata(path, method, operation, document, outputSchema) {
-    const metadata = {
-      path,
-      method,
-      operationId: operation.operationId,
-      operationSummary: operation.summary,
-      operationDescription: operation.description,
-      tags: operation.tags,
-      deprecated: operation.deprecated
-    };
-    if (operation.security || document.security) {
-      metadata.security = this.extractSecurityRequirements(
-        operation.security ?? document.security,
-        document
+  if (result["not"] && typeof result["not"] === "object") {
+    result["not"] = resolveSchemaFormats(result["not"], resolvers);
+  }
+  return result;
+}
+
+// src/ssrf.ts
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "ip6-localhost",
+  "ip6-loopback",
+  "metadata",
+  "metadata.google.internal",
+  "metadata.goog"
+]);
+function normalizeSsrfOptions(refResolution) {
+  return {
+    allowedHosts: refResolution?.allowedHosts ?? [],
+    blockedHosts: refResolution?.blockedHosts ?? [],
+    allowInternalIPs: refResolution?.allowInternalIPs ?? false
+  };
+}
+function decodeIpv4MappedIpv6(hostname) {
+  let h = hostname;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const lower = h.toLowerCase();
+  const marker = lower.lastIndexOf("::ffff:");
+  if (marker === -1) return null;
+  const tail = lower.slice(marker + "::ffff:".length);
+  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
+  const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
+    return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+  }
+  return null;
+}
+function parseIpv4(host) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return null;
+  const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  if (octets.some((n) => n > 255)) return null;
+  return octets;
+}
+function isBlockedIpv4(octets) {
+  const [a, b, c] = octets;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 0 && c === 0) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function isBlockedIpv6(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const zone = h.indexOf("%");
+  if (zone !== -1) h = h.slice(0, zone);
+  const lower = h.toLowerCase();
+  if (lower === "::" || lower === "::0") return true;
+  if (lower === "::1") return true;
+  if (/^f[cd]/.test(lower)) return true;
+  if (/^fe[89a-f]/.test(lower)) return true;
+  if (/^ff/.test(lower)) return true;
+  return false;
+}
+function isBlockedAddress(host) {
+  let h = host;
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  const mapped = decodeIpv4MappedIpv6(host);
+  if (mapped) {
+    const o = parseIpv4(mapped);
+    if (o) return isBlockedIpv4(o);
+  }
+  const v4 = parseIpv4(h);
+  if (v4) return isBlockedIpv4(v4);
+  if (h.includes(":")) return isBlockedIpv6(h);
+  return false;
+}
+function isIpLiteral(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return true;
+  return parseIpv4(hostname) !== null;
+}
+function isBlockedHostname(hostname, ssrf) {
+  if (ssrf.allowInternalIPs) {
+    return ssrf.blockedHosts.includes(hostname);
+  }
+  if (ssrf.blockedHosts.includes(hostname)) return true;
+  const lower = hostname.toLowerCase();
+  const stripped = lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
+  if (BLOCKED_HOSTNAMES.has(lower) || BLOCKED_HOSTNAMES.has(stripped)) return true;
+  return isBlockedAddress(hostname);
+}
+var SsrfResolverUnavailableError = class extends Error {
+};
+var defaultLookup = async (hostname) => {
+  let dns;
+  try {
+    dns = await import("node:dns");
+  } catch {
+    throw new SsrfResolverUnavailableError("DNS resolution is unavailable on this runtime");
+  }
+  return dns.promises.lookup(hostname, { all: true });
+};
+async function assertUrlSafe(url, ssrf, lookup = defaultLookup) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new SsrfError(`Invalid spec URL: ${url}`, { url });
+  }
+  const protocol = parsed.protocol.replace(/:$/, "");
+  if (protocol !== "http" && protocol !== "https") {
+    throw new SsrfError(`Protocol "${protocol}" is not allowed for network spec loading (only http/https)`, { url });
+  }
+  const hostname = parsed.hostname;
+  if (ssrf.allowedHosts.length > 0 && !ssrf.allowedHosts.includes(hostname)) {
+    throw new SsrfError(`Host "${hostname}" is not in the allowed-hosts list`, { url });
+  }
+  if (ssrf.allowInternalIPs) {
+    if (ssrf.blockedHosts.includes(hostname)) {
+      throw new SsrfError(`Host "${hostname}" is blocked`, { url });
+    }
+    return [];
+  }
+  if (isBlockedHostname(hostname, ssrf)) {
+    throw new SsrfError(`Host "${hostname}" maps to a blocked internal address`, { url });
+  }
+  if (isIpLiteral(hostname)) {
+    return [];
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname);
+  } catch (error) {
+    if (error instanceof SsrfResolverUnavailableError) {
+      return [];
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SsrfError(`Host "${hostname}" could not be resolved for SSRF validation: ${message}`, { url });
+  }
+  if (addresses.length === 0) {
+    throw new SsrfError(`Host "${hostname}" did not resolve to any address`, { url });
+  }
+  for (const { address } of addresses) {
+    if (isBlockedAddress(address)) {
+      throw new SsrfError(`Host "${hostname}" resolves to blocked address ${address}`, { url });
+    }
+  }
+  return addresses;
+}
+var DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+async function loadNodeHttpModules() {
+  try {
+    const [http, https] = await Promise.all([import("node:http"), import("node:https")]);
+    return { http, https };
+  } catch {
+    return null;
+  }
+}
+function pickHttpModule(protocol, modules) {
+  return protocol === "https:" ? modules.https : modules.http;
+}
+function makePinnedLookup(pinned) {
+  return (_hostname, options, callback) => {
+    const done = typeof options === "function" ? options : callback;
+    const wantsAll = typeof options === "object" && options !== null && options.all === true;
+    if (wantsAll) {
+      done(
+        null,
+        pinned.map(({ address, family }) => ({ address, family }))
       );
+    } else {
+      done(null, pinned[0].address, pinned[0].family);
     }
-    const servers = operation.servers ?? document.servers;
-    if (servers) {
-      metadata.servers = servers.map((server) => ({
-        url: this.options.baseUrl || server.url,
-        description: server.description,
-        variables: server.variables
-      }));
-    } else if (this.options.baseUrl) {
-      metadata.servers = [{ url: this.options.baseUrl }];
+  };
+}
+var NULL_BODY_STATUS = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+function nodePinnedTransport(modules) {
+  return (url, { headers, signal, pinned, maxBytes }) => new Promise((resolve, reject) => {
+    const limit = maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const lib = pickHttpModule(new URL(url).protocol, modules);
+    const requestOptions = {
+      method: "GET",
+      signal,
+      headers: { ...headers, "accept-encoding": "identity" }
+    };
+    if (pinned.length > 0) {
+      requestOptions["lookup"] = makePinnedLookup(pinned);
     }
-    const schemaObj = outputSchema;
-    if (schemaObj && Array.isArray(schemaObj["oneOf"])) {
-      const codes = schemaObj["oneOf"].map((schema) => schema["x-status-code"]).filter((code) => code !== void 0 && code !== null);
-      if (codes.length > 0) {
-        metadata.responseStatusCodes = codes;
-      }
-    } else if (schemaObj && schemaObj["x-status-code"] !== void 0 && schemaObj["x-status-code"] !== null) {
-      metadata.responseStatusCodes = [schemaObj["x-status-code"]];
+    const request = lib.request(url, requestOptions, (response) => {
+      const chunks = [];
+      let received = 0;
+      response.on("data", (chunk) => {
+        received += chunk.length;
+        if (received > limit) {
+          request.destroy();
+          reject(new SsrfError(`Response body exceeds ${limit} bytes`, { url }));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        const status = response.statusCode;
+        const responseHeaders = new Headers();
+        const entries = Object.entries(response.headers);
+        for (const [key, value] of entries) {
+          if (Array.isArray(value)) {
+            for (const item of value) responseHeaders.append(key, item);
+          } else {
+            responseHeaders.append(key, value);
+          }
+        }
+        const body = NULL_BODY_STATUS.has(status) ? null : Buffer.concat(chunks);
+        resolve(new Response(body, { status, statusText: response.statusMessage, headers: responseHeaders }));
+      });
+      response.on("error", reject);
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+function fetchTransport(fetchImpl) {
+  return (url, { headers, signal }) => fetchImpl(url, { headers, signal, redirect: "manual" });
+}
+async function selectTransport(opts, url) {
+  if (opts.fetchImpl) {
+    return fetchTransport(opts.fetchImpl);
+  }
+  const modules = await loadNodeHttpModules();
+  if (!modules) {
+    const platformFetch = globalThis.fetch;
+    if (typeof platformFetch === "function") {
+      return fetchTransport(platformFetch);
     }
-    if (operation.externalDocs) {
-      metadata.externalDocs = operation.externalDocs;
+    throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
+  }
+  return nodePinnedTransport(modules);
+}
+async function safeFetch(url, opts) {
+  const { headers, timeoutMs = 3e4, followRedirects = true, maxRedirects = 5, ssrf, lookup } = opts;
+  const transport = await selectTransport(opts, url);
+  let current = url;
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    const pinned = await assertUrlSafe(current, ssrf, lookup);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await transport(current, { headers, signal: controller.signal, pinned, maxBytes: opts.maxResponseBytes });
+    } finally {
+      clearTimeout(timer);
     }
-    const operationWithExt = operation;
-    if (operationWithExt["x-frontmcp"]) {
-      metadata.frontmcp = operationWithExt["x-frontmcp"];
+    const status = typeof response.status === "number" ? response.status : 0;
+    const isRedirect = status >= 300 && status < 400 && status !== 304;
+    if (!isRedirect || !followRedirects) {
+      return response;
     }
-    return metadata;
-  }
-  /**
-   * Extract security requirements
-   */
-  extractSecurityRequirements(security, document) {
-    if (!security || !document.components?.securitySchemes) {
-      return [];
+    const location = response.headers?.get?.("location") ?? void 0;
+    if (!location) {
+      return response;
     }
-    return security.flatMap(
-      (req) => Object.entries(req).map(([scheme, scopes]) => {
-        const securityScheme = document.components.securitySchemes[scheme];
-        if (isReferenceObject(securityScheme)) {
-          return { scheme, type: "http", scopes };
-        }
-        const apiKeyIn = "in" in securityScheme ? securityScheme.in : void 0;
-        const result = {
-          scheme,
-          type: securityScheme.type,
-          scopes,
-          name: "name" in securityScheme ? securityScheme.name : void 0,
-          in: apiKeyIn && (apiKeyIn === "query" || apiKeyIn === "header" || apiKeyIn === "cookie") ? apiKeyIn : void 0
-        };
-        if (securityScheme.type === "http") {
-          result.httpScheme = "scheme" in securityScheme ? securityScheme.scheme : void 0;
-          result.bearerFormat = "bearerFormat" in securityScheme ? securityScheme.bearerFormat : void 0;
-        }
-        result.description = "description" in securityScheme ? securityScheme.description : void 0;
-        return result;
-      })
-    );
+    current = new URL(location, current).toString();
   }
-};
+  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
+}
 
-// src/schema-builder.ts
-var SchemaBuilder = class {
-  /**
-   * Merge multiple schemas into one
-   */
-  static merge(schemas) {
-    if (schemas.length === 0) {
-      return { type: "object" };
-    }
-    if (schemas.length === 1) {
-      return schemas[0];
+// src/generator.ts
+var MCP_MAX_TOOL_NAME_LENGTH = 128;
+var DEFAULT_MAX_TOOL_NAME_LENGTH = 64;
+var MAX_NAME_DEDUP_ATTEMPTS = 256;
+function applySecureDefaults(options) {
+  if (!options.secureDefaults) return options;
+  return {
+    ...options,
+    followRedirects: options.followRedirects ?? false,
+    // Merge PER KEY: a user tightening one refResolution knob (e.g.
+    // blockedHosts) must not silently discard the preset's external-$ref
+    // lockdown. A DEFINED allowedProtocols still wins — but an explicitly
+    // undefined one (programmatic option building) must not defeat the
+    // preset via object spread copying undefined-valued keys.
+    refResolution: {
+      ...options.refResolution,
+      allowedProtocols: options.refResolution?.allowedProtocols ?? []
     }
-    const merged = {
-      type: "object",
-      properties: {},
-      required: []
-    };
-    const allRequired = /* @__PURE__ */ new Set();
-    for (const schema of schemas) {
-      if (schema.properties) {
-        merged.properties = {
-          ...merged.properties,
-          ...schema.properties
-        };
-      }
-      if (schema.required) {
-        schema.required.forEach((field) => allRequired.add(field));
+  };
+}
+function globToRegExp(glob) {
+  let pattern = "^";
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === "*") {
+      if (glob[i + 1] === "*") {
+        pattern += ".*";
+        i++;
+      } else {
+        pattern += "[^/]*";
       }
+    } else if (char === "?") {
+      pattern += "[^/]";
+    } else {
+      pattern += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
-    if (allRequired.size > 0) {
-      merged.required = Array.from(allRequired);
+  }
+  return new RegExp(`${pattern}$`);
+}
+function matchesAnyGlob(path, globs) {
+  return globs.some((glob) => globToRegExp(glob).test(path));
+}
+function fnv1aHex(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function normalizeToolName(raw, maxLength, fallbackSeed) {
+  let hashSeed = raw;
+  let name = raw.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (name.length === 0) {
+    hashSeed = fallbackSeed;
+    name = `tool_${fnv1aHex(fallbackSeed)}`;
+  }
+  const cap = Math.min(Math.max(1, maxLength), MCP_MAX_TOOL_NAME_LENGTH);
+  if (name.length > cap) {
+    if (cap >= 13) {
+      name = `${name.slice(0, cap - 9)}_${fnv1aHex(hashSeed)}`;
+    } else {
+      name = fnv1aHex(hashSeed).slice(0, cap);
     }
-    return merged;
   }
+  return name;
+}
+var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
+  document;
+  dereferencedDocument;
+  options;
   /**
-   * Create a union schema (oneOf)
+   * Private constructor - use static factory methods to create instances
    */
-  static union(schemas) {
-    if (schemas.length === 0) {
-      return {};
-    }
-    if (schemas.length === 1) {
-      return schemas[0];
-    }
-    return {
-      oneOf: schemas
+  constructor(document, rawOptions = {}) {
+    this.document = document;
+    const options = applySecureDefaults(rawOptions);
+    this.options = {
+      dereference: options.dereference ?? true,
+      baseUrl: options.baseUrl ?? "",
+      headers: options.headers ?? {},
+      timeout: options.timeout ?? 3e4,
+      validate: options.validate ?? true,
+      followRedirects: options.followRedirects ?? true,
+      refResolution: options.refResolution ?? {},
+      secureDefaults: options.secureDefaults ?? false
     };
   }
   /**
-   * Deep clone a schema
+   * Create generator from a URL
    */
-  static clone(schema) {
-    return JSON.parse(JSON.stringify(schema));
+  static async fromURL(url, rawOptions = {}) {
+    const options = applySecureDefaults(rawOptions);
+    try {
+      const response = await safeFetch(url, {
+        headers: options.headers,
+        timeoutMs: options.timeout ?? 3e4,
+        followRedirects: options.followRedirects ?? true,
+        ssrf: normalizeSsrfOptions(options.refResolution)
+      });
+      if (!response.ok) {
+        throw new LoadError(`Failed to fetch OpenAPI spec from URL: ${response.status} ${response.statusText}`, {
+          url,
+          status: response.status
+        });
+      }
+      const contentType = response.headers.get("content-type") || "";
+      const text = await response.text();
+      let document;
+      if (contentType.includes("yaml") || contentType.includes("yml") || url.match(/\.ya?ml$/i)) {
+        document = yaml.parse(text);
+      } else {
+        document = JSON.parse(text);
+      }
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      if (error instanceof LoadError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from URL: ${errorMessage}`, {
+        url,
+        originalError: error
+      });
+    }
   }
   /**
-   * Remove $ref from schema (assumes already dereferenced)
+   * Create generator from a file path
    */
-  static removeRefs(schema) {
-    const cloned = this.clone(schema);
-    this.removeRefsRecursive(cloned);
-    return cloned;
-  }
-  static removeRefsRecursive(obj) {
-    if (!obj || typeof obj !== "object") return;
-    if (obj.$ref) {
-      delete obj.$ref;
-    }
-    for (const key in obj) {
-      if (key in obj) {
-        const value = obj[key];
-        if (value && typeof value === "object") {
-          this.removeRefsRecursive(value);
+  static async fromFile(filePath, options = {}) {
+    try {
+      const [path, fs] = await Promise.all([import("path"), import("fs/promises")]);
+      const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+      const content = await fs.readFile(absolutePath, "utf-8");
+      const ext = path.extname(filePath).toLowerCase();
+      let document;
+      if (ext === ".yaml" || ext === ".yml") {
+        document = yaml.parse(content);
+      } else if (ext === ".json") {
+        document = JSON.parse(content);
+      } else {
+        try {
+          document = JSON.parse(content);
+        } catch {
+          document = yaml.parse(content);
         }
       }
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
+        filePath,
+        originalError: error
+      });
     }
   }
   /**
-   * Add description to schema
+   * Create generator from a YAML string
    */
-  static withDescription(schema, description) {
-    return {
-      ...schema,
-      description
-    };
+  static async fromYAML(yamlString, options = {}) {
+    try {
+      const document = yaml.parse(yamlString);
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
+        originalError: error
+      });
+    }
   }
   /**
-   * Add example to schema
+   * Create generator from a JSON object
    */
-  static withExample(schema, example) {
-    const existingExamples = Array.isArray(schema.examples) ? schema.examples : [];
-    return {
-      ...schema,
-      examples: [...existingExamples, example]
-    };
+  static async fromJSON(json, options = {}) {
+    const document = JSON.parse(JSON.stringify(json));
+    return new _OpenAPIToolGenerator(document, options);
   }
   /**
-   * Add default value to schema
+   * Get the OpenAPI document
    */
-  static withDefault(schema, defaultValue) {
-    return {
-      ...schema,
-      default: defaultValue
-    };
+  getDocument() {
+    return this.dereferencedDocument ?? this.document;
+  }
+  /**
+   * Validate the OpenAPI document
+   */
+  async validate() {
+    const validator = new Validator();
+    return validator.validate(this.document);
   }
+  // NOTE: internal/private-address blocking + IPv4-mapped-IPv6 decoding now live
+  // in `ssrf.ts` (`isBlockedHostname` / `isBlockedAddress` / `decodeIpv4MappedIpv6`),
+  // shared by the spec-URL fetch (`fromURL`) and the `$ref` resolver below, and
+  // augmented there with DNS resolution (closing the DNS-name-to-internal bypass)
+  // and per-hop redirect re-validation (`safeFetch`).
   /**
-   * Add format to schema
+   * Build $RefParser options based on refResolution configuration.
+   * Defaults: allow http/https, block file://, block internal IPs.
    */
-  static withFormat(schema, format) {
-    return {
-      ...schema,
-      format
+  buildRefParserOptions() {
+    const raw = this.options.refResolution;
+    const refOpts = {
+      allowedProtocols: raw.allowedProtocols ?? ["http", "https"],
+      allowedHosts: raw.allowedHosts ?? [],
+      blockedHosts: raw.blockedHosts ?? [],
+      allowInternalIPs: raw.allowInternalIPs ?? false
+    };
+    const allowedProtocols = new Set(refOpts.allowedProtocols);
+    const hasNetworkProtocol = allowedProtocols.size > 0 && !([...allowedProtocols].length === 1 && allowedProtocols.has("file"));
+    if (allowedProtocols.size === 0) {
+      return { resolve: { external: false } };
+    }
+    const resolveConfig = {
+      external: true,
+      file: allowedProtocols.has("file") ? void 0 : false
     };
+    if (hasNetworkProtocol) {
+      const hasHostAllowlist = refOpts.allowedHosts.length > 0;
+      const hostAllowSet = new Set(refOpts.allowedHosts);
+      resolveConfig["http"] = {
+        // SECURITY: never auto-follow HTTP redirects when resolving external
+        // `$ref`s. `canRead` validates only the INITIAL URL; the resolver's
+        // default redirect-following (up to 5 hops) re-fetches the `Location`
+        // target WITHOUT re-invoking `canRead`, so an allowlisted host could
+        // 302 → `http://169.254.169.254/...` and smuggle a blocked target past
+        // the allow/deny lists. `redirects: 0` refuses the first redirect, and
+        // our custom `read` (below) additionally refuses redirects itself.
+        redirects: 0,
+        // Synchronous gate: protocol, host allow-list, and literal/known
+        // internal hosts. DNS names that *resolve* to internal addresses pass
+        // here (canRead cannot be async) and are caught in `read` via DNS
+        // resolution — closing the `127.0.0.1.nip.io` bypass for `$ref`s too.
+        canRead: (file) => {
+          try {
+            const parsed = new URL(file.url);
+            const protocol = parsed.protocol.replace(":", "");
+            if (!allowedProtocols.has(protocol)) {
+              return false;
+            }
+            if (hasHostAllowlist && !hostAllowSet.has(parsed.hostname)) {
+              return false;
+            }
+            if (isBlockedHostname(parsed.hostname, refOpts)) {
+              return false;
+            }
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        // SSRF-safe fetch: resolves DNS and rejects names that map to internal
+        // addresses, and refuses redirects. NOTE: deliberately does NOT forward
+        // `this.options.headers` (the spec-load credentials) to third-party
+        // `$ref` hosts — that would leak the spec's auth token cross-origin.
+        read: async (file) => {
+          const response = await safeFetch(file.url, {
+            timeoutMs: this.options.timeout,
+            followRedirects: false,
+            ssrf: refOpts
+          });
+          if (!response.ok) {
+            throw new LoadError(
+              `Failed to resolve external $ref "${file.url}": ${response.status} ${response.statusText}`,
+              { url: file.url, status: response.status }
+            );
+          }
+          return response.text();
+        }
+      };
+    } else {
+      resolveConfig["http"] = false;
+    }
+    return { resolve: resolveConfig };
   }
   /**
-   * Add pattern to schema
+   * Does the document contain any EXTERNAL `$ref` (a ref that is not a local
+   * JSON-pointer beginning with `#`)? Only external refs require the full
+   * `$RefParser` (file/http resolvers, which pull Node builtins). A document
+   * with only internal refs can be dereferenced with the runtime-agnostic
+   * resolver below — so it works on V8 isolates (Cloudflare Workers) too.
    */
-  static withPattern(schema, pattern) {
-    return {
-      ...schema,
-      pattern
-    };
+  static hasExternalRefs(node, seen = /* @__PURE__ */ new Set()) {
+    if (node === null || typeof node !== "object") return false;
+    if (seen.has(node)) return false;
+    seen.add(node);
+    if (Array.isArray(node)) return node.some((n) => _OpenAPIToolGenerator.hasExternalRefs(n, seen));
+    const ref = node.$ref;
+    if (typeof ref === "string" && !ref.startsWith("#")) return true;
+    return Object.values(node).some(
+      (v) => _OpenAPIToolGenerator.hasExternalRefs(v, seen)
+    );
   }
   /**
-   * Add enum to schema
+   * Dereference local (`#/...`) `$ref`s without `$RefParser` — pure, dependency-
+   * free, runtime-agnostic. A pointer cache makes circular schemas resolve to a
+   * shared reference instead of recursing forever (same contract as `$RefParser`).
    */
-  static withEnum(schema, values) {
-    return {
-      ...schema,
-      enum: values
+  static dereferenceInternal(root) {
+    const cache = /* @__PURE__ */ new Map();
+    const resolvePointer = (ptr) => {
+      const parts = ptr.replace(/^#\/?/, "").split("/").filter((p) => p.length > 0).map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+      let cur = root;
+      for (const p of parts) cur = cur?.[p];
+      return cur;
+    };
+    const walk = (node) => {
+      if (node === null || typeof node !== "object") return node;
+      if (Array.isArray(node)) return node.map(walk);
+      const ref = node.$ref;
+      if (typeof ref === "string" && ref.startsWith("#")) {
+        const cached = cache.get(ref);
+        if (cached !== void 0) return cached;
+        const placeholder = {};
+        cache.set(ref, placeholder);
+        const resolved = walk(resolvePointer(ref));
+        if (resolved && typeof resolved === "object") Object.assign(placeholder, resolved);
+        return placeholder;
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      return out;
     };
+    return walk(root);
   }
   /**
-   * Add minimum/maximum constraints
+   * Initialize the generator (dereference if needed, then validate)
    */
-  static withRange(schema, min, max, options = {}) {
-    const result = { ...schema };
-    if (min !== void 0) {
-      if (options.exclusive) {
-        result.exclusiveMinimum = min;
+  async initialize() {
+    if (this.options.dereference && !this.dereferencedDocument) {
+      const cloned = JSON.parse(JSON.stringify(this.document));
+      if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
+        this.dereferencedDocument = _OpenAPIToolGenerator.dereferenceInternal(cloned);
       } else {
-        result.minimum = min;
+        try {
+          const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
+          const refParserOptions = this.buildRefParserOptions();
+          this.dereferencedDocument = await $RefParser.dereference(cloned, refParserOptions);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
+            originalError: error
+          });
+        }
       }
     }
-    if (max !== void 0) {
-      if (options.exclusive) {
-        result.exclusiveMaximum = max;
-      } else {
-        result.maximum = max;
+    if (this.options.validate) {
+      const validator = new Validator();
+      const documentToValidate = this.dereferencedDocument ?? this.document;
+      const result = await validator.validate(documentToValidate);
+      if (!result.valid) {
+        throw new ParseError("Invalid OpenAPI document", { errors: result.errors });
       }
     }
-    return result;
   }
   /**
-   * Add minLength/maxLength constraints
+   * Generate all tools from the OpenAPI specification
    */
-  static withLength(schema, minLength, maxLength) {
-    const result = { ...schema };
-    if (minLength !== void 0) {
-      result.minLength = minLength;
+  async generateTools(options = {}) {
+    await this.initialize();
+    const document = this.getDocument();
+    const tools = [];
+    const usedNames = /* @__PURE__ */ new Set();
+    if (!document.paths) {
+      return tools;
     }
-    if (maxLength !== void 0) {
-      result.maxLength = maxLength;
+    const sortedPaths = Object.entries(document.paths).sort(([a], [b]) => a < b ? -1 : 1);
+    for (const [pathStr, pathItem] of sortedPaths) {
+      if (!pathItem || "$ref" in pathItem) continue;
+      const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+      for (const method of methods) {
+        const operation = pathItem[method];
+        if (!operation) continue;
+        if (!this.shouldIncludeOperation(operation, pathStr, method, options, document, pathItem)) {
+          continue;
+        }
+        try {
+          let tool = await this.generateTool(pathStr, method, options);
+          if (usedNames.has(tool.name)) {
+            const maxLength = options.maxToolNameLength ?? DEFAULT_MAX_TOOL_NAME_LENGTH;
+            let seed = `${method} ${pathStr}`;
+            let deduped = normalizeToolName(`${tool.name}_${fnv1aHex(seed)}`, maxLength, seed);
+            let attempts = 1;
+            while (usedNames.has(deduped)) {
+              if (attempts >= MAX_NAME_DEDUP_ATTEMPTS) {
+                throw new GenerationError(
+                  `Unable to find a unique tool name for "${tool.name}" (${method.toUpperCase()} ${pathStr}) within ${MAX_NAME_DEDUP_ATTEMPTS} attempts \u2014 the name space under maxToolNameLength=${maxLength} is exhausted. Increase maxToolNameLength or rename the operation.`,
+                  { name: tool.name, method, path: pathStr, maxToolNameLength: maxLength }
+                );
+              }
+              seed += "#";
+              deduped = normalizeToolName(`${tool.name}_${fnv1aHex(seed)}`, maxLength, seed);
+              attempts++;
+            }
+            tool = { ...tool, name: deduped };
+          }
+          usedNames.add(tool.name);
+          tools.push(tool);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          console.warn(`Failed to generate tool for ${method.toUpperCase()} ${pathStr}:`, errorMessage);
+        }
+      }
     }
-    return result;
-  }
-  /**
-   * Create object schema
-   */
-  static object(properties, required) {
-    return {
-      type: "object",
-      properties,
-      ...required && required.length > 0 && { required },
-      additionalProperties: false
-    };
-  }
-  /**
-   * Create array schema
-   */
-  static array(items, constraints) {
-    return {
-      type: "array",
-      items,
-      ...constraints
-    };
+    return tools;
   }
   /**
-   * Create string schema
+   * Generate a specific tool for a path and method
    */
-  static string(constraints) {
-    return {
-      type: "string",
-      ...constraints
+  async generateTool(pathStr, method, options = {}) {
+    await this.initialize();
+    const document = this.getDocument();
+    if (!document.paths) {
+      throw new Error("No paths defined in OpenAPI document");
+    }
+    const pathItem = document.paths[pathStr];
+    const operation = pathItem?.[method.toLowerCase()];
+    if (!operation) {
+      throw new Error(`Operation not found: ${method.toUpperCase()} ${pathStr}`);
+    }
+    const parameterResolver = new ParameterResolver(options.namingStrategy, {
+      includeExamples: options.includeExamples
+    });
+    let pathParameters = void 0;
+    if (pathItem.parameters) {
+      pathParameters = pathItem.parameters.filter(
+        (p) => !isReferenceObject(p)
+      );
+    }
+    let securityRequirements = void 0;
+    const securitySpec = operation.security ?? document.security;
+    if (securitySpec) {
+      securityRequirements = this.extractSecurityRequirements(securitySpec, document);
+    }
+    const { inputSchema, mapper } = parameterResolver.resolve(
+      operation,
+      pathParameters,
+      securityRequirements,
+      options.includeSecurityInInput
+    );
+    const responseBuilder = new ResponseBuilder(options);
+    const outputSchema = responseBuilder.build(operation.responses);
+    const overrides = extractExtensionOverrides(operation);
+    const name = this.generateToolName(pathStr, method, overrides.name ?? operation.operationId, options);
+    const description = overrides.description ?? (operation.summary || operation.description || `${method.toUpperCase()} ${pathStr}`);
+    const title = overrides.title ?? operation.summary;
+    const inferred = options.inferAnnotations !== false ? inferAnnotationsFromMethod(method.toLowerCase()) : void 0;
+    const annotations = inferred || overrides.annotations ? { ...inferred, ...overrides.annotations } : void 0;
+    const metadata = this.extractMetadata(pathStr, method, operation, document, outputSchema);
+    const formatResolvers = {
+      ...options.resolveFormats ? BUILTIN_FORMAT_RESOLVERS : {},
+      ...options.formatResolvers
     };
-  }
-  /**
-   * Create number schema
-   */
-  static number(constraints) {
+    const hasFormatResolvers = Object.keys(formatResolvers).length > 0;
+    let resolvedInputSchema = hasFormatResolvers ? resolveSchemaFormats(inputSchema, formatResolvers) : inputSchema;
+    let resolvedOutputSchema = hasFormatResolvers && outputSchema ? resolveSchemaFormats(outputSchema, formatResolvers) : outputSchema;
+    const maxSchemaDepth = Math.max(1, options.maxSchemaDepth ?? 10);
+    resolvedInputSchema = SchemaBuilder.truncateDepth(resolvedInputSchema, maxSchemaDepth);
+    if (resolvedOutputSchema) {
+      resolvedOutputSchema = SchemaBuilder.truncateDepth(resolvedOutputSchema, maxSchemaDepth);
+    }
+    if (options.target) {
+      resolvedInputSchema = applyClientTarget(resolvedInputSchema, options.target);
+      if (resolvedOutputSchema) {
+        resolvedOutputSchema = applyClientTarget(resolvedOutputSchema, options.target);
+      }
+    }
     return {
-      type: "number",
-      ...constraints
+      name,
+      ...title !== void 0 && { title },
+      description,
+      ...annotations && { annotations },
+      inputSchema: resolvedInputSchema,
+      outputSchema: resolvedOutputSchema,
+      mapper,
+      metadata
     };
   }
   /**
-   * Create integer schema
+   * Check if an operation should be included
    */
-  static integer(constraints) {
-    return {
-      type: "integer",
-      ...constraints
-    };
+  shouldIncludeOperation(operation, path, method, options, document, pathItem) {
+    if (!resolveExtensionEnabled(document, pathItem, operation)) {
+      return false;
+    }
+    if (operation.deprecated && !options.includeDeprecated) {
+      return false;
+    }
+    const lowerMethod = method.toLowerCase();
+    if (options.includeMethods && !options.includeMethods.includes(lowerMethod)) {
+      return false;
+    }
+    if (options.excludeMethods?.includes(lowerMethod)) {
+      return false;
+    }
+    if (options.includePaths && !matchesAnyGlob(path, options.includePaths)) {
+      return false;
+    }
+    if (options.excludePaths && matchesAnyGlob(path, options.excludePaths)) {
+      return false;
+    }
+    const tags = operation.tags ?? [];
+    if (options.includeTags && !tags.some((tag) => options.includeTags.includes(tag))) {
+      return false;
+    }
+    if (options.excludeTags && tags.some((tag) => options.excludeTags.includes(tag))) {
+      return false;
+    }
+    if (options.includeOperations && operation.operationId) {
+      if (!options.includeOperations.includes(operation.operationId)) {
+        return false;
+      }
+    }
+    if (options.excludeOperations && operation.operationId) {
+      if (options.excludeOperations.includes(operation.operationId)) {
+        return false;
+      }
+    }
+    if (options.readOnlyOnly) {
+      const effective = {
+        ...inferAnnotationsFromMethod(lowerMethod),
+        ...extractExtensionOverrides(operation).annotations
+      };
+      if (effective.readOnlyHint !== true) {
+        return false;
+      }
+    }
+    if (options.filterFn) {
+      return options.filterFn({
+        ...operation,
+        path,
+        method
+      });
+    }
+    return true;
   }
   /**
-   * Create boolean schema
+   * Generate a tool name
    */
-  static boolean() {
-    return {
-      type: "boolean"
-    };
+  generateToolName(path, method, operationId, options = {}) {
+    let rawName;
+    if (options.namingStrategy?.toolNameGenerator) {
+      rawName = options.namingStrategy.toolNameGenerator(path, method, operationId);
+    } else if (operationId) {
+      rawName = operationId;
+    } else {
+      const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+      rawName = `${method}_${sanitized}`;
+    }
+    return normalizeToolName(
+      rawName,
+      options.maxToolNameLength ?? DEFAULT_MAX_TOOL_NAME_LENGTH,
+      `${method} ${path}`
+    );
   }
   /**
-   * Create null schema
+   * Extract metadata from operation
    */
-  static null() {
-    return {
-      type: "null"
+  extractMetadata(path, method, operation, document, outputSchema) {
+    const metadata = {
+      path,
+      method,
+      operationId: operation.operationId,
+      operationSummary: operation.summary,
+      operationDescription: operation.description,
+      tags: operation.tags,
+      deprecated: operation.deprecated
     };
-  }
-  /**
-   * Flatten nested oneOf/anyOf/allOf schemas
-   */
-  static flatten(schema, maxDepth = 10) {
-    if (maxDepth <= 0) return schema;
-    const cloned = this.clone(schema);
-    if (cloned.oneOf) {
-      const flattened = cloned.oneOf.flatMap((s) => {
-        const sub = this.flatten(s, maxDepth - 1);
-        return sub.oneOf ? sub.oneOf : [sub];
-      });
-      cloned.oneOf = flattened;
+    if (operation.security || document.security) {
+      metadata.security = this.extractSecurityRequirements(
+        operation.security ?? document.security,
+        document
+      );
     }
-    if (cloned.anyOf) {
-      const flattened = cloned.anyOf.flatMap((s) => {
-        const sub = this.flatten(s, maxDepth - 1);
-        return sub.anyOf ? sub.anyOf : [sub];
-      });
-      cloned.anyOf = flattened;
+    const servers = operation.servers ?? document.servers;
+    if (servers) {
+      metadata.servers = servers.map((server) => ({
+        url: this.options.baseUrl || server.url,
+        description: server.description,
+        variables: server.variables
+      }));
+    } else if (this.options.baseUrl) {
+      metadata.servers = [{ url: this.options.baseUrl }];
     }
-    if (cloned.allOf) {
-      const flattened = cloned.allOf.flatMap((s) => {
-        const sub = this.flatten(s, maxDepth - 1);
-        return sub.allOf ? sub.allOf : [sub];
-      });
-      cloned.allOf = flattened;
+    const schemaObj = outputSchema;
+    if (schemaObj && Array.isArray(schemaObj["oneOf"])) {
+      const codes = schemaObj["oneOf"].map((schema) => schema["x-status-code"]).filter((code) => code !== void 0 && code !== null);
+      if (codes.length > 0) {
+        metadata.responseStatusCodes = codes;
+      }
+    } else if (schemaObj && schemaObj["x-status-code"] !== void 0 && schemaObj["x-status-code"] !== null) {
+      metadata.responseStatusCodes = [schemaObj["x-status-code"]];
     }
-    return cloned;
+    if (operation.externalDocs) {
+      metadata.externalDocs = operation.externalDocs;
+    }
+    const operationWithExt = operation;
+    if (operationWithExt["x-frontmcp"]) {
+      metadata.frontmcp = operationWithExt["x-frontmcp"];
+    }
+    return metadata;
   }
   /**
-   * Simplify schema by removing unnecessary fields
+   * Extract security requirements
    */
-  static simplify(schema) {
-    const cloned = this.clone(schema);
-    if (Array.isArray(cloned.required) && cloned.required.length === 0) {
-      delete cloned.required;
-    }
-    if (cloned.properties && Object.keys(cloned.properties).length === 0) {
-      delete cloned.properties;
-    }
-    if (Array.isArray(cloned.examples) && cloned.examples.length === 0) {
-      delete cloned.examples;
-    }
-    if (cloned.title && cloned.description && cloned.title === cloned.description) {
-      delete cloned.title;
+  extractSecurityRequirements(security, document) {
+    if (!security || !document.components?.securitySchemes) {
+      return [];
     }
-    return cloned;
+    return security.flatMap(
+      (req) => Object.entries(req).map(([scheme, scopes]) => {
+        const securityScheme = document.components.securitySchemes[scheme];
+        if (isReferenceObject(securityScheme)) {
+          return { scheme, type: "http", scopes };
+        }
+        const apiKeyIn = "in" in securityScheme ? securityScheme.in : void 0;
+        const result = {
+          scheme,
+          type: securityScheme.type,
+          scopes,
+          name: "name" in securityScheme ? securityScheme.name : void 0,
+          in: apiKeyIn && (apiKeyIn === "query" || apiKeyIn === "header" || apiKeyIn === "cookie") ? apiKeyIn : void 0
+        };
+        if (securityScheme.type === "http") {
+          result.httpScheme = "scheme" in securityScheme ? securityScheme.scheme : void 0;
+          result.bearerFormat = "bearerFormat" in securityScheme ? securityScheme.bearerFormat : void 0;
+        }
+        result.description = "description" in securityScheme ? securityScheme.description : void 0;
+        return result;
+      })
+    );
   }
 };
 
@@ -2074,6 +2865,351 @@ function createSecurityContext(auth) {
     customResolver: auth.customResolver
   };
 }
+
+// src/request-builder.ts
+var RESERVED_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%23": "#",
+  "%5B": "[",
+  "%5D": "]",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "="
+};
+function encodeValue(value, allowReserved) {
+  const encoded = encodeURIComponent(value);
+  if (!allowReserved) return encoded;
+  return encoded.replace(/%3A|%2F|%3F|%23|%5B|%5D|%40|%24|%26|%2B|%2C|%3B|%3D/gi, (m) => RESERVED_DECODE[m.toUpperCase()]);
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function primitiveString(value, paramName, location) {
+  if (value === null || value === void 0 || typeof value === "object") {
+    throw new RequestBuildError(
+      `${location} parameter '${paramName}' must serialize to a primitive; received ${value === null ? "null" : Array.isArray(value) ? "an array" : typeof value}`,
+      { param: paramName, location }
+    );
+  }
+  return String(value);
+}
+function serializePathValue(mapper, value) {
+  const style = mapper.style ?? "simple";
+  const explode = mapper.explode ?? false;
+  const name = mapper.key;
+  const enc = (v) => encodeValue(primitiveString(v, name, "path"));
+  if (Array.isArray(value)) {
+    if (style === "label") {
+      return `.${value.map(enc).join(explode ? "." : ",")}`;
+    }
+    if (style === "matrix") {
+      return explode ? value.map((v) => `;${name}=${enc(v)}`).join("") : `;${name}=${value.map(enc).join(",")}`;
+    }
+    return value.map(enc).join(",");
+  }
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    if (style === "label") {
+      return explode ? entries.map(([k, v]) => `.${encodeValue(k)}=${enc(v)}`).join("") : `.${entries.map(([k, v]) => `${encodeValue(k)},${enc(v)}`).join(",")}`;
+    }
+    if (style === "matrix") {
+      return explode ? entries.map(([k, v]) => `;${encodeValue(k)}=${enc(v)}`).join("") : `;${name}=${entries.map(([k, v]) => `${encodeValue(k)},${enc(v)}`).join(",")}`;
+    }
+    return explode ? entries.map(([k, v]) => `${encodeValue(k)}=${enc(v)}`).join(",") : entries.map(([k, v]) => `${encodeValue(k)},${enc(v)}`).join(",");
+  }
+  const core = enc(value);
+  if (style === "label") return `.${core}`;
+  if (style === "matrix") return `;${name}=${core}`;
+  return core;
+}
+function serializeQueryPairs(mapper, value) {
+  const style = mapper.style ?? "form";
+  const explode = mapper.explode ?? style === "form";
+  const name = mapper.key;
+  const str = (v) => primitiveString(v, name, "query");
+  if (Array.isArray(value)) {
+    if ((style === "deepObject" ? mapper.explode ?? true : explode) || value.length === 0) {
+      return value.map((v) => [name, str(v)]);
+    }
+    const delimiter = style === "spaceDelimited" ? " " : style === "pipeDelimited" ? "|" : ",";
+    return [[name, value.map(str).join(delimiter)]];
+  }
+  if (isPlainObject(value)) {
+    if (style === "deepObject") {
+      const pairs = [];
+      const walk = (prefix, node) => {
+        for (const [k, v] of Object.entries(node)) {
+          if (v === void 0) continue;
+          if (isPlainObject(v)) {
+            walk(`${prefix}[${k}]`, v);
+          } else if (Array.isArray(v)) {
+            for (const item of v) pairs.push([`${prefix}[${k}]`, str(item)]);
+          } else {
+            pairs.push([`${prefix}[${k}]`, str(v)]);
+          }
+        }
+      };
+      walk(name, value);
+      return pairs;
+    }
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0);
+    if (explode) {
+      return entries.map(([k, v]) => [k, str(v)]);
+    }
+    return [[name, entries.map(([k, v]) => `${k},${str(v)}`).join(",")]];
+  }
+  return [[name, str(value)]];
+}
+function serializeHeaderValue(mapper, value) {
+  const explode = mapper.explode ?? false;
+  const name = mapper.key;
+  const str = (v) => primitiveString(v, name, "header");
+  if (Array.isArray(value)) {
+    return value.map(str).join(",");
+  }
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    return explode ? entries.map(([k, v]) => `${k}=${str(v)}`).join(",") : entries.map(([k, v]) => `${k},${str(v)}`).join(",");
+  }
+  return str(value);
+}
+function assertHeaderSafe(name, value) {
+  if (!/^[\w!#$%&'*+\-.^`|~]+$/.test(name)) {
+    throw new RequestBuildError(`Invalid header name '${name}' (RFC 7230 token required)`, { header: name });
+  }
+  if (/[\r\n\x00]/.test(value)) {
+    throw new RequestBuildError(`Header '${name}' value contains control characters (possible header injection)`, {
+      header: name
+    });
+  }
+}
+function assertCookieName(name) {
+  if (!/^[\w!#$%&'*+\-.^`|~]+$/.test(name)) {
+    throw new RequestBuildError(`Invalid cookie name '${name}' (RFC 6265 token required)`, { cookie: name });
+  }
+}
+function assertCookieValue(name, value) {
+  if (/[\x00-\x1f\x7f\s";\\]/.test(value)) {
+    throw new RequestBuildError(
+      `Cookie '${name}' value contains characters that break the Cookie header (RFC 6265 cookie-octet violation)`,
+      { cookie: name }
+    );
+  }
+}
+function formatSecurityValue(mapper, value) {
+  const security = mapper.security;
+  if (security.type === "http") {
+    const scheme = (security.httpScheme ?? "bearer").toLowerCase();
+    if (scheme !== "bearer" && scheme !== "basic") {
+      return value;
+    }
+    const prefix = scheme.charAt(0).toUpperCase() + scheme.slice(1);
+    return value.toLowerCase().startsWith(`${scheme} `) ? value : `${prefix} ${value}`;
+  }
+  if (security.type === "oauth2" || security.type === "openIdConnect") {
+    return value.toLowerCase().startsWith("bearer ") ? value : `Bearer ${value}`;
+  }
+  return value;
+}
+function resolveServerUrl(tool) {
+  const server = tool.metadata.servers?.[0];
+  if (!server) return "";
+  let url = server.url;
+  if (server.variables) {
+    for (const [name, variable] of Object.entries(server.variables)) {
+      if (variable && typeof variable.default === "string") {
+        url = url.replaceAll(`{${name}}`, variable.default);
+      }
+    }
+  }
+  return url;
+}
+var JSON_CONTENT = /^application\/(.+\+)?json$/i;
+function buildHttpRequest(tool, input, options = {}) {
+  const rawBase = options.baseUrl ?? resolveServerUrl(tool);
+  if (rawBase.includes("{")) {
+    throw new RequestBuildError(
+      `Base URL '${rawBase}' contains unresolved server template variables (no default value in the spec); pass an explicit baseUrl`,
+      { baseUrl: rawBase }
+    );
+  }
+  if (rawBase !== "" && !/^https?:\/\//i.test(rawBase)) {
+    throw new RequestBuildError(`Base URL must be http(s) or empty; received '${rawBase}'`, { baseUrl: rawBase });
+  }
+  let base = rawBase;
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  let path = tool.metadata.path;
+  const queryPairs = [];
+  const query = {};
+  const headers = {};
+  const cookies = {};
+  let rawBody;
+  let bodyObject;
+  let contentType;
+  let hasBody = false;
+  let binaryBody = false;
+  for (const mapper of tool.mapper) {
+    const value = input[mapper.inputKey];
+    if (mapper.security) {
+      if (value === void 0 || value === null) continue;
+      const formatted = formatSecurityValue(mapper, String(value));
+      if (mapper.type === "header") {
+        assertHeaderSafe(mapper.key, formatted);
+        headers[mapper.key] = formatted;
+      } else if (mapper.type === "query") {
+        queryPairs.push([mapper.key, formatted]);
+      } else {
+        assertCookieName(mapper.key);
+        cookies[mapper.key] = formatted;
+      }
+      continue;
+    }
+    if (value === void 0 || value === null && mapper.type !== "body") {
+      if (mapper.required) {
+        throw new RequestBuildError(
+          `Required ${mapper.type} parameter '${mapper.key}' (input key '${mapper.inputKey}') is missing`,
+          { param: mapper.key, inputKey: mapper.inputKey, location: mapper.type }
+        );
+      }
+      continue;
+    }
+    switch (mapper.type) {
+      case "path":
+        path = path.replaceAll(`{${mapper.key}}`, serializePathValue(mapper, value));
+        break;
+      case "query":
+        for (const [k, v] of serializeQueryPairs(mapper, value)) {
+          queryPairs.push([k, v, mapper.allowReserved]);
+        }
+        break;
+      case "header": {
+        const headerValue = serializeHeaderValue(mapper, value);
+        assertHeaderSafe(mapper.key, headerValue);
+        headers[mapper.key] = headerValue;
+        break;
+      }
+      case "cookie": {
+        assertCookieName(mapper.key);
+        cookies[mapper.key] = Array.isArray(value) ? value.map((v) => primitiveString(v, mapper.key, "cookie")).join(",") : primitiveString(value, mapper.key, "cookie");
+        break;
+      }
+      case "body":
+        hasBody = true;
+        contentType = contentType ?? mapper.serialization?.contentType ?? "application/json";
+        if (mapper.serialization?.binary) binaryBody = true;
+        if (mapper.wholeBody) {
+          rawBody = value;
+        } else {
+          if (bodyObject === void 0) bodyObject = {};
+          bodyObject[mapper.key] = value;
+        }
+        break;
+    }
+  }
+  if (path.includes("{")) {
+    throw new RequestBuildError(`Unresolved path parameters remain in '${path}'`, { path });
+  }
+  if (bodyObject !== void 0) rawBody = bodyObject;
+  const queryString = queryPairs.map(([k, v, allowReserved]) => {
+    query[k] = query[k] ?? [];
+    query[k].push(v);
+    const encodedKey = encodeURIComponent(k).replace(/%5B/gi, "[").replace(/%5D/gi, "]");
+    return `${encodedKey}=${encodeValue(v, allowReserved)}`;
+  }).join("&");
+  const cookieEntries = Object.entries(cookies);
+  if (cookieEntries.length > 0) {
+    for (const [k, v] of cookieEntries) assertCookieValue(k, v);
+    headers["Cookie"] = cookieEntries.map(([k, v]) => `${k}=${v}`).join("; ");
+  }
+  const contentTypeKey = Object.keys(headers).find((h) => h.toLowerCase() === "content-type") ?? "content-type";
+  const hasExplicitContentType = contentTypeKey in headers;
+  let body;
+  if (hasBody && rawBody !== void 0) {
+    const ct = contentType;
+    if (binaryBody) {
+      body = rawBody;
+      if (!hasExplicitContentType) headers[contentTypeKey] = ct;
+    } else if (ct.toLowerCase() === "application/x-www-form-urlencoded") {
+      const params = new URLSearchParams();
+      if (!isPlainObject(rawBody)) {
+        throw new RequestBuildError(`form-urlencoded bodies must be objects; received ${typeof rawBody}`, {
+          contentType: ct
+        });
+      }
+      for (const [k, v] of Object.entries(rawBody)) {
+        if (v === void 0) continue;
+        if (Array.isArray(v)) {
+          for (const item of v) params.append(k, primitiveString(item, k, "body"));
+        } else {
+          params.append(k, isPlainObject(v) ? JSON.stringify(v) : String(v));
+        }
+      }
+      body = params.toString();
+      headers[contentTypeKey] = ct;
+    } else if (ct.toLowerCase() === "multipart/form-data") {
+      if (typeof FormData === "undefined") {
+        throw new RequestBuildError("multipart/form-data requires a FormData implementation in this runtime", {});
+      }
+      const form = new FormData();
+      if (!isPlainObject(rawBody)) {
+        throw new RequestBuildError(`multipart bodies must be objects; received ${typeof rawBody}`, {
+          contentType: ct
+        });
+      }
+      for (const [k, v] of Object.entries(rawBody)) {
+        if (v === void 0) continue;
+        if (typeof Blob !== "undefined" && v instanceof Blob) {
+          form.append(k, v);
+        } else if (v instanceof Uint8Array) {
+          form.append(k, new Blob([v]));
+        } else if (isPlainObject(v) || Array.isArray(v)) {
+          form.append(k, JSON.stringify(v));
+        } else {
+          form.append(k, String(v));
+        }
+      }
+      body = form;
+      if (hasExplicitContentType) delete headers[contentTypeKey];
+    } else if (JSON_CONTENT.test(ct)) {
+      body = JSON.stringify(rawBody);
+      headers[contentTypeKey] = ct;
+    } else {
+      body = isPlainObject(rawBody) || Array.isArray(rawBody) ? JSON.stringify(rawBody) : String(rawBody);
+      headers[contentTypeKey] = ct;
+    }
+  }
+  return {
+    url: `${base}${path}${queryString ? `?${queryString}` : ""}`,
+    method: tool.metadata.method.toUpperCase(),
+    headers,
+    query,
+    cookies,
+    contentType,
+    body,
+    rawBody
+  };
+}
+
+// src/sdk.ts
+function toSdkTool(tool, wrapper) {
+  const wrapSchema = wrapper?.fromJsonSchema ?? ((schema) => schema);
+  return [
+    tool.name,
+    {
+      ...tool.title !== void 0 && { title: tool.title },
+      description: tool.description,
+      inputSchema: wrapSchema(tool.inputSchema),
+      ...tool.outputSchema !== void 0 && { outputSchema: wrapSchema(tool.outputSchema) },
+      ...tool.annotations !== void 0 && { annotations: tool.annotations }
+    }
+  ];
+}
 export {
   BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
@@ -2083,6 +3219,7 @@ export {
   OpenAPIToolGenerator,
   ParameterResolver,
   ParseError,
+  RequestBuildError,
   ResponseBuilder,
   SchemaBuilder,
   SchemaError,
@@ -2090,15 +3227,28 @@ export {
   SsrfError,
   ValidationError,
   Validator,
+  applyClientTarget,
   assertUrlSafe,
+  buildHttpRequest,
+  collapseNestedUnions,
+  collapseRootCompositions,
   createSecurityContext,
   decodeIpv4MappedIpv6,
   defaultLookup,
+  demoteFormats,
+  enforceClosedObjects,
+  ensureArrayItems,
+  extractExtensionOverrides,
+  inferAnnotationsFromMethod,
+  inlineLocalRefs,
   isBlockedAddress,
   isBlockedHostname,
   isReferenceObject,
   normalizeSsrfOptions,
+  requireAllProperties,
+  resolveExtensionEnabled,
   resolveSchemaFormats,
   safeFetch,
-  toJsonSchema
+  toJsonSchema,
+  toSdkTool
 };