将编码代理连接到 Next.js MCP 服务器
了解如何通过内置 MCP 端点让编码代理访问你正在运行的 Next.js 应用。
Model Context Protocol (MCP) 是一项开放标准,可让 AI 代理和编码助手通过一个共享接口与你的应用程序交互。
在 Next.js 16 及更高版本中,开发服务器在 /_next/mcp 暴露一个 MCP 端点。它为编码代理提供正在运行的应用的错误、路由、日志和编译问题视图。要将你的代理客户端连接到它,请安装 next-devtools-mcp 包。
诸如 next-dev-loop 之类的 Skills 会直接调用 /_next/mcp,因此无需此设置即可工作。
开始使用#
使用 add-mcp 为你机器上的编码代理安装 next-devtools-mcp:
npx add-mcp next-devtools-mcp@latest或者将其添加到项目根目录的 .mcp.json 文件中:
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}当你启动开发服务器时,next-devtools-mcp 会发现并连接到正在运行的 Next.js 实例。针对特定客户端的设置,请参阅 next-devtools-mcp 仓库。
功能#
next-devtools-mcp 将你的代理客户端连接到 Next.js 开发服务器。它为代理提供以下工具:
nextjs_index:发现正在运行的 Next.js 开发服务器,并列出每个服务器暴露的运行时工具。nextjs_call:在已发现的开发服务器上调用运行时工具。nextjs_docs:为代理指明与版本匹配的文档,这些文档随你安装的 Next.js 一起提供,位于node_modules/next/dist/docs/。browser_eval:为代理指明agent-browserCLI,用于在真实浏览器中验证页面。
nextjs_docs 和 browser_eval 本身并不执行具体工作。它们只是告诉代理文档的位置或如何运行 CLI,然后代理直接使用它们。
运行时工具#
通过 nextjs_call,代理可以使用 Next.js 开发服务器在 /_next/mcp 暴露的工具:
get_errors:获取当前错误状态,包括 Next.js 全局错误(如next.config校验错误)、浏览器运行时错误,以及带有源码映射堆栈跟踪的构建错误。get_logs:获取开发日志文件的路径,其中包含浏览器控制台日志和服务端输出。get_page_metadata:获取有关当前页面渲染构成要素的运行时元数据。需要在浏览器中打开该页面。get_project_metadata:获取项目路径和开发服务器 URL。get_routes:通过扫描文件系统获取所有将成为入口点的路由。返回按 router 类型(appRouter、pagesRouter)分组的路由。动态段以[param]或[...slug]模式显示。get_server_action_by_id:根据 ID 查找 Server Action,以找到其源文件和导出名称。get_compilation_issues:为所有路由构建模块图,并返回解析错误、模块缺失和转换错误等编译问题。不需要浏览器会话。仅支持 Turbopack。compile_route:编译特定路由而无需向其发出 HTTP 请求。接受routeSpecifier(例如get_routes返回的/blog/[slug])或path(例如/blog/hello-world),后者会解析为匹配的路由。返回该路由的所有编译问题。仅支持 Turbopack。get_request_insights:获取由本地 span 记录器捕获的近期 App Router 请求时间线、服务端 fetch 和缓存行为。需要启用experimental.requestInsights。
借助这些编译工具,代理可以直接从正在运行的开发服务器检查代码是否能编译,而无需在仍在编辑时运行 next build。
开发工作流#
- 启动你的 Next.js 开发服务器:
pnpm devnpm run devyarn devbun dev- 你的编码代理通过
next-devtools-mcp连接到正在运行的 Next.js 实例。 - 在浏览器中打开你正在开发的页面。
get_errors和get_page_metadata等工具会读取活动的浏览器会话。 - 向你的代理询问正在运行的应用,如下面的示例所示。
示例#
错误检测与诊断#
向你的代理询问正在运行的应用中的错误:
What errors are currently in my application?代理将:
- 使用
nextjs_index发现正在运行的开发服务器 - 通过
nextjs_call调用get_errors以获取当前错误 - 分析错误并建议修复方案
<details> <summary>Agent 响应(点击展开)</summary>
> 修复页面上的错误
⏺ 在更改任何内容之前,我会先检查正在运行的应用报告了哪些错误。
⏺ next-devtools - nextjs_index (MCP)
⏺ next-devtools - nextjs_call (MCP)(port: 3000, toolName: "get_errors")
⎿ # 在 1 个浏览器会话中发现错误
## 会话:/about
**发现 1 个错误**
### 运行时错误
#### 错误 1(类型:可恢复)
**错误**:水合失败,因为服务端渲染的文本与客户端不匹配。
⏺ /about 页面在服务端渲染 "server",在浏览器中渲染 "client",
这会导致水合不匹配。我会修复该组件并再次检查。</details>
概念与最佳实践#
提出概念性问题:
When should I use 'use client' in the App Router?代理会读取随项目提供的、与版本匹配的 Next.js 文档,并结合你的代码库中的示例进行回答。
工作原理#
Next.js 16 及更高版本的开发服务器在 /_next/mcp 运行一个内置 MCP 端点。next-devtools-mcp 包会发现这些端点并与之通信,因此它可以:
- 连接到运行在不同端口上的多个 Next.js 实例
- 将工具调用转发到正确的 Next.js 开发服务器
- 为每个实例向代理提供一套统一的工具
通过 next-devtools-mcp 连接的代理在不同 Next.js 项目和版本中使用相同的设置。
该端点默认启用。要禁用它,请在 next.config 中将 experimental.mcpServer 设置为 false。
故障排除#
MCP 服务器无法连接#
- 使用 Next.js 16 或更高版本
- 确认
next-devtools-mcp已在你的代理客户端中配置,例如在.mcp.json中 - 检查
next.config中experimental.mcpServer未被设置为false - 使用
npm run dev启动开发服务器,如果它已在运行则重启 - 检查你的编码代理是否已加载 MCP 服务器配置