@frontmcp/adapters 0.12.2 → 1.0.0-beta.10

package/index.js

@@ -29,6 +29,8 @@ var __decorateClass = (decorators, target, key, kind) => {
 var index_exports = {};
 __export(index_exports, {
   FRONTMCP_EXTENSION_KEY: () => FRONTMCP_EXTENSION_KEY,
+  OpenAPIFetchError: () => OpenAPIFetchError,
+  OpenApiSpecPoller: () => OpenApiSpecPoller,
   OpenapiAdapter: () => OpenapiAdapter,
   forceJwtSecurity: () => forceJwtSecurity,
   removeSecurityFromOperations: () => removeSecurityFromOperations
@@ -36,16 +38,17 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // libs/adapters/src/openapi/openapi.adapter.ts
-var import_sdk2 = require("@frontmcp/sdk");
+var import_sdk4 = require("@frontmcp/sdk");
 var import_mcp_from_openapi2 = require("mcp-from-openapi");
 
 // libs/adapters/src/openapi/openapi.tool.ts
 var import_zod2 = require("zod");
-var import_sdk = require("@frontmcp/sdk");
+var import_sdk2 = require("@frontmcp/sdk");
 var import_zod_from_json_schema = require("zod-from-json-schema");
 
 // libs/adapters/src/openapi/openapi.utils.ts
 var import_utils = require("@frontmcp/utils");
+var import_sdk = require("@frontmcp/sdk");
 function coerceToString(value, paramName, location) {
   if (value === null || value === void 0) {
     return "";
@@ -102,8 +105,10 @@ function buildRequest(tool2, input, security, baseUrl) {
       case "header": {
         const headerValue = coerceToString(value, mapper.key, "header");
         if (/[\r\n\x00\f\v]/.test(headerValue)) {
-          throw new Error(
-            `Invalid header value for '${mapper.key}': contains control characters (possible header injection attack)`
+          throw new import_sdk.PublicMcpError(
+            `Invalid header value for '${mapper.key}': contains control characters (possible header injection attack)`,
+            "INVALID_HEADER_VALUE",
+            400
           );
         }
         headers.set(mapper.key, headerValue);
@@ -683,7 +688,7 @@ function createOpenApiTool(openapiTool, options, logger) {
   if (toolTransform.ui) {
     toolMetadata["ui"] = toolTransform.ui;
   }
-  return (0, import_sdk.tool)(toolMetadata)(async (input, toolCtx) => {
+  return (0, import_sdk2.tool)(toolMetadata)(async (input, toolCtx) => {
     const ctx = toolCtx.context;
     const transformContext = {
       ctx,
@@ -886,6 +891,174 @@ function getZodSchemaFromJsonSchema(jsonSchema, toolName, logger) {
   }
 }
 
+// libs/adapters/src/openapi/openapi-spec-poller.ts
+var import_utils2 = require("@frontmcp/utils");
+
+// libs/adapters/src/openapi/openapi.errors.ts
+var import_sdk3 = require("@frontmcp/sdk");
+var OpenAPIFetchError = class extends import_sdk3.InternalMcpError {
+  constructor(url, status, statusText) {
+    super(`OpenAPI spec fetch failed from "${url}": ${status} ${statusText}`, "OPENAPI_FETCH_FAILED");
+  }
+};
+
+// libs/adapters/src/openapi/openapi-spec-poller.ts
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  initialDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  backoffMultiplier: 2
+};
+var OpenApiSpecPoller = class {
+  url;
+  intervalMs;
+  fetchTimeoutMs;
+  changeDetection;
+  retry;
+  unhealthyThreshold;
+  headers;
+  callbacks;
+  intervalTimer = null;
+  lastHash = null;
+  lastEtag = null;
+  lastModified = null;
+  consecutiveFailures = 0;
+  isPolling = false;
+  wasUnhealthy = false;
+  health = "unknown";
+  constructor(url, options = {}, callbacks = {}) {
+    this.url = url;
+    this.intervalMs = options.intervalMs ?? 6e4;
+    this.fetchTimeoutMs = options.fetchTimeoutMs ?? 1e4;
+    this.changeDetection = options.changeDetection ?? "auto";
+    this.retry = { ...DEFAULT_RETRY, ...options.retry };
+    this.unhealthyThreshold = options.unhealthyThreshold ?? 3;
+    this.headers = options.headers ?? {};
+    this.callbacks = callbacks;
+  }
+  /**
+   * Start polling for changes.
+   */
+  start() {
+    if (this.intervalTimer) return;
+    this.poll().catch(() => {
+    });
+    this.intervalTimer = setInterval(() => {
+      this.poll().catch(() => {
+      });
+    }, this.intervalMs);
+  }
+  /**
+   * Stop polling.
+   */
+  stop() {
+    if (this.intervalTimer) {
+      clearInterval(this.intervalTimer);
+      this.intervalTimer = null;
+    }
+  }
+  /**
+   * Get current stats.
+   */
+  getStats() {
+    return {
+      hash: this.lastHash,
+      consecutiveFailures: this.consecutiveFailures,
+      health: this.health,
+      isRunning: this.intervalTimer !== null
+    };
+  }
+  /**
+   * Perform a single poll cycle.
+   */
+  async poll() {
+    if (this.isPolling) return;
+    this.isPolling = true;
+    try {
+      await this.fetchWithRetry();
+    } finally {
+      this.isPolling = false;
+    }
+  }
+  async fetchWithRetry() {
+    const { maxRetries, initialDelayMs, maxDelayMs, backoffMultiplier } = this.retry;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await this.doFetch();
+        if (this.consecutiveFailures > 0) {
+          this.consecutiveFailures = 0;
+          if (this.wasUnhealthy) {
+            this.wasUnhealthy = false;
+            this.health = "healthy";
+            this.callbacks.onRecovered?.();
+          }
+        }
+        this.health = "healthy";
+        return;
+      } catch (error) {
+        if (attempt === maxRetries) {
+          this.consecutiveFailures++;
+          this.callbacks.onError?.(error instanceof Error ? error : new Error(String(error)));
+          if (this.consecutiveFailures >= this.unhealthyThreshold && !this.wasUnhealthy) {
+            this.wasUnhealthy = true;
+            this.health = "unhealthy";
+            this.callbacks.onUnhealthy?.(this.consecutiveFailures);
+          }
+          return;
+        }
+        const delay = Math.min(initialDelayMs * Math.pow(backoffMultiplier, attempt), maxDelayMs);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  async doFetch() {
+    const headers = { ...this.headers };
+    if (this.changeDetection !== "content-hash") {
+      if (this.lastEtag) {
+        headers["If-None-Match"] = this.lastEtag;
+      }
+      if (this.lastModified) {
+        headers["If-Modified-Since"] = this.lastModified;
+      }
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.fetchTimeoutMs);
+    try {
+      const response = await fetch(this.url, {
+        headers,
+        signal: controller.signal
+      });
+      if (response.status === 304) {
+        this.callbacks.onUnchanged?.();
+        return;
+      }
+      if (!response.ok) {
+        throw new OpenAPIFetchError(this.url, response.status, response.statusText);
+      }
+      const etag = response.headers.get("etag");
+      const lastModified = response.headers.get("last-modified");
+      if (etag) this.lastEtag = etag;
+      if (lastModified) this.lastModified = lastModified;
+      const body = await response.text();
+      const hash = (0, import_utils2.sha256Hex)(body);
+      if (this.lastHash && this.lastHash === hash) {
+        this.callbacks.onUnchanged?.();
+        return;
+      }
+      this.lastHash = hash;
+      this.callbacks.onChanged?.(body, hash);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * Dispose the poller and release resources.
+   */
+  dispose() {
+    this.stop();
+  }
+};
+
 // libs/adapters/src/openapi/openapi.adapter.ts
 var RESERVED_KEYS2 = ["__proto__", "constructor", "prototype"];
 function createConsoleLogger(prefix) {
@@ -899,14 +1072,22 @@ function createConsoleLogger(prefix) {
     child: (childPrefix) => createConsoleLogger(`${prefix}:${childPrefix}`)
   };
 }
-var OpenapiAdapter = class extends import_sdk2.DynamicAdapter {
+var OpenapiAdapter = class extends import_sdk4.DynamicAdapter {
   generator;
   logger;
   options;
+  poller = null;
+  updateCallbacks = /* @__PURE__ */ new Set();
+  rebuildChain = Promise.resolve();
   constructor(options) {
     super();
     this.options = options;
     this.logger = options.logger ?? createConsoleLogger(`openapi:${options.name}`);
+    if (options.polling?.enabled && !("url" in options)) {
+      throw new Error(
+        `[OpenAPI Adapter: ${options.name}] Polling requires URL-based options (use 'url' instead of 'spec').`
+      );
+    }
   }
   /**
    * Receive the SDK logger. Called by the SDK before fetch().
@@ -982,13 +1163,31 @@ Add one of the following to your adapter configuration:
     if (this.options.toolTransforms) {
       transformedTools = transformedTools.map((tool2) => this.applyToolTransforms(tool2));
     }
+    const nameMap = /* @__PURE__ */ new Map();
+    for (const tool2 of transformedTools) {
+      const meta = tool2.metadata;
+      const source = `${meta["method"]?.toUpperCase() ?? "?"} ${meta["path"] ?? "?"}`;
+      const existing = nameMap.get(tool2.name);
+      if (existing) {
+        existing.push(source);
+      } else {
+        nameMap.set(tool2.name, [source]);
+      }
+    }
+    for (const [name, sources] of nameMap) {
+      if (sources.length > 1) {
+        throw new Error(
+          `Tool name collision: "${name}" produced by ${sources.length} operations: ${sources.join(", ")}. Rename conflicting operations in your OpenAPI spec or use toolTransforms.perTool to assign unique names.`
+        );
+      }
+    }
     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;
+    const dataTransforms = this.options.dataTransforms;
     if (this.options.outputSchema || dataTransforms) {
       transformedTools = await Promise.all(
         transformedTools.map((tool2) => this.applyOutputSchemaOptions(tool2, dataTransforms))
@@ -1064,6 +1263,15 @@ ${opDescription}`;
       description
     };
   }
+  /**
+   * Look up a value in a perTool map by tool name, using own-property check.
+   * @private
+   */
+  resolvePerTool(perTool, tool2) {
+    if (!perTool) return void 0;
+    if (Object.prototype.hasOwnProperty.call(perTool, tool2.name)) return perTool[tool2.name];
+    return void 0;
+  }
   /**
    * Collect tool transforms for a specific tool
    * @private
@@ -1084,8 +1292,9 @@ ${opDescription}`;
         result.examples = [...opts.global.examples];
       }
     }
-    if (opts.perTool?.[tool2.name]) {
-      const perTool = opts.perTool[tool2.name];
+    const perToolMatch = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolMatch) {
+      const perTool = perToolMatch;
       if (perTool.name) result.name = perTool.name;
       if (perTool.description) result.description = perTool.description;
       if (perTool.hideFromDiscovery !== void 0) result.hideFromDiscovery = perTool.hideFromDiscovery;
@@ -1162,8 +1371,9 @@ ${opDescription}`;
     if (opts.global) {
       transforms.push(...opts.global);
     }
-    if (opts.perTool?.[tool2.name]) {
-      transforms.push(...opts.perTool[tool2.name]);
+    const perToolInputTransforms = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolInputTransforms) {
+      transforms.push(...perToolInputTransforms);
     }
     if (opts.generator) {
       transforms.push(...opts.generator(tool2));
@@ -1310,8 +1520,9 @@ ${opDescription}`;
       const generated = opts.generator(tool2);
       if (generated) return generated;
     }
-    if (opts.perTool?.[tool2.name]) {
-      return opts.perTool[tool2.name];
+    const perToolInputSchema = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolInputSchema) {
+      return perToolInputSchema;
     }
     return opts.global;
   }
@@ -1326,8 +1537,9 @@ ${opDescription}`;
       const generated = opts.generator(tool2);
       if (generated) return generated;
     }
-    if (opts.perTool?.[tool2.name]) {
-      return opts.perTool[tool2.name];
+    const perToolOutputSchema = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolOutputSchema) {
+      return perToolOutputSchema;
     }
     return opts.global;
   }
@@ -1429,8 +1641,9 @@ ${this.formatSchemaAsSummary(schema)}`;
     if (opts.global) {
       result = { ...opts.global };
     }
-    if (opts.perTool?.[tool2.name]) {
-      result = { ...result, ...opts.perTool[tool2.name] };
+    const perToolPre = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolPre) {
+      result = { ...result, ...perToolPre };
     }
     if (opts.generator) {
       const generated = opts.generator(tool2);
@@ -1451,12 +1664,12 @@ ${this.formatSchemaAsSummary(schema)}`;
     if (opts.global) {
       result = { ...opts.global };
     }
-    if (opts.perTool?.[tool2.name]) {
-      const perTool = opts.perTool[tool2.name];
+    const perToolPost = this.resolvePerTool(opts.perTool, tool2);
+    if (perToolPost) {
       result = result ? {
-        transform: perTool.transform,
-        filter: perTool.filter ?? result.filter
-      } : perTool;
+        transform: perToolPost.transform,
+        filter: perToolPost.filter ?? result.filter
+      } : perToolPost;
     }
     if (opts.generator) {
       const generated = opts.generator(tool2);
@@ -1508,9 +1721,69 @@ ${this.formatSchemaAsSummary(schema)}`;
     }
     return schema.type || "any";
   }
+  // ============================================================================
+  // Polling Lifecycle
+  // ============================================================================
+  /**
+   * Register a callback for when the adapter's tools are updated via polling.
+   * Returns an unsubscribe function.
+   */
+  onUpdate(callback) {
+    this.updateCallbacks.add(callback);
+    return () => {
+      this.updateCallbacks.delete(callback);
+    };
+  }
+  /**
+   * Start polling for spec changes.
+   * Creates the poller and on spec change, re-runs fetch() and calls the update callback.
+   * Rebuilds are serialized via a Promise chain to prevent races.
+   */
+  startPolling() {
+    if (this.poller) return;
+    const polling = this.options.polling;
+    if (!polling?.enabled || !("url" in this.options)) return;
+    this.poller = new OpenApiSpecPoller(this.options.url, polling, {
+      onChanged: (_spec, _hash) => {
+        this.rebuildChain = this.rebuildChain.then(async () => {
+          const previousGenerator = this.generator;
+          try {
+            this.generator = void 0;
+            const response = await this.fetch();
+            this.updateCallbacks.forEach((cb) => cb(response));
+            this.logger.info("OpenAPI spec updated, tools rebuilt");
+          } catch (error) {
+            this.generator = previousGenerator;
+            this.logger.error(`Failed to rebuild tools after spec change: ${error.message}`);
+          }
+        });
+      },
+      onError: (error) => {
+        this.logger.warn(`OpenAPI spec poll error: ${error.message}`);
+      },
+      onUnhealthy: (failures) => {
+        this.logger.error(`OpenAPI spec poller unhealthy after ${failures} consecutive failures`);
+      },
+      onRecovered: () => {
+        this.logger.info("OpenAPI spec poller recovered");
+      }
+    });
+    this.poller.start();
+    this.logger.info(`Started polling OpenAPI spec at ${this.options.polling?.intervalMs ?? 6e4}ms intervals`);
+  }
+  /**
+   * Stop polling for spec changes.
+   */
+  stopPolling() {
+    if (this.poller) {
+      this.poller.dispose();
+      this.poller = null;
+      this.logger.info("Stopped polling OpenAPI spec");
+    }
+  }
 };
 OpenapiAdapter = __decorateClass([
-  (0, import_sdk2.Adapter)({
+  (0, import_sdk4.Adapter)({
     name: "openapi",
     description: "OpenAPI adapter for FrontMCP - Automatically generates MCP tools from OpenAPI specifications"
   })
@@ -1622,6 +1895,8 @@ function removeSecurityFromOperations(spec, operations) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FRONTMCP_EXTENSION_KEY,
+  OpenAPIFetchError,
+  OpenApiSpecPoller,
   OpenapiAdapter,
   forceJwtSecurity,
   removeSecurityFromOperations

package/openapi/index.d.ts

@@ -1,5 +1,8 @@
 export { default } from './openapi.adapter';
 export * from './openapi.types';
 export * from './openapi.spec-utils';
-export { OpenApiResponse } from './openapi.utils';
+export type { OpenApiResponse } from './openapi.utils';
+export { OpenApiSpecPoller } from './openapi-spec-poller';
+export * from './openapi-spec-poller.types';
+export { OpenAPIFetchError } from './openapi.errors';
 //# sourceMappingURL=index.d.ts.map

package/openapi/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,cAAc,6BAA6B,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}