NNext.js 中文网 GitHub

将编码代理连接到 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:

Terminal
npx add-mcp next-devtools-mcp@latest

或者将其添加到项目根目录的 .mcp.json 文件中:

.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-browser CLI,用于在真实浏览器中验证页面。

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。

开发工作流#

  1. 启动你的 Next.js 开发服务器:
bash · pnpm
pnpm dev
bash · npm
npm run dev
bash · yarn
yarn dev
bash · bun
bun dev
  1. 你的编码代理通过 next-devtools-mcp 连接到正在运行的 Next.js 实例。
  2. 在浏览器中打开你正在开发的页面。get_errors 和 get_page_metadata 等工具会读取活动的浏览器会话。
  3. 向你的代理询问正在运行的应用,如下面的示例所示。

示例#

错误检测与诊断#

向你的代理询问正在运行的应用中的错误:

prompt
What errors are currently in my application?

代理将:

  • 使用 nextjs_index 发现正在运行的开发服务器
  • 通过 nextjs_call 调用 get_errors 以获取当前错误
  • 分析错误并建议修复方案

<details> <summary>Agent 响应(点击展开)</summary>

txt
> 修复页面上的错误

⏺ 在更改任何内容之前,我会先检查正在运行的应用报告了哪些错误。

⏺ next-devtools - nextjs_index (MCP)
⏺ next-devtools - nextjs_call (MCP)(port: 3000, toolName: "get_errors")
  ⎿ # 在 1 个浏览器会话中发现错误

    ## 会话:/about

    **发现 1 个错误**

    ### 运行时错误

    #### 错误 1(类型:可恢复)

    **错误**:水合失败,因为服务端渲染的文本与客户端不匹配。

⏺ /about 页面在服务端渲染 "server",在浏览器中渲染 "client",
  这会导致水合不匹配。我会修复该组件并再次检查。

</details>

概念与最佳实践#

提出概念性问题:

prompt
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 服务器配置
Next.js 中文网