### Load Migration Guide Resource

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/upgrade-nextjs-16-prompt.md

Before starting the upgrade, load the complete migration guide using the specified resource URI.

```bash
Read resource "nextjs16://migration/examples"
```

--------------------------------

### Local Development Setup

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Install and build next-devtools-mcp from source for local development. Point your client to the built `dist/index.js` file.

```bash
# Local development — build from source and point to dist/index.js
pnpm install && pnpm build
# Then configure your client with:
# { "command": "node", "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"] }
```

--------------------------------

### Start Development Server

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Start the development server to test routes interactively. MCP is enabled by default in Next.js 16+.

```bash
<pkg-manager> dev
```

--------------------------------

### Install Dependencies Locally

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Install project dependencies and build the project for local development using pnpm.

```bash
pnpm install
pnpm build
```

--------------------------------

### Start Next.js Dev Server

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Run this command to start your Next.js development server. MCP is enabled by default for Next.js 16+.

```bash
npm run dev
```

--------------------------------

### Enable Cache Components Tool Response

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

The response from the `enable_cache_components` tool provides setup guidance, including phases, notes, and configuration examples for Next.js Cache Components.

```jsonc
{
  "success": true,
  "project_path": "/path/to/my-next-app",
  "description": "Cache Components Setup Guide",
  "type": "structured_guidance",
  "guidance": "Complete phase-by-phase setup instructions...\n\n## PHASE 1: Pre-flight Checks\n...",
  "note": "Follow the phases in order for successful Cache Components setup."
}
```

--------------------------------

### Install Next.js DevTools MCP with add-mcp

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Use this command to install the MCP server for all detected coding agents in your project. Add -y to skip confirmation or -g to install globally.

```bash
npx add-mcp next-devtools-mcp@latest
```

--------------------------------

### Run Development Server with Next.js

Source: https://github.com/vercel/next-devtools-mcp/blob/main/test/fixtures/nextjs14-minimal/README.md

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Start Next.js Development Server

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/upgrade-nextjs-16-prompt.md

Launch the Next.js development server to prepare for browser-based verification. This allows testing of client-side rendering and interactivity.

```bash
<pkg-manager> run dev
```

--------------------------------

### Enable Cache Components Tool Configuration

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Configure the `enable_cache_components` tool to guide the setup of Cache Components mode in Next.js. Specify the project path for automated guidance.

```jsonc
{
  "tool": "enable_cache_components",
  "arguments": {
    "project_path": "/path/to/my-next-app"  // optional
  }
}
```

--------------------------------

### Basic 'use client' Directive Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs-fundamentals)/01-use-client.md

Use 'use client' at the top of a file to mark it as a client component. This example demonstrates a simple counter with state and an event handler.

```typescript
'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  )
}
```

--------------------------------

### Read Next.js 16 Migration Examples Resource

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Access code examples for Next.js 16 migration, covering breaking changes, using `resources/read` with the `nextjs16://migration/examples` URI.

```jsonc
{ "method": "resources/read", "params": { "uri": "nextjs16://migration/examples" } }
```

--------------------------------

### MCP Configuration

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Instructions on how to install and register the next-devtools-mcp server with various MCP-compatible AI clients.

```APIDOC
## MCP Configuration

Install and register the server in any MCP-compatible client.

```json
// ~/.cursor/mcp.json  |  .claude/mcp.json  |  .mcp.json
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}
```

```bash
# Claude Code CLI
claude mcp add next-devtools npx next-devtools-mcp@latest

# Codex CLI
codex mcp add next-devtools -- npx next-devtools-mcp@latest

# Amp CLI
amp mcp add next-devtools -- npx next-devtools-mcp@latest

# Gemini CLI (global)
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest
```

```bash
# Local development — build from source and point to dist/index.js
pnpm install && pnpm build
# Then configure your client with:
# { "command": "node", "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"] }
```
```

--------------------------------

### Next.js Cache Components Configuration Example

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Example configuration for `next.config.js` to enable Cache Components in Next.js 16, including `experimental.cacheComponents` and `cacheLife` settings.

```javascript
export default {
  experimental: {
    cacheComponents: true,  // required
  },
  cacheLife: {
    blog: { stale: 1800, revalidate: 600, expire: 43200 },
  },
}
```

