cache_stats
Monitor cache performance by retrieving hit/miss rates and entry counts. Optionally clear the cache after viewing statistics to manage data freshness.
Instructions
Get cache statistics including hit/miss rates and entry counts. Useful for monitoring performance.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| clearCache | No | If true, clears the cache after returning stats |
Implementation Reference
- src/index.ts:1013-1053 (handler)The handler function for the 'cache_stats' MCP tool. It calls getCacheStats(), computes additional metrics like hit rate and ages, generates markdown table, and optionally clears the cache.async ({ clearCache: shouldClear }) => { const stats = getCacheStats(); const now = Date.now(); const hitRate = stats.hits + stats.misses > 0 ? (stats.hits / (stats.hits + stats.misses)) * 100 : 0; const oldestAge = stats.oldestEntry ? Math.round((now - stats.oldestEntry) / 1000) : null; const newestAge = stats.newestEntry ? Math.round((now - stats.newestEntry) / 1000) : null; const cacheStatsResult = { hits: stats.hits, misses: stats.misses, hitRate: Math.round(hitRate * 100) / 100, entries: stats.entries, ttlMinutes: CACHE_TTL / 60000, oldestEntryAge: oldestAge, newestEntryAge: newestAge, }; let markdown = `# Cache Statistics\n\n`; markdown += `| Metric | Value |\n|--------|-------|\n`; markdown += `| Cache Hits | ${stats.hits} |\n`; markdown += `| Cache Misses | ${stats.misses} |\n`; markdown += `| Hit Rate | ${cacheStatsResult.hitRate}% |\n`; markdown += `| Cached Entries | ${stats.entries} |\n`; markdown += `| TTL | ${CACHE_TTL / 60000} minutes |\n`; markdown += `| Oldest Entry Age | ${oldestAge !== null ? `${oldestAge}s` : "N/A"} |\n`; markdown += `| Newest Entry Age | ${newestAge !== null ? `${newestAge}s` : "N/A"} |\n`; if (shouldClear) { clearCache(); markdown += `\n*Cache has been cleared.*\n`; } return { content: [{ type: "text" as const, text: markdown }], structuredContent: cacheStatsResult, }; }
- src/index.ts:991-999 (schema)Zod schema defining the structured output for the cache_stats tool.const CacheStatsSchema = z.object({ hits: z.number(), misses: z.number(), hitRate: z.number(), entries: z.number(), ttlMinutes: z.number(), oldestEntryAge: z.number().nullable(), newestEntryAge: z.number().nullable(), });
- src/index.ts:1001-1054 (registration)Registration of the 'cache_stats' tool with the MCP server using server.registerTool, specifying name, description, input/output schemas, and handler function.server.registerTool( "cache_stats", { description: "Get cache statistics including hit/miss rates and entry counts. Useful for monitoring performance.", inputSchema: { clearCache: z .boolean() .default(false) .describe("If true, clears the cache after returning stats"), }, outputSchema: CacheStatsSchema, }, async ({ clearCache: shouldClear }) => { const stats = getCacheStats(); const now = Date.now(); const hitRate = stats.hits + stats.misses > 0 ? (stats.hits / (stats.hits + stats.misses)) * 100 : 0; const oldestAge = stats.oldestEntry ? Math.round((now - stats.oldestEntry) / 1000) : null; const newestAge = stats.newestEntry ? Math.round((now - stats.newestEntry) / 1000) : null; const cacheStatsResult = { hits: stats.hits, misses: stats.misses, hitRate: Math.round(hitRate * 100) / 100, entries: stats.entries, ttlMinutes: CACHE_TTL / 60000, oldestEntryAge: oldestAge, newestEntryAge: newestAge, }; let markdown = `# Cache Statistics\n\n`; markdown += `| Metric | Value |\n|--------|-------|\n`; markdown += `| Cache Hits | ${stats.hits} |\n`; markdown += `| Cache Misses | ${stats.misses} |\n`; markdown += `| Hit Rate | ${cacheStatsResult.hitRate}% |\n`; markdown += `| Cached Entries | ${stats.entries} |\n`; markdown += `| TTL | ${CACHE_TTL / 60000} minutes |\n`; markdown += `| Oldest Entry Age | ${oldestAge !== null ? `${oldestAge}s` : "N/A"} |\n`; markdown += `| Newest Entry Age | ${newestAge !== null ? `${newestAge}s` : "N/A"} |\n`; if (shouldClear) { clearCache(); markdown += `\n*Cache has been cleared.*\n`; } return { content: [{ type: "text" as const, text: markdown }], structuredContent: cacheStatsResult, }; } );
- src/index.ts:298-318 (helper)Core helper function that computes raw cache statistics: hits, misses, entry count, and timestamps of oldest/newest entries.function getCacheStats(): CacheStats { let oldestEntry: number | null = null; let newestEntry: number | null = null; for (const entry of cache.values()) { if (oldestEntry === null || entry.createdAt < oldestEntry) { oldestEntry = entry.createdAt; } if (newestEntry === null || entry.createdAt > newestEntry) { newestEntry = entry.createdAt; } } return { hits: cacheHits, misses: cacheMisses, entries: cache.size, oldestEntry, newestEntry, }; }
- src/index.ts:250-256 (schema)TypeScript interface defining the structure of raw CacheStats used by getCacheStats.interface CacheStats { hits: number; misses: number; entries: number; oldestEntry: number | null; newestEntry: number | null; }