home / skills / mjunaidca / mjs-agent-skills / nextjs-devtools

nextjs-devtools skill

safe

/.claude/skills/nextjs-devtools

This skill helps you inspect and debug Next.js apps by exposing routes, components, and build info via MCP tooling.

npx playbooks add skill mjunaidca/mjs-agent-skills --skill nextjs-devtools

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.2 KB

---
name: nextjs-devtools
description: |
  Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps.
  Use when working on Next.js applications, debugging routing, or inspecting app structure.
  NOT for general React or non-Next.js projects.
---

# Next.js DevTools

Inspect and debug Next.js applications via MCP server.

## Quick Start

```bash
# Start server (spawns on-demand)
bash scripts/start-server.sh

# Or use directly via mcp-client
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t list-routes
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list-routes` | Get all app routes |
| `get-route-info` | Details for specific route |
| `list-components` | React components in app |
| `get-build-info` | Build configuration |
| `get-config` | next.config.js settings |

## Workflow Patterns

### Pattern 1: Route Inspection

```bash
# List all routes
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t list-routes

# Get specific route details
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t get-route-info \
  -p '{"route": "/api/auth"}'
```

### Pattern 2: Debug Build Issues

```bash
# Check build config
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t get-build-info

# Check next.config.js
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t get-config
```

### Pattern 3: Component Discovery

```bash
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t list-components
```

## Scripts

### start-server.sh

For persistent server (multiple calls):

```bash
bash scripts/start-server.sh
# Server runs on default port
# Use mcp-client.py with -u flag instead of -s
```

### On-Demand (Recommended)

For single calls, use `-s` flag which spawns server per-call:

```bash
python3 scripts/mcp-client.py call \
  -s "npx next-devtools-mcp@latest" \
  -t <tool-name>
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Server not starting | Check `npx next-devtools-mcp@latest` works manually |
| No routes found | Ensure running from Next.js project root |
| Build info empty | Run `next build` first |

Overview

This skill provides Next.js development tooling via an MCP server to inspect routes, components, build configuration, and runtime settings. It helps you quickly discover app structure and debug routing or build issues without manually searching the codebase. Use it from a project root to get targeted insights for Next.js apps only.

How this skill works

The skill runs tools through an MCP client that either spawns a short-lived server per call or connects to a persistent server. Available commands list routes, inspect a specific route, enumerate React components, and fetch build and next.config.js details. Results return structured information you can use to trace routing, verify builds, and locate components.

When to use it

When debugging routing problems or unexpected 404s in a Next.js app
When you need a quick inventory of pages, API routes, and components
When diagnosing build failures or verifying next.config.js settings
When onboarding into an unfamiliar Next.js codebase to map structure
When running CI or local checks that require programmatic route info

Best practices

Run commands from the Next.js project root to ensure accurate results
Use the on-demand spawn mode (-s) for single quick checks to avoid persistent processes
Start a persistent server for repeated inspections during long debugging sessions
Run next build before requesting build info to populate build-related data
Validate npx next-devtools-mcp@latest manually if the server fails to start

Example use cases

List all app routes to confirm which pages and API endpoints are exposed
Fetch route details for /api/auth to trace middleware, handlers, and params
Enumerate React components to find shared UI elements and potential duplicates
Inspect next.config.js to verify rewrites, redirects, and experimental flags
Check build info when a deployment fails to identify misconfigured outputs

FAQ

Is this tool suitable for non-Next.js React projects?

No. The tooling specifically inspects Next.js conventions and config; it will not provide meaningful results for generic React apps.

Should I run a persistent server or use on-demand mode?

Use on-demand mode (-s) for single commands. Start the persistent server when you need to run many inspections in a session to save startup overhead.