@frontmcp/plugins 0.6.0 → 0.6.2

package/{src/cache → cache}/cache.types.d.ts

@@ -34,11 +34,34 @@ export interface RedisCachePluginOptions extends BaseCachePluginOptions {
 export type MemoryCachePluginOptions = BaseCachePluginOptions & {
     type: 'memory';
 };
+/**
+ * Use global store configuration from @FrontMcp decorator.
+ * Requires `redis` to be configured in the main FrontMcp options.
+ * Supports both Redis and Vercel KV global configurations.
+ *
+ * @example
+ * ```typescript
+ * // In main.ts - configure global store
+ * @FrontMcp({
+ *   redis: { host: 'localhost', port: 6379 },
+ *   apps: [MyApp]
+ * })
+ *
+ * // In app - use global store
+ * @App({
+ *   plugins: [CachePlugin.init({ type: 'global-store' })]
+ * })
+ * class MyApp {}
+ * ```
+ */
+export interface GlobalStoreCachePluginOptions extends BaseCachePluginOptions {
+    type: 'global-store';
+}
 export type RedisCacheOptions = RedisClientCachePluginOptions | RedisCachePluginOptions;
-export type CachePluginOptions = MemoryCachePluginOptions | RedisCacheOptions;
+export type CachePluginOptions = MemoryCachePluginOptions | RedisCacheOptions | GlobalStoreCachePluginOptions;
 export interface CacheStoreInterface {
-    setValue(key: string, value: any, ttlSeconds?: number): Promise<void>;
-    getValue<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    setValue(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    getValue<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
     close(): Promise<void>;

package/cache/index.js

@@ -0,0 +1,412 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// libs/plugins/src/cache/index.ts
+var cache_exports = {};
+__export(cache_exports, {
+  default: () => CachePlugin
+});
+module.exports = __toCommonJS(cache_exports);
+
+// libs/plugins/src/cache/cache.plugin.ts
+var import_sdk4 = require("@frontmcp/sdk");
+
+// libs/plugins/src/cache/providers/cache-redis.provider.ts
+var import_ioredis = __toESM(require("ioredis"));
+var import_sdk = require("@frontmcp/sdk");
+var CacheRedisProvider = class {
+  client;
+  constructor(options) {
+    if (options.type !== "redis" && options.type !== "redis-client") {
+      throw new Error("Invalid cache provider type");
+    }
+    if (options.type === "redis-client") {
+      this.client = options.client;
+      return;
+    }
+    this.client = new import_ioredis.default({
+      lazyConnect: false,
+      maxRetriesPerRequest: 3,
+      ...options.config
+    });
+    this.client.on("connect", () => console.log("[Redis] Connected"));
+    this.client.on("error", (err) => console.error("[Redis] Error:", err));
+  }
+  /** Set a value (auto-stringifies objects) */
+  async setValue(key, value, ttlSeconds) {
+    const strValue = typeof value === "string" ? value : JSON.stringify(value);
+    if (ttlSeconds && ttlSeconds > 0) {
+      await this.client.set(key, strValue, "EX", ttlSeconds);
+    } else {
+      await this.client.set(key, strValue);
+    }
+  }
+  /** Get a value and automatically parse JSON if possible */
+  async getValue(key, defaultValue) {
+    const raw = await this.client.get(key);
+    if (raw === null) return defaultValue;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  /** Delete a key */
+  async delete(key) {
+    await this.client.del(key);
+  }
+  /** Check if a key exists */
+  async exists(key) {
+    return await this.client.exists(key) === 1;
+  }
+  /** Gracefully close the Redis connection */
+  async close() {
+    await this.client.quit();
+  }
+};
+CacheRedisProvider = __decorateClass([
+  (0, import_sdk.Provider)({
+    name: "provider:cache:redis",
+    description: "Redis-based cache provider",
+    scope: import_sdk.ProviderScope.GLOBAL
+  })
+], CacheRedisProvider);
+
+// libs/plugins/src/cache/providers/cache-memory.provider.ts
+var import_sdk2 = require("@frontmcp/sdk");
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
+var CacheMemoryProvider = class {
+  memory = /* @__PURE__ */ new Map();
+  sweeper;
+  constructor(sweepIntervalTTL = 60) {
+    this.sweeper = setInterval(() => this.sweep(), sweepIntervalTTL * 1e3);
+    this.sweeper.unref?.();
+  }
+  /** Set a value (auto-stringifies objects) */
+  async setValue(key, value, ttlSeconds) {
+    const strValue = typeof value === "string" ? value : JSON.stringify(value);
+    const existing = this.memory.get(key);
+    if (existing?.timeout) clearTimeout(existing.timeout);
+    const entry = { value: strValue };
+    if (ttlSeconds && ttlSeconds > 0) {
+      const ttlMs = ttlSeconds * 1e3;
+      entry.expiresAt = Date.now() + ttlMs;
+      if (ttlMs <= MAX_TIMEOUT_MS) {
+        entry.timeout = setTimeout(() => {
+          const e = this.memory.get(key);
+          if (e && e.expiresAt && e.expiresAt <= Date.now()) {
+            this.memory.delete(key);
+          }
+        }, ttlMs);
+        entry.timeout.unref?.();
+      }
+    }
+    this.memory.set(key, entry);
+  }
+  /** Get a value and automatically parse JSON if possible */
+  async getValue(key, defaultValue) {
+    const entry = this.memory.get(key);
+    if (!entry) return defaultValue;
+    if (this.isExpired(entry)) {
+      await this.delete(key);
+      return defaultValue;
+    }
+    const raw = entry.value;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  /** Delete a key */
+  async delete(key) {
+    const entry = this.memory.get(key);
+    if (entry?.timeout) clearTimeout(entry.timeout);
+    this.memory.delete(key);
+  }
+  /** Check if a key exists (and not expired) */
+  async exists(key) {
+    const entry = this.memory.get(key);
+    if (!entry) return false;
+    if (this.isExpired(entry)) {
+      await this.delete(key);
+      return false;
+    }
+    return true;
+  }
+  /** Gracefully close the provider */
+  async close() {
+    if (this.sweeper) clearInterval(this.sweeper);
+    for (const [, entry] of this.memory) {
+      if (entry.timeout) clearTimeout(entry.timeout);
+    }
+    this.memory.clear();
+  }
+  // ---- internals ----
+  isExpired(entry) {
+    return entry.expiresAt !== void 0 && entry.expiresAt <= Date.now();
+  }
+  /** Periodically remove expired keys to keep memory tidy */
+  sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this.memory) {
+      if (entry.expiresAt !== void 0 && entry.expiresAt <= now) {
+        if (entry.timeout) clearTimeout(entry.timeout);
+        this.memory.delete(key);
+      }
+    }
+  }
+};
+CacheMemoryProvider = __decorateClass([
+  (0, import_sdk2.Provider)({
+    name: "provider:cache:memory",
+    description: "Memory-based cache provider",
+    scope: import_sdk2.ProviderScope.GLOBAL
+  })
+], CacheMemoryProvider);
+
+// libs/plugins/src/cache/providers/cache-vercel-kv.provider.ts
+var import_sdk3 = require("@frontmcp/sdk");
+var CacheVercelKvProvider = class {
+  kv;
+  keyPrefix;
+  defaultTTL;
+  constructor(options = {}) {
+    const vercelKv = require("@vercel/kv");
+    const hasUrl = options.url !== void 0;
+    const hasToken = options.token !== void 0;
+    if (hasUrl !== hasToken) {
+      throw new Error(
+        `CacheVercelKvProvider: Both 'url' and 'token' must be provided together, or neither. Received: url=${hasUrl ? "provided" : "missing"}, token=${hasToken ? "provided" : "missing"}`
+      );
+    }
+    if (options.url && options.token) {
+      this.kv = vercelKv.createClient({
+        url: options.url,
+        token: options.token
+      });
+    } else {
+      this.kv = vercelKv.kv;
+    }
+    this.keyPrefix = options.keyPrefix ?? "cache:";
+    this.defaultTTL = options.defaultTTL ?? 60 * 60 * 24;
+  }
+  prefixKey(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  /** Set a value (auto-stringifies objects) */
+  async setValue(key, value, ttlSeconds) {
+    const strValue = typeof value === "string" ? value : JSON.stringify(value);
+    const ttl = ttlSeconds ?? this.defaultTTL;
+    if (ttl > 0) {
+      await this.kv.set(this.prefixKey(key), strValue, { ex: ttl });
+    } else {
+      await this.kv.set(this.prefixKey(key), strValue);
+    }
+  }
+  /** Get a value and automatically parse JSON if possible */
+  async getValue(key, defaultValue) {
+    const raw = await this.kv.get(this.prefixKey(key));
+    if (raw === null || raw === void 0) return defaultValue;
+    if (typeof raw === "string") {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    }
+    return raw;
+  }
+  /** Delete a key */
+  async delete(key) {
+    await this.kv.del(this.prefixKey(key));
+  }
+  /** Check if a key exists */
+  async exists(key) {
+    return await this.kv.exists(this.prefixKey(key)) === 1;
+  }
+  /** Gracefully close the provider (no-op for Vercel KV - stateless REST API) */
+  async close() {
+  }
+};
+CacheVercelKvProvider = __decorateClass([
+  (0, import_sdk3.Provider)({
+    name: "provider:cache:vercel-kv",
+    description: "Vercel KV-based cache provider",
+    scope: import_sdk3.ProviderScope.GLOBAL
+  })
+], CacheVercelKvProvider);
+
+// libs/plugins/src/cache/cache.symbol.ts
+var CacheStoreToken = /* @__PURE__ */ Symbol("plugin:cache:store");
+
+// libs/plugins/src/cache/cache.plugin.ts
+var CachePlugin = class extends import_sdk4.DynamicPlugin {
+  options;
+  constructor(options = CachePlugin.defaultOptions) {
+    super();
+    this.options = {
+      defaultTTL: 60 * 60 * 24,
+      ...options
+    };
+  }
+  async willReadCache(flowCtx) {
+    const { tool, toolContext } = flowCtx.state;
+    if (!tool || !toolContext) return;
+    const { cache } = toolContext.metadata;
+    if (!cache || typeof toolContext.input === "undefined") {
+      return;
+    }
+    const cacheStore = this.get(CacheStoreToken);
+    const hash = hashObject({ tool: tool.fullName, input: toolContext.input });
+    const cached = await cacheStore.getValue(hash);
+    if (cached !== void 0 && cached !== null) {
+      if (cache === true || cache.ttl && cache.slideWindow) {
+        const ttl = cache === true ? this.options.defaultTTL : cache.ttl ?? this.options.defaultTTL;
+        await cacheStore.setValue(hash, cached, ttl);
+      }
+      if (!tool.safeParseOutput(cached).success) {
+        await cacheStore.delete(hash);
+        return;
+      }
+      flowCtx.state.rawOutput = cached;
+      toolContext.respond(cached);
+    }
+  }
+  async willWriteCache(flowCtx) {
+    const { tool, toolContext } = flowCtx.state;
+    if (!tool || !toolContext) return;
+    const { cache } = toolContext.metadata;
+    if (!cache || typeof toolContext.input === "undefined") {
+      return;
+    }
+    const cacheStore = this.get(CacheStoreToken);
+    const ttl = cache === true ? this.options.defaultTTL : cache.ttl ?? this.options.defaultTTL;
+    const hash = hashObject({ tool: tool.fullName, input: toolContext.input });
+    await cacheStore.setValue(hash, toolContext.output, ttl);
+  }
+};
+__publicField(CachePlugin, "dynamicProviders", (options) => {
+  const providers = [];
+  switch (options.type) {
+    case "global-store":
+      providers.push({
+        name: "cache:global-store",
+        provide: CacheStoreToken,
+        inject: () => [import_sdk4.FrontMcpConfig],
+        useFactory: (config) => {
+          const storeConfig = (0, import_sdk4.getGlobalStoreConfig)("CachePlugin", config);
+          const globalOptions = options;
+          if ((0, import_sdk4.isVercelKvProvider)(storeConfig)) {
+            return new CacheVercelKvProvider({
+              url: storeConfig.url,
+              token: storeConfig.token,
+              keyPrefix: storeConfig.keyPrefix,
+              defaultTTL: globalOptions.defaultTTL
+            });
+          }
+          return new CacheRedisProvider({
+            type: "redis",
+            config: {
+              host: storeConfig.host ?? "localhost",
+              port: storeConfig.port ?? 6379,
+              password: storeConfig.password,
+              db: storeConfig.db
+            },
+            defaultTTL: globalOptions.defaultTTL
+          });
+        }
+      });
+      break;
+    case "redis":
+    case "redis-client":
+      providers.push({
+        name: "cache:redis",
+        provide: CacheStoreToken,
+        useValue: new CacheRedisProvider(options)
+      });
+      break;
+    case "memory":
+      providers.push({
+        name: "cache:memory",
+        provide: CacheStoreToken,
+        useValue: new CacheMemoryProvider(options.defaultTTL)
+      });
+      break;
+  }
+  return providers;
+});
+__publicField(CachePlugin, "defaultOptions", {
+  type: "memory"
+});
+__decorateClass([
+  import_sdk4.ToolHook.Will("execute", { priority: 1e3 })
+], CachePlugin.prototype, "willReadCache", 1);
+__decorateClass([
+  import_sdk4.ToolHook.Did("execute", { priority: 1e3 })
+], CachePlugin.prototype, "willWriteCache", 1);
+CachePlugin = __decorateClass([
+  (0, import_sdk4.Plugin)({
+    name: "cache",
+    description: "Cache plugin for caching tool results",
+    providers: [
+      /* add providers that always loaded with the plugin or default providers */
+      {
+        // this is a default provider for cache, will be overridden if dynamicProviders based on config
+        name: "cache:memory",
+        provide: CacheStoreToken,
+        useValue: new CacheMemoryProvider(60 * 60 * 24)
+      }
+    ]
+  })
+], CachePlugin);
+function hashObject(obj) {
+  const keys = Object.keys(obj).sort();
+  return keys.reduce((acc, key) => {
+    acc += key + ":";
+    const val = obj[key];
+    if (typeof val === "object" && val !== null) {
+      acc += hashObject(val);
+    } else {
+      acc += String(val);
+    }
+    acc += ";";
+    return acc;
+  }, "");
+}

package/{src/cache → cache}/providers/cache-memory.provider.d.ts

@@ -3,10 +3,10 @@ export default class CacheMemoryProvider implements CacheStoreInterface {
     private readonly memory;
     private sweeper?;
     constructor(sweepIntervalTTL?: number);
-    /** Set any value (auto-stringifies objects) */
-    setValue(key: string, value: any, ttlSeconds?: number): Promise<void>;
+    /** Set a value (auto-stringifies objects) */
+    setValue(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
     /** Get a value and automatically parse JSON if possible */
-    getValue<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    getValue<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
     /** Delete a key */
     delete(key: string): Promise<void>;
     /** Check if a key exists (and not expired) */

package/{src/cache → cache}/providers/cache-redis.provider.d.ts

@@ -2,10 +2,10 @@ import { CacheStoreInterface, RedisCacheOptions } from '../cache.types';
 export default class CacheRedisProvider implements CacheStoreInterface {
     private readonly client;
     constructor(options: RedisCacheOptions);
-    /** Set any value (auto-stringifies objects) */
-    setValue(key: string, value: any, ttlSeconds?: number): Promise<void>;
+    /** Set a value (auto-stringifies objects) */
+    setValue(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
     /** Get a value and automatically parse JSON if possible */
-    getValue<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    getValue<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
     /** Delete a key */
     delete(key: string): Promise<void>;
     /** Check if a key exists */

package/cache/providers/cache-vercel-kv.provider.d.ts

@@ -0,0 +1,24 @@
+import { CacheStoreInterface } from '../cache.types';
+export interface CacheVercelKvProviderOptions {
+    url?: string;
+    token?: string;
+    keyPrefix?: string;
+    defaultTTL?: number;
+}
+export default class CacheVercelKvProvider implements CacheStoreInterface {
+    private kv;
+    private readonly keyPrefix;
+    private readonly defaultTTL;
+    constructor(options?: CacheVercelKvProviderOptions);
+    private prefixKey;
+    /** Set a value (auto-stringifies objects) */
+    setValue(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Get a value and automatically parse JSON if possible */
+    getValue<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
+    /** Delete a key */
+    delete(key: string): Promise<void>;
+    /** Check if a key exists */
+    exists(key: string): Promise<boolean>;
+    /** Gracefully close the provider (no-op for Vercel KV - stateless REST API) */
+    close(): Promise<void>;
+}