--------------------------------

### Initiate Next.js 16 Upgrade

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Starts the Next.js 16 upgrade process. Optionally specify the project path; if omitted, it defaults to the current directory.

```json
{ "tool": "upgrade_nextjs_16", "arguments": { "project_path": "/path/to/my-next-app"  } }
```

--------------------------------

### TypeScript Configuration Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Illustrates key TypeScript compiler options used in the project, including target, module resolution, strict mode, and output directory.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist/",
    "declaration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Installs project dependencies using the pnpm package manager. Ensure pnpm is installed globally.

```bash
pnpm install
```

--------------------------------

### Cache Components Structure Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Illustrates the recommended structure for Cache Components, pushing dynamic boundaries down the tree. This approach ensures a static shell with cached components and dynamic content where necessary.

```plaintext
Static Shell (instant load)
├─ Cached Header ("use cache")
├─ Cached Sidebar ("use cache")
└─ <Suspense>
   └─ Dynamic Content (per-request)
```

--------------------------------

### Configure Runtime Prefetching with Samples

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/04-runtime-prefetching.md

Define `unstable_prefetch` with `mode: 'runtime'` and provide samples to guide prefetching behavior. This example shows prefetching based on cookie values.

```typescript
export const unstable_prefetch = {
  mode: 'runtime',
  samples: [{ cookies: [{ name: 'testCookie', value: 'testValue' }] }],
}

export default async function Page() {
  return (
    <main>
      <Suspense fallback={<div>Loading 1...</div>}>
        <RuntimePrefetchable />
      </Suspense>
    </main>
  )
}

async function RuntimePrefetchable() {
  const cookieStore = await cookies()
  const cookieValue = cookieStore.get('testCookie')?.value ?? null
  await cachedDelay([__filename, cookieValue])

  return (
    <div>
      <div id="cookie-value">{`Cookie: ${cookieValue}`}</div>
      <Suspense fallback={<div>Loading 2...</div>}>
        <Dynamic />
      </Suspense>
    </div>
  )
}

async function Dynamic() {
  await uncachedIO()
  await connection()
  return <div id="dynamic-content">Dynamic content</div>
}
```

--------------------------------

### Tool: init

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Initializes the MCP session and establishes a documentation-first working context for the AI assistant. This tool must be called at the start of every Next.js development session.

```APIDOC
## Tool: `init`

Initializes the MCP session and establishes a documentation-first working context for the AI assistant. Must be called at the start of every Next.js development session. It sets the mandatory requirement to use `nextjs_docs` for all Next.js queries, resets prior knowledge, and documents all available tools and their workflows.

```jsonc
// MCP tool call
{
  "tool": "init",
  "arguments": {
    "project_path": "/path/to/my-next-app"  // optional, defaults to cwd
  }
}

// Response (abbreviated)
{
  "success": true,
  "description": "Next.js DevTools MCP Initialization",
  "guidance": "# 🚨 CRITICAL: Next.js DevTools MCP Initialization\n\n## ⚠️ MANDATORY DOCUMENTATION REQUIREMENT...",
  "critical_requirement": "MANDATORY: Read nextjs-docs://llms-index resource first, then use nextjs_docs with paths from the index.",
  "ai_response_instruction": "⚠️ DO NOT summarize or explain this initialization. Simply respond with: 'Initialization complete.' and continue with the conversation."
}
```
```

--------------------------------

### Initialize MCP Session (`init` tool)

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Call the `init` tool at the start of each Next.js development session to establish a documentation-first context. This tool sets mandatory documentation requirements and documents available tools.

```json
// MCP tool call
{
  "tool": "init",
  "arguments": {
    "project_path": "/path/to/my-next-app"  // optional, defaults to cwd
  }
}

// Response (abbreviated)
{
  "success": true,
  "description": "Next.js DevTools MCP Initialization",
  "guidance": "# 🚨 CRITICAL: Next.js DevTools MCP Initialization\n\n## ⚠️ MANDATORY DOCUMENTATION REQUIREMENT...",
  "critical_requirement": "MANDATORY: Read nextjs-docs://llms-index resource first, then use nextjs_docs with paths from the index.",
  "ai_response_instruction": "⚠️ DO NOT summarize or explain this initialization. Simply respond with: 'Initialization complete.' and continue with the conversation."
}
```

