Iceland News MCP Server

Instructions

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;
  }