mcp-from-openapi 2.5.1 → 2.6.1

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,239 +585,1620 @@ 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
+    };
+  }
+  /**
+   * Add format to schema
+   */
+  static withFormat(schema, format) {
+    return {
+      ...schema,
+      format
+    };
+  }
+  /**
+   * Add pattern to schema
+   */
+  static withPattern(schema, pattern) {
+    return {
+      ...schema,
+      pattern
+    };
+  }
+  /**
+   * Add enum to schema
+   */
+  static withEnum(schema, values) {
+    return {
+      ...schema,
+      enum: values
+    };
+  }
+  /**
+   * 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 LoadError = 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 SsrfError = class extends LoadError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Create object schema
+   */
+  static object(properties, required) {
+    return {
+      type: "object",
+      properties,
+      ...required && required.length > 0 && { required },
+      additionalProperties: false
+    };
   }
-};
-var ParseError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Create array schema
+   */
+  static array(items, constraints) {
+    return {
+      type: "array",
+      items,
+      ...constraints
+    };
   }
-};
-var ValidationError = class extends OpenAPIToolError {
-  errors;
-  constructor(message, context) {
-    super(message, context);
-    this.errors = context?.["errors"];
+  /**
+   * Create string schema
+   */
+  static string(constraints) {
+    return {
+      type: "string",
+      ...constraints
+    };
   }
-};
-var GenerationError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+  /**
+   * Create number schema
+   */
+  static number(constraints) {
+    return {
+      type: "number",
+      ...constraints
+    };
+  }
+  /**
+   * Create integer schema
+   */
+  static integer(constraints) {
+    return {
+      type: "integer",
+      ...constraints
+    };
+  }
+  /**
+   * Create boolean schema
+   */
+  static boolean() {
+    return {
+      type: "boolean"
+    };
+  }
+  /**
+   * Create null schema
+   */
+  static null() {
+    return {
+      type: "null"
+    };
+  }
+  /**
+   * 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;
+  }
+  // Copy-on-walk over every structural keyword (same key groups as
+  // truncateDepth): `visit` transforms each node top-down and must return a
+  // new node when it changes anything.
+  static walkCopy(node, visit, seen = /* @__PURE__ */ new Map()) {
+    if (!node || typeof node !== "object") return node;
+    const existing = seen.get(node);
+    if (existing) return existing;
+    const copy = visit({ ...node });
+    seen.set(node, copy);
+    for (const key of this.TRUNCATE_MAP_KEYS) {
+      const value = copy[key];
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const mapped = {};
+        for (const [name, sub] of Object.entries(value)) {
+          mapped[name] = this.walkCopy(sub, visit, seen);
+        }
+        copy[key] = mapped;
+      }
+    }
+    for (const key of this.TRUNCATE_SCHEMA_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((item) => this.walkCopy(item, visit, seen));
+      } else if (value !== null && typeof value === "object") {
+        copy[key] = this.walkCopy(value, visit, seen);
+      }
+    }
+    for (const key of this.TRUNCATE_LIST_KEYS) {
+      const value = copy[key];
+      if (Array.isArray(value)) {
+        copy[key] = value.map((member) => this.walkCopy(member, visit, seen));
+      }
+    }
+    return copy;
+  }
+  /**
+   * Limit every object node to its first `max` properties (declaration
+   * order). Dropped properties are pruned from `required` and counted in a
+   * note appended to the node's description.
+   */
+  static limitProperties(schema, max) {
+    const bound = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      const properties = node.properties;
+      if (!properties || typeof properties !== "object") return node;
+      const entries = Object.entries(properties);
+      if (entries.length <= bound) return node;
+      const kept = entries.slice(0, bound);
+      const keptNames = new Set(kept.map(([name]) => name));
+      const dropped = entries.length - bound;
+      const note = `[${dropped} additional propert${dropped === 1 ? "y" : "ies"} omitted: exceeds maxProperties]`;
+      const next = { ...node, properties: Object.fromEntries(kept) };
+      if (Array.isArray(node.required)) {
+        const required = node.required.filter((name) => keptNames.has(String(name)));
+        if (required.length > 0) {
+          next.required = required;
+        } else {
+          delete next.required;
+        }
+      }
+      next.description = node.description ? `${node.description} ${note}` : note;
+      return next;
+    });
+  }
+  /**
+   * Cap every description in the schema tree to `maxLength` characters,
+   * truncating with an ellipsis.
+   */
+  static capDescriptions(schema, maxLength) {
+    const bound = Number.isFinite(maxLength) ? Math.max(1, Math.floor(maxLength)) : Number.MAX_SAFE_INTEGER;
+    return this.walkCopy(schema, (node) => {
+      if (typeof node.description === "string" && node.description.length > bound) {
+        return { ...node, description: `${node.description.slice(0, bound - 1)}\u2026` };
+      }
+      return node;
+    });
+  }
+  /**
+   * Remove every `examples` array from the schema tree (a token-budget
+   * trimming step — validation keywords are untouched).
+   */
+  static stripExamples(schema) {
+    return this.walkCopy(schema, (node) => {
+      if ("examples" in node) {
+        const { examples: _examples, ...rest } = node;
+        return rest;
+      }
+      return node;
+    });
+  }
+  /**
+   * 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;
   }
 };
-var SchemaError = class extends OpenAPIToolError {
-  constructor(message, context) {
-    super(message, context);
+
+// 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 };
+  }
+}
+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 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 readXMcp(node) {
+  return node["x-mcp"];
+}
+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;
+  }
+  return void 0;
+}
+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;
+}
+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 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 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
+    });
+  }
+  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;
+    }
+  }
+  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);
+    }
+  }
+  for (const key of LIST_KEYS) {
+    const value = visited[key];
+    if (Array.isArray(value)) {
+      visited[key] = value.map((member) => walkSchema(member, visit));
+    }
+  }
+  return visited;
+}
+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
+      );
+    }
+    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());
+}
+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 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;
+}
+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;
+  }
+  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
+      };
+    }
+  }
+  return node;
+}
+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;
+    }
+  });
+}
+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 };
+    }
+    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);
+      }
+    }
+    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;
+  }
+  result = collapseRootCompositions(result);
+  if (target === "openai") {
+    result = enforceClosedObjects(result);
+    result = requireAllProperties(result);
+  }
+  return result;
+}
+
+// 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);
+    }
+  }
+};
+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 OverlayError = 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/overlay.ts
+function parsePath(path) {
+  if (typeof path !== "string" || !path.startsWith("$")) {
+    throw new OverlayError(`Overlay target must be a JSONPath starting with '$'; received '${String(path)}'`, {
+      target: path
+    });
+  }
+  const segments = [];
+  let rest = path.slice(1);
+  while (rest.length > 0) {
+    let recursive = false;
+    if (rest.startsWith("..")) {
+      recursive = true;
+      rest = rest.slice(2);
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+    } else if (rest.startsWith(".")) {
+      rest = rest.slice(1);
+      if (rest.startsWith("*")) {
+        segments.push({ kind: "wildcard", recursive });
+        rest = rest.slice(1);
+        continue;
+      }
+      const bare = rest.match(/^([A-Za-z_][\w-]*)/);
+      if (bare) {
+        segments.push({ kind: "child", name: bare[1], recursive });
+        rest = rest.slice(bare[0].length);
+        continue;
+      }
+      throw new OverlayError(`Invalid JSONPath segment after '.' in '${path}'`, { target: path });
+    }
+    if (!rest.startsWith("[")) {
+      throw new OverlayError(`Invalid JSONPath segment at '${rest}' in '${path}'`, { target: path });
+    }
+    const bracket = matchBracket(rest, path);
+    const inner = bracket.inner.trim();
+    rest = bracket.rest;
+    if (inner === "*") {
+      segments.push({ kind: "wildcard", recursive });
+    } else if (/^-?\d+$/.test(inner)) {
+      segments.push({ kind: "index", index: parseInt(inner, 10), recursive });
+    } else if (/^'.*'$/.test(inner) || /^".*"$/.test(inner)) {
+      segments.push({ kind: "child", name: inner.slice(1, -1), recursive });
+    } else if (inner.startsWith("?(") && inner.endsWith(")")) {
+      segments.push(parseFilter(inner.slice(2, -1).trim(), path, recursive));
+    } else {
+      throw new OverlayError(`Unsupported JSONPath selector '[${inner}]' in '${path}'`, { target: path });
+    }
+  }
+  return segments;
+}
+function matchBracket(input, fullPath) {
+  let quote = null;
+  let depth = 0;
+  for (let i = 1; i < input.length; i++) {
+    const char = input[i];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "[") {
+      depth++;
+    } else if (char === "]") {
+      if (depth === 0) {
+        return { inner: input.slice(1, i), rest: input.slice(i + 1) };
+      }
+      depth--;
+    }
+  }
+  throw new OverlayError(`Unterminated '[' selector in '${fullPath}'`, { target: fullPath });
+}
+function parseFilter(expr, path, recursive) {
+  const match = expr.match(/^@(?:\.([A-Za-z_][\w-]*)|\['([^']*)'\]|\["([^"]*)"\])\s*(?:(==|!=)\s*(.+))?$/);
+  if (!match) {
+    throw new OverlayError(`Unsupported filter expression '?(${expr})' in '${path}'`, { target: path });
+  }
+  const field = match[1] ?? match[2] ?? match[3];
+  const op = match[4];
+  if (!op) {
+    return { kind: "filter", field, op: "exists", recursive };
+  }
+  const raw = match[5].trim();
+  let literal;
+  if (/^'.*'$/.test(raw) || /^".*"$/.test(raw)) {
+    literal = raw.slice(1, -1);
+  } else if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    literal = parseFloat(raw);
+  } else if (raw === "true" || raw === "false") {
+    literal = raw === "true";
+  } else {
+    throw new OverlayError(`Unsupported filter literal '${raw}' in '${path}'`, { target: path });
+  }
+  return { kind: "filter", field, op, literal, recursive };
+}
+function isContainer(value) {
+  return value !== null && typeof value === "object";
+}
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function descendants(match) {
+  const result = [];
+  const walk = (node) => {
+    if (!isContainer(node)) return;
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => {
+        result.push({ parent: node, key: index, value: item });
+        walk(item);
+      });
+    } else {
+      for (const [key, value] of Object.entries(node)) {
+        result.push({ parent: node, key, value });
+        walk(value);
+      }
+    }
+  };
+  walk(match.value);
+  return result;
+}
+function dedupeMatches(matches) {
+  const seen = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const match of matches) {
+    let keys = seen.get(match.parent);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      seen.set(match.parent, keys);
+    }
+    if (keys.has(match.key)) continue;
+    keys.add(match.key);
+    result.push(match);
+  }
+  return result;
+}
+function applySegment(matches, segment) {
+  const scope = segment.recursive ? matches.flatMap((m) => [m, ...descendants(m)]) : matches;
+  const next = [];
+  for (const match of scope) {
+    const node = match.value;
+    switch (segment.kind) {
+      case "child": {
+        if (isContainer(node) && !Array.isArray(node) && !UNSAFE_KEYS.has(segment.name) && Object.prototype.hasOwnProperty.call(node, segment.name)) {
+          next.push({ parent: node, key: segment.name, value: node[segment.name] });
+        }
+        break;
+      }
+      case "wildcard": {
+        if (Array.isArray(node)) {
+          node.forEach((item, index) => next.push({ parent: node, key: index, value: item }));
+        } else if (isContainer(node)) {
+          for (const [key, value] of Object.entries(node)) {
+            next.push({ parent: node, key, value });
+          }
+        }
+        break;
+      }
+      case "index": {
+        if (Array.isArray(node)) {
+          const index = segment.index < 0 ? node.length + segment.index : segment.index;
+          if (index >= 0 && index < node.length) {
+            next.push({ parent: node, key: index, value: node[index] });
+          }
+        }
+        break;
+      }
+      case "filter": {
+        const members = Array.isArray(node) ? node.map((item, index) => ({ parent: node, key: index, value: item })) : isContainer(node) ? Object.entries(node).map(([key, value]) => ({ parent: node, key, value })) : [];
+        for (const member of members) {
+          if (!isContainer(member.value) || Array.isArray(member.value)) continue;
+          const fieldValue = member.value[segment.field];
+          const keep = segment.op === "exists" ? fieldValue !== void 0 : segment.op === "==" ? fieldValue === segment.literal : fieldValue !== segment.literal;
+          if (keep) next.push(member);
+        }
+        break;
+      }
+    }
+  }
+  return next;
+}
+function deepMerge(target, update) {
+  for (const [key, value] of Object.entries(update)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    const existing = target[key];
+    if (isContainer(value) && !Array.isArray(value) && isContainer(existing) && !Array.isArray(existing)) {
+      deepMerge(existing, value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+function applyOverlay(document, overlay) {
+  if (!overlay || typeof overlay !== "object" || !Array.isArray(overlay.actions)) {
+    throw new OverlayError("Overlay document must have an actions array", {});
+  }
+  const result = JSON.parse(JSON.stringify(document));
+  for (const [index, action] of overlay.actions.entries()) {
+    if (!action || typeof action !== "object" || typeof action.target !== "string") {
+      throw new OverlayError(`Overlay action #${index} must have a string target`, { index });
+    }
+    if (action.update === void 0 && action.remove !== true) {
+      throw new OverlayError(`Overlay action #${index} needs 'update' or 'remove: true'`, {
+        index,
+        target: action.target
+      });
+    }
+    const segments = parsePath(action.target);
+    let matches = [{ parent: null, key: null, value: result }];
+    for (const segment of segments) {
+      matches = dedupeMatches(applySegment(matches, segment));
+    }
+    if (action.remove === true) {
+      const arrayRemovals = /* @__PURE__ */ new Map();
+      for (const match of matches) {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot remove the document root", { target: action.target });
+        }
+        if (Array.isArray(match.parent)) {
+          const indices = arrayRemovals.get(match.parent) ?? [];
+          indices.push(match.key);
+          arrayRemovals.set(match.parent, indices);
+        } else {
+          delete match.parent[match.key];
+        }
+      }
+      for (const [parent, indices] of arrayRemovals) {
+        for (const index2 of indices.sort((a, b) => b - a)) {
+          parent.splice(index2, 1);
+        }
+      }
+      continue;
+    }
+    for (const match of matches) {
+      const node = match.value;
+      if (Array.isArray(node)) {
+        node.push(action.update);
+      } else if (isContainer(node) && isContainer(action.update) && !Array.isArray(action.update)) {
+        deepMerge(node, action.update);
+      } else {
+        if (match.parent === null) {
+          throw new OverlayError("Overlay cannot replace the document root with a non-object", {
+            target: action.target
+          });
+        }
+        match.parent[match.key] = action.update;
+      }
+    }
+  }
+  return result;
+}
+
+// src/lint.ts
+var METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+var PAGINATION_PARAM = /^(page|limit|offset|cursor|per_page|pagesize|page_size|after|before)$/i;
+var DEEP_SCHEMA_THRESHOLD = 8;
+var WIDE_SCHEMA_THRESHOLD = 30;
+function measureSchema(node, seen = /* @__PURE__ */ new Map()) {
+  if (node === null || typeof node !== "object") {
+    return { depth: 0, widestObject: 0, hasArray: false };
+  }
+  if (seen.has(node)) {
+    return seen.get(node) ?? { depth: 0, widestObject: 0, hasArray: false };
+  }
+  seen.set(node, null);
+  const record = node;
+  let childDepth = 0;
+  let widestObject = 0;
+  let hasArray = record["type"] === "array" || Array.isArray(record["type"]) && record["type"].includes("array");
+  const visit = (child) => {
+    const shape2 = measureSchema(child, seen);
+    childDepth = Math.max(childDepth, shape2.depth);
+    widestObject = Math.max(widestObject, shape2.widestObject);
+    hasArray = hasArray || shape2.hasArray;
+  };
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    widestObject = Math.max(widestObject, Object.keys(properties).length);
+    for (const child of Object.values(properties)) visit(child);
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) visit(value);
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value)) value.forEach(visit);
+  }
+  const shape = { depth: childDepth + 1, widestObject, hasArray };
+  seen.set(node, shape);
+  return shape;
+}
+function schemaHasExample(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") {
+    if (Object.values(properties).some((child) => schemaHasExample(child, seen))) return true;
+  }
+  for (const key of ["items", "additionalProperties", "not", "contentSchema"]) {
+    const value = record[key];
+    if (value && typeof value === "object" && !Array.isArray(value) && schemaHasExample(value, seen)) return true;
+    if (Array.isArray(value) && value.some((item) => schemaHasExample(item, seen))) return true;
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    const value = record[key];
+    if (Array.isArray(value) && value.some((member) => schemaHasExample(member, seen))) return true;
+  }
+  return false;
+}
+function hasAnyExample(content) {
+  if (!content) return false;
+  return Object.values(content).some((media) => {
+    if (!media || typeof media !== "object") return false;
+    const record = media;
+    if (record["example"] !== void 0 || record["examples"] !== void 0) return true;
+    return schemaHasExample(record["schema"]);
+  });
+}
+function lintDocument(document) {
+  const findings = [];
+  const operationIds = /* @__PURE__ */ new Map();
+  const paths = document.paths ?? {};
+  for (const [pathStr, pathItem] of Object.entries(paths).sort(([a], [b]) => a < b ? -1 : 1)) {
+    if (!pathItem || "$ref" in pathItem) continue;
+    const pathLevelParameters = (pathItem["parameters"] ?? []).filter(
+      (param) => !isReferenceObject(param)
+    );
+    for (const method of METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const label = `${method.toUpperCase()} ${pathStr}`;
+      if (!operation.operationId) {
+        findings.push({
+          severity: "warning",
+          code: "missing-operation-id",
+          message: "Operation has no operationId; the tool name will be generated from the method and path.",
+          path: label,
+          hint: "Add a short, action-oriented operationId (it becomes the tool name)."
+        });
+      } else {
+        const existing = operationIds.get(operation.operationId) ?? [];
+        existing.push(label);
+        operationIds.set(operation.operationId, existing);
+        if (operation.operationId.length > 64) {
+          findings.push({
+            severity: "info",
+            code: "long-operation-id",
+            message: `operationId '${operation.operationId.slice(0, 40)}\u2026' exceeds 64 characters and will be truncated with a hash suffix.`,
+            path: label,
+            hint: "Shorten the operationId below 64 characters to keep tool names readable."
+          });
+        }
+      }
+      const prose = `${operation.summary ?? ""} ${operation.description ?? ""}`.trim();
+      if (prose.length === 0) {
+        findings.push({
+          severity: "warning",
+          code: "missing-description",
+          message: "Operation has neither summary nor description; the model only sees the method and path.",
+          path: label,
+          hint: "Describe WHEN to use this operation and what it returns (or patch it in with an overlay)."
+        });
+      } else if (prose.length < 20) {
+        findings.push({
+          severity: "info",
+          code: "vague-description",
+          message: `Operation description is only ${prose.length} characters \u2014 likely too vague for reliable tool selection.`,
+          path: label,
+          hint: "Expand the description with the use case and key parameters."
+        });
+      }
+      const parameters = [
+        ...pathLevelParameters,
+        ...(operation.parameters ?? []).filter((param) => !isReferenceObject(param))
+      ];
+      const undescribed = parameters.filter((param) => !param.description).map((param) => param.name);
+      if (undescribed.length > 0) {
+        findings.push({
+          severity: "info",
+          code: "missing-parameter-description",
+          message: `Parameter(s) without description: ${undescribed.join(", ")}.`,
+          path: label,
+          hint: "Describe each parameter \u2014 models mis-fill undocumented arguments."
+        });
+      }
+      const responses = operation.responses ?? {};
+      const successCodes = Object.keys(responses).filter((code) => /^2(\d\d|XX)$/i.test(code));
+      if (successCodes.length === 0 && !responses["default"]) {
+        findings.push({
+          severity: "warning",
+          code: "missing-success-response",
+          message: "Operation declares no 2xx or default response; no output schema can be generated.",
+          path: label,
+          hint: "Add the success response with its schema."
+        });
+      }
+      let responseShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const code of [...successCodes, "default"]) {
+        const response = responses[code];
+        if (!response || typeof response !== "object" || isReferenceObject(response)) continue;
+        const content = response["content"];
+        if (!content) continue;
+        for (const media of Object.values(content)) {
+          const schema = media && typeof media === "object" ? media["schema"] : void 0;
+          const shape = measureSchema(schema);
+          responseShape = {
+            depth: Math.max(responseShape.depth, shape.depth),
+            widestObject: Math.max(responseShape.widestObject, shape.widestObject),
+            hasArray: responseShape.hasArray || shape.hasArray
+          };
+        }
+      }
+      if (method === "get" && responseShape.hasArray) {
+        const hasPagination = parameters.some((param) => param.in === "query" && PAGINATION_PARAM.test(param.name));
+        if (!hasPagination) {
+          findings.push({
+            severity: "warning",
+            code: "unpaginated-list",
+            message: "GET returns an array but declares no pagination parameter \u2014 responses can blow past client result limits (Claude Code caps tool results at 25K tokens).",
+            path: label,
+            hint: "Add limit/cursor/page parameters, or shape responses at the server."
+          });
+        }
+      }
+      const body = operation.requestBody;
+      const bodyContent = body && !isReferenceObject(body) ? body.content : void 0;
+      let requestShape = { depth: 0, widestObject: 0, hasArray: false };
+      for (const media of Object.values(bodyContent ?? {})) {
+        const schema = media && typeof media === "object" ? media["schema"] : void 0;
+        const shape = measureSchema(schema);
+        requestShape = {
+          depth: Math.max(requestShape.depth, shape.depth),
+          widestObject: Math.max(requestShape.widestObject, shape.widestObject),
+          hasArray: requestShape.hasArray || shape.hasArray
+        };
+      }
+      const maxDepth = Math.max(requestShape.depth, responseShape.depth);
+      if (maxDepth > DEEP_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "warning",
+          code: "deep-schema",
+          message: `Schema nesting reaches depth ${maxDepth} (threshold ${DEEP_SCHEMA_THRESHOLD}) \u2014 deep schemas cost tokens and reduce accuracy.`,
+          path: label,
+          hint: "Flatten the schema, or bound generation with maxSchemaDepth."
+        });
+      }
+      const maxWidth = Math.max(requestShape.widestObject, responseShape.widestObject);
+      if (maxWidth > WIDE_SCHEMA_THRESHOLD) {
+        findings.push({
+          severity: "info",
+          code: "wide-schema",
+          message: `An object schema declares ${maxWidth} properties (threshold ${WIDE_SCHEMA_THRESHOLD}).`,
+          path: label,
+          hint: "Split the payload, or bound generation with maxProperties."
+        });
+      }
+      if (bodyContent && !hasAnyExample(bodyContent)) {
+        findings.push({
+          severity: "info",
+          code: "missing-request-example",
+          message: "Request body has no example \u2014 examples measurably improve complex-parameter accuracy.",
+          path: label,
+          hint: "Add a media-type example (and enable includeExamples), or patch one in with an overlay."
+        });
+      }
+    }
+  }
+  for (const [operationId, labels] of operationIds) {
+    if (labels.length > 1) {
+      findings.push({
+        severity: "error",
+        code: "duplicate-operation-id",
+        message: `operationId '${operationId}' is used by ${labels.length} operations: ${labels.join(", ")}.`,
+        path: labels[0],
+        hint: "Make operationIds unique \u2014 duplicates force hash-suffixed tool names."
+      });
+    }
+  }
+  const rank = { error: 0, warning: 1, info: 2 };
+  findings.sort(
+    (a, b) => rank[a.severity] - rank[b.severity] || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || (a.code < b.code ? -1 : 1)
+  );
+  return {
+    findings,
+    counts: {
+      error: findings.filter((f) => f.severity === "error").length,
+      warning: findings.filter((f) => f.severity === "warning").length,
+      info: findings.filter((f) => f.severity === "info").length
+    }
+  };
+}
+
+// src/validator.ts
+var Validator = class {
+  /**
+   * Validate an OpenAPI document
+   */
+  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"
+      });
+    }
+    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 (!document.info.version) {
+        errors.push({
+          message: "Missing required field: info.version",
+          path: "/info/version",
+          code: "MISSING_VERSION"
+        });
+      }
+    }
+    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 (!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"
+      });
+    }
+    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
+    };
+  }
+  /**
+   * Check if OpenAPI version is valid
+   */
+  isValidOpenAPIVersion(version) {
+    return /^3\.[01]\.\d+$/.test(version);
+  }
+  /**
+   * Validate paths
+   */
+  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);
+        }
+      }
+      if (!hasOperations && !pathItem.$ref) {
+        warnings.push({
+          message: `Path has no operations: ${path}`,
+          path: `/paths/${path}`,
+          code: "NO_OPERATIONS"
+        });
+      }
+    }
+  }
+  /**
+   * Validate an operation
+   */
+  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"
+        });
+      }
+    }
+  }
+  /**
+   * Validate parameters
+   */
+  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"
+        });
+      }
+    }
   }
 };
 