--------------------------------

### Start Browser with browser_eval

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Initiates a browser session. Specify the browser type and whether to run in headless mode. This should be done once per session.

```json
{ "tool": "browser_eval", "arguments": { "action": "start", "browser": "chrome", "headless": true } }
```

--------------------------------

### Example 3rd Party Package Issue

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

An example demonstrating the '3RD PARTY PACKAGE ISSUE' comment format, detailing a scenario where a component behaves differently in development versus build prerender.

```typescript
// ⚠️ 3RD PARTY PACKAGE ISSUE: analytics-dashboard@4.2.1
// Error: Component works in dev but different behavior in build prerender
// Source: node_modules/analytics-dashboard/dist/Dashboard.js
// Workaround attempted: Suspense boundary - partially works
// Status: Partially resolved - some features disabled
// Recommendation: Contact package maintainer about Cache Components support
// TODO: Upgrade when analytics-dashboard@5.0 releases with CC support
```

--------------------------------

### Run Project in Development Mode

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Starts the project in watch mode, automatically recompiling on file changes. Useful for active development.

```bash
pnpm dev
```

--------------------------------

### Configure Gemini CLI for Next.js DevTools MCP

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Install the Next.js DevTools MCP server project-wide or globally using the Gemini CLI. Manual configuration is also an option.

```bash
gemini mcp add next-devtools npx next-devtools-mcp@latest
```

```bash
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest
```

--------------------------------

### Static Route Handler Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/13-route-handlers.md

This handler contains no dynamic data, so it will be pre-rendered at build time and served as a static response.

```typescript
// app/api/project-info/route.ts
export async function GET() {
  return Response.json({
    projectName: 'Next.js',
  })
}
```

--------------------------------

### Route Segment Config Migration Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Example of migrating a Route Segment Config export by adding a comment indicating the original value and the new migration strategy.

```typescript
// MIGRATED from: export const revalidate = 60
// → Add "use cache" + cacheLife('minutes') to maintain ~60s revalidation
```

--------------------------------

### Start Browser Automation for Debugging

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Initiate browser automation, typically for debugging unclear errors. This command starts a Chrome browser in headless mode.

```javascript
browser_eval({ action: "start", browser: "chrome", headless: true })
```

--------------------------------

### Complete Next.js 16 beta config and component

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-beta-to-stable.md

Example of `next.config.js` and a page component (`app/blog/page.tsx`) using `experimental.cacheComponents` and `experimental.cacheLife` before migration.

```js
// next.config.js
export default {
  experimental: {
    cacheComponents: true,
    cacheLife: {
      default: {
        stale: 3600,
        revalidate: 900,
        expire: 86400,
      },
      blog: {
        stale: 1800,
        revalidate: 600,
        expire: 43200,
      },
    },
  },
}
```

```tsx
// app/blog/page.tsx
import { unstable_cacheLife } from 'next/cache'

export default async function BlogPage() {
  unstable_cacheLife('blog')

  const posts = await fetchPosts()
  return <div>{posts.map(post => <Post key={post.id} {...post} />)}</div>
}
```

--------------------------------

### Read Next.js 16 Migration Beta to Stable Resource

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Read the guide for migrating from beta to stable versions of Next.js 16, focusing on `experimental.cacheLife` to `cacheLife` changes, using `resources/read`.

```jsonc
{ "method": "resources/read", "params": { "uri": "nextjs16://migration/beta-to-stable" } }
```

--------------------------------

### Configure Auto-Initialization for Other AI Assistants

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Add this instruction to your AI coding assistant's configuration file to automatically call the `init` tool when starting a Next.js project. This ensures proper context and documentation.

```markdown
**Next.js Initialization**: When starting work on a Next.js project, automatically
call the `init` tool from the next-devtools-mcp server FIRST. This establishes
proper context and ensures all Next.js queries use official documentation.
```

--------------------------------

### Configure Auto-Initialization for Claude

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Add this markdown to your `CLAUDE.md` file to automatically call the `init` tool when starting a Next.js session. This ensures proper context and documentation requirements are met.

