mcpField
N
nextjs-cache-handler-mcp

nextjs-cache-handler-mcp

Local
github.com/leejpsdDeveloper Tools6Updated 9w ago
Repository

About nextjs-cache-handler-mcp

nextjs-cache-handler-mcp is an MCP server for inspecting and operating Next.js Redis caches, aimed at developers and AI agents working with deployments. It checks tag state, simulates SWR behavior, and gates invalidation behind confirmation.

Key features

  1. 01Check Redis cache health
  2. 02Search and decode cache entries
  3. 03Inspect tag state across both layers
  4. 04Simulate SWR freshness and reads
  5. 05Soft or hard tag invalidation

Use cases

  1. 01Diagnosing why a page is not updating
  2. 02Checking entry TTLs and tags
  3. 03Assessing invalidation across cache layers
  4. 04Invalidating a tag after confirmation

MCP support

The local stdio MCP server connects to the user's Redis and gives AI agents cache inspection and operation tools; invalidation is a dry run unless confirmed.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "leejpsd-nextjs-cache-handler": {
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp"
      ],
      "env": {
        "REDIS_URL": "<REDIS_URL>",
        "DEPLOYMENT_VERSION": "<DEPLOYMENT_VERSION>",
        "HASH_TAG": "<HASH_TAG>"
      }
    }
  }
}
Run commandnpx -y @leejpsd/nextjs-cache-handler-mcp
Environment variables to set
REDIS_URLSecretRedis connection string the cache handler uses
DEPLOYMENT_VERSIONDeploy namespace (recommended)
HASH_TAGSet 'true' when handlers use hashTag: true (Redis Cluster)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@leejpsd/nextjs-cache-handler-mcp0.1.2

Tools

7

Saved tool list · updated 2w ago

This tool takes no parameters.

Details

From the project README

@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

ToolWhat it answersWrites?
cache_healthIs Redis up? What's cached, per layer/kind?no
cache_searchWhich keys match this pattern?no
cache_inspectDecode one entry: kind, age, tags, TTL, compression, sizesno
tag_stateIs this tag invalidated right now, on BOTH cache layers?no
explain_keyParse a raw Redis key into layer/kind/namespace/keyno
simulate_swrWould this entry be fresh / stale / expired, and what happens on read?no
invalidate_tagSoft (SWR) or hard invalidation — dry-run unless confirm: truegated

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.