mcp-from-openapi 2.1.2 → 2.3.0

package/esm/index.mjs

@@ -1,10 +1,9 @@
-// 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 $RefParser from "@apidevtools/json-schema-ref-parser";
+import * as fs from "fs/promises";
 
-// libs/mcp-from-openapi/src/types.ts
+// src/types.ts
 function isReferenceObject(obj) {
   return obj && typeof obj === "object" && "$ref" in obj;
 }
@@ -70,7 +69,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 +334,7 @@ var ParameterResolver = class {
   }
 };
 
-// libs/mcp-from-openapi/src/response-builder.ts
+// src/response-builder.ts
 var ResponseBuilder = class {
   preferredStatusCodes;
   includeAllResponses;
@@ -455,7 +454,7 @@ var ResponseBuilder = class {
   }
 };
 
-// libs/mcp-from-openapi/src/validator.ts
+// src/validator.ts
 var Validator = class {
   /**
    * Validate an OpenAPI document
@@ -646,7 +645,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 +685,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;
@@ -702,7 +810,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 ?? {}
     };
   }
   /**
@@ -808,19 +917,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 {
+        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))
+          JSON.parse(JSON.stringify(this.document)),
+          refParserOptions
         );
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -829,6 +1035,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
@@ -897,11 +1111,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
     };
@@ -1024,7 +1245,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 +1524,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
@@ -1351,6 +1572,7 @@ var SecurityResolver = class {
     if (requiresSignature) {
       resolved.requiresSignature = true;
       resolved.signatureInfo = {
+        /* c8 ignore next -- signatureScheme is always set from security.scheme */
         scheme: signatureScheme || "unknown"
       };
     }
@@ -1396,6 +1618,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":
@@ -1543,6 +1766,7 @@ function createSecurityContext(auth) {
   };
 }
 export {
+  BUILTIN_FORMAT_RESOLVERS,
   GenerationError,
   LoadError,
   OpenAPIToolError,
@@ -1557,5 +1781,6 @@ export {
   Validator,
   createSecurityContext,
   isReferenceObject,
+  resolveSchemaFormats,
   toJsonSchema
 };

package/esm/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": "module",
   "main": "../index.js",
@@ -46,19 +45,26 @@
         "types": "../index.d.ts",
         "default": "./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/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

@@ -35,7 +35,21 @@ export declare class OpenAPIToolGenerator {
      */
     validate(): Promise<ValidationResult>;
     /**
-     * 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.
+     */
+    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, 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, 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';