```markdown
**When starting work on a Next.js project, ALWAYS call the `init` tool from
next-devtools-mcp FIRST to set up proper context and establish documentation
requirements. Do this automatically without being asked.**
```

--------------------------------

### Resource Definition Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Defines an MCP resource, including its metadata (URI, name, description, mimeType) and a handler function that returns the resource content.

```typescript
export const metadata = {
  uri: "cache-components://overview",
  name: "Cache Components Overview",
  description: "An overview of how to set up and use Cache Components.",
  mimeType: "text/markdown"
};

export const handler = async () => {
  // Return content from a markdown file or generated string
  return "# Cache Components\n\nThis section covers Cache Components setup...";
};

```

--------------------------------

### Runtime Prefetch: Inclusion of Request Parameters

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/04-runtime-prefetching.md

Confirms that parameters, search parameters, cookies, and headers are always included in runtime prefetch responses. This example shows how to access and assert their presence.

```typescript
// These are ALL included in runtime prefetch:
const { id } = await params
const { q } = await searchParams
const cookie = (await cookies()).get("name")
const header = (await headers()).get("user-agent")

// Test assertion:
// - Prefetch response includes: "Param: 123"
// - Prefetch response includes: "Search param: 456"
// - Prefetch response includes: "Cookie: initialValue"
// - Prefetch response includes: "Header: present"
```

--------------------------------

### Configure Auto-Initialization for Cursor

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Add this rule to your `.cursorrules` file to automatically call the `init` tool at the start of every Next.js session. This establishes proper context and documentation requirements.

```text
When working with Next.js, always call the init tool from next-devtools-mcp
at the start of the session to establish proper context and documentation requirements.
```

--------------------------------

### Basic Segment Cache Behavior Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Demonstrates how the client-side router cache (segment cache) works when navigating between pages. It shows prefetching, instant navigation from cache, and cache persistence.

```typescript
// When you navigate between pages:

// Step 1: Link becomes visible
<Link href="/target">Target</Link>
// → Triggers prefetch
// → Stores result in client segment cache

// Step 2: User clicks link
// → Reads from segment cache (instant navigation!)
// → No network request needed

// Step 3: Navigate back, then forward again
// → Still uses segment cache (if not stale)
```

--------------------------------

### Tool Definition Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Defines a single MCP tool, including its input schema (using Zod), metadata (name, description), and the handler function that performs the tool's action.

```typescript
import { z } from "zod";

export const inputSchema = z.object({
  query: z.string().describe("The search query.")
});

export const metadata = {
  name: "nextjs_docs",
  description: "Search Next.js documentation and knowledge base."
};

export const handler = async (input: z.infer<typeof inputSchema>) => {
  // ... implementation to search docs
  return { result: "Search results..." };
};

```

--------------------------------

### Build Output Error Examples

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Review the build output for specific error messages related to caching. These messages indicate issues like accessing data without Suspense, dynamic value detection during prerender, or using unsupported APIs within cached functions.

```text
Route "/dashboard": A component accessed data, headers, params, 
searchParams, 
or a short-lived cache without a Suspense boundary nor a "use cache" above it.

Route "/blog/[slug]": Dynamic value detected during prerender

Route "/api/users": Cannot use cookies() inside a cached function

Route "/api/products": Cannot serialize Response object for caching
```

--------------------------------

### Workflow Summary for Cache Component Migration

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

This visual summary outlines the recommended steps for migrating to Cache Components, emphasizing iterative fixing and build verification before proceeding.

```text
Step 1: Remove obvious breaking changes (exports, unstable_noStore)
  ↓
Step 2: Build to capture all errors
  ↓
Step 3A: Fix ALL obvious errors from build output (NO dev server)
  ↓
Step 3B: Re-run build to verify fixes
  ↓
Step 3C: Final build verification
  ↓
  ├─ All pass (0 errors)? → Success! Go to Phase 4 - Option A
  ├─ Clear errors remain? → Back to Step 3A
  └─ Unclear errors remain? → Go to Phase 4 - Option B
```

--------------------------------

### Example Unresolved Issue

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

An example of the 'UNRESOLVED' comment format, illustrating a custom animation timing issue that causes inconsistent cached values between prerender and runtime.

