mcp-from-openapi 2.1.2 → 2.3.0

package/index.js

@@ -27,9 +27,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// libs/mcp-from-openapi/src/index.ts
+// src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BUILTIN_FORMAT_RESOLVERS: () => BUILTIN_FORMAT_RESOLVERS,
   GenerationError: () => GenerationError,
   LoadError: () => LoadError,
   OpenAPIToolError: () => OpenAPIToolError,
@@ -44,17 +45,17 @@ __export(index_exports, {
   Validator: () => Validator,
   createSecurityContext: () => createSecurityContext,
   isReferenceObject: () => isReferenceObject,
+  resolveSchemaFormats: () => resolveSchemaFormats,
   toJsonSchema: () => toJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
 
-// libs/mcp-from-openapi/src/generator.ts
+// src/generator.ts
 var yaml = __toESM(require("yaml"));
-var fs = __toESM(require("fs/promises"));
 var path = __toESM(require("path"));
-var import_json_schema_ref_parser = __toESM(require("@apidevtools/json-schema-ref-parser"));
+var fs = __toESM(require("fs/promises"));
 
-// libs/mcp-from-openapi/src/types.ts
+// src/types.ts
 function isReferenceObject(obj) {
   return obj && typeof obj === "object" && "$ref" in obj;
 }
@@ -120,7 +121,7 @@ function toJsonSchema(schema) {
   return result;
 }
 
-// libs/mcp-from-openapi/src/parameter-resolver.ts
+// src/parameter-resolver.ts
 var ParameterResolver = class {
   namingStrategy;
   constructor(namingStrategy) {
@@ -385,7 +386,7 @@ var ParameterResolver = class {
   }
 };
 
-// libs/mcp-from-openapi/src/response-builder.ts
+// src/response-builder.ts
 var ResponseBuilder = class {
   preferredStatusCodes;
   includeAllResponses;
@@ -505,7 +506,7 @@ var ResponseBuilder = class {
   }
 };
 
-// libs/mcp-from-openapi/src/validator.ts
+// src/validator.ts
 var Validator = class {
   /**
    * Validate an OpenAPI document
@@ -696,7 +697,7 @@ var Validator = class {
   }
 };
 
-// libs/mcp-from-openapi/src/errors.ts
+// src/errors.ts
 var OpenAPIToolError = class extends Error {
   context;
   constructor(message, context) {
@@ -736,7 +737,116 @@ var SchemaError = class extends OpenAPIToolError {
   }
 };
 
-// libs/mcp-from-openapi/src/generator.ts
+// 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;
   dereferencedDocument;
@@ -752,7 +862,8 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
       headers: options.headers ?? {},
       timeout: options.timeout ?? 3e4,
       validate: options.validate ?? true,
-      followRedirects: options.followRedirects ?? true
+      followRedirects: options.followRedirects ?? true,
+      refResolution: options.refResolution ?? {}
     };
   }
   /**
@@ -858,19 +969,116 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     return validator.validate(this.document);
   }
   /**
-   * Initialize the generator (dereference if needed)
+   * Hostnames and IP patterns that are blocked by default to prevent SSRF.
+   * Covers RFC 1918/6598 private ranges, link-local, loopback, and cloud metadata endpoints.
    */
-  async initialize() {
-    if (this.options.validate) {
-      const result = await this.validate();
-      if (!result.valid) {
-        throw new ParseError("Invalid OpenAPI document", { errors: result.errors });
+  static BLOCKED_HOSTNAME_PATTERNS = [
+    "localhost",
+    "metadata.google.internal",
+    /^127\.\d+\.\d+\.\d+$/,
+    // 127.0.0.0/8 loopback
+    /^10\.\d+\.\d+\.\d+$/,
+    // 10.0.0.0/8 private
+    /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+    // 172.16.0.0/12 private
+    /^192\.168\.\d+\.\d+$/,
+    // 192.168.0.0/16 private
+    /^169\.254\.\d+\.\d+$/,
+    // 169.254.0.0/16 link-local / cloud metadata
+    /^0\.0\.0\.0$/,
+    // unspecified
+    "::1",
+    // IPv6 loopback
+    /^fd[0-9a-f]{2}:/i,
+    // fd00::/8 IPv6 ULA
+    /^fe80:/i,
+    // fe80::/10 IPv6 link-local
+    /^\[::1\]$/,
+    // bracketed IPv6 loopback
+    /^\[fd[0-9a-f]{2}:/i,
+    // bracketed IPv6 ULA
+    /^\[fe80:/i
+    // bracketed IPv6 link-local
+  ];
+  /**
+   * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
+   */
+  isBlockedHost(hostname, refOpts) {
+    if (refOpts.allowInternalIPs) {
+      return refOpts.blockedHosts.includes(hostname);
+    }
+    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;
       }
     }
+    return false;
+  }
+  /**
+   * 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"] = {
+        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 (this.isBlockedHost(parsed.hostname, refOpts)) {
+              return false;
+            }
+            return true;
+          } catch {
+            return false;
+          }
+        }
+      };
+    } else {
+      resolveConfig["http"] = false;
+    }
+    return { resolve: resolveConfig };
+  }
+  /**
+   * Initialize the generator (dereference if needed, then validate)
+   */
+  async initialize() {
     if (this.options.dereference && !this.dereferencedDocument) {
       try {
-        this.dereferencedDocument = await import_json_schema_ref_parser.default.dereference(
-          JSON.parse(JSON.stringify(this.document))
+        const { default: $RefParser } = await import("@apidevtools/json-schema-ref-parser");
+        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);
@@ -879,6 +1087,14 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
         });
       }
     }
+    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 });
+      }
+    }
   }
   /**
    * Generate all tools from the OpenAPI specification
@@ -947,11 +1163,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
     };
@@ -1074,7 +1297,7 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   }
 };
 
-// libs/mcp-from-openapi/src/schema-builder.ts
+// src/schema-builder.ts
 var SchemaBuilder = class {
   /**
    * Merge multiple schemas into one
@@ -1353,7 +1576,7 @@ var SchemaBuilder = class {
   }
 };
 
-// libs/mcp-from-openapi/src/security-resolver.ts
+// src/security-resolver.ts
 var SecurityResolver = class {
   /**
    * Resolve security parameters from mapper entries
@@ -1401,6 +1624,7 @@ var SecurityResolver = class {
     if (requiresSignature) {
       resolved.requiresSignature = true;
       resolved.signatureInfo = {
+        /* c8 ignore next -- signatureScheme is always set from security.scheme */
         scheme: signatureScheme || "unknown"
       };
     }
