Nextjs Cache Handler MCP server

@leejpsd/nextjs-cache-handler

v1.0.0 — install with

npm install @leejpsd/nextjs-cache-handler, or wire everything with

npx nextjs-cache-handler init --yes. Production-validated against

AWS ECS Fargate with multi-instance Redis (24h live-traffic soak and a

live Redis-reboot drill with zero 5xx — see

docs/staging-verification-2026-08-01.md),

and exercised end-to-end against Next.js 16.3 (both cache interfaces).

v0.4 adds: build-output cache seeding (first request after deploy is a

HIT), pub/sub tag propagation (~3ms cross-instance), Redis Cluster

e2e in CI, a CLI (init / doctor / seed), and agent-native assets

(skill, rules, MCP server).

1.0 freezes the public API under semver — the eight entry points, the

CacheHandlerOptions surface, the Redis key shapes and tag-marker format,

and the metric event names. Upgrading from 0.4.x needs no changes.

🤖 For AI agents

Working with Claude Code / Codex / Cursor? Give your agent this URL and it will install and wire everything (version detection, wrapper files, next.config patch, verification):

https://raw.githubusercontent.com/leejpsd/nextjs-cache-handler/main/setup-instructions/setup.md

An agent skill with decision tables, invalidation semantics, and a troubleshooting playbook ships in the package (AGENTS.md, skills/nextjs-redis-cache/SKILL.md) and via npx skills add leejpsd/nextjs-cache-handler.

For cache operations from your agent (health, tag state, safe invalidation), the companion MCP server is on the official registry as io.github.leejpsd/nextjs-cache-handler-mcp — or one command: npx nextjs-cache-handler init --yes wires handlers, rules, and .mcp.json together.

The Redis cache handler for Next.js 15/16 that ships both cacheHandler (ISR / Pages Router) and cacheHandlers ('use cache' directive, cacheComponents: true) — the area where @fortedigital/nextjs-cache-handler currently lists "Help needed".

// next.config.ts
const nextConfig = {
  cacheComponents: true,
  cacheHandler: require.resolve("./cache-incremental.cjs"),
  cacheHandlers: { default: require.resolve("./cache-components.cjs") },
};

// cache-components.cjs
const { createCacheComponentsHandler } = require("@leejpsd/nextjs-cache-handler/cache-components");
module.exports = createCacheComponentsHandler({
  client: { type: "redis", url: process.env.REDIS_URL },
  buildNamespace: process.env.DEPLOYMENT_VERSION, // auto-isolates deploys
});

That's it. 'use cache', revalidateTag, updateTag, cacheLife all work.

Why this exists

Next.js 16 split caching into two handler interfaces:

As of 2026-05, the leading OSS Redis handler @fortedigital/nextjs-cache-handler@3.2.0 declares peerDependencies.next: ">=16.1.5" but the README marks the new plural interface as ❌ "Not yet supported - Help needed":

Shortened. The full README is on GitHub.