```typescript
// ⚠️ UNRESOLVED: Custom animation timing issue
// Issue: Animation component behaves differently in cache vs runtime
// Error: Cached value inconsistent between prerender and runtime
// Recommendation: Investigate hydration mismatch, may need "use cache: private"
// TODO: Profile in production build to understand timing behavior
```

--------------------------------

### Verify Upgrade with Build

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/upgrade-nextjs-16-prompt.md

Run a build command to ensure the automated upgrade was successful and no build errors were introduced. This is a critical step before proceeding to browser verification.

```bash
<pkg-manager> run build
```

--------------------------------

### Run Build with Debug Prerender

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Execute the build command with the --debug-prerender flag for the best output when capturing all issues. This is the first attempt for debugging.

```bash
<pkg-manager> run build -- --debug-prerender
```

--------------------------------

### Next.js Cache Components Directive Example

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Example of adding the `cacheLife` directive in a Next.js page component to manage cache behavior for specific data fetches.

```typescript
import { cacheLife } from 'next/cache'
export default async function BlogPage() {
  cacheLife('blog')
  const posts = await fetchPosts()
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}
```

--------------------------------

### Build Process: Resource Copying

Source: https://github.com/vercel/next-devtools-mcp/blob/main/CLAUDE.md

Copies markdown files from `src/resources/` and `src/prompts/` to their respective locations within the `dist/` directory. This ensures resources are available after the build.

```bash
node scripts/copy-resources.js
```

--------------------------------

### Check Current Next.js Version

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/upgrade-nextjs-16-prompt.md

Verify the current installed version of Next.js in your package.json file.

```bash
grep '"next":' package.json
```

--------------------------------

### List All Resources

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Use the `resources/list` method to retrieve a list of all available knowledge-base resources.

```jsonc
{ "method": "resources/list" }
```

--------------------------------

### Dynamic Route Handler Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/13-route-handlers.md

This handler is dynamic and executes at request time, returning a fresh random number for each request.

```typescript
// app/api/random-number/route.ts
export async function GET() {
  return Response.json({
    randomNumber: Math.random(),
  })
}
```

--------------------------------

### Initialize Next.js DevTools Context

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Use the init tool to set up the MCP context for your Next.js application. This ensures the AI assistant uses official Next.js documentation for queries.

```text
Use the init tool to set up Next.js DevTools context
```

--------------------------------

### Complete Next.js 16 stable config and component

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-beta-to-stable.md

Example of `next.config.js` and a page component (`app/blog/page.tsx`) after migrating `cacheLife` to top-level and `unstable_cacheLife` to `cacheLife`.

```js
// next.config.js
export default {
  experimental: {
    cacheComponents: true, // Stays here
  },
  cacheLife: {
    // Moved to top-level
    default: {
      stale: 3600,
      revalidate: 900,
      expire: 86400,
    },
    blog: {
      stale: 1800,
      revalidate: 600,
      expire: 43200,
    },
  },
}
```

```tsx
// app/blog/page.tsx
import { cacheLife } from 'next/cache'

export default async function BlogPage() {
  cacheLife('blog')

  const posts = await fetchPosts()
  return <div>{posts.map(post => <Post key={post.id} {...post} />)}</div>
}
```

--------------------------------

### Configure Local MCP Server

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Configure your MCP client to use a locally running instance of next-devtools-mcp. Replace the path with your cloned repository's absolute path.

```json
{
  "mcpServers": {
    "next-devtools": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}
```

--------------------------------

### Beta to Stable Migration Resource

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/upgrade-nextjs-16-prompt.md

If migrating from a beta version, apply this resource for additional configuration changes. This moves 'experimental.cacheLife' to the root level.

```text
Read resource "nextjs16://migration/beta-to-stable"
```

--------------------------------

### Cache Invalidation APIs

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Provides examples of cache invalidation APIs. `updateTag` and `refresh` are for Server Actions only, while `revalidateTag` can be used in Server Actions and Route Handlers.

```typescript
// Server Actions only:
updateTag('tag')        // Immediate expiry, read-your-own-writes
refresh()               // Client router cache refresh
```

```typescript
// Server Actions + Route Handlers:
revalidateTag('tag', 'max')  // Stale-while-revalidate (recommended)
revalidateTag('tag')         // Legacy (deprecated)
```

