@frontmcp/adapters 0.7.1 → 0.8.0

package/esm/index.mjs

@@ -125,9 +125,6 @@ function applyAdditionalHeaders(headers, additionalHeaders) {
 var DEFAULT_MAX_RESPONSE_SIZE = 10 * 1024 * 1024;
 async function parseResponse(response, options) {
   const maxSize = options?.maxResponseSize ?? DEFAULT_MAX_RESPONSE_SIZE;
-  if (!response.ok) {
-    throw new Error(`API request failed: ${response.status}`);
-  }
   const contentLength = response.headers.get("content-length");
   if (contentLength) {
     const length = parseInt(contentLength, 10);
@@ -141,14 +138,29 @@ async function parseResponse(response, options) {
     throw new Error(`Response size (${byteSize} bytes) exceeds maximum allowed (${maxSize} bytes)`);
   }
   const contentType = response.headers.get("content-type");
+  let data;
   if (contentType?.toLowerCase().includes("application/json")) {
     try {
-      return { data: JSON.parse(text) };
+      data = JSON.parse(text);
     } catch {
-      return { data: text };
+      data = text;
     }
+  } else {
+    data = text;
+  }
+  if (!response.ok) {
+    return {
+      status: response.status,
+      ok: false,
+      data,
+      error: typeof data === "object" && data !== null && "message" in data ? String(data.message) : typeof data === "string" ? data : `HTTP ${response.status} error`
+    };
   }
-  return { data: text };
+  return {
+    status: response.status,
+    ok: true,
+    data
+  };
 }
 
 // libs/adapters/src/openapi/openapi.security.ts
@@ -574,15 +586,32 @@ function createOpenApiTool(openapiTool, options, logger) {
   const metadata = openapiTool.metadata;
   const inputTransforms = metadata.adapter?.inputTransforms ?? [];
   const toolTransform = metadata.adapter?.toolTransform ?? {};
+  const postToolTransform = metadata.adapter?.postToolTransform;
   const frontmcpValidation = validateFrontMcpExtension(metadata.frontmcp, openapiTool.name, logger);
   const frontmcpExt = frontmcpValidation.data;
   const schemaResult = getZodSchemaFromJsonSchema(openapiTool.inputSchema, openapiTool.name, logger);
+  let wrappedOutputSchema;
+  if (openapiTool.outputSchema !== void 0) {
+    const baseOutputSchema = openapiTool.outputSchema ?? { type: "string" };
+    wrappedOutputSchema = {
+      type: "object",
+      properties: {
+        status: { type: "number", description: "HTTP status code" },
+        ok: { type: "boolean", description: "Whether the response was successful" },
+        data: baseOutputSchema,
+        error: { type: "string", description: "Error message for non-ok responses" }
+      },
+      required: ["status", "ok"]
+    };
+  }
   const toolMetadata = {
     id: openapiTool.name,
     name: openapiTool.name,
     description: openapiTool.description,
     inputSchema: schemaResult.schema.shape || {},
-    rawInputSchema: openapiTool.inputSchema
+    rawInputSchema: openapiTool.inputSchema,
+    // Add output schema for tool/list to expose (only if not moved to description)
+    ...wrappedOutputSchema && { rawOutputSchema: wrappedOutputSchema }
   };
   if (schemaResult.conversionFailed) {
     toolMetadata["_schemaConversionFailed"] = true;
@@ -695,11 +724,71 @@ function createOpenApiTool(openapiTool, options, logger) {
         body: serializedBody,
         signal: controller.signal
       });
-      return await parseResponse(response, { maxResponseSize: options.maxResponseSize });
+      const apiResponse = await parseResponse(response, { maxResponseSize: options.maxResponseSize });
+      let transformedData = apiResponse.data;
+      if (postToolTransform) {
+        const transformCtx = {
+          ctx,
+          tool: openapiTool,
+          status: apiResponse.status,
+          ok: apiResponse.ok,
+          adapterOptions: options
+        };
+        const shouldTransform = postToolTransform.filter ? postToolTransform.filter(transformCtx) : true;
+        if (shouldTransform) {
+          try {
+            transformedData = await postToolTransform.transform(apiResponse.data, transformCtx);
+          } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            const errorStack = err instanceof Error ? err.stack : void 0;
+            logger.error(`[${openapiTool.name}] Post-tool output transform failed`, {
+              error: errorMessage,
+              stack: errorStack,
+              status: apiResponse.status,
+              ok: apiResponse.ok
+            });
+          }
+        }
+      }
+      if (!apiResponse.ok) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                status: apiResponse.status,
+                error: apiResponse.error,
+                data: transformedData
+              })
+            }
+          ],
+          isError: true,
+          _meta: {
+            status: apiResponse.status,
+            errorCode: "OPENAPI_ERROR"
+          }
+        };
+      }
+      return {
+        status: apiResponse.status,
+        ok: true,
+        data: transformedData
+      };
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
-        throw new Error(`Request timeout after ${requestTimeout}ms for tool '${openapiTool.name}'`);
+        const timeoutError = new Error(`Request timeout after ${requestTimeout}ms for tool '${openapiTool.name}'`);
+        logger.error(`[${openapiTool.name}] API request timeout`, {
+          timeout: requestTimeout,
+          url,
+          method: openapiTool.metadata.method.toUpperCase()
+        });
+        throw timeoutError;
       }
