mcp-from-openapi 2.1.0 → 2.1.1

package/esm/index.mjs

@@ -0,0 +1,1561 @@
+// libs/mcp-from-openapi/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";
+
+// libs/mcp-from-openapi/src/types.ts
+function isReferenceObject(obj) {
+  return obj && typeof obj === "object" && "$ref" in obj;
+}
+function toJsonSchema(schema) {
+  if (isReferenceObject(schema)) {
+    return { $ref: schema.$ref };
+  }
+  const { exclusiveMaximum, exclusiveMinimum, maximum, minimum, ...rest } = schema;
+  const result = { ...rest };
+  if (typeof exclusiveMaximum === "boolean") {
+    if (exclusiveMaximum && maximum !== void 0) {
+      result["exclusiveMaximum"] = maximum;
+    } else if (maximum !== void 0) {
+      result["maximum"] = maximum;
+    }
+  } else if (exclusiveMaximum !== void 0) {
+    result["exclusiveMaximum"] = exclusiveMaximum;
+    if (maximum !== void 0) {
+      result["maximum"] = maximum;
+    }
+  } else if (maximum !== void 0) {
+    result["maximum"] = maximum;
+  }
+  if (typeof exclusiveMinimum === "boolean") {
+    if (exclusiveMinimum && minimum !== void 0) {
+      result["exclusiveMinimum"] = minimum;
+    } else if (minimum !== void 0) {
+      result["minimum"] = minimum;
+    }
+  } else if (exclusiveMinimum !== void 0) {
+    result["exclusiveMinimum"] = exclusiveMinimum;
+    if (minimum !== void 0) {
+      result["minimum"] = minimum;
+    }
+  } else if (minimum !== void 0) {
+    result["minimum"] = minimum;
+  }
+  if (result["properties"] && typeof result["properties"] === "object") {
+    const props = {};
+    for (const [key, value] of Object.entries(result["properties"])) {
+      props[key] = toJsonSchema(value);
+    }
+    result["properties"] = props;
+  }
+  if (result["items"]) {
+    if (Array.isArray(result["items"])) {
+      result["items"] = result["items"].map(toJsonSchema);
+    } else {
+      result["items"] = toJsonSchema(result["items"]);
+    }
+  }
+  if (result["additionalProperties"] && typeof result["additionalProperties"] === "object") {
+    result["additionalProperties"] = toJsonSchema(result["additionalProperties"]);
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    if (result[key] && Array.isArray(result[key])) {
+      result[key] = result[key].map(toJsonSchema);
+    }
+  }
+  if (result["not"]) {
+    result["not"] = toJsonSchema(result["not"]);
+  }
+  return result;
+}
+
+// libs/mcp-from-openapi/src/parameter-resolver.ts
+var ParameterResolver = class {
+  namingStrategy;
+  constructor(namingStrategy) {
+    this.namingStrategy = namingStrategy ?? {
+      conflictResolver: this.defaultConflictResolver
+    };
+  }
+  /**
+   * Default conflict resolver: prefix with location
+   */
+  defaultConflictResolver(paramName, location, index) {
+    const locationPrefix = {
+      path: "path",
+      query: "query",
+      header: "header",
+      cookie: "cookie",
+      body: "body"
+    }[location];
+    return `${locationPrefix}${paramName.charAt(0).toUpperCase()}${paramName.slice(1)}`;
+  }
+  /**
+   * Resolve all parameters for an operation
+   */
+  resolve(operation, pathParameters, securityRequirements, includeSecurityInInput) {
+    const allParameters = [...pathParameters ?? [], ...operation.parameters ?? []];
+    const requestBody = operation.requestBody;
+    const parametersByName = /* @__PURE__ */ new Map();
+    allParameters.forEach((param) => {
+      const info = {
+        name: param.name,
+        location: param.in,
+        required: param.required ?? param.in === "path",
+        schema: param.schema ?? { type: "string" },
+        description: param.description,
+        style: param.style,
+        explode: param.explode,
+        allowReserved: param.allowReserved,
+        deprecated: param.deprecated
+      };
+      if (!parametersByName.has(param.name)) {
+        parametersByName.set(param.name, []);
+      }
+      parametersByName.get(param.name).push(info);
+    });
+    if (requestBody?.content) {
+      const contentType = this.selectContentType(requestBody.content);
+      const mediaType = requestBody.content[contentType];
+      if (mediaType?.schema) {
+        this.extractBodyParameters(mediaType.schema, parametersByName, requestBody.required ?? false, contentType);
+      }
+    }
+    const properties = {};
+    const required = [];
+    const mapper = [];
+    for (const [originalName, params] of parametersByName.entries()) {
+      if (params.length === 1) {
+        const param = params[0];
+        const inputKey = originalName;
+        properties[inputKey] = this.buildParameterSchema(param);
+        if (param.required) {
+          required.push(inputKey);
+        }
+        mapper.push({
+          inputKey,
+          type: param.location,
+          key: originalName,
+          required: param.required,
+          style: param.style,
+          explode: param.explode,
+          serialization: param.serialization
+        });
+      } else {
+        params.forEach((param, index) => {
+          const inputKey = this.namingStrategy.conflictResolver(originalName, param.location, index);
+          properties[inputKey] = this.buildParameterSchema(param);
+          if (param.required) {
+            required.push(inputKey);
+          }
+          mapper.push({
+            inputKey,
+            type: param.location,
+            key: originalName,
+            required: param.required,
+            style: param.style,
+            explode: param.explode,
+            serialization: param.serialization
+          });
+        });
+      }
+    }
+    if (securityRequirements && securityRequirements.length > 0) {
+      this.processSecurityRequirements(
+        securityRequirements,
+        properties,
+        required,
+        mapper,
+        includeSecurityInInput ?? false
+      );
+    }
+    const inputSchema = {
+      type: "object",
+      properties,
+      ...required.length > 0 && { required },
+      additionalProperties: false
+    };
+    return { inputSchema, mapper };
+  }
+  /**
+   * Extract parameters from request body schema
+   */
+  extractBodyParameters(schema, parametersByName, required, contentType, prefix = "") {
+    if (!schema || typeof schema !== "object") return;
+    const jsonSchema = toJsonSchema(schema);
+    if (jsonSchema.type === "object" && jsonSchema.properties) {
+      const requiredFields = new Set(jsonSchema.required ?? []);
+      for (const [propName, propSchema] of Object.entries(jsonSchema.properties)) {
+        const fullName = prefix ? `${prefix}.${propName}` : propName;
+        const isRequired = required && requiredFields.has(propName);
+        if (typeof propSchema === "object") {
+          const info = {
+            name: fullName,
+            location: "body",
+            required: isRequired,
+            schema: propSchema,
+            description: propSchema.description,
+            serialization: {
+              contentType
+            }
+          };
+          if (!parametersByName.has(fullName)) {
+            parametersByName.set(fullName, []);
+          }
+          parametersByName.get(fullName).push(info);
+        }
+      }
+    } else {
+      const bodyParamName = prefix || "body";
+      const info = {
+        name: bodyParamName,
+        location: "body",
+        required,
+        schema,
+        serialization: {
+          contentType
+        }
+      };
+      if (!parametersByName.has(bodyParamName)) {
+        parametersByName.set(bodyParamName, []);
+      }
+      parametersByName.get(bodyParamName).push(info);
+    }
+  }
+  /**
+   * Build JSON Schema for a parameter
+   */
+  buildParameterSchema(param) {
+    const schema = toJsonSchema(param.schema);
+    if (param.description) {
+      schema.description = param.description;
+    }
+    if (param.deprecated) {
+      schema["deprecated"] = true;
+    }
+    schema["x-parameter-location"] = param.location;
+    if (param.style) {
+      schema["x-parameter-style"] = param.style;
+    }
+    if (param.explode !== void 0) {
+      schema["x-parameter-explode"] = param.explode;
+    }
+    return schema;
+  }
+  /**
+   * Select the most appropriate content type
+   */
+  selectContentType(content) {
+    const preferences = [
+      "application/json",
+      "application/x-www-form-urlencoded",
+      "multipart/form-data",
+      "application/xml",
+      "text/plain"
+    ];
+    for (const pref of preferences) {
+      if (content[pref]) return pref;
+    }
+    const firstKey = Object.keys(content)[0];
+    if (!firstKey) {
+      throw new Error("No content type available in request body");
+    }
+    return firstKey;
+  }
+  /**
+   * Process security requirements and add to mapper/inputSchema
+   */
+  processSecurityRequirements(securityRequirements, properties, required, mapper, includeInInput) {
+    for (const secReq of securityRequirements) {
+      const { scheme, type, name: apiKeyName, in: apiKeyIn, scopes } = secReq;
+      const securityInfo = {
+        scheme,
+        type,
+        scopes
+      };
+      let inputKey;
+      let headerKey;
+      let paramLocation;
+      let description;
+      let schema;
+      if (type === "http") {
+        inputKey = scheme;
+        headerKey = "Authorization";
+        paramLocation = "header";
+        const httpScheme = "httpScheme" in secReq && secReq.httpScheme ? secReq.httpScheme : "bearer";
+        const bearerFormat = "bearerFormat" in secReq ? secReq.bearerFormat : void 0;
+        securityInfo.httpScheme = httpScheme;
+        if (bearerFormat) {
+          securityInfo.bearerFormat = bearerFormat;
+        }
+        description = `${httpScheme.charAt(0).toUpperCase()}${httpScheme.slice(1)} authentication token`;
+        if (bearerFormat) {
+          description += ` (${bearerFormat})`;
+        }
+        schema = {
+          type: "string",
+          description
+        };
+      } else if (type === "apiKey") {
+        inputKey = scheme;
+        headerKey = apiKeyName || "X-API-Key";
+        paramLocation = apiKeyIn || "header";
+        securityInfo.apiKeyName = apiKeyName;
+        securityInfo.apiKeyIn = apiKeyIn;
+        description = `API key for ${scheme}`;
+        schema = {
+          type: "string",
+          description
+        };
+      } else if (type === "oauth2" || type === "openIdConnect") {
+        inputKey = scheme;
+        headerKey = "Authorization";
+        paramLocation = "header";
+        description = `OAuth2 access token${scopes && scopes.length > 0 ? ` (scopes: ${scopes.join(", ")})` : ""}`;
+        schema = {
+          type: "string",
+          description
+        };
+      } else {
+        continue;
+      }
+      mapper.push({
+        inputKey,
+        type: paramLocation,
+        key: headerKey,
+        required: true,
+        security: securityInfo
+      });
+      if (includeInInput) {
+        properties[inputKey] = schema;
+        required.push(inputKey);
+      }
+    }
+  }
+};
+
+// libs/mcp-from-openapi/src/response-builder.ts
+var ResponseBuilder = class {
+  preferredStatusCodes;
+  includeAllResponses;
+  constructor(options = {}) {
+    this.preferredStatusCodes = options.preferredStatusCodes ?? [200, 201, 204, 202, 203, 206];
+    this.includeAllResponses = options.includeAllResponses ?? true;
+  }
+  /**
+   * Build output schema from responses
+   */
+  build(responses) {
+    if (!responses || Object.keys(responses).length === 0) {
+      return void 0;
+    }
+    const schemas = this.extractResponseSchemas(responses);
+    if (schemas.length === 0) {
+      return void 0;
+    }
+    if (schemas.length === 1) {
+      return schemas[0].schema;
+    }
+    if (this.includeAllResponses) {
+      return {
+        oneOf: schemas.map((s) => s.schema),
+        description: "Response can be one of multiple status codes"
+      };
+    } else {
+      const preferred = this.selectPreferredSchema(schemas);
+      return preferred.schema;
+    }
+  }
+  /**
+   * Extract schemas from all responses
+   */
+  extractResponseSchemas(responses) {
+    const schemas = [];
+    for (const [statusCode, response] of Object.entries(responses)) {
+      if (isReferenceObject(response)) continue;
+      if (statusCode === "default") continue;
+      const code = parseInt(statusCode, 10);
+      if (isNaN(code)) continue;
+      const schema = this.extractResponseSchema(response, code);
+      if (schema) {
+        schemas.push(schema);
+      }
+    }
+    if (schemas.length === 0 && responses["default"]) {
+      const defaultResponse = responses["default"];
+      if (!isReferenceObject(defaultResponse)) {
+        const schema = this.extractResponseSchema(defaultResponse, 0);
+        if (schema) {
+          schemas.push(schema);
+        }
+      }
+    }
+    return schemas;
+  }
+  /**
+   * Extract schema from a single response
+   */
+  extractResponseSchema(response, statusCode) {
+    if (!response.content) {
+      return {
+        statusCode,
+        schema: {
+          type: "null",
+          description: response.description,
+          "x-status-code": statusCode
+        }
+      };
+    }
+    const contentType = this.selectContentType(response.content);
+    const mediaType = response.content[contentType];
+    if (!mediaType?.schema) {
+      return null;
+    }
+    const schema = {
+      ...toJsonSchema(mediaType.schema),
+      "x-status-code": statusCode
+    };
+    if (!schema.description && response.description) {
+      schema.description = response.description;
+    }
+    schema["x-content-type"] = contentType;
+    return { statusCode, schema };
+  }
+  /**
+   * Select the most appropriate content type
+   */
+  selectContentType(content) {
+    const preferences = [
+      "application/json",
+      "application/hal+json",
+      "application/problem+json",
+      "application/xml",
+      "text/plain",
+      "text/html"
+    ];
+    for (const pref of preferences) {
+      if (content[pref]) return pref;
+    }
+    return Object.keys(content)[0];
+  }
+  /**
+   * Select the preferred schema based on status code preferences
+   */
+  selectPreferredSchema(schemas) {
+    for (const preferredCode of this.preferredStatusCodes) {
+      const found = schemas.find((s) => s.statusCode === preferredCode);
+      if (found) return found;
+    }
+    const success = schemas.find((s) => s.statusCode >= 200 && s.statusCode < 300);
+    if (success) return success;
+    const redirect = schemas.find((s) => s.statusCode >= 300 && s.statusCode < 400);
+    if (redirect) return redirect;
+    return schemas[0];
+  }
+};
+
+// libs/mcp-from-openapi/src/validator.ts
+var Validator = class {
+  /**
+   * Validate an OpenAPI document
+   */
+  async validate(document) {
+    const errors = [];
+    const warnings = [];
+    if (!document.openapi) {
+      errors.push({
+        message: "Missing required field: openapi",
+        path: "/openapi",
+        code: "MISSING_OPENAPI_VERSION"
+      });
+    } else if (!this.isValidOpenAPIVersion(document.openapi)) {
+      errors.push({
+        message: `Unsupported OpenAPI version: ${document.openapi}. Expected 3.0.x or 3.1.x`,
+        path: "/openapi",
+        code: "INVALID_OPENAPI_VERSION"
+      });
+    }
+    if (!document.info) {
+      errors.push({
+        message: "Missing required field: info",
+        path: "/info",
+        code: "MISSING_INFO"
+      });
+    } else {
+      if (!document.info.title) {
+        errors.push({
+          message: "Missing required field: info.title",
+          path: "/info/title",
+          code: "MISSING_TITLE"
+        });
+      }
+      if (!document.info.version) {
+        errors.push({
+          message: "Missing required field: info.version",
+          path: "/info/version",
+          code: "MISSING_VERSION"
+        });
+      }
+    }
+    if (!document.paths || Object.keys(document.paths).length === 0) {
+      warnings.push({
+        message: "No paths defined in OpenAPI document",
+        path: "/paths",
+        code: "NO_PATHS"
+      });
+    } else {
+      this.validatePaths(document.paths, errors, warnings);
+    }
+    if (!document.servers || document.servers.length === 0) {
+      warnings.push({
+        message: "No servers defined. You may need to provide a baseUrl option.",
+        path: "/servers",
+        code: "NO_SERVERS"
+      });
+    }
+    if (document.security && !document.components?.securitySchemes) {
+      warnings.push({
+        message: "Security requirements defined but no security schemes found",
+        path: "/security",
+        code: "NO_SECURITY_SCHEMES"
+      });
+    }
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : void 0,
+      warnings: warnings.length > 0 ? warnings : void 0
+    };
+  }
+  /**
+   * Check if OpenAPI version is valid
+   */
+  isValidOpenAPIVersion(version) {
+    return /^3\.[01]\.\d+$/.test(version);
+  }
+  /**
+   * Validate paths
+   */
+  validatePaths(paths, errors, warnings) {
+    for (const [path2, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue;
+      if (!path2.startsWith("/")) {
+        errors.push({
+          message: `Path must start with '/': ${path2}`,
+          path: `/paths/${path2}`,
+          code: "INVALID_PATH_FORMAT"
+        });
+      }
+      const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+      let hasOperations = false;
+      for (const method of methods) {
+        const operation = pathItem[method];
+        if (operation) {
+          hasOperations = true;
+          this.validateOperation(operation, path2, method, errors, warnings);
+        }
+      }
+      if (!hasOperations && !pathItem.$ref) {
+        warnings.push({
+          message: `Path has no operations: ${path2}`,
+          path: `/paths/${path2}`,
+          code: "NO_OPERATIONS"
+        });
+      }
+    }
+  }
+  /**
+   * Validate an operation
+   */
+  validateOperation(operation, path2, method, errors, warnings) {
+    const basePath = `/paths/${path2}/${method}`;
+    if (!operation.operationId) {
+      warnings.push({
+        message: `Operation missing operationId: ${method.toUpperCase()} ${path2}`,
+        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}`,
+        path: `${basePath}/responses`,
+        code: "NO_RESPONSES"
+      });
+    }
+    if (operation.parameters) {
+      this.validateParameters(operation.parameters, path2, method, errors, warnings);
+    }
+    const pathParams = path2.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}`,
+          path: `${basePath}/parameters`,
+          code: "MISSING_PATH_PARAMETER"
+        });
+      }
+    }
+  }
+  /**
+   * Validate parameters
+   */
+  validateParameters(parameters, path2, method, errors, warnings) {
+    const basePath = `/paths/${path2}/${method}/parameters`;
+    for (let i = 0; i < parameters.length; i++) {
+      const param = parameters[i];
+      const paramPath = `${basePath}/${i}`;
+      if (!param.name) {
+        errors.push({
+          message: "Parameter missing name",
+          path: `${paramPath}/name`,
+          code: "MISSING_PARAMETER_NAME"
+        });
+      }
+      if (!param.in) {
+        errors.push({
+          message: 'Parameter missing "in" field',
+          path: `${paramPath}/in`,
+          code: "MISSING_PARAMETER_IN"
+        });
+      } else if (!["path", "query", "header", "cookie"].includes(param.in)) {
+        errors.push({
+          message: `Invalid parameter location: ${param.in}`,
+          path: `${paramPath}/in`,
+          code: "INVALID_PARAMETER_IN"
+        });
+      }
+      if (param.in === "path" && !param.required) {
+        errors.push({
+          message: `Path parameter '${param.name}' must be required`,
+          path: `${paramPath}/required`,
+          code: "PATH_PARAMETER_NOT_REQUIRED"
+        });
+      }
+      if (!param.schema && !param.content) {
+        errors.push({
+          message: `Parameter '${param.name}' missing schema or content`,
+          path: `${paramPath}`,
+          code: "MISSING_PARAMETER_SCHEMA"
+        });
+      }
+    }
+  }
+};
+
+// libs/mcp-from-openapi/src/errors.ts
+var OpenAPIToolError = class extends Error {
+  context;
+  constructor(message, context) {
+    super(message);
+    this.name = this.constructor.name;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var LoadError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ParseError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var ValidationError = class extends OpenAPIToolError {
+  errors;
+  constructor(message, context) {
+    super(message, context);
+    this.errors = context?.["errors"];
+  }
+};
+var GenerationError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+var SchemaError = class extends OpenAPIToolError {
+  constructor(message, context) {
+    super(message, context);
+  }
+};
+
+// libs/mcp-from-openapi/src/generator.ts
+var OpenAPIToolGenerator = class _OpenAPIToolGenerator {
+  document;
+  dereferencedDocument;
+  options;
+  /**
+   * Private constructor - use static factory methods to create instances
+   */
+  constructor(document, options = {}) {
+    this.document = document;
+    this.options = {
+      dereference: options.dereference ?? true,
+      baseUrl: options.baseUrl ?? "",
+      headers: options.headers ?? {},
+      timeout: options.timeout ?? 3e4,
+      validate: options.validate ?? true,
+      followRedirects: options.followRedirects ?? true
+    };
+  }
+  /**
+   * Create generator from a URL
+   */
+  static async fromURL(url, options = {}) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeout ?? 3e4);
+      const response = await fetch(url, {
+        headers: options.headers,
+        signal: controller.signal,
+        redirect: options.followRedirects ?? true ? "follow" : "manual"
+      });
+      clearTimeout(timeout);
+      if (!response.ok) {
+        throw new LoadError(`Failed to fetch OpenAPI spec from URL: ${response.status} ${response.statusText}`, {
+          url,
+          status: response.status
+        });
+      }
+      const contentType = response.headers.get("content-type") || "";
+      const text = await response.text();
+      let document;
+      if (contentType.includes("yaml") || contentType.includes("yml") || url.match(/\.ya?ml$/i)) {
+        document = yaml.parse(text);
+      } else {
+        document = JSON.parse(text);
+      }
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      if (error instanceof LoadError) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from URL: ${errorMessage}`, {
+        url,
+        originalError: error
+      });
+    }
+  }
+  /**
+   * Create generator from a file path
+   */
+  static async fromFile(filePath, options = {}) {
+    try {
+      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();
+      let document;
+      if (ext === ".yaml" || ext === ".yml") {
+        document = yaml.parse(content);
+      } else if (ext === ".json") {
+        document = JSON.parse(content);
+      } else {
+        try {
+          document = JSON.parse(content);
+        } catch {
+          document = yaml.parse(content);
+        }
+      }
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new LoadError(`Failed to load OpenAPI spec from file: ${errorMessage}`, {
+        filePath,
+        originalError: error
+      });
+    }
+  }
+  /**
+   * Create generator from a YAML string
+   */
+  static async fromYAML(yamlString, options = {}) {
+    try {
+      const document = yaml.parse(yamlString);
+      return new _OpenAPIToolGenerator(document, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ParseError(`Failed to parse YAML: ${errorMessage}`, {
+        originalError: error
+      });
+    }
+  }
+  /**
+   * Create generator from a JSON object
+   */
+  static async fromJSON(json, options = {}) {
+    const document = JSON.parse(JSON.stringify(json));
+    return new _OpenAPIToolGenerator(document, options);
+  }
+  /**
+   * Get the OpenAPI document
+   */
+  getDocument() {
+    return this.dereferencedDocument ?? this.document;
+  }
+  /**
+   * Validate the OpenAPI document
+   */
+  async validate() {
+    const validator = new Validator();
+    return validator.validate(this.document);
+  }
+  /**
+   * Initialize the generator (dereference if needed)
+   */
+  async initialize() {
+    if (this.options.validate) {
+      const result = await this.validate();
+      if (!result.valid) {
+        throw new ParseError("Invalid OpenAPI document", { errors: result.errors });
+      }
+    }
+    if (this.options.dereference && !this.dereferencedDocument) {
+      try {
+        this.dereferencedDocument = await $RefParser.dereference(
+          JSON.parse(JSON.stringify(this.document))
+        );
+      } 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
+   */
+  async generateTools(options = {}) {
+    await this.initialize();
+    const document = this.getDocument();
+    const tools = [];
+    if (!document.paths) {
+      return tools;
+    }
+    for (const [pathStr, pathItem] of Object.entries(document.paths)) {
+      if (!pathItem || "$ref" in pathItem) continue;
+      const methods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+      for (const method of methods) {
+        const operation = pathItem[method];
+        if (!operation) continue;
+        if (!this.shouldIncludeOperation(operation, pathStr, method, options)) {
+          continue;
+        }
+        try {
+          const tool = await this.generateTool(pathStr, method, options);
+          tools.push(tool);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          console.warn(`Failed to generate tool for ${method.toUpperCase()} ${pathStr}:`, errorMessage);
+        }
+      }
+    }
+    return tools;
+  }
+  /**
+   * Generate a specific tool for a path and method
+   */
+  async generateTool(pathStr, method, options = {}) {
+    await this.initialize();
+    const document = this.getDocument();
+    if (!document.paths) {
+      throw new Error("No paths defined in OpenAPI document");
+    }
+    const pathItem = document.paths[pathStr];
+    const operation = pathItem?.[method.toLowerCase()];
+    if (!operation) {
+      throw new Error(`Operation not found: ${method.toUpperCase()} ${pathStr}`);
+    }
+    const parameterResolver = new ParameterResolver(options.namingStrategy);
+    let pathParameters = void 0;
+    if (pathItem.parameters) {
+      pathParameters = pathItem.parameters.filter(
+        (p) => !isReferenceObject(p)
+      );
+    }
+    let securityRequirements = void 0;
+    const securitySpec = operation.security ?? document.security;
+    if (securitySpec) {
+      securityRequirements = this.extractSecurityRequirements(securitySpec, document);
+    }
+    const { inputSchema, mapper } = parameterResolver.resolve(
+      operation,
+      pathParameters,
+      securityRequirements,
+      options.includeSecurityInInput
+    );
+    const responseBuilder = new ResponseBuilder(options);
+    const outputSchema = responseBuilder.build(operation.responses);
+    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);
+    return {
+      name,
+      description,
+      inputSchema,
+      outputSchema,
+      mapper,
+      metadata
+    };
+  }
+  /**
+   * Check if an operation should be included
+   */
+  shouldIncludeOperation(operation, path2, method, options) {
+    if (operation.deprecated && !options.includeDeprecated) {
+      return false;
+    }
+    if (options.includeOperations && operation.operationId) {
+      if (!options.includeOperations.includes(operation.operationId)) {
+        return false;
+      }
+    }
+    if (options.excludeOperations && operation.operationId) {
+      if (options.excludeOperations.includes(operation.operationId)) {
+        return false;
+      }
+    }
+    if (options.filterFn) {
+      return options.filterFn({
+        ...operation,
+        path: path2,
+        method
+      });
+    }
+    return true;
+  }
+  /**
+   * Generate a tool name
+   */
+  generateToolName(path2, method, operationId, options = {}) {
+    if (options.namingStrategy?.toolNameGenerator) {
+      return options.namingStrategy.toolNameGenerator(path2, method, operationId);
+    }
+    if (operationId) {
+      return operationId;
+    }
+    const sanitized = path2.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) {
+    const metadata = {
+      path: path2,
+      method,
+      operationId: operation.operationId,
+      operationSummary: operation.summary,
+      operationDescription: operation.description,
+      tags: operation.tags,
+      deprecated: operation.deprecated
+    };
+    if (operation.security || document.security) {
+      metadata.security = this.extractSecurityRequirements(
+        operation.security ?? document.security,
+        document
+      );
+    }
+    const servers = operation.servers ?? document.servers;
+    if (servers) {
+      metadata.servers = servers.map((server) => ({
+        url: this.options.baseUrl || server.url,
+        description: server.description,
+        variables: server.variables
+      }));
+    } else if (this.options.baseUrl) {
+      metadata.servers = [{ url: this.options.baseUrl }];
+    }
+    const schemaObj = outputSchema;
+    if (schemaObj && Array.isArray(schemaObj["oneOf"])) {
+      const codes = schemaObj["oneOf"].map((schema) => schema["x-status-code"]).filter((code) => code !== void 0 && code !== null);
+      if (codes.length > 0) {
+        metadata.responseStatusCodes = codes;
+      }
+    } else if (schemaObj && schemaObj["x-status-code"] !== void 0 && schemaObj["x-status-code"] !== null) {
+      metadata.responseStatusCodes = [schemaObj["x-status-code"]];
+    }
+    if (operation.externalDocs) {
+      metadata.externalDocs = operation.externalDocs;
+    }
+    const operationWithExt = operation;
+    if (operationWithExt["x-frontmcp"]) {
+      metadata.frontmcp = operationWithExt["x-frontmcp"];
+    }
+    return metadata;
+  }
+  /**
+   * Extract security requirements
+   */
+  extractSecurityRequirements(security, document) {
+    if (!security || !document.components?.securitySchemes) {
+      return [];
+    }
+    return security.flatMap(
+      (req) => Object.entries(req).map(([scheme, scopes]) => {
+        const securityScheme = document.components.securitySchemes[scheme];
+        if (isReferenceObject(securityScheme)) {
+          return { scheme, type: "http", scopes };
+        }
+        const apiKeyIn = "in" in securityScheme ? securityScheme.in : void 0;
+        const result = {
+          scheme,
+          type: securityScheme.type,
+          scopes,
+          name: "name" in securityScheme ? securityScheme.name : void 0,
+          in: apiKeyIn && (apiKeyIn === "query" || apiKeyIn === "header" || apiKeyIn === "cookie") ? apiKeyIn : void 0
+        };
+        if (securityScheme.type === "http") {
+          result.httpScheme = "scheme" in securityScheme ? securityScheme.scheme : void 0;
+          result.bearerFormat = "bearerFormat" in securityScheme ? securityScheme.bearerFormat : void 0;
+        }
+        result.description = "description" in securityScheme ? securityScheme.description : void 0;
+        return result;
+      })
+    );
+  }
+};
+
+// libs/mcp-from-openapi/src/schema-builder.ts
+var SchemaBuilder = class {
+  /**
+   * Merge multiple schemas into one
+   */
+  static merge(schemas) {
+    if (schemas.length === 0) {
+      return { type: "object" };
+    }
+    if (schemas.length === 1) {
+      return schemas[0];
+    }
+    const merged = {
+      type: "object",
+      properties: {},
+      required: []
+    };
+    const allRequired = /* @__PURE__ */ new Set();
+    for (const schema of schemas) {
+      if (schema.properties) {
+        merged.properties = {
+          ...merged.properties,
+          ...schema.properties
+        };
+      }
+      if (schema.required) {
+        schema.required.forEach((field) => allRequired.add(field));
+      }
+    }
+    if (allRequired.size > 0) {
+      merged.required = Array.from(allRequired);
+    }
+    return merged;
+  }
+  /**
+   * Create a union schema (oneOf)
+   */
+  static union(schemas) {
+    if (schemas.length === 0) {
+      return {};
+    }
+    if (schemas.length === 1) {
+      return schemas[0];
+    }
+    return {
+      oneOf: schemas
+    };
+  }
+  /**
+   * Deep clone a schema
+   */
+  static clone(schema) {
+    return JSON.parse(JSON.stringify(schema));
+  }
+  /**
+   * Remove $ref from schema (assumes already dereferenced)
+   */
+  static removeRefs(schema) {
+    const cloned = this.clone(schema);
+    this.removeRefsRecursive(cloned);
+    return cloned;
+  }
+  static removeRefsRecursive(obj) {
+    if (!obj || typeof obj !== "object") return;
+    if (obj.$ref) {
+      delete obj.$ref;
+    }
+    for (const key in obj) {
+      if (key in obj) {
+        const value = obj[key];
+        if (value && typeof value === "object") {
+          this.removeRefsRecursive(value);
+        }
+      }
+    }
+  }
+  /**
+   * Add description to schema
+   */
+  static withDescription(schema, description) {
+    return {
+      ...schema,
+      description
+    };
+  }
+  /**
+   * Add example to schema
+   */
+  static withExample(schema, example) {
+    const existingExamples = Array.isArray(schema.examples) ? schema.examples : [];
+    return {
+      ...schema,
+      examples: [...existingExamples, example]
+    };
+  }
+  /**
+   * Add default value to schema
+   */
+  static withDefault(schema, defaultValue) {
+    return {
+      ...schema,
+      default: defaultValue
+    };
+  }
+  /**
+   * Add format to schema
+   */
+  static withFormat(schema, format) {
+    return {
+      ...schema,
+      format
+    };
+  }
+  /**
+   * Add pattern to schema
+   */
+  static withPattern(schema, pattern) {
+    return {
+      ...schema,
+      pattern
+    };
+  }
+  /**
+   * Add enum to schema
+   */
+  static withEnum(schema, values) {
+    return {
+      ...schema,
+      enum: values
+    };
+  }
+  /**
+   * Add minimum/maximum constraints
+   */
+  static withRange(schema, min, max, options = {}) {
+    const result = { ...schema };
+    if (min !== void 0) {
+      if (options.exclusive) {
+        result.exclusiveMinimum = min;
+      } else {
+        result.minimum = min;
+      }
+    }
+    if (max !== void 0) {
+      if (options.exclusive) {
+        result.exclusiveMaximum = max;
+      } else {
+        result.maximum = max;
+      }
+    }
+    return result;
+  }
+  /**
+   * Add minLength/maxLength constraints
+   */
+  static withLength(schema, minLength, maxLength) {
+    const result = { ...schema };
+    if (minLength !== void 0) {
+      result.minLength = minLength;
+    }
+    if (maxLength !== void 0) {
+      result.maxLength = maxLength;
+    }
+    return result;
+  }
+  /**
+   * Create object schema
+   */
+  static object(properties, required) {
+    return {
+      type: "object",
+      properties,
+      ...required && required.length > 0 && { required },
+      additionalProperties: false
+    };
+  }
+  /**
+   * Create array schema
+   */
+  static array(items, constraints) {
+    return {
+      type: "array",
+      items,
+      ...constraints
+    };
+  }
+  /**
+   * Create string schema
+   */
+  static string(constraints) {
+    return {
+      type: "string",
+      ...constraints
+    };
+  }
+  /**
+   * Create number schema
+   */
+  static number(constraints) {
+    return {
+      type: "number",
+      ...constraints
+    };
+  }
+  /**
+   * Create integer schema
+   */
+  static integer(constraints) {
+    return {
+      type: "integer",
+      ...constraints
+    };
+  }
+  /**
+   * Create boolean schema
+   */
+  static boolean() {
+    return {
+      type: "boolean"
+    };
+  }
+  /**
+   * Create null schema
+   */
+  static null() {
+    return {
+      type: "null"
+    };
+  }
+  /**
+   * Flatten nested oneOf/anyOf/allOf schemas
+   */
+  static flatten(schema, maxDepth = 10) {
+    if (maxDepth <= 0) return schema;
+    const cloned = this.clone(schema);
+    if (cloned.oneOf) {
+      const flattened = cloned.oneOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.oneOf ? sub.oneOf : [sub];
+      });
+      cloned.oneOf = flattened;
+    }
+    if (cloned.anyOf) {
+      const flattened = cloned.anyOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.anyOf ? sub.anyOf : [sub];
+      });
+      cloned.anyOf = flattened;
+    }
+    if (cloned.allOf) {
+      const flattened = cloned.allOf.flatMap((s) => {
+        const sub = this.flatten(s, maxDepth - 1);
+        return sub.allOf ? sub.allOf : [sub];
+      });
+      cloned.allOf = flattened;
+    }
+    return cloned;
+  }
+  /**
+   * Simplify schema by removing unnecessary fields
+   */
+  static simplify(schema) {
+    const cloned = this.clone(schema);
+    if (Array.isArray(cloned.required) && cloned.required.length === 0) {
+      delete cloned.required;
+    }
+    if (cloned.properties && Object.keys(cloned.properties).length === 0) {
+      delete cloned.properties;
+    }
+    if (Array.isArray(cloned.examples) && cloned.examples.length === 0) {
+      delete cloned.examples;
+    }
+    if (cloned.title && cloned.description && cloned.title === cloned.description) {
+      delete cloned.title;
+    }
+    return cloned;
+  }
+};
+
+// libs/mcp-from-openapi/src/security-resolver.ts
+var SecurityResolver = class {
+  /**
+   * Resolve security parameters from mapper entries
+   *
+   * @param mappers - Parameter mappers from the tool definition
+   * @param context - Security context with auth values or custom resolver
+   * @returns Resolved headers, query params, and cookies with auth applied
+   */
+  async resolve(mappers, context) {
+    const resolved = {
+      headers: {},
+      query: {},
+      cookies: {}
+    };
+    if (context.clientCertificate) {
+      resolved.clientCertificate = context.clientCertificate;
+    }
+    let requiresSignature = false;
+    let signatureScheme;
+    for (const mapper of mappers) {
+      if (!mapper.security) {
+        continue;
+      }
+      if (this.isSignatureBasedAuth(mapper.security)) {
+        requiresSignature = true;
+        signatureScheme = mapper.security.scheme;
+        continue;
+      }
+      const authValue = await this.resolveAuthValue(mapper.security, context);
+      if (!authValue) {
+        continue;
+      }
+      const headerName = mapper.key;
+      if (mapper.type === "header") {
+        resolved.headers[headerName] = authValue;
+      } else if (mapper.type === "query") {
+        resolved.query[headerName] = authValue;
+      } else if (mapper.type === "cookie") {
+        resolved.cookies[headerName] = authValue;
+      }
+    }
+    if (context.cookies) {
+      resolved.cookies = { ...resolved.cookies, ...context.cookies };
+    }
+    if (requiresSignature) {
+      resolved.requiresSignature = true;
+      resolved.signatureInfo = {
+        scheme: signatureScheme || "unknown"
+      };
+    }
+    return resolved;
+  }
+  /**
+   * Check if security scheme requires request signing
+   */
+  isSignatureBasedAuth(security) {
+    const signatureSchemes = ["aws4", "hmac", "signature", "hawk", "custom-signature"];
+    return signatureSchemes.some(
+      (scheme) => security.scheme.toLowerCase().includes(scheme)
+    );
+  }
+  /**
+   * Resolve the actual auth value based on security type
+   */
+  async resolveAuthValue(security, context) {
+    if (context.customResolver) {
+      const customValue = await context.customResolver(security);
+      if (customValue !== void 0) {
+        return customValue;
+      }
+    }
+    if (security.type === "http") {
+      return this.resolveHttpAuth(security, context);
+    } else if (security.type === "apiKey") {
+      return this.resolveApiKey(security, context);
+    } else if (security.type === "oauth2" || security.type === "openIdConnect") {
+      return this.resolveOAuth2(security, context);
+    }
+    return void 0;
+  }
+  /**
+   * Resolve HTTP authentication (bearer, basic, digest, etc.)
+   */
+  resolveHttpAuth(security, context) {
+    const scheme = security.httpScheme?.toLowerCase() || "bearer";
+    switch (scheme) {
+      case "bearer":
+        return this.resolveBearerAuth(context);
+      case "basic":
+        return this.resolveBasicAuth(context);
+      case "digest":
+        return this.resolveDigestAuth(context);
+      case "hoba":
+      case "mutual":
+      case "negotiate":
+      case "vapid":
+      case "scram":
+        return this.resolveCustomHttpScheme(scheme, security, context);
+      default:
+        return void 0;
+    }
+  }
+  /**
+   * Resolve Bearer token authentication
+   */
+  resolveBearerAuth(context) {
+    const token = context.jwt;
+    if (!token) return void 0;
+    return `Bearer ${token}`;
+  }
+  /**
+   * Resolve Basic authentication
+   */
+  resolveBasicAuth(context) {
+    const credentials = context.basic;
+    if (!credentials) return void 0;
+    return `Basic ${credentials}`;
+  }
+  /**
+   * Resolve Digest authentication
+   */
+  resolveDigestAuth(context) {
+    const digest = context.digest;
+    if (!digest) return void 0;
+    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}"` : ""
+    ].filter(Boolean);
+    return `Digest ${parts.join(", ")}`;
+  }
+  /**
+   * Resolve custom HTTP authentication schemes
+   */
+  resolveCustomHttpScheme(scheme, security, context) {
+    const headerKey = security.apiKeyName || `X-${scheme.toUpperCase()}`;
+    if (context.customHeaders?.[headerKey]) {
+      return context.customHeaders[headerKey];
+    }
+    return void 0;
+  }
+  /**
+   * Resolve API key authentication
+   */
+  resolveApiKey(security, context) {
+    if (context.apiKeys && security.apiKeyName) {
+      const key = context.apiKeys[security.apiKeyName];
+      if (key) return key;
+    }
+    if (context.customHeaders && security.apiKeyName) {
+      const header = context.customHeaders[security.apiKeyName];
+      if (header) return header;
+    }
+    return context.apiKey;
+  }
+  /**
+   * Resolve OAuth2/OpenID Connect authentication
+   */
+  resolveOAuth2(security, context) {
+    const token = context.oauth2Token;
+    if (!token) return void 0;
+    return `Bearer ${token}`;
+  }
+  /**
+   * Check if any security requirements are missing from context
+   *
+   * @param mappers - Parameter mappers from the tool definition
+   * @param context - Security context with auth values
+   * @returns Array of missing security scheme names
+   */
+  async checkMissingSecurity(mappers, context) {
+    const missing = [];
+    for (const mapper of mappers) {
+      if (!mapper.security) continue;
+      const authValue = await this.resolveAuthValue(mapper.security, context);
+      if (!authValue) {
+        missing.push(mapper.security.scheme);
+      }
+    }
+    return missing;
+  }
+  /**
+   * Sign a request for signature-based authentication
+   *
+   * Use this when resolved.requiresSignature is true.
+   * This method will call the signatureGenerator from context to sign the request.
+   *
+   * @param mappers - Parameter mappers from the tool definition
+   * @param signatureData - Request data to sign
+   * @param context - Security context with signature generator
+   * @returns Headers with signature added
+   *
+   * @example
+   * ```typescript
+   * const resolved = resolver.resolve(tool.mapper, context);
+   * if (resolved.requiresSignature) {
+   *   const signedHeaders = await resolver.signRequest(
+   *     tool.mapper,
+   *     { method: 'GET', url: 'https://api.example.com/data', headers: resolved.headers },
+   *     context
+   *   );
+   *   // Use signedHeaders in request
+   * }
+   * ```
+   */
+  async signRequest(mappers, signatureData, context) {
+    const headers = { ...signatureData.headers };
+    if (!context.signatureGenerator) {
+      throw new Error("Signature-based auth required but no signatureGenerator provided");
+    }
+    for (const mapper of mappers) {
+      if (!mapper.security || !this.isSignatureBasedAuth(mapper.security)) {
+        continue;
+      }
+      const signature = await context.signatureGenerator(signatureData, mapper.security);
+      if (mapper.type === "header") {
+        headers[mapper.key] = signature;
+      }
+    }
+    return headers;
+  }
+};
+function createSecurityContext(auth) {
+  return {
+    ...auth,
+    jwt: auth.jwt,
+    basic: auth.basic,
+    apiKey: auth.apiKey,
+    oauth2Token: auth.oauth2Token,
+    customResolver: auth.customResolver
+  };
+}
+export {
+  GenerationError,
+  LoadError,
+  OpenAPIToolError,
+  OpenAPIToolGenerator,
+  ParameterResolver,
+  ParseError,
+  ResponseBuilder,
+  SchemaBuilder,
+  SchemaError,
+  SecurityResolver,
+  ValidationError,
+  Validator,
+  createSecurityContext,
+  isReferenceObject,
+  toJsonSchema
+};