--------------------------------

### Migrate unstable_noStore() calls

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Example of migrating away from unstable_noStore(). Shows removal of import and call, with a comment indicating it's now dynamic by default with Cache Components.

```typescript
// Remove: import { unstable_noStore } from 'next/cache'
// Remove: unstable_noStore()

// MIGRATED: Removed unstable_noStore() - dynamic by default with Cache Components
// TODO: Will add "use cache" or Suspense boundary after analyzing build errors
```

--------------------------------

### Search for experimental.dynamicIO Flag

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Use grep to find any usage of the `experimental.dynamicIO` flag in your `next.config.js` file.

```bash
# Search for old flag
grep -r "experimental.dynamicIO" next.config.*

```

--------------------------------

### Search for AMP Usage

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Use grep to find all instances of AMP-related functions and configurations in your project files.

```bash
grep -r "useAmp\|amp:" app/ src/ pages/
```

--------------------------------

### Mixed Cardinality generateStaticParams - Low Card

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Defines static parameters for a low-cardinality route segment. This file is part of a mixed cardinality example where this parameter will be fully prerendered.

```typescript
export async function generateStaticParams() {
  return [{ lowcard: "one" }, { lowcard: "two" }]
}
```

--------------------------------

### Search for Runtime Config Usage

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Use grep to locate `serverRuntimeConfig` and `publicRuntimeConfig` in your `next.config.js` files.

```bash
# Search for runtime config
grep -r "serverRuntimeConfig\|publicRuntimeConfig" next.config.*

```

--------------------------------

### Query Next.js Route Structure

Source: https://github.com/vercel/next-devtools-mcp/blob/main/README.md

Use this prompt to get information about the structure of your Next.js application's routes. The coding agent utilizes `nextjs_index` and `nextjs_call` tools.

```text
Next Devtools, show me the structure of my routes
```

--------------------------------

### Connect and call tools on an MCP server

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Use these helpers to spawn and communicate with external MCP servers over stdio. Ensure the server is running before attempting to connect.

```typescript
import {
  connectToMCPServer,
  callServerTool,
  listServerTools,
  disconnectFromMCPServer,
  type MCPConnection,
} from "./src/_internal/mcp-client.js"

// Connect to playwright-mcp
const connection: MCPConnection = await connectToMCPServer(
  "npx",
  ["-y", "@playwright/mcp@latest", "--headless"],
  { cwd: process.cwd() }
)

// List available tools on the connected server
const tools: string[] = await listServerTools(connection)
// → ["browser_navigate", "browser_click", "browser_take_screenshot", ...]

// Call a tool with arguments
const result = await callServerTool(connection, "browser_navigate", {
  url: "http://localhost:3000",
})

// Clean up when done
await disconnectFromMCPServer(connection)
```

--------------------------------

### Next.js Cache Directive Comment Templates

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Provides commented import templates for `cacheLife` and `cacheTag` to guide developers in choosing and configuring revalidation strategies when using the 'use cache' directive.

```typescript
// ⚠️ CACHING STRATEGY DECISION NEEDED:
// This component uses "use cache" - decide on revalidation strategy
// 
// Uncomment ONLY ONE of the following strategies based on your needs:

// Option A: Time-based revalidation (most common)
// import { cacheLife } from 'next/cache';
// cacheLife('hours');  // Revalidates every hour, expires after 1 day

// Option B: On-demand tag-based revalidation
// import { cacheTag } from 'next/cache';
// cacheTag('resource-name');  // Tag for manual revalidation via updateTag/revalidateTag

// Option C: Long-term caching (use sparingly)
// import { cacheLife } from 'next/cache';
// cacheLife('max');  // Revalidates every 30 days, cached for 1 year

// Option D: Short-lived cache (frequently updated content)
// import { cacheLife } from 'next/cache';
// cacheLife('minutes');  // Revalidates every minute, expires after 1 hour

// Option E: Custom inline profile (advanced)
// import { cacheLife } from 'next/cache';
// cacheLife({ 
//   stale: 300,      // Client caches for 5 minutes
//   revalidate: 3600,  // Revalidates every hour
//   expire: 86400      // Expires after 24 hours
// });

export default async function Page() {
  "use cache";
  // User should uncomment and configure ONE of the cacheLife/cacheTag options above
  
  const data = await fetch('...');
  return <div>{data}</div>;
}
```