@@ -1012,822 +2526,860 @@ function nodePinnedTransport(modules) {
             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);
-    }
-    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 status = typeof response.status === "number" ? response.status : 0;
-    const isRedirect = status >= 300 && status < 400 && status !== 304;
-    if (!isRedirect || !followRedirects) {
-      return response;
-    }
-    const location = response.headers?.get?.("location") ?? void 0;
-    if (!location) {
-      return response;
-    }
-    current = new URL(location, current).toString();
-  }
-  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
-}
-
-// 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 ?? {}
-    };
-  }
-  /**
-   * Create generator from a URL
-   */
-  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)
-      });
-      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
-      });
-    }
-  }
-  /**
-   * 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
-      });
-    }
-  }
-  /**
-   * 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
-      });
-    }
-  }
-  /**
-   * Create generator from a JSON object
-   */
-  static async fromJSON(json, options = {}) {
-    const document = JSON.parse(JSON.stringify(json));
-    return new _OpenAPIToolGenerator(document, options);
-  }
-  /**
-   * Get the OpenAPI document
-   */
-  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;
+        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);
     }
-    return { resolve: resolveConfig };
+    throw new SsrfError("No fetch implementation available to load OpenAPI spec from URL", { url });
   }
-  /**
-   * 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)
-    );
+  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 status = typeof response.status === "number" ? response.status : 0;
+    const isRedirect = status >= 300 && status < 400 && status !== 304;
+    if (!isRedirect || !followRedirects) {
+      return response;
+    }
+    const location = response.headers?.get?.("location") ?? void 0;
+    if (!location) {
+      return response;
+    }
+    current = new URL(location, current).toString();
   }
-  /**
-   * 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;
+  throw new SsrfError(`Too many redirects while loading OpenAPI spec (max ${maxRedirects})`, { url });
+}
+
+// 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 ?? []
+    }
+  };
+}
+function hasUnboundedArray(node, seen = /* @__PURE__ */ new Set()) {
+  if (node === null || typeof node !== "object" || seen.has(node)) return false;
+  seen.add(node);
+  const record = node;
+  const type = record["type"];
+  const isArray = type === "array" || Array.isArray(type) && type.includes("array");
+  if (isArray && record["maxItems"] === void 0) return true;
+  const children = [];
+  const properties = record["properties"];
+  if (properties && typeof properties === "object") children.push(...Object.values(properties));
+  for (const key of ["items", "additionalProperties", "contentSchema"]) {
+    const value = record[key];
+    if (Array.isArray(value)) children.push(...value);
+    else if (value && typeof value === "object") children.push(value);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+    if (Array.isArray(record[key])) children.push(...record[key]);
+  }
+  return children.some((child) => hasUnboundedArray(child, seen));
+}
+function detectResponseHints(outputSchema, mapper) {
+  const paginationParams = [
+    ...new Set(mapper.filter((m) => m.type === "query" && !m.security && PAGINATION_PARAM.test(m.key)).map((m) => m.key))
+  ];
+  const unboundedArray = outputSchema !== void 0 && hasUnboundedArray(outputSchema);
+  if (!unboundedArray && paginationParams.length === 0) return void 0;
+  return {
+    ...unboundedArray && { unboundedArray: true },
+    ...paginationParams.length > 0 && { paginationParams },
+    ...unboundedArray && paginationParams.length === 0 && { largeResponseRisk: true }
+  };
+}
+function composeDescription(operation, method, pathStr, strategy) {
+  const fallback = `${method.toUpperCase()} ${pathStr}`;
+  const summary = operation.summary?.trim();
+  const description = operation.description?.trim();
+  switch (strategy) {
+    case "descriptionOnly":
+      return description || summary || fallback;
+    case "combined":
+      if (summary && description && summary !== description) {
+        return `${summary}
+
+${description}`;
       }
-      const out = {};
-      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
-      return out;
-    };
-    return walk(root);
+      return summary || description || fallback;
+    case "full": {
+      const parts = [];
+      if (summary) parts.push(summary);
+      if (description && description !== summary) parts.push(description);
+      if (operation.operationId) parts.push(`Operation: ${operation.operationId}`);
+      parts.push(fallback);
+      return parts.join("\n\n");
+    }
+    default:
+      return summary || description || fallback;
   }
