@mcp-utils/cache

Wraps MCP tool handlers with automatic time-to-live (TTL) caching that stores tool execution results in memory and returns cached responses within the TTL window. Implements a decorator pattern that intercepts tool calls, checks cache state, executes handlers only on cache misses, and automatically evicts stale entries. Integrates directly with MCP server tool registries to transparently cache responses without modifying handler logic.

Automatically generates cache keys from tool parameters by serializing input arguments into deterministic strings, enabling cache hits when identical parameters are passed to the same tool. Uses JSON serialization with consistent key ordering to ensure that parameter variations (e.g., different object property order) do not create duplicate cache entries. Supports custom key generation strategies for tools with non-serializable parameters or complex equality semantics.

Exposes cache performance metrics (hit rate, miss rate, entry count, eviction count) via a metrics API that tracks cache operations in real time. Emits events or logs on cache hits, misses, and evictions, enabling developers to monitor cache effectiveness and debug performance issues. Integrates with vurb's observability layer to provide structured logging and optional integration with external monitoring systems.

Allows developers to define rules that determine whether a tool response should be cached based on the tool parameters, response content, or execution context. Supports predicates like 'cache only if response status is success' or 'skip cache for parameters matching pattern X'. Implements a filter chain pattern that evaluates bypass rules before storing responses in cache, enabling selective caching for tools with non-deterministic or context-dependent outputs.

Provides imperative APIs to manually clear cache entries by tool name, parameter pattern, or globally, and to force refresh of specific cached entries. Supports both synchronous invalidation (immediate removal) and asynchronous refresh (background re-execution). Integrates with MCP server lifecycle hooks to enable cache clearing on server shutdown or configuration changes.