@leejpsd/nextjs-cache-handler-mcp

@leejpsd/nextjs-cache-handler-mcp

MCP (Model Context Protocol) server for @leejpsd/nextjs-cache-handler Redis caches. Lets AI agents (Claude Code, Cursor, …) inspect and operate a running deployment's Next.js cache: "why isn't this page updating?" becomes a tag_state call instead of guesswork.

Setup

Project .mcp.json (Claude Code picks this up automatically):

{
  "mcpServers": {
    "nextjs-cache": {
      "command": "npx",
      "args": ["-y", "@leejpsd/nextjs-cache-handler-mcp"],
      "env": {
        "REDIS_URL": "redis://127.0.0.1:6379",
        "DEPLOYMENT_VERSION": "your-deploy-id"
      }
    }
  }
}

Runs locally over stdio and connects to YOUR Redis — nothing is hosted.

AWS/ElastiCache note: ElastiCache is VPC-internal, so a locally running MCP server needs an SSH tunnel/bastion (point REDIS_URL at the tunnel). Agents running inside the VPC (CI, in-cluster) connect directly. Pair with the AWS agent skills/MCP: they handle the infrastructure, this server handles cache semantics.

Tools

Tool	What it answers	Writes?
cache_health	Is Redis up? What's cached, per layer/kind?	no
cache_search	Which keys match this pattern?	no
cache_inspect	Decode one entry: kind, age, tags, TTL, compression, sizes	no
tag_state	Is this tag invalidated right now, on BOTH cache layers?	no
explain_key	Parse a raw Redis key into layer/kind/namespace/key	no
simulate_swr	Would this entry be fresh / stale / expired, and what happens on read?	no
invalidate_tag	Soft (SWR) or hard invalidation — dry-run unless confirm: true	gated

Env: REDIS_URL (required), DEPLOYMENT_VERSION (recommended — scopes namespace-aware tools), CACHE_KEY_PREFIX / ISR_KEY_PREFIX (only when the handlers use custom prefixes).