@@ -1446,6 +1670,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":
@@ -1594,6 +1819,7 @@ function createSecurityContext(auth) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
   OpenAPIToolError,
@@ -1608,5 +1834,6 @@ function createSecurityContext(auth) {
   Validator,
   createSecurityContext,
   isReferenceObject,
+  resolveSchemaFormats,
   toJsonSchema
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -20,15 +20,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/agentfront/frontmcp.git",
-    "directory": "libs/mcp-from-openapi"
+    "url": "git+https://github.com/agentfront/mcp-from-openapi.git"
   },
   "bugs": {
-    "url": "https://github.com/agentfront/frontmcp/issues"
+    "url": "https://github.com/agentfront/mcp-from-openapi/issues"
   },
-  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/mcp-from-openapi/README.md",
+  "homepage": "https://github.com/agentfront/mcp-from-openapi#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "type": "commonjs",
   "main": "./index.js",
@@ -46,19 +45,26 @@
         "types": "./index.d.ts",
         "default": "./esm/index.mjs"
       }
-    },
-    "./esm": null
+    }
   },
   "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.1"
+    "yaml": "^2.8.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@swc/core": "~1.5.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",
+    "tslib": "^2.8.1",
     "typescript": "^5.0.0",
     "zod": "^4.0.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
@@ -326,6 +326,37 @@ export interface ServerInfo {
      */
     variables?: Record<string, ServerVariableObject>;
 }
+/**
+ * Controls how external $ref pointers are resolved during dereferencing.
+ * By default, only http/https protocols are allowed and internal/private
+ * IP addresses are blocked to prevent SSRF attacks.
+ */
+export interface RefResolutionOptions {
+    /**
+     * Protocols allowed for external $ref resolution.
+     * Any protocol string is accepted (http, https, ftp, ws, wss, etc.).
+     * @default ['http', 'https']
+     */
+    allowedProtocols?: string[];
+    /**
+     * Hostnames allowed for external $ref resolution (network protocols only).
+     * When set, only refs pointing to these hosts are resolved.
+     * When not set, all hosts are allowed except blocked internal ranges.
+     */
+    allowedHosts?: string[];
+    /**
+     * Additional hostnames/IPs to block. Applied on top of the built-in
+     * internal IP block list (localhost, 169.254.x.x, 10.x.x.x, etc.).
+     */
+    blockedHosts?: string[];
+    /**
+     * Disable the built-in internal/private IP block list.
+     * WARNING: Enabling this may expose your application to SSRF attacks
+     * against cloud metadata endpoints and internal services.
+     * @default false
+     */
+    allowInternalIPs?: boolean;
+}
 /**
  * Options for loading OpenAPI specifications
  */
@@ -359,6 +390,12 @@ export interface LoadOptions {
      * @default true
      */
     followRedirects?: boolean;
+    /**
+     * Controls external $ref resolution security.
+     * By default, file:// is blocked and internal IPs are blocked.
+     * @see RefResolutionOptions
+     */
+    refResolution?: RefResolutionOptions;
 }
 /**
  * Operation object with additional context for filtering
@@ -420,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
  */
@@ -493,4 +551,3 @@ export interface ValidationWarning {
      */
     code?: string;
 }
-export {};

package/CHANGELOG.md

@@ -1,81 +0,0 @@
-## [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.