--------------------------------

### Runtime Prefetching Scenarios

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/04-runtime-prefetching.md

Illustrates three scenarios for runtime prefetching: in-page dynamic content, private cache, and passing promises to a public cache. Each scenario highlights what is included and excluded from the prefetch.

```typescript
// SCENARIO 1: in-page (no cache, just dynamic)
// Path: /in-page/cookies
export default async function Page() {
  const cookieStore = await cookies()
  const cookieValue = cookieStore.get('testCookie')?.value

  return (
    <>
      <div id="cookie-value">Cookie: {cookieValue}</div>
      <Suspense><Dynamic /></Suspense>
    </>
  )
}

// Runtime prefetch includes: ✅ Cookie value
// Runtime prefetch excludes: ❌ Dynamic content

// SCENARIO 2: in-private-cache
// Path: /in-private-cache/cookies
async function privateCache() {
  'use cache: private'
  const cookieStore = await cookies()
  const cookieValue = cookieStore.get('testCookie')?.value ?? null
  await cachedDelay([__filename, cookieValue])
  return cookieValue
}

// Runtime prefetch includes: ✅ Private cache result
// Runtime prefetch excludes: ❌ Dynamic content

// SCENARIO 3: passed-to-public-cache
// Path: /passed-to-public-cache/cookies
async function publicCache(cookiePromise: Promise<string | null>) {
  'use cache'
  const cookieValue = await cookiePromise
  await cachedDelay([__filename, cookieValue])
  return cookieValue
}

async function RuntimePrefetchable() {
  await cookies()  // Guard from static prerender

  const cookieValue = await publicCache(
    cookies().then(c => c.get('testCookie')?.value ?? null)
  )
  return <div id="cookie-value">Cookie: {cookieValue}</div>
}

// Pattern: Pass cookie Promise to public cache
// This allows public cache while still accessing cookies!
```

--------------------------------

### Search for PPR Configs

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Use grep to find occurrences of `experimental.ppr` and `experimental_ppr` in your project configuration and app files.

```bash
# Search for PPR configs
grep -r "experimental.ppr\|experimental_ppr" next.config.* app/ src/

```

--------------------------------

### Nested generateStaticParams Example

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Demonstrates how nested generateStaticParams functions in different layout files combine to generate all possible route combinations. Parent parameters can be accessed in child generateStaticParams functions.

```typescript
// app/[locale]/layout.tsx
export async function generateStaticParams() {
  return [{ locale: "en" }, { locale: "es" }]
}

// app/[locale]/[category]/layout.tsx
export async function generateStaticParams() {
  return [{ category: "tech" }, { category: "lifestyle" }]
}

// app/[locale]/[category]/[id]/page.tsx
export async function generateStaticParams() {
  // Can access parent params!
  return [{ id: "1" }, { id: "2" }]
}

// GENERATED ROUTES (all combinations):
// /en/tech/1
// /en/tech/2
// /en/lifestyle/1
// /en/lifestyle/2
// /es/tech/1
// /es/tech/2
// /es/lifestyle/1
// /es/lifestyle/2

// Total: 2 × 2 × 2 = 8 routes prerendered
```

--------------------------------

### Read Next.js Fundamentals 'use client' Resource

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Read about the usage and rationale for adding 'use client' directives in Next.js Server Components architecture using `resources/read`.

```jsonc
{ "method": "resources/read", "params": { "uri": "nextjs-fundamentals://use-client" } }
```

--------------------------------

### Migrate revalidate = 60 to cacheLife('minutes')

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Example migration for 'export const revalidate = 60'. Suggests adding 'use cache' and cacheLife('minutes') to maintain approximately 60s revalidation.

```typescript
// MIGRATED from: export const revalidate = 60
// → Add "use cache" + cacheLife('minutes') to maintain ~60s revalidation
import { cacheLife } from 'next/cache'

export default async function Page() {
  "use cache"
  cacheLife('minutes')  // Replaces: export const revalidate = 60
  // ...
}
```

--------------------------------

