@frontmcp/adapters 0.12.2 → 1.0.0-beta.10

package/esm/index.mjs

@@ -20,6 +20,7 @@ import { convertJsonSchemaToZod } from "zod-from-json-schema";
 
 // libs/adapters/src/openapi/openapi.utils.ts
 import { validateBaseUrl } from "@frontmcp/utils";
+import { PublicMcpError } from "@frontmcp/sdk";
 function coerceToString(value, paramName, location) {
   if (value === null || value === void 0) {
     return "";
@@ -76,8 +77,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 PublicMcpError(
+            `Invalid header value for '${mapper.key}': contains control characters (possible header injection attack)`,
+            "INVALID_HEADER_VALUE",
+            400
           );
         }
         headers.set(mapper.key, headerValue);
@@ -860,6 +863,174 @@ function getZodSchemaFromJsonSchema(jsonSchema, toolName, logger) {
   }
 }
 
+// libs/adapters/src/openapi/openapi-spec-poller.ts
+import { sha256Hex } from "@frontmcp/utils";
+
+// libs/adapters/src/openapi/openapi.errors.ts
+import { InternalMcpError } from "@frontmcp/sdk";
+var OpenAPIFetchError = class extends 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 = 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) {
@@ -877,10 +1048,18 @@ var OpenapiAdapter = class extends 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().
@@ -956,13 +1135,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))
@@ -1038,6 +1235,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
@@ -1058,8 +1264,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;
@@ -1136,8 +1343,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));
@@ -1284,8 +1492,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;
   }
@@ -1300,8 +1509,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;
   }
@@ -1403,8 +1613,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);
@@ -1425,12 +1636,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);
@@ -1482,6 +1693,66 @@ ${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([
   Adapter({
@@ -1595,6 +1866,8 @@ function removeSecurityFromOperations(spec, operations) {
 }
 export {
   FRONTMCP_EXTENSION_KEY,
+  OpenAPIFetchError,
+  OpenApiSpecPoller,
   OpenapiAdapter,
   forceJwtSecurity,
   removeSecurityFromOperations