mcp-tools

# Next.js DevTools MCP `next-devtools-mcp` (current version 0.4.0) is Vercel's official MCP server for Next.js development. It is a **thin connector**: it discovers running Next.js 16+ dev servers and proxies their built-in MCP endpoint at `/_next/mcp`, plus provides two gateways — one to version-matched documentation, one to browser automation. As of 0.4.0 the server exposes exactly four tools: `nextjs_index`, `nextjs_call`, `nextjs_docs`, and `browser_eval`. ## Setup Add to project `.mcp.json`: ```json { "mcpServers": { "next-devtools": { "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] } } } ``` Or install via CLI: ```bash # Universal (writes the right config for your detected client) npx add-mcp next-devtools-mcp@latest # Claude Code claude mcp add next-devtools npx next-devtools-mcp@latest # Cursor # Go to Settings → MCP → New MCP Server # VS Code code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}' ``` Requirements: - Node.js v20.19+ - For runtime tools (`nextjs_index`, `nextjs_call`): Next.js 16+ with the dev server running — use **`next@>=16.3.8`**: before it, the dev server's `/_next/mcp` endpoint did not verify which website a request came from, so a malicious page visited by the developer could read the project path, error-report source snippets, the route inventory and dev logs (GHSA-39w2-rjm5-chcv, low severity, dev server only). Update `next` before wiring this up > **Removed in 0.4.0:** the `init`, `upgrade_nextjs_16`, and `enable_cache_components` tools no longer exist. Upgrade and Cache Components workflows now live in the upgrade codemod (`npx @next/codemod@canary upgrade latest`, or the `next upgrade` command in 16.1+) and the migration guide at `/docs/app/guides/migrating-to-cache-components`. ## Tools Reference ### `nextjs_index` Discover all running Next.js 16+ dev servers and list their available MCP tools. No parameters required. Returns JSON with discovered servers (port, PID, URL) and available tools. Typical runtime tools per server (the exact set varies by Next.js version): - `get_errors` — Current build, runtime, and type errors - `get_logs` — Path to development log file - `get_page_metadata` — Route and component metadata - `get_project_metadata` — Project structure and config - `get_routes` — All filesystem routes grouped by router type (added in 16.1) - `get_server_action_by_id` — Look up Server Actions by ID - `get_compilation_issues` — Compilation issues from the bundler (16.3+, Turbopack only) - `compile_route` — Compile a route on demand; accepts a route specifier like `/blog/[slug]` or a path like `/blog/hello` (16.3+, Turbopack only) ### `nextjs_call` Execute a specific tool on a running Next.js dev server. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `port` | number | Yes | Dev server port (from `nextjs_index`) | | `toolName` | string | Yes | Tool name to invoke | | `args` | object | No | Arguments for the tool | ### `nextjs_docs` A **gateway** to version-accurate Next.js documentation. It no longer takes search/get parameters — instead it points the agent at the docs bundled with the installed Next.js version at `node_modules/next/dist/docs/`, which the agent then reads directly as files. Since Next.js 16.3, `next dev` also auto-writes a version-matched AGENTS.md block pointing at these bundled docs (see `/docs/app/guides/ai-agents`), so agents get correct documentation with zero setup. ### `browser_eval` A **gateway** to the [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI. It is not a Playwright action proxy — instead of taking `start`/`navigate`/`click` actions, it tells the agent how to install and run the `agent-browser` CLI for browser automation. Use for: - Verifying pages after changes - Detecting hydration errors visually - Taking screenshots for comparison - Capturing browser console errors **React introspection (agent-browser 0.27 or later).** Launch `agent-browser` with `--enable react-devtools` to get React DevTools commands on top of DOM, console, network and Web Vitals: `react tree` (component tree), `react inspect <fiberId>` (one component), `react renders start` / `stop` (profile re-renders) and `react suspense --only-dynamic --json` (what is holding a render — handy for Cache Components blocking-route errors). Install or upgrade with `npm install -g agent-browser@latest` (the 16.3 release post pinned `agent-browser@^0.27`; the requirement is 0.27 or later). ## First-party Next.js Agent Skills (16.3) Next.js 16.3 retired the old knowledge-only skills (the bundled docs now do that job) and ships four workflow skills, installed with `npx skills add vercel/next.js --skill <name>`: | Skill | Use for | |-------|---------| | `next-dev-loop` | Full dev feedback loop: `/_next/mcp` (routes, logs, compilation issues) plus `agent-browser` (DOM, console, network, React tree). Needs agent-browser 0.27+ | | `next-cache-components-adoption` | Turns Cache Components on and adopts routes one feature at a time (incremental or direct mode) | | `next-cache-components-optimizer` | Turns "this navigation must be instant" into a failing `instant()` test and works it to green | | `next-partial-prefetching-adoption` | Enables Partial Prefetching and works through links until each reuses a shared loading shell | Other 16.3 agent affordances: any docs page is available as Markdown by appending `.md` to the URL (index at `/docs/llms.txt`, everything in `/docs/llms-full.txt`), and `agentRules: false` in `next.config.ts` stops `next dev` from maintaining the AGENTS.md block. ## Typical Workflow 1. **Start dev server** — `npm run dev` 2. **Discover servers** — Call `nextjs_index` to find running instances 3. **Check errors** — Call `nextjs_call` with `get_errors` 4. **Read docs** — Use the `nextjs_docs` gateway to locate the bundled docs, then read the files directly 5. **Verify changes** — Use the `browser_eval` gateway to drive `agent-browser` for screenshots and testing ## Architecture ``` Coding Agent ↓ next-devtools-mcp ↓ ├─→ Next.js Dev Server (/_next/mcp) — Runtime diagnostics ├─→ agent-browser CLI (gateway) — Browser automation └─→ node_modules/next/dist/docs/ (gateway) — Version-matched docs ``` The MCP server bridges the agent to three systems: the running Next.js app, the `agent-browser` CLI, and the documentation bundled with the installed Next.js version. ## Zero-Setup Docs Tip Since Next.js 16.3, running `next dev` automatically maintains an AGENTS.md block in your project that points coding agents at the version-matched docs in `node_modules/next/dist/docs/`. No manual CLAUDE.md instructions are needed — the framework keeps agents aligned with the exact installed version.