@frontmcp/adapters 0.12.2 → 1.0.0-beta.2

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().
@@ -962,7 +1141,7 @@ Add one of the following to your adapter configuration:
     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))
@@ -1482,6 +1661,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 +1834,8 @@ function removeSecurityFromOperations(spec, operations) {
 }
 export {
   FRONTMCP_EXTENSION_KEY,
+  OpenAPIFetchError,
+  OpenApiSpecPoller,
   OpenapiAdapter,
   forceJwtSecurity,
   removeSecurityFromOperations

package/esm/openapi/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().
@@ -962,7 +1141,7 @@ Add one of the following to your adapter configuration:
     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))
@@ -1482,6 +1661,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 +1834,8 @@ function removeSecurityFromOperations(spec, operations) {
 }
 export {
   FRONTMCP_EXTENSION_KEY,
+  OpenAPIFetchError,
+  OpenApiSpecPoller,
   OpenapiAdapter as default,
   forceJwtSecurity,
   removeSecurityFromOperations

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/adapters",
-  "version": "0.12.2",
+  "version": "1.0.0-beta.2",
   "description": "Adapters for the FrontMCP framework",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -54,8 +54,8 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@frontmcp/utils": "0.12.2",
-    "@frontmcp/sdk": "0.12.2",
+    "@frontmcp/utils": "1.0.0-beta.2",
+    "@frontmcp/sdk": "1.0.0-beta.2",
     "zod": "^4.0.0",
     "openapi-types": "^12.1.3",
     "mcp-from-openapi": "2.1.2",

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,WAAW,CAAA;AACnD,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACtD,cAAc,WAAW,CAAC"}