Next.js DevTools MCP

Automate and test web applications using Playwright browser automation. This tool connects to playwright-mcp server and provides access to all Playwright capabilities. CRITICAL FOR PAGE VERIFICATION: When verifying pages in Next.js projects (especially during upgrades or testing), you MUST use browser automation to load pages in a real browser instead of curl or simple HTTP requests. This is because: - Browser automation actually renders the page and executes JavaScript (curl only fetches HTML) - Detects runtime errors, hydration issues, and client-side problems that curl cannot catch - Verifies the full user experience, not just HTTP status codes - Captures browser console errors and warnings via console_messages action IMPORTANT FOR NEXT.JS PROJECTS: If working with a Next.js application, PRIORITIZE using the 'nextjs_index' and 'nextjs_call' tools instead of browser console log forwarding. Next.js has built-in MCP integration that provides superior error reporting, build diagnostics, and runtime information directly from the Next.js dev server. Only use browser_eval's console_messages action as a fallback when these Next.js tools are not available or when you specifically need to test client-side browser behavior that Next.js runtime cannot capture. Available actions: - start: Start browser automation (automatically installs if needed). Verbose logging is always enabled. - navigate: Navigate to a URL - click: Click on an element - type: Type text into an element - fill_form: Fill multiple form fields at once - evaluate: Execute JavaScript in browser context - screenshot: Take a screenshot of the page - console_messages: Get browser console messages (for Next.js, prefer nextjs_index/nextjs_call tools instead) - close: Close the browser - drag: Perform drag and drop - upload_file: Upload files - list_tools: List all available browser automation tools from the server Note: The playwright-mcp server will be automatically installed if not present.

Migrate Next.js applications to Cache Components mode and complete setup for Next.js 16. Use this tool when you need to: - Migrate to Cache Components mode - Migrate to cache components - Enable Cache Components - Set up Cache Components - Convert to Cache Components This tool handles ALL steps for migrating and enabling Cache Components: - Configuration: Updates cacheComponents flag (experimental in 16.0.0, stable in canary > 16), removes incompatible flags - Dev Server: Starts dev server (MCP is enabled by default in Next.js 16+) - Error Detection: Loads all routes via browser automation, collects errors using Next.js MCP - Automated Fixing: Adds Suspense boundaries, "use cache" directives, generateStaticParams, cacheLife profiles, cache tags - Verification: Validates all routes work with zero errors Key Features: - One-time dev server start (no restarts needed) - Automated error detection using Next.js MCP tools - Browser-based testing with browser automation - Fast Refresh applies fixes instantly - Comprehensive fix strategies for all error types - Support for "use cache", "use cache: private", Suspense boundaries - Cache invalidation with cacheTag() and cacheLife() configuration Requires: - Next.js 16.0.0+ (stable or canary only - beta versions are NOT supported) - Clean working directory preferred - Browser automation installed (auto-installed if needed) This tool embeds complete knowledge base for: - Cache Components mechanics - Error patterns and solutions - Caching strategies (static vs dynamic) - Advanced patterns (cacheLife, cacheTag, draft mode) - Build behavior and prefetching - Test-driven patterns from 125+ fixtures

⚠️ CALL THIS FIRST - Initialize Next.js DevTools MCP context and establish MANDATORY documentation requirements. **IMPORTANT: This tool MUST be called at the START of every Next.js development session.** This tool: - Establishes MANDATORY requirement to use nextjs_docs for ALL Next.js-related queries - Instructs AI to forget any prior Next.js knowledge and always query docs - Documents all available MCP tools (nextjs_docs, nextjs_index, nextjs_call, browser_eval, upgrade_nextjs_16, enable_cache_components) Use this tool at the beginning of a Next.js session to: - Reset AI's Next.js knowledge baseline - Ensure 100% documentation-first approach with no exceptions - Understand available tools and their use cases - Follow best practices for Next.js development

Fetch Next.js official documentation by path. IMPORTANT: You MUST first read the `nextjs-docs://llms-index` MCP resource to get the correct path. Do NOT guess paths. Workflow: 1. Read the `nextjs-docs://llms-index` resource to get the documentation index 2. Find the relevant path in the index for what you're looking for 3. Call this tool with that exact path Example: nextjs_docs({ path: "/docs/app/api-reference/functions/refresh" })

Discover all running Next.js development servers and list their available MCP tools. WHEN TO USE THIS TOOL - Use proactively in these scenarios: 1. **Before implementing ANY changes to the app**: When asked to add, modify, or fix anything in the application: - "Add a loading state" → Check current component structure and routes first - "Fix the navigation" → Inspect existing routes and components - "Update the API endpoint" → Query current routes and data flows - "Add error handling" → Check runtime errors and component hierarchy - "Refactor the auth logic" → Inspect current auth implementation and routes - "Optimize performance" → Check runtime diagnostics and component tree Use this to understand where changes should be made and what currently exists. 2. **For diagnostic and investigation questions**: - "What's happening?" / "What's going on?" / "Why isn't this working?" - "Check the errors" / "See what's wrong" - "What routes are available?" / "Show me the routes" - "Clear the cache" / "Reset everything" - Questions about build status, compilation errors, or runtime diagnostics 3. **For agentic codebase search**: Use this as FIRST CHOICE for searching the currently running app. If not found, fallback to static codebase search tools. KEY PRINCIPLE: If the request involves the running Next.js application (whether to investigate OR modify it), query the runtime FIRST to understand current state before proceeding. REQUIREMENTS: - Next.js 16 or later (MCP support was added in v16) - If you're on Next.js 15 or earlier, use the 'upgrade-nextjs-16' MCP prompt to upgrade first Next.js 16+ exposes an MCP (Model Context Protocol) endpoint at /_next/mcp automatically when the dev server starts. No configuration needed - MCP is enabled by default in Next.js 16 and later. This tool discovers all running Next.js servers and returns: - Server port, PID, and URL - Complete list of available MCP tools for each server - Tool descriptions and input schemas After calling this tool, use 'nextjs_call' to execute specific tools. [IMPORTANT] If auto-discovery returns no servers: 1. Ask the user which port their Next.js dev server is running on 2. Call this tool again with the 'port' parameter set to the user-provided port If the MCP endpoint is not available: 1. Ensure you're running Next.js 16 or later (use the 'upgrade-nextjs-16' prompt to upgrade) 2. Verify the dev server is running (npm run dev) 3. Check that the dev server started successfully without errors

Guide through upgrading Next.js to version 16. CRITICAL: Runs the official codemod FIRST (requires clean git state) for automatic upgrades and fixes, then handles remaining issues manually. The codemod upgrades Next.js, React, and React DOM automatically. Covers async API changes, config moves, image defaults, parallel routes, and deprecations.

Complete Cache Components setup for Next.js 16. Handles ALL steps: updates experimental.cacheComponents flag, removes incompatible flags, migrates Route Segment Config, starts dev server with MCP, detects all errors via chrome_devtools + get_errors, automatically fixes all issues by adding Suspense boundaries, 'use cache' directives, generateStaticParams, cacheLife profiles, cache tags, and validates everything with zero errors.

Critical errors AI agents make, quick reference for Cache Components

Fundamental paradigm shift and cacheComponents behavior

Public cache mechanics using 'use cache'

Private cache mechanics using 'use cache: private'

Prefetch configuration and stale time rules