用途:在 next dev 过程中建立“编辑—验证”节奏。改完代码后,不仅确认类型或构建通过,还要确认运行时确实按预期工作,并通过同一运行应用的两种视角交叉核对。
主要能力: /_next/mcp 是 Next.js 暴露自身信息的 HTTP 端点,了解路由、segment、RSC、server actions、服务端日志以及 Next.js 所看到的错误,可用 tools/list 查看当前工具面。 agent-browser 是驱动真实 Chrome 的 CLI,了解与框架无关的浏览器信息:DOM、console、network、React fiber、vitals。 二者互相验证。
使用方式:先做 preflight,确认两个视角可用;为当前 checkout 派生稳定 session id(agent-browser session id --scope worktree --prefix next-dev-loop),设置 AGENT_BROWSER_SESSION 与 AGENT_BROWSER_RESTORE,再用 agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url> 打开目标 URL。若首次运行或会话过期且页面受限,由用户完成登录。随后探测 /_next/mcp 的 tools/list,确认 get_compilation_issues 存在,并读取 next dev 横幅端口,非 3000 时设置 NEXT_MCP_URL。编辑前用 get_routes 等缩小搜索范围,编辑后按四类失败模式逐一检查:能否编译、运行是否报错、行为是否符合预期、React 层行为是否正常。
限制与要求:需 Next.js 16.3+ 且使用 Turbopack(/_next/mcp 与 get_compilation_issues 的前提),agent-browser 需 >= 0.31.1。这些是硬性下限,缺失时应告知用户升级方法并停止,不要退回到 grep 源码或更弱的探测。升级 Next.js 可用 pnpm next upgrade 或 npx next upgrade;安装或升级 agent-browser 用 npm i -g agent-browser@latest。每条 agent-browser 命令都必须带上 session 与 restore 上下文,否则可能使用空的默认浏览器或无法保存登录状态。两个视角不一致时,应先怀疑工具(如过期或指向错误的浏览器会话),再调试应用。/_next/mcp 回复是 SSE,需从 data: 行读取 JSON。get_errors 与 get_page_metadata 需至少一次导航后才有数据。结束时用同一 session 与 restore 上下文执行 close 以保存 cookie,保持 next dev 运行以便下一轮。
适用场景:在 Next.js 应用开发中需要验证改动实际运行时效果,特别是涉及路由、RSC、server actions、React 渲染行为等框架级问题时。