mcp-from-openapi 2.2.0 → 2.4.0

package/esm/index.mjs

@@ -1,8 +1,5 @@
 // src/generator.ts
 import * as yaml from "yaml";
-import * as path from "path";
-import * as fs from "fs/promises";
-import $RefParser from "@apidevtools/json-schema-ref-parser";
 
 // src/types.ts
 function isReferenceObject(obj) {
@@ -537,12 +534,12 @@ var Validator = class {
    * Validate paths
    */
   validatePaths(paths, errors, warnings) {
-    for (const [path2, pathItem] of Object.entries(paths)) {
+    for (const [path, pathItem] of Object.entries(paths)) {
       if (!pathItem) continue;
-      if (!path2.startsWith("/")) {
+      if (!path.startsWith("/")) {
         errors.push({
-          message: `Path must start with '/': ${path2}`,
-          path: `/paths/${path2}`,
+          message: `Path must start with '/': ${path}`,
+          path: `/paths/${path}`,
           code: "INVALID_PATH_FORMAT"
         });
       }
@@ -552,13 +549,13 @@ var Validator = class {
         const operation = pathItem[method];
         if (operation) {
           hasOperations = true;
-          this.validateOperation(operation, path2, method, errors, warnings);
+          this.validateOperation(operation, path, method, errors, warnings);
         }
       }
       if (!hasOperations && !pathItem.$ref) {
         warnings.push({
-          message: `Path has no operations: ${path2}`,
-          path: `/paths/${path2}`,
+          message: `Path has no operations: ${path}`,
+          path: `/paths/${path}`,
           code: "NO_OPERATIONS"
         });
       }
@@ -567,33 +564,33 @@ var Validator = class {
   /**
    * Validate an operation
    */
-  validateOperation(operation, path2, method, errors, warnings) {
-    const basePath = `/paths/${path2}/${method}`;
+  validateOperation(operation, path, method, errors, warnings) {
+    const basePath = `/paths/${path}/${method}`;
     if (!operation.operationId) {
       warnings.push({
-        message: `Operation missing operationId: ${method.toUpperCase()} ${path2}`,
+        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()} ${path2}`,
+        message: `Operation missing responses: ${method.toUpperCase()} ${path}`,
         path: `${basePath}/responses`,
         code: "NO_RESPONSES"
       });
     }
     if (operation.parameters) {
-      this.validateParameters(operation.parameters, path2, method, errors, warnings);
+      this.validateParameters(operation.parameters, path, method, errors, warnings);
     }
-    const pathParams = path2.match(/\{([^}]+)\}/g)?.map((p) => p.slice(1, -1)) ?? [];
+    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()} ${path2}`,
+          message: `Path parameter '${param}' not defined in parameters: ${method.toUpperCase()} ${path}`,
           path: `${basePath}/parameters`,
           code: "MISSING_PATH_PARAMETER"
         });
@@ -603,8 +600,8 @@ var Validator = class {
   /**
    * Validate parameters
    */
-  validateParameters(parameters, path2, method, errors, warnings) {
-    const basePath = `/paths/${path2}/${method}/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}`;
@@ -686,6 +683,115 @@ var SchemaError = class extends OpenAPIToolError {
   }
 };
 
+// src/format-resolver.ts
+var BUILTIN_FORMAT_RESOLVERS = {
+  // String formats
+  uuid: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+    description: schema.description || "UUID string (RFC 4122)"
+  }),
+  "date-time": (schema) => ({
+    ...schema,
+    description: schema.description || "ISO 8601 date-time (e.g., 2024-01-15T09:30:00Z)"
+  }),
+  date: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^\\d{4}-\\d{2}-\\d{2}$",
+    description: schema.description || "ISO 8601 date (e.g., 2024-01-15)"
+  }),
+  time: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^\\d{2}:\\d{2}:\\d{2}",
+    description: schema.description || "ISO 8601 time (e.g., 09:30:00)"
+  }),
+  email: (schema) => ({
+    ...schema,
+    description: schema.description || "Email address (RFC 5322)"
+  }),
+  uri: (schema) => ({
+    ...schema,
+    description: schema.description || "URI (RFC 3986)"
+  }),
+  "uri-reference": (schema) => ({
+    ...schema,
+    description: schema.description || "URI reference (RFC 3986)"
+  }),
+  hostname: (schema) => ({
+    ...schema,
+    description: schema.description || "Internet hostname (RFC 1123)"
+  }),
+  ipv4: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$",
+    description: schema.description || "IPv4 address"
+  }),
+  ipv6: (schema) => ({
+    ...schema,
+    description: schema.description || "IPv6 address (RFC 4291)"
+  }),
+  // Integer formats
+  int32: (schema) => ({
+    ...schema,
+    minimum: schema.minimum ?? -2147483648,
+    maximum: schema.maximum ?? 2147483647
+  }),
+  int64: (schema) => ({
+    ...schema,
+    minimum: schema.minimum ?? Number.MIN_SAFE_INTEGER,
+    maximum: schema.maximum ?? Number.MAX_SAFE_INTEGER
+  }),
+  // Binary/encoding formats
+  byte: (schema) => ({
+    ...schema,
+    pattern: schema.pattern ?? "^[A-Za-z0-9+/]*={0,2}$",
+    description: schema.description || "Base64-encoded string (RFC 4648)"
+  }),
+  binary: (schema) => ({
+    ...schema,
+    description: schema.description || "Binary data"
+  }),
+  // Sensitive data formats
+  password: (schema) => ({
+    ...schema,
+    description: schema.description || "Password (sensitive, UI should mask input)"
+  })
+};
+function resolveSchemaFormats(schema, resolvers) {
+  if (!schema || typeof schema !== "object") return schema;
+  let result = { ...schema };
+  const format = result["format"];
+  if (format && resolvers[format]) {
+    result = { ...resolvers[format](result) };
+  }
+  if (result["properties"] && typeof result["properties"] === "object") {
+    const props = {};
+    for (const [key, value] of Object.entries(result["properties"])) {
+      props[key] = resolveSchemaFormats(value, resolvers);
+    }
+    result["properties"] = props;
+  }
+  if (result["items"]) {
+    if (Array.isArray(result["items"])) {
+      result["items"] = result["items"].map((item) => resolveSchemaFormats(item, resolvers));
+    } else {
+      result["items"] = resolveSchemaFormats(result["items"], resolvers);
+    }
+  }
+  if (result["additionalProperties"] && typeof result["additionalProperties"] === "object") {
+    result["additionalProperties"] = resolveSchemaFormats(result["additionalProperties"], resolvers);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    if (result[key] && Array.isArray(result[key])) {
+      result[key] = result[key].map((s) => resolveSchemaFormats(s, resolvers));
+    }
+  }
+  if (result["not"] && typeof result["not"] === "object") {
+    result["not"] = resolveSchemaFormats(result["not"], resolvers);
+  }
+  return result;
+}
+
 // src/generator.ts
 var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   document;
@@ -750,6 +856,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
    */
   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();
@@ -840,6 +947,31 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     /^\[fe80:/i
     // bracketed IPv6 link-local
   ];
+  /**
+   * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
+   * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4,
+   * or `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
+   * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
+   * dotted-quad blocklist patterns miss — letting an attacker reach a private /
+   * metadata IPv4 through the v6 mapping. We re-check the decoded v4.
+   */
+  static mappedIPv4FromIPv6(hostname) {
+    let h = hostname;
+    if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+    const lower = h.toLowerCase();
+    const marker = lower.lastIndexOf("::ffff:");
+    if (marker === -1) return null;
+    const tail = lower.slice(marker + "::ffff:".length);
+    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail)) return tail;
+    const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hex) {
+      const hi = parseInt(hex[1], 16);
+      const lo = parseInt(hex[2], 16);
+      if (Number.isNaN(hi) || Number.isNaN(lo)) return null;
+      return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+    }
+    return null;
+  }
   /**
    * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
    */
