mcp-from-openapi 2.2.0 → 2.4.0

package/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BUILTIN_FORMAT_RESOLVERS: () => BUILTIN_FORMAT_RESOLVERS,
   GenerationError: () => GenerationError,
   LoadError: () => LoadError,
   OpenAPIToolError: () => OpenAPIToolError,
@@ -44,15 +45,13 @@ __export(index_exports, {
   Validator: () => Validator,
   createSecurityContext: () => createSecurityContext,
   isReferenceObject: () => isReferenceObject,
+  resolveSchemaFormats: () => resolveSchemaFormats,
   toJsonSchema: () => toJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/generator.ts
 var yaml = __toESM(require("yaml"));
-var path = __toESM(require("path"));
-var fs = __toESM(require("fs/promises"));
-var import_json_schema_ref_parser = __toESM(require("@apidevtools/json-schema-ref-parser"));
 
 // src/types.ts
 function isReferenceObject(obj) {
@@ -587,12 +586,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"
         });
       }
@@ -602,13 +601,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"
         });
       }
@@ -617,33 +616,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"
         });
@@ -653,8 +652,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}`;
@@ -736,6 +735,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;
@@ -800,6 +908,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();
@@ -890,6 +999,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).
    */
@@ -900,11 +1034,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;
@@ -934,6 +1073,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);
@@ -959,29 +1106,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 import_json_schema_ref_parser.default.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
@@ -1050,11 +1252,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
     };
@@ -1062,7 +1271,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;
     }
@@ -1079,7 +1288,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     if (options.filterFn) {
       return options.filterFn({
         ...operation,
-        path: path2,
+        path,
         method
       });
     }
@@ -1088,22 +1297,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,
@@ -1504,6 +1713,7 @@ var SecurityResolver = class {
     if (requiresSignature) {
       resolved.requiresSignature = true;
       resolved.signatureInfo = {
+        /* c8 ignore next -- signatureScheme is always set from security.scheme */
         scheme: signatureScheme || "unknown"
       };
     }
@@ -1549,6 +1759,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":
@@ -1581,16 +1792,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(", ")}`;
   }
@@ -1697,6 +1910,7 @@ function createSecurityContext(auth) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
   OpenAPIToolError,
@@ -1711,5 +1925,6 @@ function createSecurityContext(auth) {
   Validator,
   createSecurityContext,
   isReferenceObject,
+  resolveSchemaFormats,
   toJsonSchema
 });

package/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": "commonjs",
   "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/types.d.ts

@@ -1,6 +1,6 @@
 import type { JSONSchema } from 'zod/v4/core';
 /** JSON Schema type from Zod v4 */
-type JsonSchema = JSONSchema.JSONSchema;
+export type JsonSchema = JSONSchema.JSONSchema;
 import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 /**
  * OpenAPI specification version 3.0.x or 3.1.x
@@ -457,7 +457,28 @@ export interface GenerateOptions {
      * @default false
      */
     includeSecurityInInput?: boolean;
+    /**
+     * Enable built-in format-to-schema resolution.
+     * Enriches schemas with concrete constraints (patterns, descriptions, min/max)
+     * based on OpenAPI format values (uuid, date-time, email, int32, etc.).
+     * @default false
+     */
+    resolveFormats?: boolean;
+    /**
+     * Custom format resolvers. Keys are format names, values are functions
+     * that receive the original schema and return an enriched schema.
+     *
+     * When used with `resolveFormats: true`, custom resolvers are merged with
+     * built-in resolvers (custom takes precedence for the same format).
+     * When used without `resolveFormats`, only custom resolvers are applied.
+     */
+    formatResolvers?: Record<string, FormatResolver>;
 }
+/**
+ * A function that enriches a JSON Schema based on its format field.
+ * Receives the schema and returns a new schema with additional constraints.
+ */
+export type FormatResolver = (schema: JsonSchema) => JsonSchema;
 /**
  * Naming strategy for resolving parameter conflicts
  */
@@ -530,4 +551,3 @@ export interface ValidationWarning {
      */
     code?: string;
 }
-export {};

package/CHANGELOG.md

@@ -1,83 +0,0 @@
-## [2.2.0] - 2026-04-07
-
-## [2.1.2] - 2025-12-27
-
-### Changed
-
-- Added `publish-alpha` Nx target to enable alpha publishing flow using common script.
-
-## [2.1.1] - 2025-12-24
-
-### Fixed
-
-- Revised build setup to emit CJS and ESM bundles with corrected export map and sideEffects flag to improve tree shaking.
-- Synced package entry points and type outputs with the new build artifacts while preserving the public API surface.
-
-## [2.1.0] - 2025-12-19
-
-### Added
-
-- Introduced logger support within the OpenAPI adapter to improve observability.
-- Expanded security handling with automatic auth type routing and enhanced documentation.
-
-### Changed
-
-- Refined security resolver examples and guidance for broader authentication scheme coverage.
-
-## [2.0.0] - 2025-12-11
-
-### Breaking
-
-- Migrated to Zod v4 (now a peer dependency) and aligned JSON schema types with Zod’s v4 JSONSchema
-- Renamed utility export `toJSONSchema7` to `toJsonSchema`, affecting consumers of the types/helpers
-
-### Changed
-
-- Updated SWC/Jest config to inline ES2022 settings and modernized tooling versions
-- Adjusted exports formatting and minor parameter resolver refactors for consistency
-
-# Changelog
-
-## [1.0.0] - 2025-11-21
-
-### Features
-
-- Production-ready library for converting OpenAPI specifications into MCP tool definitions
-- OpenAPI 3.0+ and Swagger 2.0 support
-- Comprehensive operation parsing:
-  - RESTful endpoint detection (GET, POST, PUT, PATCH, DELETE, etc.)
-  - Path parameter extraction and validation
-  - Query parameter handling
-  - Request body schema conversion
-  - Response schema parsing
-- Advanced OpenAPI features:
-  - Reference resolution ($ref) across the entire specification
-  - Security scheme detection and configuration
-  - Parameter conflict resolution
-  - Operation naming controls and customization
-- Request mapper generation:
-  - Automatic parameter mapping from MCP tool inputs to HTTP requests
-  - Type-safe parameter handling
-  - Support for different parameter locations (path, query, header, cookie)
-  - Request body transformation
-- Tool metadata generation:
-  - Descriptive tool names from operation IDs
-  - Documentation from OpenAPI descriptions
-  - Schema validation rules
-- Multiple input formats:
-  - JSON OpenAPI specifications
-  - YAML OpenAPI specifications
-  - Inline specification objects
-  - URL references to remote specifications
-- Type-safe TypeScript implementation
-- Node.js 18+ compatibility
-
-### Documentation
-
-- Complete API reference
-- OpenAPI conversion examples
-- Integration guides for MCP servers
-- Best practices for tool generation
-
-This is the first official release of `mcp-from-openapi`, extracted from the FrontMCP framework to be published as a
-standalone, reusable library for the community.