import { DynamicPlugin, FrontMcpConfig, FrontMcpContextStorage, getGlobalStoreConfig, isAnonymousSubject, isVercelKvProvider, Plugin, resolvePrincipal, storeProvider, ToolHook, type FlowCtxOf, type FrontMcpConfigType, type PluginStoreInBrowser, type PluginStoreServer, type ProviderType, } from '@frontmcp/sdk'; import { sha256Hex } from '@frontmcp/utils'; import { CachePluginConfigurationError } from './cache.errors'; import { CacheStoreToken } from './cache.symbol'; import { type CachePluginOptions, type GlobalStoreCachePluginOptions } from './cache.types'; import CacheMemoryProvider from './providers/cache-memory.provider'; import CacheRedisProvider from './providers/cache-redis.provider'; import CacheVercelKvProvider from './providers/cache-vercel-kv.provider'; /** * Default bypass header for cache. * Uses x-frontmcp-* prefix to match the header extraction pattern in FrontMcpContextStorage. */ const DEFAULT_BYPASS_HEADER = 'x-frontmcp-disable-cache'; /** The only request headers the request context keeps, so the only ones a bypass header can be. */ const BYPASS_HEADER_PREFIX = 'x-frontmcp-'; /** * Refuse a `bypassHeader` the plugin can never see (#678). * * The header is read from the request context, which keeps a request's `x-frontmcp-*` headers and * no others. Any other name (`x-no-cache`, as the docs once showed) started a server whose bypass * header was silently ignored. */ function assertReadableBypassHeader(bypassHeader: string | undefined): void { if (bypassHeader === undefined) return; const name = bypassHeader.toLowerCase(); if (name.startsWith(BYPASS_HEADER_PREFIX) && name.length > BYPASS_HEADER_PREFIX.length) return; throw new CachePluginConfigurationError( `CachePlugin bypassHeader "${bypassHeader}" is never seen by the plugin: only request headers that start ` + `with "${BYPASS_HEADER_PREFIX}" reach it. Rename it, e.g. "${BYPASS_HEADER_PREFIX}no-cache".`, ); } const CACHE_TYPES: readonly string[] = ['memory', 'redis', 'redis-client', 'global-store']; /** Refuse a `type` the plugin has no store for: it started a server that cached in memory (#1178). */ function assertKnownCacheType(type: unknown): void { if (type === undefined || CACHE_TYPES.includes(type as string)) return; throw new CachePluginConfigurationError( `CachePlugin type ${JSON.stringify(type)} is not supported. Supported types: ${CACHE_TYPES.map((name) => `"${name}"`).join(', ')}.`, ); } /** * Check if a tool name matches any of the provided patterns. * Supports exact names and glob patterns with wildcards (*). */ function matchesToolPattern(toolName: string, patterns: string[]): boolean { if (!patterns || patterns.length === 0) return false; return patterns.some((pattern) => { if (pattern.includes('*')) { // Escape special regex characters except * const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&'); // Convert * to regex .* const regex = new RegExp('^' + escaped.replace(/\*/g, '.*') + '$'); return regex.test(toolName); } return pattern === toolName; }); } @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. // A factory, so each server gets its own store: a value built here is one store for every // server in the process, created when this module loads. name: 'cache:memory', provide: CacheStoreToken, inject: () => [] as const, useFactory: () => new CacheMemoryProvider(60 * 60 * 24), }, ], }) export default class CachePlugin extends DynamicPlugin { /** A cache on Redis, which a browser refuses at startup (#1033): Vercel KV, over HTTPS, is not one. */ static override browserStores = (options: CachePluginOptions, server: PluginStoreServer): PluginStoreInBrowser[] => { const onRedis = options.type === 'redis' || options.type === 'redis-client' || (options.type === 'global-store' && server.redis !== undefined && !isVercelKvProvider(server.redis)); return [ { plugin: 'CachePlugin', option: onRedis ? `type: '${options.type}'` : undefined, memory: "type: 'memory'" }, ]; }; static override dynamicProviders = (options: CachePluginOptions) => { const providers: ProviderType[] = []; switch (options.type) { case 'global-store': // Use inject/useFactory to access FrontMcpConfig at runtime providers.push( storeProvider({ name: 'cache:global-store', provide: CacheStoreToken, inject: () => [FrontMcpConfig] as const, useFactory: (config: FrontMcpConfigType) => { const storeConfig = getGlobalStoreConfig('CachePlugin', config); const globalOptions = options as GlobalStoreCachePluginOptions; if (isVercelKvProvider(storeConfig)) { return new CacheVercelKvProvider({ url: storeConfig.url, token: storeConfig.token, keyPrefix: storeConfig.keyPrefix, defaultTTL: globalOptions.defaultTTL, }); } // Redis provider (including legacy format without provider field) return new CacheRedisProvider({ type: 'redis', config: { host: storeConfig.host ?? 'localhost', port: storeConfig.port ?? 6379, password: storeConfig.password, db: storeConfig.db, tls: storeConfig.tls ? {} : undefined, keyPrefix: storeConfig.keyPrefix, }, defaultTTL: globalOptions.defaultTTL, }); }, }), ); break; case 'redis': case 'redis-client': { let store: CacheRedisProvider | undefined; providers.push( storeProvider({ name: 'cache:redis', provide: CacheStoreToken, // Built when the first server starts, after a browser's startup check; the servers of one `init()` share it. inject: () => [] as const, useFactory: () => (store ??= new CacheRedisProvider(options)), }), ); break; } case 'memory': providers.push({ name: 'cache:memory', provide: CacheStoreToken, // Built per server: `init()` runs once, so a value here would be shared by every server using it. inject: () => [] as const, useFactory: () => new CacheMemoryProvider(options.defaultTTL), }); break; } return providers; }; static defaultOptions: CachePluginOptions = { type: 'memory', }; options: CachePluginOptions; constructor(options: CachePluginOptions = CachePlugin.defaultOptions) { super(); assertKnownCacheType(options.type); assertReadableBypassHeader(options.bypassHeader); this.options = { defaultTTL: 60 * 60 * 24, ...options, }; } /** * Check if a tool should be cached based on metadata or tools list. */ private shouldCacheTool( toolName: string, cacheMetadata?: boolean | { ttl?: number; slideWindow?: boolean }, ): boolean { // `ttl: 0` (or less) turns caching off, over the tool patterns too. It used to count as // "cache this", and a TTL of 0 is an entry that never expires (#647). if (typeof cacheMetadata === 'object' && cacheMetadata.ttl !== undefined && cacheMetadata.ttl <= 0) { return false; } // If metadata explicitly enables cache, use it if (cacheMetadata) return true; // Check if tool matches the configured patterns const patterns = this.options.toolPatterns ?? []; return matchesToolPattern(toolName, patterns); } /** * Check if cache should be bypassed based on request headers. * Accesses headers from FrontMcpContextStorage which extracts x-frontmcp-* custom headers. */ private shouldBypassCache(_flowCtx: FlowCtxOf<'tools:call-tool'>): boolean { const bypassHeader = this.options.bypassHeader ?? DEFAULT_BYPASS_HEADER; try { // Get custom headers from the context storage // Headers with x-frontmcp-* prefix are stored in metadata.customHeaders const contextStorage = this.get(FrontMcpContextStorage); const context = contextStorage?.getStore(); const customHeaders = context?.metadata?.customHeaders; if (!customHeaders) return false; // Headers are stored lowercase in customHeaders const headerKey = bypassHeader.toLowerCase(); const headerValue = customHeaders[headerKey]; return headerValue === 'true' || headerValue === '1'; } catch { // Context storage not available - bypass header cannot be checked return false; } } /** * Get TTL for a tool, with metadata taking precedence over defaults. */ private getTtl(cacheMetadata?: boolean | { ttl?: number; slideWindow?: boolean }): number { if (typeof cacheMetadata === 'object' && cacheMetadata.ttl !== undefined) { return cacheMetadata.ttl; } return this.options.defaultTTL ?? 60 * 60 * 24; } @ToolHook.Will('execute', { priority: 1000 }) async willReadCache(flowCtx: FlowCtxOf<'tools:call-tool'>) { const { tool, toolContext } = flowCtx.state; if (!tool || !toolContext) return; // Check bypass header if (this.shouldBypassCache(flowCtx)) { return; } const { cache } = toolContext.metadata; // Check if tool should be cached (via metadata or tools list) // Check both fullName (includes app owner) and name (just namespace:tool) for pattern matching if ( (!this.shouldCacheTool(tool.fullName, cache) && !this.shouldCacheTool(tool.name, cache)) || typeof toolContext.input === 'undefined' ) { return; } const hash = this.buildCacheKey(tool.fullName, toolContext, callSurfaceOf(flowCtx)); if (hash === undefined) return; const cacheStore = this.get(CacheStoreToken); const cached = await cacheStore.getValue(hash); if (cached !== undefined && cached !== null) { /** * Double check the entry is still a result to serve: one that no longer matches the tool's * output schema, or an error result an earlier version cached, is dropped and the tool runs. */ if (isErrorResult(cached) || !tool.safeParseOutput(cached).success) { await cacheStore.delete(hash); return; } // Only `slideWindow: true` refreshes the TTL on a read, over the tool's `ttl` or the plugin's // `defaultTTL`. `cache: true` is the plugin defaults, and `slideWindow` defaults to false: it // used to slide on every hit, so an entry read often enough never expired (#678). if (typeof cache === 'object' && cache.slideWindow) { await cacheStore.setValue(hash, cached, this.getTtl(cache)); } /** * Mark the hit on the result's own _meta. Merging it into the cached value made it part * of the tool's data: without an outputSchema it reached structuredContent and the text. */ flowCtx.state.set('resultMeta', { ...flowCtx.state.resultMeta, cache: 'hit' }); /** * Answer with the cached output in place of the tool: the call finalizes it as a returned value */ toolContext.respond(cached); } } @ToolHook.Did('execute', { priority: 1000 }) async willWriteCache(flowCtx: FlowCtxOf<'tools:call-tool'>) { const { tool, toolContext } = flowCtx.state; if (!tool || !toolContext) return; // Check bypass header if (this.shouldBypassCache(flowCtx)) { return; } const { cache } = toolContext.metadata; // Check if tool should be cached (via metadata or tools list) // Check both fullName (includes app owner) and name (just namespace:tool) for pattern matching const shouldCache = this.shouldCacheTool(tool.fullName, cache) || this.shouldCacheTool(tool.name, cache); if (!shouldCache || typeof toolContext.input === 'undefined') { return; } // A result the tool returned with `isError: true` reports a failure (a timeout upstream, a // missing record); caching it answered every later call with that failure until the TTL ran // out, without running the tool again (#678). if (isErrorResult(toolContext.output)) { return; } const hash = this.buildCacheKey(tool.fullName, toolContext, callSurfaceOf(flowCtx)); if (hash === undefined) return; const cacheStore = this.get(CacheStoreToken); await cacheStore.setValue(hash, toolContext.output, this.getTtl(cache)); } /** * The identity a cache entry belongs to (GHSA-r6v6-p4r8-p936). * * Most caches sit in front of tools whose output depends on who is asking. Without this the * key was the tool plus its arguments, so the first caller's response was served to every * later one: `getProfile({})` is the same key for everybody. * * The session is the last resort rather than the first choice, because an authenticated * caller can hold several sessions and should share their own cached entries across them. * * Undefined for a caller with none of these: no later call could build its key again. */ private resolveCallerIdentity(toolContext: unknown): string | undefined { const ctx = toolContext as { authInfo?: { extra?: Record; clientId?: string }; tryGetContext?: () => { verifiedSessionId?: string; authInfo?: { extra?: Record; clientId?: string }; }; }; const requestContext = ctx.tryGetContext?.(); const authInfo = ctx.authInfo ?? requestContext?.authInfo; const issuer = verifiedIssuerOf(authInfo); // An `anon:` id is minted per request or per session, so it names no one; the session below still can. const subject = authInfo?.extra?.['sub'] ?? authInfo?.extra?.['userId']; if (!isAnonymousSubject(subject)) return subjectIdentity('user', subject, issuer); if (!isAnonymousSubject(authInfo?.clientId)) return subjectIdentity('client', authInfo?.clientId, issuer); // Stateless, per-request and unaccepted client session ids identify no one; only a verified session does. const sessionId = requestContext?.verifiedSessionId; if (sessionId) return `session:${sessionId}`; return undefined; } /** * Build the storage key for a tool call, or undefined when the caller has no identity to key by: * such a call is neither served from the cache nor stored in it. * * Read and write both go through here. They used to build the key at two separate call * sites, and a key that differs between them silently disables the cache rather than * failing visibly. The call's surface is part of it: what a tool acting for the caller * (CodeCall's search and describe) returns depends on it. */ private buildCacheKey( toolFullName: string, toolContext: { input?: unknown }, surface: string | undefined, ): string | undefined { const identity = this.options.keyByIdentity === false ? 'shared' : this.resolveCallerIdentity(toolContext); if (identity === undefined) return undefined; // Digest rather than concatenate: `hashObject` joined keys and values with `:` and `;`, // so distinct inputs could produce the same string, and the key grew with the payload. return sha256Hex(JSON.stringify({ identity, tool: toolFullName, input: stableValue(toolContext.input), surface })); } /** * Check if a tool is cacheable based on metadata or tools list. * This can be used by other plugins or flows to determine cacheability. */ isCacheable(toolName: string): boolean { return matchesToolPattern(toolName, this.options.toolPatterns ?? []); } } /** The surface (`'mcp'`, `'agent'`, ...) a call arrived on, from the context its flow was started with. */ function callSurfaceOf(flowCtx: FlowCtxOf<'tools:call-tool'>): string | undefined { const rawInput = flowCtx.rawInput as { ctx?: { surface?: unknown } } | null | undefined; const surface = rawInput?.ctx?.surface; return typeof surface === 'string' ? surface : undefined; } /** The issuer of the caller's verified token, or undefined when it names none. */ function verifiedIssuerOf(authInfo: unknown): string | undefined { const issuer = resolvePrincipal(authInfo as Partial> | undefined).claims['iss']; return typeof issuer === 'string' && issuer.length > 0 ? issuer : undefined; } /** * A signed-in caller's identity: `:`, paired with the issuer of its token when the token names one, * since a subject is unique only within its issuer. */ function subjectIdentity(kind: 'user' | 'client', subject: unknown, issuer: string | undefined): string { const identity = `${kind}:${subject}`; return issuer === undefined ? identity : JSON.stringify([issuer, identity]); } /** * Whether a tool's output is an MCP result the tool returned as a failure: a `CallToolResult` * (a `content` array, the shape the SDK passes through as-is) with `isError: true`. */ function isErrorResult(output: unknown): boolean { if (typeof output !== 'object' || output === null) return false; const result = output as { content?: unknown; isError?: unknown }; return result.isError === true && Array.isArray(result.content); } /** * Reduce a value to a form whose JSON encoding does not depend on key insertion order, so the * same arguments always produce the same key. */ function stableValue(value: unknown): unknown { if (Array.isArray(value)) { return value.map(stableValue); } if (typeof value === 'object' && value !== null) { const source = value as Record; return Object.keys(source) .sort() .reduce>((acc, key) => { acc[key] = stableValue(source[key]); return acc; }, {}); } return value; }