-  /**
-   * 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
-          });
-        }
+}
+function propertyNames(schema, cap = 8) {
+  const properties = schema["properties"];
+  if (!properties || typeof properties !== "object") return "";
+  const names = Object.keys(properties);
+  const listed = names.slice(0, cap).join(", ");
+  return names.length > cap ? `${listed}, \u2026` : listed;
+}
+function summarizeOutputSchema(schema) {
+  const record = schema;
+  const variants = record["oneOf"];
+  if (Array.isArray(variants) && variants.length > 0) {
+    const first = variants[0];
+    const firstSummary = first && typeof first === "object" ? summarizeOutputSchema(first) : void 0;
+    return firstSummary ? `${firstSummary} (${variants.length} response variants)` : void 0;
+  }
+  const type = record["type"];
+  if (type === "object" || type === void 0 && record["properties"]) {
+    const names = propertyNames(record);
+    return names ? `object with fields: ${names}` : "object";
+  }
+  if (type === "array") {
+    const items = record["items"];
+    if (items && typeof items === "object" && !Array.isArray(items)) {
+      const itemRecord = items;
+      if (itemRecord["type"] === "object" || itemRecord["properties"]) {
+        const names = propertyNames(itemRecord);
+        return names ? `array of objects with fields: ${names}` : "array of objects";
       }
-    }
-    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 });
+      if (typeof itemRecord["type"] === "string") {
+        return `array of ${itemRecord["type"]}`;
       }
     }
+    return "array";
   }
-  /**
-   * 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"];
-      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 (typeof type === "string" && type !== "null") {
+    return type;
+  }
+  return void 0;
+}
+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, "\\$&");
+    }
+  }
+  return new RegExp(`${pattern}$`);
+}
+function matchesAnyGlob(path, globs) {
+  return globs.some((glob) => globToRegExp(glob).test(path));
+}
+function trimUnderscores(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "_") start++;
+  while (end > start && value[end - 1] === "_") end--;
+  return value.slice(start, end);
+}
+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 = trimUnderscores(raw.replace(/[^A-Za-z0-9_.-]/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 tools;
   }
+  return name;
+}
+var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
+  document;
+  dereferencedDocument;
+  options;
   /**
-   * Generate a specific tool for a path and method
+   * Private constructor - use static factory methods to create instances
    */
