next-devtools-guide

# Next.js DevTools MCP

**Requirements**: Node.js v20.19+, npm or pnpm, Next.js 16+ for runtime diagnostics.

**Total capabilities**: 7 Tools + 2 Prompts + 17 Resources = 26 available features.

**Tool naming**: All tools follow `mcp__plugin_next-devtools_next-devtools__<tool-name>`. This file uses abbreviated names for brevity.

See `references/tools-reference.md` for the complete tools table and `nextjs_call` tool names.

## Tools (7)

| Tool | Purpose |
|------|---------|
| `init` | Initialize MCP context with documentation-first behavior |
| `nextjs_index` | Discover running Next.js dev servers and available MCP tools |
| `nextjs_call` | Call a specific MCP tool on a running Next.js dev server |
| `nextjs_docs` | Fetch Next.js official documentation by path |
| `browser_eval` | Playwright browser automation for testing |
| `enable_cache_components` | Migrate to Next.js 16 Cache Components mode |
| `upgrade_nextjs_16` | Guide through upgrade to Next.js 16 |

## Prompts (2)

| Prompt | Purpose |
|--------|---------|
| `upgrade-nextjs-16` | Complete upgrade guide including codemod execution and manual fixes |
| `enable-cache-components` | Complete Cache Components setup with automated error fixing |

## Resources (17)

**Cache Components (13):**
- `cache-components://overview` - Critical errors AI agents make, quick reference
- `cache-components://core-mechanics` - Fundamental paradigm shift and cacheComponents behavior
- `cache-components://public-caches` - Public cache mechanics using 'use cache'
- `cache-components://private-caches` - Private cache mechanics using 'use cache: private'
- `cache-components://runtime-prefetching` - Prefetch configuration and stale time rules
- `cache-components://request-apis` - Async params, searchParams, cookies(), headers() patterns
- `cache-components://cache-invalidation` - updateTag(), revalidateTag() patterns and strategies
- `cache-components://advanced-patterns` - cacheLife(), cacheTag(), draft mode
- `cache-components://build-behavior` - Prerendering, static shells, build-time behavior
- `cache-components://error-patterns` - Common errors and solutions
- `cache-components://test-patterns` - Real test-driven patterns from 125+ fixtures
- `cache-components://reference` - Mental models, API reference, checklists
- `cache-components://route-handlers` - Using 'use cache' in Route Handlers (API Routes)

**Other (4):**
- `nextjs-fundamentals://use-client` - Learn when and why to use 'use client' in Server Components
- `nextjs16://migration/beta-to-stable` - Complete guide for migrating from Next.js 16 beta to stable
- `nextjs16://migration/examples` - Real-world examples of migrating to Next.js 16
- `nextjs-docs://llms-index` - Complete Next.js documentation index

## Session Initialization

Call `init` at the start of every session to establish documentation-first behavior and tool usage guidance.

## Quick Start

**Next.js 16+ (runtime diagnostics):**

1. Start the dev server: `npm run dev` (or `pnpm dev`)
2. Call `init` to initialize MCP context
3. Call `nextjs_index` to discover the running server and available tools
4. Call `nextjs_call` with the desired `toolName` to execute tools on the dev server

**All Next.js versions (automation and docs):**

After `init`, use `upgrade_nextjs_16`, `enable_cache_components`, `nextjs_docs`, or `browser_eval` as needed.

## Common Workflows

**Before implementing changes**: Call `nextjs_index` to understand current application state, then `nextjs_call` with the appropriate tool.

**Error detection**: Call `nextjs_index`, then `nextjs_call` with `toolName="get_errors"`.

**Route inspection**: Call `nextjs_index`, then `nextjs_call` with `toolName="get_routes"`.

**Server Action tracing**: Call `nextjs_call` with `toolName="get_server_action_by_id"` and appropriate args.

**Documentation search**: Read the `nextjs-docs://llms-index` MCP resource to get the correct path, then call `nextjs_docs` with that path.

**Important**: The `args` parameter for `nextjs_call` MUST be an object. Omit `args` entirely if the tool takes no arguments.

## Troubleshooting

**MCP server not connecting:**

- Verify Next.js v16+
- Confirm `next-devtools-mcp` is configured in `.mcp.json`
- Start or restart the dev server (`npm run dev`)
- If `nextjs_index` auto-discovery fails, ask the user which port their dev server is running on and pass it as the `port` parameter

**"No server info found"**: Dev server must be running. Use the `upgrade_nextjs_16` tool if on Next.js 15 or earlier.

**Module not found**: Clear the npx cache and restart the MCP client.

## Best Practices

- Call `init` at session start before using other tools
- Start the dev server before using `nextjs_index` or `nextjs_call`
- Prefer `nextjs_index`/`nextjs_call` over `browser_eval` for error detection and diagnostics
- Use `browser_eval` only for tasks requiring actual page rendering or JavaScript execution
- Read `nextjs-docs://llms-index` resource first before calling `nextjs_docs`