### Configure Runtime Prefetching

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Configure runtime prefetching for dynamic pages by providing sample request data. Static prefetching is the default and can be omitted.

```typescript
export const unstable_prefetch = {
  mode: 'runtime',
  samples: [
    {
      cookies: [{ name: string, value: string, httpOnly?: boolean, path?: string }],
      headers: [['name', 'value']],
      params: { key: 'value' },
      searchParams: { key: 'value' }
    }
  ]
}

// OR

export const unstable_prefetch = {
  mode: 'static'  // Default, can omit
}
```

--------------------------------

### Invoke enable-cache-components Prompt

Source: https://context7.com/vercel/next-devtools-mcp/llms.txt

Use the MCP GetPrompt method to invoke the `enable-cache-components` prompt, which provides a workflow for enabling Cache Components.

```jsonc
{ "method": "prompts/get", "params": { "name": "enable-cache-components", "arguments": { "project_path": "/my/app" } } }
```

--------------------------------

### Static vs. Dynamic Content in Prefetch

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Illustrates how static content within a component is prefetched and available instantly, while dynamic content is prefetched only up to its loading state. Navigation then streams the actual dynamic content.

```typescript
export default function Page() {
  return (
    <div id="nav">
      <div data-streaming-text-static="Static in nav">Static in nav</div>
      <Suspense fallback={<div>Loading... [Dynamic in nav]</div>}>
        <DynamicContent />
      </Suspense>
    </div>
  )
}

async function DynamicContent() {
  await connection()
  return <div data-streaming-text-dynamic="Dynamic in nav">Dynamic in nav</div>
}

// PREFETCH BEHAVIOR:
// 1. Link visible → Prefetch triggered
// 2. Prefetch includes: "Static in nav" ✅
// 3. Prefetch includes: "Loading... [Dynamic in nav]" ✅ (fallback)
// 4. Prefetch EXCLUDES: "Dynamic in nav" ❌ (actual content)

// NAVIGATION BEHAVIOR:
// 1. Click link (before dynamic loads)
// 2. Immediately show: "Static in nav" + "Loading... [Dynamic in nav]"
// 3. Then stream: "Dynamic in nav" (replaces loading)

// Key: Static shell renders instantly from prefetch cache
```

--------------------------------

### Passing Server Actions to Client Components

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs-fundamentals)/01-use-client.md

This example shows the correct way to handle events by passing a Server Action from a Server Component to a Client Component. The Server Action is executed on the server.

```typescript
// ✅ CORRECT - Use Server Action instead
'use server'
async function handleClickAction() {
  console.log('clicked on server')
}

// In Server Component:
import { InteractiveComponent } from '@/components/interactive'

export default function ServerComponent() {
  return <InteractiveComponent action={handleClickAction} />
}

// In Client Component:
'use client'
export function InteractiveComponent({ action }) {
  return <button onClick={() => action()}>Click me</button>
}
```

--------------------------------

### Migrate Runtime Config to .env Files

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(nextjs16)/migration/nextjs-16-migration-examples.md

Replace `serverRuntimeConfig` and `publicRuntimeConfig` in `next.config.js` with environment variables defined in `.env` files.

```diff
// ❌ BEFORE - next.config.js
module.exports = {
- serverRuntimeConfig: { apiKey: 'secret' },
- publicRuntimeConfig: { apiUrl: 'https://api.example.com' }
}

// ✅ AFTER - Use .env files
// .env.local
API_KEY=secret
NEXT_PUBLIC_API_URL=https://api.example.com
```

--------------------------------

### Mixed Cardinality generateStaticParams - High Card

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/resources/(cache-components)/12-reference.md

Defines static parameters for a high-cardinality route segment. This file is part of a mixed cardinality example where this parameter, if not present in the parent, will lead to partial prerendering or dynamic rendering.

```typescript
export async function generateStaticParams() {
  return [{ highcard: "build" }]
}
```

--------------------------------

### Load Cache Components Overview Resource

Source: https://github.com/vercel/next-devtools-mcp/blob/main/src/prompts/enable-cache-components-prompt.md

Loads the essential overview resource for Cache Components, providing critical context and highlighting common mistakes.

```plaintext
ReadMcpResourceTool(server="next-devtools", uri="cache-components://overview")
```