From 9c37a35358efb20d3b06afa97893e084ed4880a5 Mon Sep 17 00:00:00 2001 From: Jude Gao Date: Tue, 16 Jun 2026 11:10:51 -0400 Subject: [PATCH] docs: update MCP guides for thin next-devtools-mcp The next-devtools-mcp knowledge-base and migration tools are being replaced by the docs Next.js bundles in node_modules/next/dist/docs/ and by the upgrade codemod. Update the MCP guide capabilities and the v16 upgrade guide to describe the docs gateway, runtime diagnostics, and codemod-based upgrades instead of the removed knowledge-base/upgrade/cache-components tools. --- docs/01-app/02-guides/mcp.mdx | 8 ++--- .../01-app/02-guides/upgrading/version-16.mdx | 36 +++---------------- 2 files changed, 7 insertions(+), 37 deletions(-) diff --git a/docs/01-app/02-guides/mcp.mdx b/docs/01-app/02-guides/mcp.mdx index d94f6ae327c8..364ce3c903ff 100644 --- a/docs/01-app/02-guides/mcp.mdx +++ b/docs/01-app/02-guides/mcp.mdx @@ -43,9 +43,7 @@ For more configuration options, see the [next-devtools-mcp repository](https://g ### Development Tools -- **Next.js Knowledge Base**: Query comprehensive Next.js documentation and best practices -- **Migration and Upgrade Tools**: Automated helpers for upgrading to Next.js 16 with codemods -- **Caching Guide**: Setup and configuration assistance for Cache Components +- **Documentation Gateway**: Points your agent at the version-accurate docs bundled with your installed Next.js (in `node_modules/next/dist/docs/`), so explanations and generated code match the version you are running - **Browser Testing**: [Playwright MCP](https://github.com/microsoft/playwright-mcp) integration for verifying pages in the browser > **Note:** The Next.js team is actively expanding these capabilities. New tools and features are added regularly to improve the agent development experience. @@ -159,7 +157,7 @@ Get help with Next.js concepts and migrations: User: "Help me upgrade my Next.js app to version 16" ``` -The agent will analyze your current version, guide you through automated migrations with codemods, and provide step-by-step instructions for handling breaking changes. +The agent will run the official upgrade codemod (`npx @next/codemod@latest upgrade latest`) and provide step-by-step instructions for handling breaking changes. Ask conceptual questions: @@ -167,7 +165,7 @@ Ask conceptual questions: User: "When should I use 'use client' in App Router?" ``` -The agent will query the Next.js knowledge base and provide documentation-backed explanations with examples from your codebase. +The agent will read the version-accurate Next.js docs bundled with your project and provide documentation-backed explanations with examples from your codebase. ## How it works diff --git a/docs/01-app/02-guides/upgrading/version-16.mdx b/docs/01-app/02-guides/upgrading/version-16.mdx index 28597b088fe5..8c2205e6802f 100644 --- a/docs/01-app/02-guides/upgrading/version-16.mdx +++ b/docs/01-app/02-guides/upgrading/version-16.mdx @@ -8,15 +8,11 @@ description: Upgrade your Next.js Application from Version 15 to 16. ## Upgrading from 15 to 16 -### Using AI Agents with Next.js DevTools MCP +### Using AI Agents -If you're using an AI coding assistant that supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), you can use the **Next.js DevTools MCP** to automate the upgrade process and migration tasks. +If you're using an AI coding assistant, it can run the upgrade for you with the [codemod](#using-the-codemod) below and then help resolve any remaining breaking changes. -#### Setup - -Add the following configuration to your MCP client, for each coding agent you can read [this section](https://github.com/vercel/next-devtools-mcp#mcp-client-configuration) for configuration details. - -**example:** +For the best results, also configure the [`next-devtools-mcp`](https://github.com/vercel/next-devtools-mcp) server. It lets your agent inspect your running dev server for migration errors and read the version-accurate Next.js docs bundled with your project: ```json filename=".mcp.json" { @@ -29,31 +25,7 @@ Add the following configuration to your MCP client, for each coding agent you ca } ``` -For more information, visit the [`next-devtools-mcp`](https://github.com/vercel/next-devtools-mcp) documentation to configure with your MCP client. - -> **Note:** Using `next-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Next.js DevTools MCP server. - -#### Example Prompts - -Once configured, you can use natural language prompts to upgrade your Next.js app: - -**To upgrade to Next.js 16:** - -Connect to your coding agent and then prompt: - -```txt -Next Devtools, help me upgrade my Next.js app to version 16 -``` - -**To migrate to Cache Components (after upgrading to v16):** - -Connect to your coding agent and then prompt: - -```txt -Next Devtools, migrate my Next.js app to cache components -``` - -Learn more in the documentation [here](/docs/app/guides/mcp). +See the [Next.js MCP guide](/docs/app/guides/mcp) and the [`next-devtools-mcp` documentation](https://github.com/vercel/next-devtools-mcp#mcp-client-configuration) for client setup. Then ask your agent to upgrade your app — it will run the codemod and use the dev server's diagnostics to fix breaking changes. ### Using the Codemod