@@ -850,11 +982,16 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (refOpts.blockedHosts.includes(hostname)) {
       return true;
     }
-    for (const pattern of _OpenAPIToolGenerator.BLOCKED_HOSTNAME_PATTERNS) {
-      if (typeof pattern === "string") {
-        if (hostname === pattern) return true;
-      } else {
-        if (pattern.test(hostname)) return true;
+    const candidates = [hostname];
+    const mapped = _OpenAPIToolGenerator.mappedIPv4FromIPv6(hostname);
+    if (mapped) candidates.push(mapped);
+    for (const candidate of candidates) {
+      for (const pattern of _OpenAPIToolGenerator.BLOCKED_HOSTNAME_PATTERNS) {
+        if (typeof pattern === "string") {
+          if (candidate === pattern) return true;
+        } else {
+          if (pattern.test(candidate)) return true;
+        }
       }
     }
     return false;
@@ -884,6 +1021,14 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       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` (below) 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 allowlist/blocklist. Setting `redirects: 0` refuses the first
+        // redirect; legitimate refs resolve in one hop.
+        redirects: 0,
         canRead: (file) => {
           try {
             const parsed = new URL(file.url);
@@ -909,29 +1054,84 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     return { resolve: resolveConfig };
   }
   /**
-   * Initialize the generator (dereference if needed)
+   * Does the document contain any EXTERNAL `$ref` (a ref that is not a local
+   * JSON-pointer beginning with `#`)? Only external refs require the full
+   * `$RefParser` (file/http resolvers, which pull Node builtins). A document
+   * with only internal refs can be dereferenced with the runtime-agnostic
+   * resolver below — so it works on V8 isolates (Cloudflare Workers) too.
+   */
+  static hasExternalRefs(node, seen = /* @__PURE__ */ new Set()) {
+    if (node === null || typeof node !== "object") return false;
+    if (seen.has(node)) return false;
+    seen.add(node);
+    if (Array.isArray(node)) return node.some((n) => _OpenAPIToolGenerator.hasExternalRefs(n, seen));
+    const ref = node.$ref;
+    if (typeof ref === "string" && !ref.startsWith("#")) return true;
+    return Object.values(node).some(
+      (v) => _OpenAPIToolGenerator.hasExternalRefs(v, seen)
+    );
+  }
+  /**
+   * Dereference local (`#/...`) `$ref`s without `$RefParser` — pure, dependency-
+   * free, runtime-agnostic. A pointer cache makes circular schemas resolve to a
+   * shared reference instead of recursing forever (same contract as `$RefParser`).
+   */
+  static dereferenceInternal(root) {
+    const cache = /* @__PURE__ */ new Map();
+    const resolvePointer = (ptr) => {
+      const parts = ptr.replace(/^#\/?/, "").split("/").filter((p) => p.length > 0).map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+      let cur = root;
+      for (const p of parts) cur = cur?.[p];
+      return cur;
+    };
+    const walk = (node) => {
+      if (node === null || typeof node !== "object") return node;
+      if (Array.isArray(node)) return node.map(walk);
+      const ref = node.$ref;
+      if (typeof ref === "string" && ref.startsWith("#")) {
+        const cached = cache.get(ref);
+        if (cached !== void 0) return cached;
+        const placeholder = {};
+        cache.set(ref, placeholder);
+        const resolved = walk(resolvePointer(ref));
+        if (resolved && typeof resolved === "object") Object.assign(placeholder, resolved);
+        return placeholder;
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      return out;
+    };
+    return walk(root);
+  }
+  /**
+   * Initialize the generator (dereference if needed, then validate)
    */
   async initialize() {
+    if (this.options.dereference && !this.dereferencedDocument) {
+      const cloned = JSON.parse(JSON.stringify(this.document));
+      if (!_OpenAPIToolGenerator.hasExternalRefs(cloned)) {
+        this.dereferencedDocument = _OpenAPIToolGenerator.dereferenceInternal(cloned);
+      } else {
+        try {
+          const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
+          const refParserOptions = this.buildRefParserOptions();
+          this.dereferencedDocument = await $RefParser.dereference(cloned, refParserOptions);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
+            originalError: error
+          });
+        }
+      }
+    }
     if (this.options.validate) {
-      const result = await this.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 (this.options.dereference && !this.dereferencedDocument) {
-      try {
-        const refParserOptions = this.buildRefParserOptions();
-        this.dereferencedDocument = await $RefParser.dereference(
-          JSON.parse(JSON.stringify(this.document)),
-          refParserOptions
-        );
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new ParseError(`Failed to dereference OpenAPI document: ${errorMessage}`, {
-          originalError: error
-        });
-      }
-    }
   }
   /**
    * Generate all tools from the OpenAPI specification
@@ -1000,11 +1200,18 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     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,
-      outputSchema,
+      inputSchema: resolvedInputSchema,
+      outputSchema: resolvedOutputSchema,
       mapper,
       metadata
     };
@@ -1012,7 +1219,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Check if an operation should be included
    */
-  shouldIncludeOperation(operation, path2, method, options) {
+  shouldIncludeOperation(operation, path, method, options) {
     if (operation.deprecated && !options.includeDeprecated) {
       return false;
     }
@@ -1029,7 +1236,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (options.filterFn) {
       return options.filterFn({
         ...operation,
-        path: path2,
+        path,
         method
       });
     }
@@ -1038,22 +1245,22 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   /**
    * Generate a tool name
    */
-  generateToolName(path2, method, operationId, options = {}) {
+  generateToolName(path, method, operationId, options = {}) {
     if (options.namingStrategy?.toolNameGenerator) {
-      return options.namingStrategy.toolNameGenerator(path2, method, operationId);
+      return options.namingStrategy.toolNameGenerator(path, method, operationId);
     }
     if (operationId) {
       return operationId;
     }
-    const sanitized = path2.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+    const sanitized = path.replace(/\{([^}]+)\}/g, "By_$1").replace(/[^a-zA-Z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
     return `${method}_${sanitized}`;
   }
   /**
    * Extract metadata from operation
    */
-  extractMetadata(path2, method, operation, document, outputSchema) {
+  extractMetadata(path, method, operation, document, outputSchema) {
     const metadata = {
-      path: path2,
+      path,
       method,
       operationId: operation.operationId,
       operationSummary: operation.summary,
@@ -1454,6 +1661,7 @@ var SecurityResolver = class {
     if (requiresSignature) {
       resolved.requiresSignature = true;
       resolved.signatureInfo = {
+        /* c8 ignore next -- signatureScheme is always set from security.scheme */
         scheme: signatureScheme || "unknown"
       };
     }
@@ -1499,6 +1707,7 @@ var SecurityResolver = class {
         return this.resolveBasicAuth(context);
       case "digest":
         return this.resolveDigestAuth(context);
+      /* c8 ignore next -- hoba is part of the same fall-through as mutual/negotiate/vapid/scram */
       case "hoba":
       case "mutual":
       case "negotiate":
@@ -1531,16 +1740,18 @@ 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 token = (v) => String(v).replace(/[\r\n",]/g, "");
     const parts = [
-      `username="${digest.username}"`,
-      digest.realm ? `realm="${digest.realm}"` : "",
-      digest.nonce ? `nonce="${digest.nonce}"` : "",
-      digest.uri ? `uri="${digest.uri}"` : "",
-      digest.response ? `response="${digest.response}"` : "",
-      digest.opaque ? `opaque="${digest.opaque}"` : "",
-      digest.qop ? `qop=${digest.qop}` : "",
-      digest.nc ? `nc=${digest.nc}` : "",
-      digest.cnonce ? `cnonce="${digest.cnonce}"` : ""
+      `username="${quoted(digest.username)}"`,
+      digest.realm ? `realm="${quoted(digest.realm)}"` : "",
+      digest.nonce ? `nonce="${quoted(digest.nonce)}"` : "",
+      digest.uri ? `uri="${quoted(digest.uri)}"` : "",
+      digest.response ? `response="${quoted(digest.response)}"` : "",
+      digest.opaque ? `opaque="${quoted(digest.opaque)}"` : "",
+      digest.qop ? `qop=${token(digest.qop)}` : "",
+      digest.nc ? `nc=${token(digest.nc)}` : "",
+      digest.cnonce ? `cnonce="${quoted(digest.cnonce)}"` : ""
     ].filter(Boolean);
     return `Digest ${parts.join(", ")}`;
   }
@@ -1646,6 +1857,7 @@ function createSecurityContext(auth) {
   };
 }
 export {
+  BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
   OpenAPIToolError,
@@ -1660,5 +1872,6 @@ export {
   Validator,
   createSecurityContext,
   isReferenceObject,
+  resolveSchemaFormats,
   toJsonSchema
 };

package/esm/package.json

@@ -1,9 +1,10 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
+  "packageManager": "yarn@4.14.1",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -27,7 +28,7 @@
   },
   "homepage": "https://github.com/agentfront/mcp-from-openapi#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "type": "module",
   "main": "../index.js",
@@ -48,7 +49,7 @@
     }
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^11.9.3",
+    "@apidevtools/json-schema-ref-parser": "^15.3.5",
     "openapi-types": "^12.1.3",
     "yaml": "^2.8.3"
   },
@@ -60,6 +61,7 @@
     "@swc/helpers": "^0.5.18",
     "@swc/jest": "~0.2.38",
     "@types/jest": "^29.5.0",
+    "@types/json-schema": "^7.0.15",
     "@types/node": "^24.0.0",
     "esbuild": "^0.27.2",
     "jest": "^29.7.0",

package/format-resolver.d.ts

@@ -0,0 +1,12 @@
+import type { JsonSchema, FormatResolver } from './types';
+/**
+ * Built-in format resolvers that enrich JSON Schema with concrete constraints.
+ * Each resolver only adds constraints if not already present on the schema.
+ */
+export declare const BUILTIN_FORMAT_RESOLVERS: Record<string, FormatResolver>;
+/**
+ * Recursively resolve format fields in a JSON Schema tree.
+ * For each schema node with a `format` field, the matching resolver
+ * is applied to enrich the schema with concrete constraints.
+ */
+export declare function resolveSchemaFormats(schema: JsonSchema, resolvers: Record<string, FormatResolver>): JsonSchema;

package/generator.d.ts

@@ -39,6 +39,15 @@ export declare class OpenAPIToolGenerator {
      * Covers RFC 1918/6598 private ranges, link-local, loopback, and cloud metadata endpoints.
      */
     private static readonly BLOCKED_HOSTNAME_PATTERNS;
+    /**
+     * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
+     * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4,
+     * or `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
+     * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
+     * dotted-quad blocklist patterns miss — letting an attacker reach a private /
+     * metadata IPv4 through the v6 mapping. We re-check the decoded v4.
+     */
+    private static mappedIPv4FromIPv6;
     /**
      * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
      */
@@ -49,7 +58,21 @@ export declare class OpenAPIToolGenerator {
      */
     private buildRefParserOptions;
     /**
-     * Initialize the generator (dereference if needed)
+     * 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.
+     */
+    private static hasExternalRefs;
+    /**
+     * 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`).
+     */
+    private static dereferenceInternal;
+    /**
+     * Initialize the generator (dereference if needed, then validate)
      */
     private initialize;
     /**

package/index.d.ts

@@ -4,7 +4,8 @@ export { ParameterResolver } from './parameter-resolver';
 export { ResponseBuilder } from './response-builder';
 export { Validator } from './validator';
 export { SecurityResolver, createSecurityContext } from './security-resolver';
+export { BUILTIN_FORMAT_RESOLVERS, resolveSchemaFormats } from './format-resolver';
 export { OpenAPIToolError, LoadError, ParseError, ValidationError, GenerationError, SchemaError } from './errors';
-export type { McpOpenAPITool, ParameterMapper, ToolMetadata, FrontMcpExtensionData, SerializationInfo, SecurityRequirement, SecurityParameterInfo, ServerInfo, RefResolutionOptions, LoadOptions, GenerateOptions, NamingStrategy, OperationWithContext, OpenAPIDocument, OpenAPIVersion, HTTPMethod, ParameterLocation, AuthType, OperationObject, ParameterObject, RequestBodyObject, ResponseObject, ResponsesObject, MediaTypeObject, HeaderObject, ExampleObject, PathItemObject, PathsObject, ServerObject, SecuritySchemeObject, ReferenceObject, TagObject, ExternalDocumentationObject, ServerVariableObject, EncodingObject, SecurityRequirementObject, SchemaObject, ValidationResult, ValidationErrorDetail, ValidationWarning, } from './types';
+export type { McpOpenAPITool, ParameterMapper, ToolMetadata, FrontMcpExtensionData, SerializationInfo, SecurityRequirement, SecurityParameterInfo, ServerInfo, RefResolutionOptions, LoadOptions, GenerateOptions, FormatResolver, JsonSchema, NamingStrategy, OperationWithContext, OpenAPIDocument, OpenAPIVersion, HTTPMethod, ParameterLocation, AuthType, OperationObject, ParameterObject, RequestBodyObject, ResponseObject, ResponsesObject, MediaTypeObject, HeaderObject, ExampleObject, PathItemObject, PathsObject, ServerObject, SecuritySchemeObject, ReferenceObject, TagObject, ExternalDocumentationObject, ServerVariableObject, EncodingObject, SecurityRequirementObject, SchemaObject, ValidationResult, ValidationErrorDetail, ValidationWarning, } from './types';
 export type { SecurityContext, ResolvedSecurity, DigestAuthCredentials, ClientCertificate, AWSCredentials, SignatureData, } from './security-resolver';
 export { isReferenceObject, toJsonSchema } from './types';