@mcp-utils/cache

LLM agents are repetitive by design. They call the same tools with the same arguments dozens of times per task. Without a cache, every single call hits your database.

This is how you stop it:

import { withCache } from '@mcp-utils/cache';

// Before: 50 identical requests = 50 database queries
handler: async (ctx, args) => success(await db.products.findAll())

// After: 50 identical requests = 1 database query
handler: withCache(
    async (ctx, args) => success(await db.products.findAll()),
    { ttl: 60_000 }
)

One wrapper. Instant responses on repeat calls. No infrastructure changes.

Install

npm install @mcp-utils/cache

Usage

Basic cache

import { withCache } from '@mcp-utils/cache';

const listProducts = withCache(
    async (ctx, args) => success(await db.products.findAll()),
    { ttl: 60_000 },
);

Custom cache key

By default the cache key is JSON.stringify(args). Take control when you need it:

const getUser = withCache(
    async (ctx, args) => success(await api.users.get(args['userId'])),
    {
        ttl: 5 * 60_000,
        key: (args) => `user:${args['userId']}`,
    },
);

Bounded memory

Prevent unbounded growth in long-running servers:

const search = withCache(handler, {
    ttl: 30_000,
    maxSize: 200,
});

Shared policy across handlers

import { createCache } from '@mcp-utils/cache';

const cached = createCache({ ttl: 30_000, maxSize: 500 });

const listUsers = cached(async (ctx, args) => success(await db.users.findAll()));
const listRoles = cached(async (ctx, args) => success(await db.roles.findAll()));

API

withCache(handler, options)

| Option | Type | Default | Description | |---|---|---|---| | ttl | number | required | Time-to-live in milliseconds | | key | (args) => string | JSON.stringify(args) | Cache key factory | | maxSize | number | 500 | Max entries; oldest evicted when exceeded |

• Error responses (isError: true) are never cached — only successes are
• Each withCache call has its own isolated cache store

createCache(options)

Returns a decorator: (handler) => wrappedHandler. Same options as withCache.

Part of @mcp-utils — production-grade utilities for MCP server development.

License

Apache-2.0