MCP Utility Tools

Instructions

Implementation Reference

• src/index.ts:305-322 (handler)

  Handler for cache_put tool: extracts key, value, optional ttl_seconds from args, computes expiresAt, stores in global cache Map, returns JSON success response with details.

  case "cache_put": {
    const { key, value, ttl_seconds = 300 } = args as any;
    
    const expiresAt = Date.now() + (ttl_seconds * 1000);
    cache.set(key, { value, expiresAt });
  
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: true,
          key,
          ttl_seconds,
          expires_at: new Date(expiresAt).toISOString()
        })
      }]
    };
  }

• src/index.ts:98-121 (registration)

  Registration of the cache_put tool in the tools array used by ListToolsRequestSchema handler, includes name, description, and inputSchema.

  {
    name: "cache_put",
    description: "Store a value in the cache with TTL",
    inputSchema: {
      type: "object",
      properties: {
        key: {
          type: "string",
          description: "Cache key"
        },
        value: {
          description: "Value to cache (any JSON-serializable data)"
        },
        ttl_seconds: {
          type: "number",
          description: "Time to live in seconds",
          default: 300,
          minimum: 1,
          maximum: 86400 // 24 hours
        }
      },
      required: ["key", "value"]
    }
  },

• src/index-v2.ts:441-461 (handler)

  Handler for cache_put tool in v2: supports namespace via getCacheKey, stores with TTL in cache, returns success with namespace and cache_size.

  case "cache_put": {
    const { key, value, ttl_seconds = 300, namespace = "default" } = args as any;
    const cacheKey = getCacheKey(key, namespace);
    
    const expiresAt = Date.now() + (ttl_seconds * 1000);
    cache.set(cacheKey, { value, expiresAt });
  
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          success: true,
          key,
          namespace,
          ttl_seconds,
          expires_at: new Date(expiresAt).toISOString(),
          cache_size: cache.size
        })
      }]
    };
  }

• src/index-v2.ts:115-143 (registration)

  Registration of cache_put tool in v2 tools array, adds optional namespace to schema.

  {
    name: "cache_put",
    description: "Store a value in the cache with TTL. Useful for caching API responses, computed values, etc.",
    inputSchema: {
      type: "object",
      properties: {
        key: {
          type: "string",
          description: "Cache key"
        },
        value: {
          description: "Value to cache (any JSON-serializable data)"
        },
        ttl_seconds: {
          type: "number",
          description: "Time to live in seconds",
          default: 300,
          minimum: 1,
          maximum: 86400 // 24 hours
        },
        namespace: {
          type: "string",
          description: "Optional namespace to prevent key collisions",
          default: "default"
        }
      },
      required: ["key", "value"]
    }
  },

• src/index.ts:12-28 (helper)

  Global cache storage helper: defines CacheEntry interface, initializes Map, and sets up periodic cleanup of expired entries. Used by all cache_* tools.

  // Cache storage with TTL support
  interface CacheEntry {
    value: any;
    expiresAt: number;
  }
  
  const cache = new Map<string, CacheEntry>();
  
  // Clean up expired cache entries periodically
  setInterval(() => {
    const now = Date.now();
    for (const [key, entry] of cache.entries()) {
      if (entry.expiresAt <= now) {
        cache.delete(key);
      }
    }
  }, 60000); // Clean every minute