[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-vercel--next-devtools-mcp":3,"tool-vercel--next-devtools-mcp":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",148568,2,"2026-04-09T23:34:24",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":78,"owner_twitter":77,"owner_website":79,"owner_url":80,"languages":81,"stars":90,"forks":91,"last_commit_at":92,"license":77,"difficulty_score":32,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":101,"github_topics":102,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":108,"updated_at":109,"faqs":110,"releases":143},6139,"vercel\u002Fnext-devtools-mcp","next-devtools-mcp","Next.js Development for Coding Agent","next-devtools-mcp 是一款专为 Next.js 开发打造的智能辅助工具，它基于模型上下文协议（MCP）构建，旨在让 Claude、Cursor 等 AI 编程助手更深入地理解并操作 Next.js 项目。\n\n在开发复杂的 Next.js 应用时，通用型 AI 往往难以精准掌握框架特有的路由规则、服务端渲染机制或目录结构，导致生成的代码需要大量人工修正。next-devtools-mcp 通过提供专用的开发工具集，填补了这一空白。它能将项目的上下文信息准确传递给 AI，使助手能够执行更精准的文件生成、配置调整及错误排查任务，从而显著提升开发效率与代码质量。\n\n这款工具主要面向使用 Next.js 进行全栈或前端开发的程序员，特别是那些已经习惯借助 AI 编辑器（如 Cursor、VS Code Copilot）或终端助手（如 Claude Code）来提升工作流的开发者。其核心亮点在于广泛的兼容性，支持一键集成到主流 AI 开发环境中，无论是通过命令行快速安装，还是手动配置 JSON，都能轻松启用。只需简单的设置，即可让现有的 AI 助手瞬间变身成为精通 Next.js ","next-devtools-mcp 是一款专为 Next.js 开发打造的智能辅助工具，它基于模型上下文协议（MCP）构建，旨在让 Claude、Cursor 等 AI 编程助手更深入地理解并操作 Next.js 项目。\n\n在开发复杂的 Next.js 应用时，通用型 AI 往往难以精准掌握框架特有的路由规则、服务端渲染机制或目录结构，导致生成的代码需要大量人工修正。next-devtools-mcp 通过提供专用的开发工具集，填补了这一空白。它能将项目的上下文信息准确传递给 AI，使助手能够执行更精准的文件生成、配置调整及错误排查任务，从而显著提升开发效率与代码质量。\n\n这款工具主要面向使用 Next.js 进行全栈或前端开发的程序员，特别是那些已经习惯借助 AI 编辑器（如 Cursor、VS Code Copilot）或终端助手（如 Claude Code）来提升工作流的开发者。其核心亮点在于广泛的兼容性，支持一键集成到主流 AI 开发环境中，无论是通过命令行快速安装，还是手动配置 JSON，都能轻松启用。只需简单的设置，即可让现有的 AI 助手瞬间变身成为精通 Next.js 的专家伙伴，让编码过程更加流畅自然。","# Next.js DevTools MCP\n\n[![npm next-devtools-mcp package](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fnext-devtools-mcp.svg)](https:\u002F\u002Fnpmjs.org\u002Fpackage\u002Fnext-devtools-mcp)\n\n`next-devtools-mcp` is a Model Context Protocol (MCP) server that provides Next.js development tools and utilities for coding agents like Claude and Cursor.\n\n\n## Getting Started\n\n### Requirements\n\n- [Node.js](https:\u002F\u002Fnodejs.org\u002F) v20.19 or a newer [latest maintenance LTS](https:\u002F\u002Fgithub.com\u002Fnodejs\u002FRelease#release-schedule) version\n- [npm](https:\u002F\u002Fwww.npmjs.com\u002F) or [pnpm](https:\u002F\u002Fpnpm.io\u002F)\n\n\n### Install with add-mcp\n\nInstall the MCP server for all your coding agents:\n\n```bash\nnpx add-mcp next-devtools-mcp@latest\n```\n\nAdd `-y` to skip the confirmation prompt and install to all detected agents already in use in the project directory. Add `-g` to install globally across all projects.\n\n\n### Manual installation\n\nAdd the following config to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> Using `next-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Next.js DevTools MCP server.\n\n### MCP Client Configuration\n\n\u003Cdetails>\n\u003Csummary>Amp\u003C\u002Fsummary>\n\n**Using Amp CLI:**\n\n```bash\namp mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\n**Or configure manually:**\n\nFollow [Amp's MCP documentation](https:\u002F\u002Fampcode.com\u002Fmanual#mcp) and apply the standard configuration shown above.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Claude Code\u003C\u002Fsummary>\n\nUse the Claude Code CLI to add the Next.js DevTools MCP server:\n\n```bash\nclaude mcp add next-devtools npx next-devtools-mcp@latest\n```\n\nAlternatively, manually configure Claude by editing your MCP settings file and adding the configuration shown above.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Codex\u003C\u002Fsummary>\n\n**Using Codex CLI:**\n\n```bash\ncodex mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\n**Or configure manually:**\n\nFollow the MCP setup guide with the standard configuration format:\n- Command: `npx`\n- Arguments: `-y, next-devtools-mcp@latest`\n\n**Windows 11 Special Configuration:**\n\nUpdate `.codex\u002Fconfig.toml` with environment variables and increased startup timeout:\n\n```toml\nenv = { SystemRoot=\"C:\\\\Windows\", PROGRAMFILES=\"C:\\\\Program Files\" }\nstartup_timeout_ms = 20_000\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Cursor\u003C\u002Fsummary>\n\n**Click the button to install:**\n\n[Install in Cursor](https:\u002F\u002Fcursor.com\u002Fen\u002Finstall-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)\n\n**Or install manually:**\n\nGo to `Cursor Settings` → `MCP` → `New MCP Server`. Use the config provided above.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Gemini\u003C\u002Fsummary>\n\n**Using Gemini CLI:**\n\nProject-wide installation:\n```bash\ngemini mcp add next-devtools npx next-devtools-mcp@latest\n```\n\nGlobal installation:\n```bash\ngemini mcp add -s user next-devtools npx next-devtools-mcp@latest\n```\n\n**Or configure manually:**\n\nFollow the MCP setup guide with these parameters:\n- Command: `npx`\n- Arguments: `-y, next-devtools-mcp@latest`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Google Antigravity\u003C\u002Fsummary>\n\n**Configure in MCP config file:**\n\nAdd this to your Antigravity MCP config file: `.gemini\u002Fantigravity\u002Fmcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\nSee [Antigravity MCP docs](https:\u002F\u002Fantigravity.google\u002Fdocs\u002Fmcp) for more info.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>VS Code \u002F Copilot\u003C\u002Fsummary>\n\n**Using VS Code CLI:**\n\n```bash\ncode --add-mcp '{\"name\":\"next-devtools\",\"command\":\"npx\",\"args\":[\"-y\",\"next-devtools-mcp@latest\"]}'\n```\n\n**Or configure manually:**\n\nFollow the official VS Code MCP server setup guide and add the Next.js DevTools server through VS Code settings.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Warp\u003C\u002Fsummary>\n\n**Using Warp UI:**\n\nNavigate to `Settings | AI | Manage MCP Servers` and select `+ Add` to register a new MCP server with the following configuration:\n- Name: `next-devtools`\n- Command: `npx`\n- Arguments: `-y, next-devtools-mcp@latest`\n\n\u003C\u002Fdetails>\n\n## Quick Start\n\n### For Next.js 16+ Projects (Recommended)\n\nTo unlock the full power of runtime diagnostics, start your Next.js dev server:\n\n```bash\nnpm run dev\n```\n\nNext.js 16+ has MCP enabled by default at `http:\u002F\u002Flocalhost:3000\u002F_next\u002Fmcp` (or whichever port your dev server uses). The `next-devtools-mcp` server will automatically discover and connect to it.\n\n**⚠️ IMPORTANT: Start every Next.js session by calling the `init` tool to set up proper context:**\n\n```\nUse the init tool to set up Next.js DevTools context\n```\n\nThis initializes the MCP context and ensures the AI assistant uses official Next.js documentation for all queries.\n\n**After initialization, try these prompts to explore runtime diagnostics:**\n\n```\nNext Devtools, what errors are in my Next.js application?\n```\n\n```\nNext Devtools, show me the structure of my routes\n```\n\n```\nNext Devtools, what's in the development server logs?\n```\n\nYour coding agent will use the `nextjs_index` and `nextjs_call` tools to query your running application's actual state.\n\n### For All Next.js Projects\n\nYou can use the development automation and documentation tools regardless of Next.js version:\n\n```\nNext Devtools, help me upgrade my Next.js app to version 16\n```\n\n```\nNext Devtools, enable Cache Components in my Next.js app\n```\n\n```\nNext Devtools, search Next.js docs for generateMetadata\n```\n\n### 💡 Pro Tip: Auto-Initialize on Every Session\n\nTo make your AI assistant **automatically call the `init` tool** at the start of every Next.js session without being asked, add this instruction to your agent's configuration file:\n\n\u003Cdetails>\n\u003Csummary>Claude Code \u002F Claude Desktop\u003C\u002Fsummary>\n\nAdd to `~\u002F.claude\u002FCLAUDE.md` (global) or `.\u002F.claude\u002FCLAUDE.md` (project-specific):\n\n```markdown\n**When starting work on a Next.js project, ALWAYS call the `init` tool from\nnext-devtools-mcp FIRST to set up proper context and establish documentation\nrequirements. Do this automatically without being asked.**\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Cursor\u003C\u002Fsummary>\n\nAdd to `.cursorrules` in your project root or global Cursor settings:\n\n```\nWhen working with Next.js, always call the init tool from next-devtools-mcp\nat the start of the session to establish proper context and documentation requirements.\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Codex \u002F Other AI Coding Assistants\u003C\u002Fsummary>\n\nAdd to your agent's configuration file (e.g., `.codex\u002Finstructions.md`, `agent.md`, or similar):\n\n```markdown\n**Next.js Initialization**: When starting work on a Next.js project, automatically\ncall the `init` tool from the next-devtools-mcp server FIRST. This establishes\nproper context and ensures all Next.js queries use official documentation.\n```\n\n\u003C\u002Fdetails>\n\n**Why this matters:**\n- ✅ Ensures consistent context across all Next.js work\n- ✅ Automatically establishes the documentation-first requirement\n- ✅ No need to manually call init every time\n- ✅ Works across all your Next.js projects\n\n## MCP Resources\n\nThe knowledge base resources are automatically available to your coding agent and are split into focused sections for efficient context management. Current resource URIs:\n\n\u003Cdetails>\n\u003Csummary>📚 Available Knowledge Base Resources (click to expand)\u003C\u002Fsummary>\n\n- Cache Components (12 sections):\n  - `cache-components:\u002F\u002Foverview`\n  - `cache-components:\u002F\u002Fcore-mechanics`\n  - `cache-components:\u002F\u002Fpublic-caches`\n  - `cache-components:\u002F\u002Fprivate-caches`\n  - `cache-components:\u002F\u002Fruntime-prefetching`\n  - `cache-components:\u002F\u002Frequest-apis`\n  - `cache-components:\u002F\u002Fcache-invalidation`\n  - `cache-components:\u002F\u002Fadvanced-patterns`\n  - `cache-components:\u002F\u002Fbuild-behavior`\n  - `cache-components:\u002F\u002Ferror-patterns`\n  - `cache-components:\u002F\u002Ftest-patterns`\n  - `cache-components:\u002F\u002Freference`\n\n- Next.js 16 migration:\n  - `nextjs16:\u002F\u002Fmigration\u002Fbeta-to-stable`\n  - `nextjs16:\u002F\u002Fmigration\u002Fexamples`\n\n- Next.js fundamentals:\n  - `nextjs-fundamentals:\u002F\u002Fuse-client`\n\n\u003C\u002Fdetails>\n\nResources are loaded on-demand by your coding agent, providing targeted knowledge without overwhelming the context window.\n\n## MCP Prompts\n\nPre-configured prompts to help with common Next.js development tasks:\n\n\u003Cdetails>\n\u003Csummary>💡 Available Prompts (click to expand)\u003C\u002Fsummary>\n\n- **`upgrade-nextjs-16`** - Guide for upgrading to Next.js 16\n- **`enable-cache-components`** - Migrate and enable Cache Components mode for Next.js 16\n\n\u003C\u002Fdetails>\n\n## MCP Tools\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>init\u003C\u002Fcode>\u003C\u002Fsummary>\n\nInitialize Next.js DevTools MCP context and establish documentation requirements.\n\n**Capabilities:**\n- Sets up proper context for AI assistants working with Next.js\n- Establishes requirement to use `nextjs_docs` for ALL Next.js-related queries\n- Documents all available MCP tools and their use cases\n- Provides best practices for Next.js development with MCP\n- Includes example workflows and quick start checklist\n\n**When to use:**\n- At the beginning of a Next.js development session\n- To understand available tools and establish proper context\n- To ensure documentation-first approach for Next.js development\n\n**Input:**\n- `project_path` (optional) - Path to Next.js project (defaults to current directory)\n\n**Output:**\n- Comprehensive initialization context and guidance for Next.js development with MCP tools\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_docs\u003C\u002Fcode>\u003C\u002Fsummary>\n\nSearch and retrieve Next.js official documentation and knowledge base.\n\n**Capabilities:**\n- Two-step process: 1) Search for docs by keyword to get paths, 2) Fetch full markdown content by path\n- Uses official Next.js documentation search API\n- Provides access to comprehensive Next.js guides, API references, and best practices\n- Supports filtering by router type (App Router, Pages Router, or both)\n\n**Input:**\n- `action` (required) - Action to perform: `search` to find docs, `get` to fetch full content\n- `query` (optional) - Required for `search`. Keyword search query (e.g., 'metadata', 'generateStaticParams', 'middleware')\n- `path` (optional) - Required for `get`. Doc path from search results (e.g., '\u002Fdocs\u002Fapp\u002Fapi-reference\u002Ffunctions\u002Frefresh')\n- `anchor` (optional) - Optional for `get`. Anchor\u002Fsection from search results (e.g., 'usage')\n- `routerType` (optional) - For `search` only. Filter by: `app`, `pages`, or `all` (default: `all`)\n\n**Output:**\n- Search results with doc titles, paths, content snippets, sections, and anchors\n- Full markdown content for specific documentation pages\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>browser_eval\u003C\u002Fcode>\u003C\u002Fsummary>\n\nAutomate and test web applications using Playwright browser automation.\n\n**When to use:**\n- Verifying pages in Next.js projects (especially during upgrades or testing)\n- Testing user interactions and flows\n- Taking screenshots for visual verification\n- Detecting runtime errors, hydration issues, and client-side problems\n- Capturing browser console errors and warnings\n\n**Important:** For Next.js projects, prioritize using the `nextjs_index` and `nextjs_call` tools instead of browser console log forwarding. Only use browser_eval's `console_messages` action as a fallback when these tools are not available.\n\n**Available actions:**\n- `start` - Start browser automation (automatically installs if needed)\n- `navigate` - Navigate to a URL\n- `click` - Click on an element\n- `type` - Type text into an element\n- `fill_form` - Fill multiple form fields at once\n- `evaluate` - Execute JavaScript in browser context\n- `screenshot` - Take a screenshot of the page\n- `console_messages` - Get browser console messages\n- `close` - Close the browser\n- `drag` - Perform drag and drop\n- `upload_file` - Upload files\n- `list_tools` - List all available browser automation tools from the server\n\n**Input:**\n- `action` (required) - The action to perform\n- `browser` (optional) - Browser to use: `chrome`, `firefox`, `webkit`, `msedge` (default: `chrome`)\n- `headless` (optional) - Run browser in headless mode (default: `true`)\n- Action-specific parameters (see tool description for details)\n\n**Output:**\n- JSON with action result, screenshots (base64), console messages, or error information\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_index\u003C\u002Fcode>\u003C\u002Fsummary>\n\nDiscover all running Next.js dev servers and list their available MCP tools.\n\n**What this tool does:**\n\nAutomatically discovers all running Next.js 16+ dev servers on your machine and lists the runtime diagnostic tools available from each server's built-in MCP endpoint at `\u002F_next\u002Fmcp`.\n\n**No parameters required** - Just call the tool and it will scan for servers.\n\n**Available Next.js Runtime Tools** (varies by Next.js version):\n- `get_errors` - Get current build, runtime, and type errors\n- `get_logs` - Get path to development log file (browser console + server output)\n- `get_page_metadata` - Query application routes, pages, and component metadata\n- `get_project_metadata` - Get project structure, config, and dev server URL\n- `get_server_action_by_id` - Look up Server Actions by ID to find source files\n\n**Requirements:**\n- Next.js 16+ (MCP enabled by default)\n- Running dev server (`npm run dev`)\n\n**Output:**\n- JSON with list of discovered servers, each containing:\n  - Port, PID, URL\n  - Available tools with descriptions and input schemas\n\n**Example prompts:**\n- \"Next Devtools, what servers are running?\"\n- \"Next Devtools, show me available diagnostic tools\"\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_call\u003C\u002Fcode>\u003C\u002Fsummary>\n\nExecute a specific MCP tool on a running Next.js dev server.\n\n**What this tool does:**\n\nCalls a specific runtime diagnostic tool on a Next.js 16+ dev server's built-in MCP endpoint at `\u002F_next\u002Fmcp`.\n\n**Input Parameters:**\n- `port` (required) - Dev server port (use `nextjs_index` first to discover)\n- `toolName` (required) - Name of the Next.js tool to invoke\n- `args` (optional) - Arguments object for the tool (only if required by that tool)\n\n**Requirements:**\n- Next.js 16+ (MCP enabled by default)\n- Running dev server (`npm run dev`)\n- Use `nextjs_index` first to discover available servers and tools\n\n**Typical workflow:**\n\n```javascript\n\u002F\u002F Step 1: Discover servers and tools\n\u002F\u002F (call nextjs_index first)\n\n\u002F\u002F Step 2: Call a specific tool\n{\n  \"port\": 3000,\n  \"toolName\": \"get_errors\"\n  \u002F\u002F args is optional and only needed if the tool requires parameters\n}\n```\n\n**Output:**\n- JSON with tool execution results\n\n**Example prompts that use this tool:**\n- \"Next Devtools, what errors are in my Next.js app?\"\n- \"Next Devtools, show me my application routes\"\n- \"Next Devtools, what's in the dev server logs?\"\n- \"Next Devtools, find the Server Action with ID xyz\"\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>upgrade_nextjs_16\u003C\u002Fcode>\u003C\u002Fsummary>\n\nGuides through upgrading Next.js to version 16 with automated codemod execution.\n\n**Capabilities:**\n- Runs official Next.js codemod automatically (requires clean git state)\n- Handles async API changes (params, searchParams, cookies, headers)\n- Migrates configuration changes\n- Updates image defaults and optimization\n- Fixes parallel routes and dynamic segments\n- Handles deprecated API removals\n- Provides guidance for React 19 compatibility\n\n**Input:**\n- `project_path` (optional) - Path to Next.js project (defaults to current directory)\n\n**Output:**\n- Structured JSON with step-by-step upgrade guidance\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>enable_cache_components\u003C\u002Fcode>\u003C\u002Fsummary>\n\nComplete Cache Components setup, enablement, and migration for Next.js 16 with automated error detection and fixing. This tool is used for migrating Next.js applications to Cache Components mode.\n\n**Capabilities:**\n- Pre-flight checks (package manager, Next.js version, configuration)\n- Enable Cache Components configuration\n- Start dev server with MCP enabled\n- Automated route verification and error detection\n- Automated error fixing with intelligent boundary setup (Suspense, caching directives, static params)\n- Final verification and build testing\n\n**Input:**\n- `project_path` (optional) - Path to Next.js project (defaults to current directory)\n\n**Output:**\n- Structured JSON with complete setup guidance and phase-by-phase instructions\n\n**Example Usage:**\n\nWith Claude Code:\n```\nNext Devtools, help me enable Cache Components in my Next.js 16 app\n```\n\nWith other agents or programmatically:\n```json\n{\n  \"tool\": \"enable_cache_components\",\n  \"args\": {\n    \"project_path\": \"\u002Fpath\u002Fto\u002Fproject\"\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n## Privacy & Telemetry\n\n### What Data is Collected\n\n`next-devtools-mcp` collects anonymous usage telemetry to help improve the tool. The following data is collected:\n\n- **Tool usage**: Which MCP tools are invoked (e.g., `nextjs_index`, `nextjs_call`, `browser_eval`, `upgrade_nextjs_16`)\n- **Error events**: Anonymous error messages when tools fail\n- **Session metadata**: Session ID, timestamps, and basic environment info (OS, Node.js version)\n\n**What is NOT collected:**\n- Your project code, file contents, or file paths\n- Personal information or identifiable data\n- API keys, credentials, or sensitive configuration\n- Arguments passed to tools (except tool names)\n\nLocal files are written under `~\u002F.next-devtools-mcp\u002F` (anonymous `telemetry-id`, `telemetry-salt`, and a debug log `mcp.log`). Events are sent to the telemetry endpoint in the background to help us understand usage patterns and improve reliability.\n\n### Opt-Out\n\nTo disable telemetry completely, set the environment variable:\n\n```bash\nexport NEXT_TELEMETRY_DISABLED=1\n```\n\nAdd this to your shell configuration file (e.g., `~\u002F.bashrc`, `~\u002F.zshrc`) to make it permanent.\n\nYou can also delete your local telemetry data at any time:\n\n```bash\nrm -rf ~\u002F.next-devtools-mcp\n```\n\n## Troubleshooting\n\n### Module Not Found Error\n\nIf you encounter an error like:\n\n```\nError [ERR_MODULE_NOT_FOUND]: Cannot find module '...\\next-devtools-mcp\\dist\\resources\\(cache-components)\\...'\n```\n\n**Solution:** Clear your npx cache and restart your MCP client (Cursor, Claude Code, etc.). The server will be freshly installed.\n\n### \"No server info found\" Error\n\nIf you see `[error] No server info found`:\n\n**Solutions:**\n1. Make sure your Next.js dev server is running: `npm run dev`\n2. If using Next.js 15 or earlier, use the `upgrade_nextjs_16` tool to upgrade to Next.js 16+\n3. Verify your dev server started successfully without errors\n\n**Note:** The `nextjs_index` and `nextjs_call` tools require Next.js 16+ with a running dev server. Other tools (`nextjs_docs`, `browser_eval`, `upgrade_nextjs_16`, `enable_cache_components`) work without a running server.\n\n## Local Development\n\nTo run the MCP server locally for development:\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   pnpm install\n   pnpm build\n   ```\n3. Configure your MCP client to use the local version:\n   ```json\n   {\n     \"mcpServers\": {\n       \"next-devtools\": {\n         \"command\": \"node\",\n         \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fnext-devtools-mcp\u002Fdist\u002Findex.js\"]\n       }\n     }\n   }\n   ```\n\n   Note: Replace `\u002Fabsolute\u002Fpath\u002Fto\u002Fnext-devtools-mcp` with the actual absolute path to your cloned repository.\n\n   or manually add, e.g. with codex:\n   ```\n   codex mcp add next-devtools-local -- node dist\u002Findex.js\n   ```\n\n## Features\n\nThis MCP server provides coding agents with comprehensive Next.js development capabilities through three primary mechanisms:\n\n### **1. Runtime Diagnostics & Live State Access** (Next.js 16+)\nConnect directly to your running Next.js dev server's built-in MCP endpoint to query:\n- Real-time build and runtime errors\n- Application routes, pages, and component metadata\n- Development server logs and diagnostics\n- Server Actions and component hierarchies\n\n### **2. Development Automation**\nTools for common Next.js workflows:\n- **Automated Next.js 16 upgrades** with official codemods\n- **Cache Components migration and setup** with error detection and automated fixes\n- **Browser testing integration** via Playwright for visual verification\n\n### **3. Knowledge Base & Documentation**\n- Curated Next.js 16 knowledge base (12 focused resources on Cache Components, async APIs, etc.)\n- Direct access to official Next.js documentation via search API\n- Pre-configured prompts for upgrade guidance and Cache Components enablement\n\n> **Learn more:** See the [Next.js MCP documentation](https:\u002F\u002Fnextjs.org\u002Fdocs\u002Fapp\u002Fguides\u002Fmcp) for details on how MCP servers work with Next.js and coding agents.\n\n## How It Works\n\nThis package provides a **bridge MCP server** that connects your coding agent to Next.js development tools:\n\n```\nCoding Agent\n      ↓\n  next-devtools-mcp (this package)\n      ↓\n      ├─→ Next.js Dev Server MCP Endpoint (\u002F_next\u002Fmcp) ← Runtime diagnostics\n      ├─→ Playwright MCP Server ← Browser automation\n      └─→ Knowledge Base & Tools ← Documentation, upgrades, setup automation\n```\n\n**Key Architecture Points:**\n\n1. **For Next.js 16+ projects**: This server automatically discovers and connects to your running Next.js dev server's built-in MCP endpoint at `http:\u002F\u002Flocalhost:PORT\u002F_next\u002Fmcp`. This gives coding agents direct access to runtime errors, routes, logs, and application state.\n\n2. **For all Next.js projects**: Provides development automation tools (upgrades, Cache Components setup), documentation access, and browser testing capabilities that work independently of the runtime connection.\n\n3. **Simple workflow**: Call `nextjs_index` to see all servers and available tools, then call `nextjs_call` with the specific port and tool name you want to execute.\n\n\n## License\n\nMIT License\n","# Next.js 开发工具 MCP\n\n[![npm next-devtools-mcp 包](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fnext-devtools-mcp.svg)](https:\u002F\u002Fnpmjs.org\u002Fpackage\u002Fnext-devtools-mcp)\n\n`next-devtools-mcp` 是一个模型上下文协议 (MCP) 服务器，为 Claude 和 Cursor 等编码助手提供 Next.js 开发工具和实用程序。\n\n\n## 快速入门\n\n### 要求\n\n- [Node.js](https:\u002F\u002Fnodejs.org\u002F) v20.19 或更高版本的 [最新维护版 LTS](https:\u002F\u002Fgithub.com\u002Fnodejs\u002FRelease#release-schedule)\n- [npm](https:\u002F\u002Fwww.npmjs.com\u002F) 或 [pnpm](https:\u002F\u002Fpnpm.io\u002F)\n\n\n### 使用 add-mcp 安装\n\n为所有编码助手安装 MCP 服务器：\n\n```bash\nnpx add-mcp next-devtools-mcp@latest\n```\n\n添加 `-y` 可跳过确认提示，并将该服务器安装到项目目录中已检测到的所有助手上。添加 `-g` 可以全局安装到所有项目中。\n\n\n### 手动安装\n\n将以下配置添加到您的 MCP 客户端：\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> 使用 `next-devtools-mcp@latest` 可确保您的 MCP 客户端始终使用最新版本的 Next.js 开发工具 MCP 服务器。\n\n### MCP 客户端配置\n\n\u003Cdetails>\n\u003Csummary>Amp\u003C\u002Fsummary>\n\n**使用 Amp CLI：**\n\n```bash\namp mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\n**或手动配置：**\n\n请参考 [Amp 的 MCP 文档](https:\u002F\u002Fampcode.com\u002Fmanual#mcp)，并应用上述标准配置。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Claude Code\u003C\u002Fsummary>\n\n使用 Claude Code CLI 添加 Next.js 开发工具 MCP 服务器：\n\n```bash\nclaude mcp add next-devtools npx next-devtools-mcp@latest\n```\n\n或者，您也可以手动编辑 MCP 设置文件，添加上述配置。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Codex\u003C\u002Fsummary>\n\n**使用 Codex CLI：**\n\n```bash\ncodex mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\n**或手动配置：**\n\n按照 MCP 设置指南，使用标准配置格式：\n- 命令：`npx`\n- 参数：`-y, next-devtools-mcp@latest`\n\n**Windows 11 特殊配置：**\n\n更新 `.codex\u002Fconfig.toml` 文件，添加环境变量并增加启动超时时间：\n\n```toml\nenv = { SystemRoot=\"C:\\\\Windows\", PROGRAMFILES=\"C:\\\\Program Files\" }\nstartup_timeout_ms = 20_000\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Cursor\u003C\u002Fsummary>\n\n**点击按钮即可安装：**\n\n[在 Cursor 中安装](https:\u002F\u002Fcursor.com\u002Fen\u002Finstall-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)\n\n**或手动安装：**\n\n前往 `Cursor 设置` → `MCP` → `新建 MCP 服务器`。使用上面提供的配置。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Gemini\u003C\u002Fsummary>\n\n**使用 Gemini CLI：**\n\n项目范围安装：\n```bash\ngemini mcp add next-devtools npx next-devtools-mcp@latest\n```\n\n全局安装：\n```bash\ngemini mcp add -s user next-devtools npx next-devtools-mcp@latest\n```\n\n**或手动配置：**\n\n按照 MCP 设置指南，使用以下参数：\n- 命令：`npx`\n- 参数：`-y, next-devtools-mcp@latest`\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Google Antigravity\u003C\u002Fsummary>\n\n**在 MCP 配置文件中配置：**\n\n将以下内容添加到您的 Antigravity MCP 配置文件：`.gemini\u002Fantigravity\u002Fmcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n更多信息请参阅 [Antigravity MCP 文档](https:\u002F\u002Fantigravity.google\u002Fdocs\u002Fmcp)。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>VS Code \u002F Copilot\u003C\u002Fsummary>\n\n**使用 VS Code CLI：**\n\n```bash\ncode --add-mcp '{\"name\":\"next-devtools\",\"command\":\"npx\",\"args\":[\"-y\",\"next-devtools-mcp@latest\"]}'\n```\n\n**或手动配置：**\n\n按照官方 VS Code MCP 服务器设置指南，在 VS Code 设置中添加 Next.js 开发工具服务器。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Warp\u003C\u002Fsummary>\n\n**使用 Warp UI：**\n\n导航至 `设置 | AI | 管理 MCP 服务器`，选择 `+ 添加`，使用以下配置注册新的 MCP 服务器：\n- 名称：`next-devtools`\n- 命令：`npx`\n- 参数：`-y, next-devtools-mcp@latest`\n\n\u003C\u002Fdetails>\n\n## 快速开始\n\n### 对于 Next.js 16+ 项目（推荐）\n\n要充分发挥运行时诊断功能，请启动您的 Next.js 开发服务器：\n\n```bash\nnpm run dev\n```\n\nNext.js 16+ 默认启用了 MCP，地址为 `http:\u002F\u002Flocalhost:3000\u002F_next\u002Fmcp`（或您的开发服务器使用的其他端口）。`next-devtools-mcp` 服务器会自动发现并连接到它。\n\n**⚠️ 重要提示：每次启动 Next.js 会话时，请先调用 `init` 工具以设置正确的上下文：**\n\n```\n使用 init 工具设置 Next.js 开发工具上下文\n```\n\n这将初始化 MCP 上下文，确保 AI 助手在所有查询中都使用官方 Next.js 文档。\n\n**初始化完成后，您可以尝试以下提示来探索运行时诊断功能：**\n\n```\nNext Devtools，我的 Next.js 应用程序中有哪些错误？\n```\n\n```\nNext Devtools，展示我的路由结构\n```\n\n```\nNext Devtools，开发服务器日志中有什么内容？\n```\n\n您的编码助手将使用 `nextjs_index` 和 `nextjs_call` 工具查询您正在运行的应用程序的实际状态。\n\n### 对于所有 Next.js 项目\n\n无论 Next.js 版本如何，您都可以使用开发自动化和文档工具：\n\n```\nNext Devtools，帮我将我的 Next.js 应用升级到 16 版\n```\n\n```\nNext Devtools，启用我 Next.js 应用中的缓存组件\n```\n\n```\nNext Devtools，搜索 Next.js 文档中的 generateMetadata\n```\n\n### 💡 专业提示：在每个会话中自动初始化\n\n为了让您的 AI 助手在每次 Next.js 会话开始时**无需提示即可自动调用 `init` 工具**，请将以下指令添加到您的代理配置文件中：\n\n\u003Cdetails>\n\u003Csummary>Claude Code \u002F Claude Desktop\u003C\u002Fsummary>\n\n添加到 `~\u002F.claude\u002FCLAUDE.md`（全局）或 `.\u002F.claude\u002FCLAUDE.md`（项目特定）：\n\n```markdown\n**在开始处理 Next.js 项目时，务必首先调用 next-devtools-mcp 中的 `init` 工具，以设置正确的上下文并确立文档优先的要求。此操作应自动执行，无需提示。**\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Cursor\u003C\u002Fsummary>\n\n添加到项目根目录下的 `.cursorrules` 文件或 Cursor 的全局设置中：\n\n```\n在使用 Next.js 时，应在会话开始时始终调用 next-devtools-mcp 中的 init 工具，以建立适当的上下文和文档优先要求。\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Codex \u002F 其他 AI 编程助手\u003C\u002Fsummary>\n\n添加到您的代理配置文件中（例如 `.codex\u002Finstructions.md`、`agent.md` 或类似文件）：\n\n```markdown\n**Next.js 初始化**：当开始处理 Next.js 项目时，应首先自动调用 next-devtools-mcp 服务器中的 `init` 工具。这将建立正确的上下文，并确保所有 Next.js 相关查询都使用官方文档。\n```\n\n\u003C\u002Fdetails>\n\n**这样做有何意义：**\n- ✅ 确保在所有 Next.js 工作中保持一致的上下文\n- ✅ 自动确立“文档优先”的要求\n- ✅ 无需每次都手动调用 init\n- ✅ 适用于您所有的 Next.js 项目\n\n## MCP 资源\n\n知识库资源会自动提供给您的编程助手，并被划分为多个重点部分，以便高效管理上下文。当前资源 URI 如下：\n\n\u003Cdetails>\n\u003Csummary>📚 可用知识库资源（点击展开）\u003C\u002Fsummary>\n\n- 缓存组件（12 个部分）：\n  - `cache-components:\u002F\u002Foverview`\n  - `cache-components:\u002F\u002Fcore-mechanics`\n  - `cache-components:\u002F\u002Fpublic-caches`\n  - `cache-components:\u002F\u002Fprivate-caches`\n  - `cache-components:\u002F\u002Fruntime-prefetching`\n  - `cache-components:\u002F\u002Frequest-apis`\n  - `cache-components:\u002F\u002Fcache-invalidation`\n  - `cache-components:\u002F\u002Fadvanced-patterns`\n  - `cache-components:\u002F\u002Fbuild-behavior`\n  - `cache-components:\u002F\u002Ferror-patterns`\n  - `cache-components:\u002F\u002Ftest-patterns`\n  - `cache-components:\u002F\u002Freference`\n\n- Next.js 16 迁移：\n  - `nextjs16:\u002F\u002Fmigration\u002Fbeta-to-stable`\n  - `nextjs16:\u002F\u002Fmigration\u002Fexamples`\n\n- Next.js 基础知识：\n  - `nextjs-fundamentals:\u002F\u002Fuse-client`\n\n\u003C\u002Fdetails>\n\n这些资源由您的编程助手按需加载，提供有针对性的知识，而不会使上下文窗口过于拥挤。\n\n## MCP 提示语\n\n预配置的提示语，用于帮助处理常见的 Next.js 开发任务：\n\n\u003Cdetails>\n\u003Csummary>💡 可用提示语（点击展开）\u003C\u002Fsummary>\n\n- **`upgrade-nextjs-16`** - 升级到 Next.js 16 的指南\n- **`enable-cache-components`** - 将 Next.js 16 迁移到缓存组件模式并启用该功能\n\n\u003C\u002Fdetails>\n\n## MCP 工具\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>init\u003C\u002Fcode>\u003C\u002Fsummary>\n\n初始化 Next.js 开发工具 MCP 上下文，并确立文档优先的要求。\n\n**功能：**\n- 为使用 Next.js 的 AI 助手设置合适的上下文\n- 确立在所有 Next.js 相关查询中必须使用 `nextjs_docs` 的要求\n- 记录所有可用的 MCP 工具及其使用场景\n- 提供使用 MCP 进行 Next.js 开发的最佳实践\n- 包含示例工作流程和快速入门检查清单\n\n**适用场景：**\n- 在 Next.js 开发会话开始时\n- 了解可用工具并建立适当的上下文\n- 确保采用文档优先的 Next.js 开发方法\n\n**输入：**\n- `project_path`（可选）— Next.js 项目的路径（默认为当前目录）\n\n**输出：**\n- 完整的初始化上下文及使用 MCP 工具进行 Next.js 开发的指导信息\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_docs\u003C\u002Fcode>\u003C\u002Fsummary>\n\n搜索并检索 Next.js 官方文档和知识库。\n\n**功能：**\n- 分两步进行：1) 根据关键词搜索文档路径，2) 根据路径获取完整的 Markdown 内容\n- 使用官方 Next.js 文档搜索 API\n- 提供对全面的 Next.js 指南、API 参考和最佳实践的访问\n- 支持按路由器类型筛选（App Router、Pages Router 或两者）\n\n**输入：**\n- `action`（必填）— 要执行的操作：`search` 用于查找文档，`get` 用于获取完整内容\n- `query`（可选）— 必须用于 `search`。关键词搜索查询（例如，“metadata”、“generateStaticParams”、“middleware”）\n- `path`（可选）— 必须用于 `get`。来自搜索结果的文档路径（例如，“\u002Fdocs\u002Fapp\u002Fapi-reference\u002Ffunctions\u002Frefresh”）\n- `anchor`（可选）— 可用于 `get`。来自搜索结果的锚点或章节（例如，“usage”）\n- `routerType`（可选）— 仅用于 `search`。筛选条件：`app`、`pages` 或 `all`（默认为 `all`）\n\n**输出：**\n- 包含文档标题、路径、内容摘要、章节和锚点的搜索结果\n- 特定文档页面的完整 Markdown 内容\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>browser_eval\u003C\u002Fcode>\u003C\u002Fsummary>\n\n使用 Playwright 浏览器自动化工具来自动测试 Web 应用程序。\n\n**适用场景：**\n- 验证 Next.js 项目中的页面（尤其是在升级或测试期间）\n- 测试用户交互和流程\n- 截取屏幕截图以进行视觉验证\n- 检测运行时错误、水合问题以及客户端问题\n- 捕获浏览器控制台中的错误和警告信息\n\n**重要提示：** 对于 Next.js 项目，应优先使用 `nextjs_index` 和 `nextjs_call` 工具，而不是通过浏览器控制台转发日志。只有在这些工具不可用时，才应将 `browser_eval` 的 `console_messages` 功能作为备用方案。\n\n**可用操作：**\n- `start` — 启动浏览器自动化（如果需要会自动安装）\n- `navigate` — 导航到指定 URL\n- `click` — 点击某个元素\n- `type` — 在元素中输入文本\n- `fill_form` — 一次性填写多个表单字段\n- `evaluate` — 在浏览器上下文中执行 JavaScript\n- `screenshot` — 截取页面的屏幕截图\n- `console_messages` — 获取浏览器控制台消息\n- `close` — 关闭浏览器\n- `drag` — 执行拖放操作\n- `upload_file` — 上传文件\n- `list_tools` — 列出服务器上所有可用的浏览器自动化工具\n\n**输入：**\n- `action`（必填）— 要执行的操作\n- `browser`（可选）— 要使用的浏览器：`chrome`、`firefox`、`webkit`、`msedge`（默认为 `chrome`）\n- `headless`（可选）— 是否以无头模式运行浏览器（默认为 `true`）\n- 操作特定的参数（详情请参阅工具描述）\n\n**输出：**\n- 包含操作结果、截图（Base64 编码）、控制台消息或错误信息的 JSON 数据\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_index\u003C\u002Fcode>\u003C\u002Fsummary>\n\n发现所有正在运行的 Next.js 开发服务器，并列出它们可用的 MCP 工具。\n\n**此工具的作用：**\n\n自动发现您机器上所有正在运行的 Next.js 16+ 开发服务器，并列出每个服务器在 `\u002F_next\u002Fmcp` 内置 MCP 端点上可用的运行时诊断工具。\n\n**无需参数** - 直接调用该工具即可扫描服务器。\n\n**可用的 Next.js 运行时工具**（因 Next.js 版本而异）：\n- `get_errors` - 获取当前构建、运行时和类型错误\n- `get_logs` - 获取开发日志文件路径（浏览器控制台 + 服务器输出）\n- `get_page_metadata` - 查询应用路由、页面和组件元数据\n- `get_project_metadata` - 获取项目结构、配置和开发服务器 URL\n- `get_server_action_by_id` - 根据 ID 查找服务器操作以定位源文件\n\n**要求：**\n- Next.js 16+（默认启用 MCP）\n- 正在运行的开发服务器（`npm run dev`）\n\n**输出：**\n- 包含已发现服务器列表的 JSON，每个服务器包含：\n  - 端口、PID、URL\n  - 可用工具及其描述和输入模式\n\n**示例提示：**\n- “Next Devtools，有哪些服务器正在运行？”\n- “Next Devtools，给我看看可用的诊断工具”\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>nextjs_call\u003C\u002Fcode>\u003C\u002Fsummary>\n\n在正在运行的 Next.js 开发服务器上执行特定的 MCP 工具。\n\n**此工具的作用：**\n\n调用 Next.js 16+ 开发服务器内置 MCP 端点 `\u002F_next\u002Fmcp` 上的特定运行时诊断工具。\n\n**输入参数：**\n- `port`（必填）- 开发服务器端口（请先使用 `nextjs_index` 发现）\n- `toolName`（必填）- 要调用的 Next.js 工具名称\n- `args`（可选）- 该工具的参数对象（仅当该工具需要参数时）\n\n**要求：**\n- Next.js 16+（默认启用 MCP）\n- 正在运行的开发服务器（`npm run dev`）\n- 请先使用 `nextjs_index` 发现可用的服务器和工具\n\n**典型工作流程：**\n\n```javascript\n\u002F\u002F 第一步：发现服务器和工具\n\u002F\u002F （先调用 nextjs_index）\n\n\u002F\u002F 第二步：调用特定工具\n{\n  \"port\": 3000,\n  \"toolName\": \"get_errors\"\n  \u002F\u002F args 是可选的，只有当工具需要参数时才需要\n}\n```\n\n**输出：**\n- 包含工具执行结果的 JSON\n\n**使用此工具的示例提示：**\n- “Next Devtools，我的 Next.js 应用中有哪些错误？”\n- “Next Devtools，给我看看我的应用路由”\n- “Next Devtools，开发服务器日志里有什么？”\n- “Next Devtools，找到 ID 为 xyz 的服务器操作”\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>upgrade_nextjs_16\u003C\u002Fcode>\u003C\u002Fsummary>\n\n指导将 Next.js 升级到版本 16，并自动执行代码转换。\n\n**功能：**\n- 自动运行官方 Next.js 代码转换（需要干净的 Git 状态）\n- 处理异步 API 变更（params、searchParams、cookies、headers）\n- 迁移配置更改\n- 更新图像默认设置和优化\n- 修复并行路由和动态段\n- 处理已弃用 API 的移除\n- 提供 React 19 兼容性指导\n\n**输入：**\n- `project_path`（可选）- Next.js 项目的路径（默认为当前目录）\n\n**输出：**\n- 包含逐步升级指导的结构化 JSON\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Ccode>enable_cache_components\u003C\u002Fcode>\u003C\u002Fsummary>\n\n为 Next.js 16 完成缓存组件的设置、启用和迁移，并自动检测和修复错误。此工具用于将 Next.js 应用迁移到缓存组件模式。\n\n**功能：**\n- 预检检查（包管理器、Next.js 版本、配置）\n- 启用缓存组件配置\n- 启动启用 MCP 的开发服务器\n- 自动验证路由并检测错误\n- 自动修复错误，智能设置边界（Suspense、缓存指令、静态参数）\n- 最终验证和构建测试\n\n**输入：**\n- `project_path`（可选）- Next.js 项目的路径（默认为当前目录）\n\n**输出：**\n- 包含完整设置指导和分阶段说明的结构化 JSON\n\n**示例用法：**\n\n通过 Claude Code：\n```\nNext Devtools，帮我在我 Next.js 16 应用中启用缓存组件\n```\n\n通过其他代理或编程方式：\n```json\n{\n  \"tool\": \"enable_cache_components\",\n  \"args\": {\n    \"project_path\": \"\u002Fpath\u002Fto\u002Fproject\"\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\n\n## 隐私与遥测\n\n### 收集的数据\n\n`next-devtools-mcp` 会收集匿名使用遥测数据，以帮助改进该工具。收集以下数据：\n\n- **工具使用情况**：调用了哪些 MCP 工具（例如 `nextjs_index`、`nextjs_call`、`browser_eval`、`upgrade_nextjs_16`）\n- **错误事件**：工具失败时的匿名错误信息\n- **会话元数据**：会话 ID、时间戳以及基本环境信息（操作系统、Node.js 版本）\n\n**不会收集的内容：**\n- 您的项目代码、文件内容或文件路径\n- 个人信息或可识别数据\n- API 密钥、凭据或其他敏感配置\n- 传递给工具的参数（工具名称除外）\n\n本地文件会写入 `~\u002F.next-devtools-mcp\u002F` 目录下（包含匿名的 `telemetry-id`、`telemetry-salt` 和调试日志 `mcp.log`）。事件会在后台发送到遥测端点，以帮助我们了解使用模式并提高可靠性。\n\n### 选择退出\n\n要完全禁用遥测，请设置环境变量：\n\n```bash\nexport NEXT_TELEMETRY_DISABLED=1\n```\n\n将其添加到您的 shell 配置文件（如 `~\u002F.bashrc`、`~\u002F.zshrc`）以使其永久生效。\n\n您也可以随时删除本地遥测数据：\n\n```bash\nrm -rf ~\u002F.next-devtools-mcp\n```\n\n## 故障排除\n\n### 模块未找到错误\n\n如果您遇到类似以下错误：\n\n```\nError [ERR_MODULE_NOT_FOUND]: Cannot find module '...\\next-devtools-mcp\\dist\\resources\\(cache-components)\\...'\n```\n\n**解决方案：** 清除 npx 缓存并重启您的 MCP 客户端（Cursor、Claude Code 等）。服务器将被重新安装。\n\n### “未找到服务器信息”错误\n\n如果您看到 `[error] No server info found`：\n\n**解决方案：**\n1. 确保您的 Next.js 开发服务器正在运行：`npm run dev`\n2. 如果您使用的是 Next.js 15 或更早版本，请使用 `upgrade_nextjs_16` 工具升级到 Next.js 16+\n3. 验证您的开发服务器是否成功启动且没有错误\n\n**注意：** `nextjs_index` 和 `nextjs_call` 工具需要 Next.js 16+ 并且开发服务器正在运行。其他工具（`nextjs_docs`、`browser_eval`、`upgrade_nextjs_16`、`enable_cache_components`）无需运行服务器即可使用。\n\n## 本地开发\n\n要在本地运行 MCP 服务器进行开发：\n\n1. 克隆仓库\n2. 安装依赖项：\n   ```bash\n   pnpm install\n   pnpm build\n   ```\n3. 配置您的 MCP 客户端以使用本地版本：\n   ```json\n   {\n     \"mcpServers\": {\n       \"next-devtools\": {\n         \"command\": \"node\",\n         \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fnext-devtools-mcp\u002Fdist\u002Findex.js\"]\n       }\n     }\n   }\n   ```\n\n   注意：将 `\u002Fabsolute\u002Fpath\u002Fto\u002Fnext-devtools-mcp` 替换为您克隆仓库的实际绝对路径。\n\n   或者手动添加，例如使用 codex：\n   ```\n   codex mcp add next-devtools-local -- node dist\u002Findex.js\n   ```\n\n## 功能\n\n该 MCP 服务器通过三种主要机制，为编码代理提供全面的 Next.js 开发能力：\n\n### **1. 运行时诊断与实时状态访问**（Next.js 16+）\n直接连接到您正在运行的 Next.js 开发服务器内置的 MCP 端点，以查询：\n- 实时构建和运行时错误\n- 应用程序路由、页面和组件元数据\n- 开发服务器日志和诊断信息\n- Server Actions 和组件层级结构\n\n### **2. 开发自动化**\n针对常见 Next.js 工作流的工具：\n- 使用官方 codemod 自动完成 Next.js 16 升级\n- 带有错误检测和自动修复功能的 Cache Components 迁移与设置\n- 通过 Playwright 集成浏览器测试，实现视觉验证\n\n### **3. 知识库与文档**\n- 精选的 Next.js 16 知识库（包含 12 个关于 Cache Components、异步 API 等主题的重点资源）\n- 通过搜索 API 直接访问官方 Next.js 文档\n- 预配置的提示，用于升级指导和 Cache Components 的启用\n\n> **了解更多：** 请参阅 [Next.js MCP 文档](https:\u002F\u002Fnextjs.org\u002Fdocs\u002Fapp\u002Fguides\u002Fmcp)，了解 MCP 服务器如何与 Next.js 及编码代理协同工作。\n\n## 工作原理\n\n本包提供一个 **桥接 MCP 服务器**，将您的编码代理与 Next.js 开发工具连接起来：\n\n```\n编码代理\n      ↓\n  next-devtools-mcp（本包）\n      ↓\n      ├─→ Next.js 开发服务器 MCP 端点（\u002F_next\u002Fmcp）← 运行时诊断\n      ├─→ Playwright MCP 服务器 ← 浏览器自动化\n      └─→ 知识库与工具 ← 文档、升级、设置自动化\n```\n\n**关键架构要点：**\n\n1. **适用于 Next.js 16+ 项目**：该服务器会自动发现并连接到您正在运行的 Next.js 开发服务器在 `http:\u002F\u002Flocalhost:PORT\u002F_next\u002Fmcp` 上的内置 MCP 端点。这使得编码代理可以直接访问运行时错误、路由、日志和应用状态。\n   \n2. **适用于所有 Next.js 项目**：提供开发自动化工具（升级、Cache Components 设置）、文档访问以及独立于运行时连接的浏览器测试功能。\n\n3. **简单的工作流程**：调用 `nextjs_index` 查看所有服务器及可用工具，然后使用特定端口和所需工具名称调用 `nextjs_call` 来执行相应操作。\n\n\n## 许可证\n\nMIT 许可证","# next-devtools-mcp 快速上手指南\n\n`next-devtools-mcp` 是一个基于模型上下文协议（MCP）的服务器，专为 Claude、Cursor 等 AI 编程助手设计，提供 Next.js 开发工具、运行时诊断能力及官方文档检索功能。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: v20.19 或更新的 LTS 版本（推荐最新维护版）。\n*   **包管理器**: `npm` 或 `pnpm`。\n*   **AI 客户端**: 已安装支持 MCP 协议的编程助手（如 Cursor, Claude Code, VS Code Copilot 等）。\n\n## 安装步骤\n\n您可以选择使用自动化工具一键安装，或手动配置。\n\n### 方式一：使用 add-mcp 自动安装（推荐）\n\n该命令会自动检测项目中使用的 AI 代理并进行配置：\n\n```bash\nnpx add-mcp next-devtools-mcp@latest\n```\n\n*   添加 `-y` 参数可跳过确认提示。\n*   添加 `-g` 参数可全局安装到所有项目。\n\n### 方式二：手动配置\n\n如果您需要手动编辑 MCP 配置文件，请添加以下配置项：\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n> **注意**：使用 `@latest` 标签可确保始终运行最新版本。\n\n#### 主流客户端快速配置命令\n\n*   **Cursor**: 点击 [Install in Cursor](https:\u002F\u002Fcursor.com\u002Fen\u002Finstall-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9) 按钮，或在设置中手动添加上述 JSON。\n*   **Claude Code**:\n    ```bash\n    claude mcp add next-devtools npx next-devtools-mcp@latest\n    ```\n*   **VS Code \u002F Copilot**:\n    ```bash\n    code --add-mcp '{\"name\":\"next-devtools\",\"command\":\"npx\",\"args\":[\"-y\",\"next-devtools-mcp@latest\"]}'\n    ```\n*   **Gemini CLI**:\n    ```bash\n    gemini mcp add next-devtools npx next-devtools-mcp@latest\n    ```\n\n## 基本使用\n\n### 1. 启动 Next.js 开发服务器\n\n对于 **Next.js 16+** 项目，MCP 功能默认开启。请先启动您的开发服务器：\n\n```bash\nnpm run dev\n```\n\n服务器将在 `http:\u002F\u002Flocalhost:3000\u002F_next\u002Fmcp`（或对应端口）暴露接口，`next-devtools-mcp` 会自动发现并连接。\n\n### 2. 初始化上下文（关键步骤）\n\n在开始任何 Next.js 相关任务前，**必须**先调用 `init` 工具以建立正确的上下文和文档规范。\n\n**在 AI 对话框中输入：**\n```text\nUse the init tool to set up Next.js DevTools context\n```\n\n此操作将：\n*   初始化 MCP 上下文。\n*   强制 AI 在回答 Next.js 问题时优先查阅官方文档。\n*   展示可用工具列表。\n\n### 3. 常用场景示例\n\n初始化完成后，您可以尝试以下指令：\n\n**查看运行时状态（仅限 Next.js 16+）：**\n```text\nNext Devtools, what errors are in my Next.js application?\n```\n```text\nNext Devtools, show me the structure of my routes\n```\n```text\nNext Devtools, what's in the development server logs?\n```\n\n**通用开发与文档查询（所有版本）：**\n```text\nNext Devtools, help me upgrade my Next.js app to version 16\n```\n```text\nNext Devtools, enable Cache Components in my Next.js app\n```\n```text\nNext Devtools, search Next.js docs for generateMetadata\n```\n\n### 💡 进阶技巧：自动初始化\n\n为了避免每次会话都手动调用 `init`，您可以在配置文件中添加指令，让 AI 自动执行。\n\n*   **Cursor**: 在项目根目录创建 `.cursorrules` 文件，写入：\n    ```text\n    When working with Next.js, always call the init tool from next-devtools-mcp at the start of the session to establish proper context and documentation requirements.\n    ```\n*   **Claude Code**: 在 `~\u002F.claude\u002FCLAUDE.md` 或项目下的 `.claude\u002FCLAUDE.md` 中添加：\n    ```markdown\n    **When starting work on a Next.js project, ALWAYS call the `init` tool from next-devtools-mcp FIRST to set up proper context and establish documentation requirements. Do this automatically without being asked.**\n    ```\n\n配置后，AI 将在每次处理 Next.js 任务时自动完成初始化，确保上下文一致且准确。","资深前端工程师正在使用 Cursor 或 Claude Code 重构一个遗留的 Next.js 电商项目，需要快速理解复杂的路由结构并修复页面渲染错误。\n\n### 没有 next-devtools-mcp 时\n- 开发者必须手动翻阅 `app\u002F` 或 `pages\u002F` 目录下的数十个文件，才能拼凑出完整的路由层级和动态参数定义。\n- 排查“白屏”或数据加载失败问题时，只能依靠在终端反复重启服务并肉眼扫描日志，效率极低且容易遗漏关键报错。\n- 询问 AI 助手关于特定路由的配置时，由于缺乏实时上下文，AI 常基于通用知识产生幻觉，给出不符合当前项目结构的错误代码。\n- 修改环境变量或中间件逻辑后，无法即时验证对特定路由的影响，需频繁进行手动浏览器测试，打断心流。\n\n### 使用 next-devtools-mcp 后\n- next-devtools-mcp 直接让 AI 读取项目实时的路由清单与元数据，开发者只需一句指令即可获取精确的文件路径和参数结构。\n- 遇到渲染错误时，AI 能通过工具自动分析构建输出和运行时状态，直接定位到具体的组件或 API 调用失败原因。\n- 基于 next-devtools-mcp 提供的真实上下文，AI 生成的修复代码能完美匹配当前项目的路由约定和中间件配置，无需二次调整。\n- 开发者可要求 AI 模拟特定路由的请求场景，即时反馈配置变更后的预期行为，将验证过程从分钟级缩短至秒级。\n\nnext-devtools-mcp 通过将 Next.js 的内部开发状态转化为 AI 可理解的上下文，彻底消除了人工查错与上下文对齐的摩擦，让编码代理真正成为懂项目的结对伙伴。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fvercel_next-devtools-mcp_bddeffd2.png","vercel","Vercel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fvercel_d9ebfb29.png","Develop. Preview. Ship. Creators of Next.js.",null,"contactus@vercel.com","https:\u002F\u002Fvercel.com","https:\u002F\u002Fgithub.com\u002Fvercel",[82,86],{"name":83,"color":84,"percentage":85},"TypeScript","#3178c6",89.8,{"name":87,"color":88,"percentage":89},"JavaScript","#f1e05a",10.2,712,50,"2026-04-10T02:40:40","Linux, macOS, Windows","未说明",{"notes":96,"python":97,"dependencies":98},"该工具是基于 Node.js 的 MCP 服务器，无需 Python 环境。支持 Windows、macOS 和 Linux。在 Windows 11 上使用 Codex 客户端时，需特殊配置环境变量和启动超时时间。运行 Next.js 16+ 项目时可自动连接本地开发服务器获取运行时诊断信息。","不需要",[99,100],"Node.js v20.19+","npm 或 ppm",[13],[103,104,105,106,107],"mcp-server","next-devtools","nextjs","coding-agents","mcp","2026-03-27T02:49:30.150509","2026-04-10T15:52:53.757640",[111,116,121,126,131,135,139],{"id":112,"question_zh":113,"answer_zh":114,"source_url":115},27792,"为什么在 Windows 上运行 `discover_servers` 时无法发现正在运行的 Next.js 开发服务器？","这是因为 Windows 系统没有 `ps aux` 命令，导致工具在尝试查找进程时失败。该问题已在后续版本中修复（参考 PR #67 和 #101）。如果遇到此问题，请确保将 `next-devtools-mcp` 更新到最新版本。此外，早期版本可能因缺少 `Accept: text\u002Fevent-stream` 请求头而返回 406 错误，新版已自动处理此头部信息。","https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fissues\u002F56",{"id":117,"question_zh":118,"answer_zh":119,"source_url":120},27793,"在 Windows 上使用 MCP 自动发现功能失败并返回 406 错误怎么办？","这是由于客户端发起请求时未包含必要的 `Accept` 请求头。Next.js MCP 端点要求客户端必须同时接受 `application\u002Fjson` 和 `text\u002Fevent-stream`。手动测试时，需使用如下 curl 命令：`curl -X POST http:\u002F\u002Flocalhost:3000\u002F_next\u002Fmcp -H \"Content-Type: application\u002Fjson\" -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" ...`。该问题已在最新版本中修复，请升级 `next-devtools-mcp` 至最新版以自动解决此问题。","https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fissues\u002F90",{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},27794,"执行 `next-devtools.init` 后，AI 代理（如 Codex）为什么会停止响应并进入空闲状态？","这是因为初始化完成的回复消息中包含过于严格的“禁止回复”指令，导致代理误以为任务结束。维护者已修改了初始化完成的提示语，软化了回复限制，使代理能继续处理后续请求。请升级到包含此修复的最新版本（参考 PR #110），即可解决代理在初始化后停滞的问题。","https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fissues\u002F109",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},27795,"如何在本地临时解决 Bun 运行时或 npm 缓存导致的 MCP 连接问题？","如果遇到运行时环境问题（如 npm 缓存损坏或 Bun 兼容性疑问），可以尝试将 MCP 服务器本地安装而不是全局运行。具体步骤是：在项目本地执行安装命令，然后在 `.mcp.json` 配置文件中将命令指向本地安装的路径。有用户反馈：“我在本地安装后，将路由指向本地实例，问题就解决了。”虽然这不是最理想的方案，但可作为临时变通方法。","https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fissues\u002F100",{"id":132,"question_zh":133,"answer_zh":134,"source_url":115},27796,"在 Windows 的 Cursor 编辑器中配置 MCP 时，为什么会出现连接失败或发现多个重复服务器？","这通常是因为配置文件 `.cursor\u002Fmcp.json` 中同时存在手动添加的条目和内置条目，导致冲突。建议检查配置文件，确保只保留一个正确的 `next-devtools` 服务器配置。如果问题依旧，请确认是否使用了最新版本的插件，因为旧版本在 Windows 上存在进程发现逻辑缺陷（依赖 `ps aux`）。更新到最新版本通常能解决此类发现和连接冲突问题。",{"id":136,"question_zh":137,"answer_zh":138,"source_url":130},27797,"如何正确向维护者报告关于 Bun 运行时的具体问题？","如果要报告 Bun 运行时相关的问题，必须提供可复现的详细步骤，否则问题可能会因信息不足被关闭。报告时需包含：1. 复现步骤（Steps to reproduce）；2. 预期行为与实际行为的对比（Expected vs actual behavior）；3. 使用的 Bun 版本号（Bun version）。仅提供模糊的请求（如“请添加 Bun 支持”）而无具体报错或场景描述，通常无法得到有效处理。",{"id":140,"question_zh":141,"answer_zh":142,"source_url":120},27798,"Mac 用户正常但 Windows 用户无法自动发现服务器，且手动指定端口可以成功，这是为什么？","这是 Windows 平台特有的兼容性问题。Mac 上的自动发现依赖于 Unix 风格的进程管理命令，而 Windows 缺乏相应环境导致自动探测失败。虽然自动发现（`discover_servers`）在旧版本 Windows 上失效，但你可以通过手动指定端口来绕过此限制，例如调用工具时显式传入参数：`nextjs_call({ port: 3000, toolName: 'get_routes' })`。建议尽快升级到修复了 Windows 进程查询逻辑的最新版本。",[144,149,154,159,164,169,174,179,184,189,194,199,204,209,214,219],{"id":145,"version":146,"summary_zh":147,"released_at":148},188704,"v0.3.10","## 变更内容\n* 文档：由 @0ldh 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F111 中向 README 添加了 Google Antigravity 的配置说明。\n* 性能：由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F112 中优化了文档查找性能。\n\n## 新贡献者\n* @0ldh 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F111 中完成了首次贡献。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.9...v0.3.10","2026-01-08T20:59:30",{"id":150,"version":151,"summary_zh":152,"released_at":153},188705,"v0.3.8","## 变更内容\n* 修复：由 @Burry 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F105 中修复，从截图结果中过滤 Base64 编码的图片\n* 修复（初始化）：避免因严格禁止回复而导致的代理空闲问题（修复 #109），由 @MapleCity1314 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F110 中完成\n\n## 新贡献者\n* @Burry 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F105 中完成了首次贡献\n* @MapleCity1314 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F110 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.7...v0.3.8","2026-01-02T21:44:21",{"id":155,"version":156,"summary_zh":157,"released_at":158},188706,"v0.3.7","### 修复\n* 修复：将 @modelcontextprotocol\u002Fsdk 升级至 1.24.3（CVE-2025-66414），由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F107 中完成\n\n### 其他\n* 修复：将 Next.js 升级至 16.0.7（CVE-2025-55182），由 @ctate 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F106 中完成\n\n* @ctate 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F106 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.6...v0.3.7","2025-12-12T08:41:12",{"id":160,"version":161,"summary_zh":162,"released_at":163},188707,"v0.3.6","### 改进\n\n* 修复截图功能因使用错误的 Playwright MCP 工具名称而导致的问题，由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F98 中完成\n* 改进端口发现机制，由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F101 中完成\n\n### 其他\n\n* ci：在版本号升级时更新 mcp 注册表的 server.json 文件，由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F102 中完成\n* 增加针对常见用户问题的故障排除章节，由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F97 中完成\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.5...v0.3.6","2025-12-05T13:37:39",{"id":165,"version":166,"summary_zh":167,"released_at":168},188708,"v0.3.5","## 变更内容\n* 通过将服务器列表和工具列表合并，简化 Next.js 服务器发现功能，由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F96 中实现。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.4...v0.3.5","2025-11-25T02:37:14",{"id":170,"version":171,"summary_zh":172,"released_at":173},188709,"v0.3.4","## 改进\n* 功能：在 #88 和 #93 中，由 @M1ngY 和 @huozhi 为 Next.js 开发服务器添加 HTTPS 支持\n* 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F92 中，@huozhi 将 nextjs 文档中的 llms.txt 内容添加为资源\n\n## 新贡献者\n* @M1ngY 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F88 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.3...v0.3.4","2025-11-21T14:41:18",{"id":175,"version":176,"summary_zh":177,"released_at":178},188710,"v0.3.3","## 变更内容\n* 由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F87 中修复了 WSL 下的服务器发现问题\n* 文档：将机制移至底部，由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F89 中完成\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.2...v0.3.3","2025-11-13T16:13:53",{"id":180,"version":181,"summary_zh":182,"released_at":183},188711,"v0.3.2","### 改进\n* 由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F82 中丰富缓存组件工具的描述\n* 由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F83 中移除迁移到缓存组件时的 useCache 标志\n* 由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F84 中处理路由处理器场景下的缓存使用\n* 由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F85 中添加 MCP 工具使用情况的遥测跟踪\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.1...v0.3.2","2025-11-08T19:43:46",{"id":185,"version":186,"summary_zh":187,"released_at":188},188712,"v0.3.1","### 补丁\n* 修复：由 @huozhi 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F81 中修复了 CJS 导入进程辅助工具的问题。\n\n\n**完整更新日志**：https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.3.0...v0.3.1","2025-11-06T01:00:57",{"id":190,"version":191,"summary_zh":192,"released_at":193},188713,"v0.3.0","### 功能\n* 由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F79 中添加了用于 Next.js MCP 的初始化工具\n\n\n\n### 其他\n* 由 @gaojude 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F69 中改进了 README 的清晰度，并移除了过时的实验性 MCP\n* 由 @quuu 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F80 中迁移到使用官方的 MCP TypeScript SDK\n\n## 新贡献者\n* @quuu 在 https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F80 中做出了他们的首次贡献\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.6...v0.3.0","2025-11-05T21:31:08",{"id":195,"version":196,"summary_zh":197,"released_at":198},188714,"v0.2.6","### Patches\r\n* bump deps and lock exact version by @huozhi in #77 and #78\r\n\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.5...v0.2.6","2025-11-04T16:25:05",{"id":200,"version":201,"summary_zh":202,"released_at":203},188715,"v0.2.5","### Patches\r\n* fix: discover next-server by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F75\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.4...v0.2.5","2025-11-03T23:28:14",{"id":205,"version":206,"summary_zh":207,"released_at":208},188716,"v0.2.4","### Patches\r\n* Fix Next.js runtime discovery on Windows by @gaojude in #67\r\n* fix: generateImageMetadata receives already awaited params by @icyJoseph in #71\r\n\r\n### Improvement\r\n* Use official docs search API to implement nextjs_docs MCP tool by @gaojude in #68\r\n\r\n\r\n### Misc\r\n* docs: update claude.md by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F72\r\n* ci: add job to bump version by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F73\r\n* ci: use vercel release bot by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F74\r\n\r\n## New Contributors\r\n* @icyJoseph made their first contribution in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F71\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.3...v0.2.4","2025-11-03T15:09:45",{"id":210,"version":211,"summary_zh":212,"released_at":213},188717,"v0.2.3","## Improvements\r\n\r\n* reduce prompt token size by reorganizing the knowledge by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F64\r\n* Clean up REQUIRES_CANARY_FOR_CACHE_COMPONENTS by @gaojude in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F65\r\n* detect version channel by @huozhi in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F66\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.1...v0.2.3","2025-10-29T20:58:33",{"id":215,"version":216,"summary_zh":217,"released_at":218},188718,"v0.2.2","### Improvements\r\n\r\n* Migrate to xmcp framework by @gaojude in https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fpull\u002F60\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp\u002Fcompare\u002Fv0.2.1...v0.2.2","2025-10-28T14:48:11",{"id":220,"version":221,"summary_zh":222,"released_at":223},188719,"v0.2.0","## Next.js DevTools MCP\r\n\r\n> 🎉 Frist official release of Next.js DevTool MCP \r\n\r\nNext.js DevTool MCP is a MCP server that connects AI coding agents and assistants to your Next.js\r\napplications, enabling direct interaction and intelligent automation.\r\n\r\n### Features\r\n\r\n- Automated upgrades to Next.js 16 with official codemods\r\n- Cache Components setup with error detection and fixing\r\n- Real-time runtime diagnostics from your dev server\r\n- Next.js 16 knowledge base and documentation search\r\n- Browser automation for testing and verification\r\n\r\n\r\nGet started with the [README.md](https:\u002F\u002Fgithub.com\u002Fvercel\u002Fnext-devtools-mcp) or learn more in the [Next.js MCP Guide](https:\u002F\u002Fnextjs.org\u002Fdocs\u002Fapp\u002Fguides\u002Fmcp).","2025-10-22T03:57:37"]