-  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);
-    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 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
+  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,
+      overlays: options.overlays
     };
+    if (this.options.overlays) {
+      const overlays = Array.isArray(this.options.overlays) ? this.options.overlays : [this.options.overlays];
+      for (const overlay of overlays) {
+        this.document = applyOverlay(this.document, overlay);
+      }
+    }
   }
   /**
-   * Check if an operation should be included
+   * Create generator from a URL
    */
-  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;
+  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);
       }
-    }
-    if (options.excludeOperations && operation.operationId) {
-      if (options.excludeOperations.includes(operation.operationId)) {
-        return false;
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      if (error instanceof LoadError || error instanceof OverlayError) {
+        throw error;
       }
-    }
-    if (options.filterFn) {
-      return options.filterFn({
-        ...operation,
-        path,
-        method
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from URL: ${errorMessage}`, {
+        url,
+        originalError: error
       });
     }
-    return true;
   }
   /**
-   * Generate a tool name
+   * Create generator from a file path
    */
-  generateToolName(path, method, operationId, options = {}) {
-    if (options.namingStrategy?.toolNameGenerator) {
-      return options.namingStrategy.toolNameGenerator(path, method, operationId);
-    }
-    if (operationId) {
-      return operationId;
+  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) {
+      if (error instanceof OverlayError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
+        filePath,
+        originalError: error
+      });
     }
-    const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
-    return `${method}_${sanitized}`;
   }
   /**
-   * Extract metadata from operation
+   * Create generator from a YAML string
    */
-  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
-      );
-    }
-    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 }];
-    }
-    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;
+  static async fromYAML(yamlString, options = {}) {
+    try {
+      const document = yaml.parse(yamlString);
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      if (error instanceof OverlayError) {
+        throw error;
       }
-    } else if (schemaObj && schemaObj["x-status-code"] !== void 0 && schemaObj["x-status-code"] !== null) {
-      metadata.responseStatusCodes = [schemaObj["x-status-code"]];
-    }
-    if (operation.externalDocs) {
-      metadata.externalDocs = operation.externalDocs;
-    }
-    const operationWithExt = operation;
-    if (operationWithExt["x-frontmcp"]) {
-      metadata.frontmcp = operationWithExt["x-frontmcp"];
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
+        originalError: error
+      });
     }
-    return metadata;
   }
   /**
-   * Extract security requirements
+   * Create generator from a JSON object
    */
-  extractSecurityRequirements(security, document) {
-    if (!security || !document.components?.securitySchemes) {
-      return [];
-    }
-    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;
-      })
-    );
+  static async fromJSON(json, options = {}) {
+    const document = JSON.parse(JSON.stringify(json));
+    return new _OpenAPIToolGenerator(document, options);
   }
-};
-
-// src/schema-builder.ts
-var SchemaBuilder = class {
   /**
-   * Merge multiple schemas into one
+   * Get the OpenAPI document
    */
-  static merge(schemas) {
-    if (schemas.length === 0) {
-      return { type: "object" };
-    }
-    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 (schema.required) {
-        schema.required.forEach((field) => allRequired.add(field));
-      }
-    }
-    if (allRequired.size > 0) {
-      merged.required = Array.from(allRequired);
-    }
-    return merged;
+  getDocument() {
+    return this.dereferencedDocument ?? this.document;
   }
   /**
-   * Create a union schema (oneOf)
+   * Validate the OpenAPI document
    */
-  static union(schemas) {
-    if (schemas.length === 0) {
-      return {};
-    }
-    if (schemas.length === 1) {
-      return schemas[0];
-    }
-    return {
-      oneOf: schemas
-    };
+  async validate() {
+    const validator = new Validator();
+    return validator.validate(this.document);
   }
   /**
-   * Deep clone a schema
+   * Lint the loaded document for agent-readiness (missing operationIds,
+   * vague descriptions, unpaginated lists, oversized schemas, ...). Runs
+   * after overlays and dereferencing so findings reflect what tools would
+   * actually be generated from.
    */
-  static clone(schema) {
-    return JSON.parse(JSON.stringify(schema));
+  async lint() {
+    await this.initialize(false);
+    return lintDocument(this.getDocument());
   }
+  // 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`).
   /**
-   * Remove $ref from schema (assumes already dereferenced)
+   * Build $RefParser options based on refResolution configuration.
+   * Defaults: allow http/https, block file://, block internal IPs.
    */
-  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;
+  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 } };
     }