+      logger.error(`[${openapiTool.name}] API request failed`, {
+        url,
+        method: openapiTool.metadata.method.toUpperCase(),
+        error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : err
+      });
       throw err;
     } finally {
       clearTimeout(timeoutId);
@@ -870,6 +959,15 @@ Add one of the following to your adapter configuration:
     if (this.options.inputTransforms) {
       transformedTools = transformedTools.map((tool2) => this.applyInputTransforms(tool2));
     }
+    if (this.options.schemaTransforms) {
+      transformedTools = transformedTools.map((tool2) => this.applySchemaTransforms(tool2));
+    }
+    const dataTransforms = this.options.dataTransforms || this.options.outputTransforms;
+    if (this.options.outputSchema || dataTransforms) {
+      transformedTools = await Promise.all(
+        transformedTools.map((tool2) => this.applyOutputSchemaOptions(tool2, dataTransforms))
+      );
+    }
     const tools = transformedTools.map((openapiTool) => createOpenApiTool(openapiTool, this.options, this.logger));
     return { tools };
   }
@@ -1139,6 +1237,251 @@ ${opDescription}`;
       }
     };
   }
+  /**
+   * Apply schema transforms to an OpenAPI tool.
+   * Modifies input and output schema definitions.
+   * @private
+   */
+  applySchemaTransforms(tool2) {
+    const opts = this.options.schemaTransforms;
+    if (!opts) return tool2;
+    const ctx = {
+      tool: tool2,
+      adapterOptions: this.options
+    };
+    let newInputSchema = tool2.inputSchema;
+    let newOutputSchema = tool2.outputSchema;
+    if (opts.input) {
+      const inputTransform = this.collectInputSchemaTransform(tool2);
+      if (inputTransform) {
+        newInputSchema = inputTransform(newInputSchema, ctx);
+      }
+    }
+    if (opts.output) {
+      const outputTransform = this.collectOutputSchemaTransform(tool2);
+      if (outputTransform) {
+        newOutputSchema = outputTransform(newOutputSchema, ctx);
+      }
+    }
+    if (newInputSchema === tool2.inputSchema && newOutputSchema === tool2.outputSchema) {
+      return tool2;
+    }
+    this.logger.debug(`Applied schema transforms to '${tool2.name}'`);
+    return {
+      ...tool2,
+      inputSchema: newInputSchema,
+      outputSchema: newOutputSchema
+    };
+  }
+  /**
+   * Collect input schema transform for a specific tool.
+   * @private
+   */
+  collectInputSchemaTransform(tool2) {
+    const opts = this.options.schemaTransforms?.input;
+    if (!opts) return void 0;
+    if (opts.generator) {
+      const generated = opts.generator(tool2);
+      if (generated) return generated;
+    }
+    if (opts.perTool?.[tool2.name]) {
+      return opts.perTool[tool2.name];
+    }
+    return opts.global;
+  }
+  /**
+   * Collect output schema transform for a specific tool.
+   * @private
+   */
+  collectOutputSchemaTransform(tool2) {
+    const opts = this.options.schemaTransforms?.output;
+    if (!opts) return void 0;
+    if (opts.generator) {
+      const generated = opts.generator(tool2);
+      if (generated) return generated;
+    }
+    if (opts.perTool?.[tool2.name]) {
+      return opts.perTool[tool2.name];
+    }
+    return opts.global;
+  }
+  /**
+   * Apply output schema options to an OpenAPI tool.
+   * Handles output schema mode and async description formatting.
+   * @private
+   */
+  async applyOutputSchemaOptions(tool2, dataTransforms) {
+    const outputSchemaOpts = this.options.outputSchema;
+    let newDescription = tool2.description;
+    let newOutputSchema = tool2.outputSchema;
+    const mode = outputSchemaOpts?.mode ?? "definition";
+    if (newOutputSchema && (mode === "description" || mode === "both")) {
+      const descriptionFormat = outputSchemaOpts?.descriptionFormat ?? "summary";
+      const formatter = outputSchemaOpts?.descriptionFormatter;
+      const formatterCtx = {
+        tool: tool2,
+        adapterOptions: this.options,
+        originalDescription: tool2.description
+      };
+      let schemaText;
+      if (formatter) {
+        schemaText = await Promise.resolve(formatter(newOutputSchema, formatterCtx));
+      } else {
+        schemaText = this.formatSchemaForDescription(newOutputSchema, descriptionFormat);
+      }
+      newDescription = tool2.description + schemaText;
+    }
+    if (mode === "description") {
+      newOutputSchema = void 0;
+    }
+    const preTransform = this.collectPreToolTransformsFromDataTransforms(tool2, dataTransforms);
+    if (preTransform) {
+      const ctx = {
+        tool: tool2,
+        adapterOptions: this.options
+      };
+      if (preTransform.transformSchema) {
+        newOutputSchema = preTransform.transformSchema(newOutputSchema, ctx);
+      }
+      if (preTransform.transformDescription) {
+        newDescription = preTransform.transformDescription(newDescription, newOutputSchema, ctx);
+      }
+    }
+    const postTransform = this.collectPostToolTransformsFromDataTransforms(tool2, dataTransforms);
+    if (newDescription === tool2.description && newOutputSchema === tool2.outputSchema && !postTransform) {
+      return tool2;
+    }
+    this.logger.debug(`Applied output schema options to '${tool2.name}' (mode: ${mode})`);
+    const metadataRecord = tool2.metadata;
+    const existingAdapter = metadataRecord["adapter"];
+    return {
+      ...tool2,
+      description: newDescription,
+      outputSchema: newOutputSchema,
+      metadata: {
+        ...tool2.metadata,
+        adapter: {
+          ...existingAdapter || {},
+          ...postTransform && { postToolTransform: postTransform }
+        }
+      }
+    };
+  }
+  /**
+   * Format schema for description based on mode.
+   * @private
+   */
+  formatSchemaForDescription(schema, mode) {
+    switch (mode) {
+      case "jsonSchema":
+        return `
+
+## Output Schema
+\`\`\`json
+${JSON.stringify(schema, null, 2)}
+\`\`\``;
+      case "summary":
+        return `
+
+## Returns
+${this.formatSchemaAsSummary(schema)}`;
+      default:
+        return `
+
+## Returns
+${this.formatSchemaAsSummary(schema)}`;
+    }
+  }
+  /**
+   * Collect pre-tool transforms from dataTransforms options.
+   * @private
+   */
+  collectPreToolTransformsFromDataTransforms(tool2, dataTransforms) {
+    const opts = dataTransforms?.preToolTransforms;
+    if (!opts) return void 0;
+    let result;
+    if (opts.global) {
+      result = { ...opts.global };
+    }
+    if (opts.perTool?.[tool2.name]) {
+      result = { ...result, ...opts.perTool[tool2.name] };
+    }
+    if (opts.generator) {
+      const generated = opts.generator(tool2);
+      if (generated) {
+        result = { ...result, ...generated };
+      }
+    }
+    return result;
+  }
+  /**
+   * Collect post-tool transforms from dataTransforms options.
+   * @private
+   */
+  collectPostToolTransformsFromDataTransforms(tool2, dataTransforms) {
+    const opts = dataTransforms?.postToolTransforms;
+    if (!opts) return void 0;
+    let result;
+    if (opts.global) {
+      result = { ...opts.global };
+    }
+    if (opts.perTool?.[tool2.name]) {
+      const perTool = opts.perTool[tool2.name];
+      result = result ? {
+        transform: perTool.transform,
+        filter: perTool.filter ?? result.filter
+      } : perTool;
+    }
+    if (opts.generator) {
+      const generated = opts.generator(tool2);
+      if (generated) {
+        result = result ? {
+          transform: generated.transform,
+          filter: generated.filter ?? result.filter
+        } : generated;
+      }
+    }
+    return result;
+  }
+  /**
+   * Format JSON Schema as human-readable summary.
+   * @private
+   */
+  formatSchemaAsSummary(schema) {
+    const lines = [];
+    if (schema.type === "object" && schema.properties) {
+      const required = new Set(schema.required || []);
+      for (const [name, propSchema] of Object.entries(schema.properties)) {
+        const isRequired = required.has(name);
+        const typeStr = this.getSchemaTypeString(propSchema);
+        const desc = propSchema.description ? ` - ${propSchema.description}` : "";
+        const reqStr = isRequired ? " (required)" : " (optional)";
+        lines.push(`- **${name}**: ${typeStr}${reqStr}${desc}`);
+      }
+    } else if (schema.type === "array" && schema.items) {
+      const itemType = this.getSchemaTypeString(schema.items);
+      lines.push(`Array of ${itemType}`);
+    } else {
+      lines.push(this.getSchemaTypeString(schema));
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Get human-readable type string from JSON Schema.
+   * @private
+   */
+  getSchemaTypeString(schema) {
+    if (schema.type === "array") {
+      return schema.items ? `${this.getSchemaTypeString(schema.items)}[]` : "array";
+    }
+    if (schema.type === "object") {
+      return schema.title || "object";
+    }
+    if (Array.isArray(schema.type)) {
+      return schema.type.join(" | ");
+    }
+    return schema.type || "any";
+  }
 };
 OpenapiAdapter = __decorateClass([
   Adapter({
@@ -1149,7 +1492,110 @@ OpenapiAdapter = __decorateClass([
 
 // libs/adapters/src/openapi/openapi.types.ts
 var FRONTMCP_EXTENSION_KEY = "x-frontmcp";
+
+// libs/adapters/src/openapi/openapi.spec-utils.ts
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+function forceJwtSecurity(spec, options = {}) {
+  const result = deepClone(spec);
+  const {
+    schemeName = "BearerAuth",
+    schemeType = "bearer",
+    apiKeyIn = "header",
+    apiKeyName = "X-API-Key",
+    operations,
+    description
+  } = options;
+  if (!result.components) {
+    result.components = {};
+  }
+  if (!result.components.securitySchemes) {
+    result.components.securitySchemes = {};
+  }
+  let securityScheme;
+  switch (schemeType) {
+    case "bearer":
+      securityScheme = {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
+        description: description ?? "JWT Bearer token authentication"
+      };
+      break;
+    case "apiKey":
+      securityScheme = {
+        type: "apiKey",
+        in: apiKeyIn,
+        name: apiKeyName,
+        description: description ?? `API Key authentication via ${apiKeyIn}`
+      };
+      break;
+    case "basic":
+      securityScheme = {
+        type: "http",
+        scheme: "basic",
+        description: description ?? "HTTP Basic authentication"
+      };
+      break;
+    default:
+      throw new Error(`Unsupported scheme type: ${schemeType}`);
+  }
+  result.components.securitySchemes[schemeName] = securityScheme;
+  const securityRequirement = {
+    [schemeName]: []
+  };
+  if (!result.paths) {
+    return result;
+  }
+  const operationSet = operations ? new Set(operations) : null;
+  for (const [, pathItem] of Object.entries(result.paths)) {
+    if (!pathItem) continue;
+    const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      if (operationSet) {
+        if (!operation.operationId || !operationSet.has(operation.operationId)) {
+          continue;
+        }
+      }
+      if (!operation.security) {
+        operation.security = [];
+      }
+      const hasSecurityRequirement = operation.security.some((req) => Object.keys(req).includes(schemeName));
+      if (!hasSecurityRequirement) {
+        operation.security.push(securityRequirement);
+      }
+    }
+  }
+  return result;
+}
+function removeSecurityFromOperations(spec, operations) {
+  const result = deepClone(spec);
+  if (!result.paths) {
+    return result;
+  }
+  const operationSet = operations ? new Set(operations) : null;
+  for (const [, pathItem] of Object.entries(result.paths)) {
+    if (!pathItem) continue;
+    const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      if (operationSet) {
+        if (!operation.operationId || !operationSet.has(operation.operationId)) {
+          continue;
+        }
+      }
+      operation.security = [];
+    }
+  }
+  return result;
+}
 export {
   FRONTMCP_EXTENSION_KEY,
-  OpenapiAdapter
+  OpenapiAdapter,
+  forceJwtSecurity,
+  removeSecurityFromOperations
 };