Skip to content

docs: update MCP guides for the thin next-devtools-mcp #94859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gaojude wants to merge 1 commit into
base: canary
Choose a base branch
from
+7 −37
Open

docs: update MCP guides for the thin next-devtools-mcp #94859

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 3 additions & 5 deletions docs/01-app/02-guides/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -159,15 +157,15 @@ 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:

```bash
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

Expand Down
36 changes: 4 additions & 32 deletions docs/01-app/02-guides/upgrading/version-16.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
{
Expand All @@ -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

Expand Down
Loading