-    for (const key in obj) {
-      if (key in obj) {
-        const value = obj[key];
-        if (value && typeof value === "object") {
-          this.removeRefsRecursive(value);
+    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 description to schema
-   */
-  static withDescription(schema, description) {
-    return {
-      ...schema,
-      description
-    };
-  }
-  /**
-   * Add example to schema
-   */
-  static withExample(schema, example) {
-    const existingExamples = Array.isArray(schema.examples) ? schema.examples : [];
-    return {
-      ...schema,
-      examples: [...existingExamples, example]
-    };
-  }
-  /**
-   * Add default value to schema
-   */
-  static withDefault(schema, defaultValue) {
-    return {
-      ...schema,
-      default: defaultValue
-    };
-  }
-  /**
-   * Add format 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 withFormat(schema, format) {
-    return {
-      ...schema,
-      format
-    };
+  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 pattern 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 withPattern(schema, pattern) {
-    return {
-      ...schema,
-      pattern
+  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;
     };
-  }
-  /**
-   * Add enum to schema
-   */
-  static withEnum(schema, values) {
-    return {
-      ...schema,
-      enum: values
+    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(runValidation = this.options.validate) {
+    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 (runValidation) {
+      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 ?? composeDescription(operation, method, pathStr, options.descriptionStrategy ?? "summaryOnly");
+    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) {
-    return {
-      type: "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);
+    }
+    const applyTrim = (schema, isInputRoot) => {
+      let trimmed = schema;
+      if (options.stripExamples) trimmed = SchemaBuilder.stripExamples(trimmed);
+      if (options.maxDescriptionLength !== void 0) {
+        trimmed = SchemaBuilder.capDescriptions(trimmed, options.maxDescriptionLength);
+      }
+      if (options.maxProperties !== void 0) {
+        if (isInputRoot) {
+          const properties = trimmed.properties;
+          if (properties && typeof properties === "object") {
+            const limited = {};
+            for (const [key, value] of Object.entries(properties)) {
+              limited[key] = SchemaBuilder.limitProperties(value, options.maxProperties);
+            }
+            trimmed = { ...trimmed, properties: limited };
+          }
+        } else {
+          trimmed = SchemaBuilder.limitProperties(trimmed, options.maxProperties);
+        }
+      }
+      return trimmed;
     };
-  }
-  /**
-   * Create integer schema
-   */
-  static integer(constraints) {
+    if (options.stripExamples || options.maxProperties !== void 0 || options.maxDescriptionLength !== void 0) {
+      resolvedInputSchema = applyTrim(resolvedInputSchema, true);
+      if (resolvedOutputSchema) {
+        resolvedOutputSchema = applyTrim(resolvedOutputSchema, false);
+      }
+    }
+    if (options.target) {
+      resolvedInputSchema = applyClientTarget(resolvedInputSchema, options.target);
+      if (resolvedOutputSchema) {
+        resolvedOutputSchema = applyClientTarget(resolvedOutputSchema, options.target);
+      }
+    }
+    const responseHints = detectResponseHints(resolvedOutputSchema, mapper);
+    if (responseHints) {
+      metadata.responseHints = responseHints;
+    }
+    let finalDescription = description;
+    if (options.appendResponseSummary && resolvedOutputSchema) {
+      const summary = summarizeOutputSchema(resolvedOutputSchema);
+      if (summary) {
+        finalDescription = `${finalDescription}
+
+Returns: ${summary}`;
+      }
+    }
     return {
-      type: "integer",
-      ...constraints
+      name,
+      ...title !== void 0 && { title },
+      description: finalDescription,
+      ...annotations && { annotations },
+      inputSchema: resolvedInputSchema,
+      outputSchema: resolvedOutputSchema,
+      mapper,
+      metadata
     };
   }
   /**
-   * Create boolean schema
+   * Check if an operation should be included
    */
-  static boolean() {
-    return {
-      type: "boolean"
-    };
+  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 null schema
+   * Generate a tool name
    */
-  static null() {
-    return {
-      type: "null"
-    };
+  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 = trimUnderscores(
+        path.replace(/\{([^{}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_")
+      );
+      rawName = `${method}_${sanitized}`;
+    }
+    return normalizeToolName(
+      rawName,
+      options.maxToolNameLength ?? DEFAULT_MAX_TOOL_NAME_LENGTH,
+      `${method} ${path}`
+    );
   }
   /**
-   * Flatten nested oneOf/anyOf/allOf schemas
+   * Extract metadata from operation
    */
-  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;
+  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 (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;
+      })
+    );
   }
 };
 
@@ -1958,7 +3510,7 @@ var SecurityResolver = class {
   resolveDigestAuth(context) {
     const digest = context.digest;
     if (!digest) return void 0;
-    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/"/g, '\\"');
+    const quoted = (v) => String(v).replace(/[\r\n]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     const token = (v) => String(v).replace(/[\r\n",]/g, "");
     const parts = [
       `username="${quoted(digest.username)}"`,
@@ -2074,6 +3626,389 @@ 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 }
+    }
+  ];
+}
+
+// src/token-report.ts
+function estimateToolTokens(tool) {
+  const advertised = {
+    name: tool.name,
+    ...tool.title !== void 0 && { title: tool.title },
+    description: tool.description,
+    ...tool.annotations !== void 0 && { annotations: tool.annotations },
+    inputSchema: tool.inputSchema,
+    ...tool.outputSchema !== void 0 && { outputSchema: tool.outputSchema }
+  };
+  return Math.ceil(JSON.stringify(advertised).length / 4);
+}
+function analyzeToolSet(tools, options = {}) {
+  const tokenBudget = options.tokenBudget ?? 1e4;
+  const maxRecommendedTools = options.maxRecommendedTools ?? 40;
+  const perToolWarning = options.perToolWarning ?? 2e3;
+  const perTool = tools.map((tool) => ({ name: tool.name, tokens: estimateToolTokens(tool) })).sort((a, b) => b.tokens - a.tokens || (a.name < b.name ? -1 : 1));
+  const estimatedTokens = perTool.reduce((sum, entry) => sum + entry.tokens, 0);
+  const warnings = [];
+  if (tools.length > maxRecommendedTools) {
+    warnings.push(
+      `${tools.length} tools exceeds the ~${maxRecommendedTools}-tool range where model selection accuracy degrades \u2014 curate with filters (tags, paths, readOnlyOnly) or split into focused servers.`
+    );
+  }
+  if (estimatedTokens > tokenBudget) {
+    warnings.push(
+      `Estimated ${estimatedTokens} tokens of tool definitions exceeds the ${tokenBudget}-token budget \u2014 trim schemas (maxSchemaDepth, maxProperties) or reduce the tool count.`
+    );
+  }
+  const heavy = perTool.filter((entry) => entry.tokens > perToolWarning);
+  if (heavy.length > 0) {
+    warnings.push(
+      `${heavy.length} tool(s) exceed ${perToolWarning} tokens each (${heavy.slice(0, 3).map((entry) => `${entry.name}: ~${entry.tokens}`).join(", ")}${heavy.length > 3 ? ", \u2026" : ""}) \u2014 consider schema trimming for these.`
+    );
+  }
+  return { toolCount: tools.length, estimatedTokens, perTool, warnings };
+}
 export {
   BLOCKED_HOSTNAMES,
   BUILTIN_FORMAT_RESOLVERS,
@@ -2081,8 +4016,10 @@ export {
   LoadError,
   OpenAPIToolError,
   OpenAPIToolGenerator,
+  OverlayError,
   ParameterResolver,
   ParseError,
+  RequestBuildError,
   ResponseBuilder,
   SchemaBuilder,
   SchemaError,
@@ -2090,15 +4027,32 @@ export {
   SsrfError,
   ValidationError,
   Validator,
+  analyzeToolSet,
+  applyClientTarget,
+  applyOverlay,
   assertUrlSafe,
+  buildHttpRequest,
+  collapseNestedUnions,
+  collapseRootCompositions,
   createSecurityContext,
   decodeIpv4MappedIpv6,
   defaultLookup,
+  demoteFormats,
+  enforceClosedObjects,
+  ensureArrayItems,
+  estimateToolTokens,
+  extractExtensionOverrides,
+  inferAnnotationsFromMethod,
+  inlineLocalRefs,
   isBlockedAddress,
   isBlockedHostname,
   isReferenceObject,
+  lintDocument,
   normalizeSsrfOptions,
+  requireAllProperties,
+  resolveExtensionEnabled,
   resolveSchemaFormats,
   safeFetch,
-  toJsonSchema
+  toJsonSchema,
+  toSdkTool
 };