open-index/open-npm huggingface dataset:
npm package: @mcp-utils/cache
Description: TTL cache wrapper for MCP tool handlers — powered by vurb.
Latest version: 1.0.1

# @mcp-utils/cache

<div align="center">

[![npm](https://img.shields.io/npm/v/@mcp-utils/cache?color=ff4d00&label=npm)](https://npmjs.com/package/@mcp-utils/cache)
[![License](https://img.shields.io/npm/l/@mcp-utils/cache)](LICENSE)

</div>

---

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:

```ts
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

```bash
npm install @mcp-utils/cache
```

## Usage

### Basic cache

```ts
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:

```ts
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:

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

### Shared policy across handlers

```ts
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](https://npmjs.com/org/mcp-utils)** — production-grade utilities for MCP server development.

## License

Apache-2.0