mcp-from-openapi 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,5 @@
+## [2.2.0] - 2026-04-07
+
 ## [2.1.2] - 2025-12-27
 
 ### Changed

package/esm/index.mjs

@@ -1,10 +1,10 @@
-// libs/mcp-from-openapi/src/generator.ts
+// src/generator.ts
 import * as yaml from "yaml";
-import * as fs from "fs/promises";
 import * as path from "path";
+import * as fs from "fs/promises";
 import $RefParser from "@apidevtools/json-schema-ref-parser";
 
-// libs/mcp-from-openapi/src/types.ts
+// src/types.ts
 function isReferenceObject(obj) {
   return obj && typeof obj === "object" && "$ref" in obj;
 }
@@ -70,7 +70,7 @@ function toJsonSchema(schema) {
   return result;
 }
 
-// libs/mcp-from-openapi/src/parameter-resolver.ts
+// src/parameter-resolver.ts
 var ParameterResolver = class {
   namingStrategy;
   constructor(namingStrategy) {
@@ -335,7 +335,7 @@ var ParameterResolver = class {
   }
 };
 
-// libs/mcp-from-openapi/src/response-builder.ts
+// src/response-builder.ts
 var ResponseBuilder = class {
   preferredStatusCodes;
   includeAllResponses;
@@ -455,7 +455,7 @@ var ResponseBuilder = class {
   }
 };
 
-// libs/mcp-from-openapi/src/validator.ts
+// src/validator.ts
 var Validator = class {
   /**
    * Validate an OpenAPI document
@@ -646,7 +646,7 @@ var Validator = class {
   }
 };
 
-// libs/mcp-from-openapi/src/errors.ts
+// src/errors.ts
 var OpenAPIToolError = class extends Error {
   context;
   constructor(message, context) {
@@ -686,7 +686,7 @@ var SchemaError = class extends OpenAPIToolError {
   }
 };
 
-// libs/mcp-from-openapi/src/generator.ts
+// src/generator.ts
 var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   document;
   dereferencedDocument;
@@ -702,7 +702,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 ?? {}
     };
   }
   /**
@@ -807,6 +808,106 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
+  /**
+   * 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.
+   */
+  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)
    */
@@ -819,8 +920,10 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     }
     if (this.options.dereference && !this.dereferencedDocument) {
       try {
+        const refParserOptions = this.buildRefParserOptions();
         this.dereferencedDocument = await $RefParser.dereference(
-          JSON.parse(JSON.stringify(this.document))
+          JSON.parse(JSON.stringify(this.document)),
+          refParserOptions
         );
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1024,7 +1127,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
@@ -1303,7 +1406,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

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -20,13 +20,12 @@
   ],
   "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"
   },
@@ -46,19 +45,25 @@
         "types": "../index.d.ts",
         "default": "./index.mjs"
       }
-    },
-    "./esm": null
+    }
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.9.3",
     "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/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/generator.d.ts

@@ -34,6 +34,20 @@ export declare class OpenAPIToolGenerator {
      * Validate the OpenAPI document
      */
     validate(): Promise<ValidationResult>;
+    /**
+     * 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.
+     */
+    private static readonly BLOCKED_HOSTNAME_PATTERNS;
+    /**
+     * Check whether a hostname is blocked (internal/private IP or explicit blocklist).
+     */
+    private isBlockedHost;
+    /**
+     * Build $RefParser options based on refResolution configuration.
+     * Defaults: allow http/https, block file://, block internal IPs.
+     */
+    private buildRefParserOptions;
     /**
      * Initialize the generator (dereference if needed)
      */

package/index.d.ts

@@ -5,6 +5,6 @@ export { ResponseBuilder } from './response-builder';
 export { Validator } from './validator';
 export { SecurityResolver, createSecurityContext } from './security-resolver';
 export { OpenAPIToolError, LoadError, ParseError, ValidationError, GenerationError, SchemaError } from './errors';
-export type { McpOpenAPITool, ParameterMapper, ToolMetadata, FrontMcpExtensionData, SerializationInfo, SecurityRequirement, SecurityParameterInfo, ServerInfo, 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, 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';

package/index.js

@@ -27,7 +27,7 @@ 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, {
   GenerationError: () => GenerationError,
@@ -48,13 +48,13 @@ __export(index_exports, {
 });
 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 fs = __toESM(require("fs/promises"));
 var import_json_schema_ref_parser = __toESM(require("@apidevtools/json-schema-ref-parser"));
 
-// libs/mcp-from-openapi/src/types.ts
+// src/types.ts
 function isReferenceObject(obj) {
   return obj && typeof obj === "object" && "$ref" in obj;
 }
@@ -120,7 +120,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 +385,7 @@ var ParameterResolver = class {
   }
 };
 
-// libs/mcp-from-openapi/src/response-builder.ts
+// src/response-builder.ts
 var ResponseBuilder = class {
   preferredStatusCodes;
   includeAllResponses;
@@ -505,7 +505,7 @@ var ResponseBuilder = class {
   }
 };
 
-// libs/mcp-from-openapi/src/validator.ts
+// src/validator.ts
 var Validator = class {
   /**
    * Validate an OpenAPI document
@@ -696,7 +696,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 +736,7 @@ var SchemaError = class extends OpenAPIToolError {
   }
 };
 
-// libs/mcp-from-openapi/src/generator.ts
+// src/generator.ts
 var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
   document;
   dereferencedDocument;
@@ -752,7 +752,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 ?? {}
     };
   }
   /**
@@ -857,6 +858,106 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     const validator = new Validator();
     return validator.validate(this.document);
   }
+  /**
+   * 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.
+   */
+  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)
    */
@@ -869,8 +970,10 @@ var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
     }
     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))
+          JSON.parse(JSON.stringify(this.document)),
+          refParserOptions
         );
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1074,7 +1177,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 +1456,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-from-openapi",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Production-ready library for converting OpenAPI specifications into MCP tool definitions",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -20,13 +20,12 @@
   ],
   "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"
   },
@@ -46,19 +45,25 @@
         "types": "./index.d.ts",
         "default": "./esm/index.mjs"
       }
-    },
-    "./esm": null
+    }
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.9.3",
     "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/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

@@ -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