@ai-mapping/mcp-nextjs-dev/README.md

MCP server for managing Next.js development processes with AI tools

# @ai-mapping/mcp-nextjs-dev

> MCP server for managing Next.js development processes with Claude Code

An official Model Context Protocol (MCP) server that enables AI assistants like Claude Code to manage Next.js development servers without blocking. Start, monitor, and debug Next.js applications seamlessly through AI-powered development workflows.

## Features

🚀 **Non-blocking Next.js development server management**  
📊 **Real-time log access and filtering**  
🛠️ **Process monitoring and control**  
🔧 **Debug-friendly with comprehensive error handling**  
🤖 **Optimized for AI assistant integration**

## Problem Solved

Claude Code hangs when running `npm run dev` because the process doesn't terminate. This MCP server provides asynchronous tools to start Next.js development servers in the background and access their logs for analysis.

## Installation

### Prerequisites
- Node.js 22+ 
- Next.js project

### Quick Start
```bash
# Install and run
npx @ai-mapping/mcp-nextjs-dev

# Or install globally
npm install -g @ai-mapping/mcp-nextjs-dev
mcp-nextjs-dev
```

### Claude Code Integration
Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "nextjs-dev": {
      "command": "npx",
      "args": ["@ai-mapping/mcp-nextjs-dev"],
      "cwd": "."
    }
  }
}
```

## Usage with Claude Code

### Example Prompts

**Start Development Server:**
```
"Start the Next.js development server for this project"
```

**Check for Errors:**
```
"Are there any compilation errors in the Next.js logs? Show me the last 20 error messages."
```

**Monitor Server Status:**
```
"Is the Next.js development server still running? What's the current status?"
```

**Debug Issues:**
```
"The app isn't working. Can you check the Next.js logs for any warnings or errors in the last 2 minutes?"
```

**Clean Shutdown:**
```
"Stop the Next.js development server and clean up any processes."
```

### Available Tools

- `nextjs_dev_start` - Start Next.js development server
- `nextjs_get_logs` - Retrieve filtered development logs  
- `nextjs_get_status` - Check server status and uptime
- `nextjs_stop_server` - Stop development server gracefully

## Configuration

### Command Line Options
```bash
npx @ai-mapping/mcp-nextjs-dev --help
npx @ai-mapping/mcp-nextjs-dev --debug
```

### Environment Variables
```bash
# Enable debug logging
DEBUG=1 npx @ai-mapping/mcp-nextjs-dev
```

## Development

This project uses:
- TypeScript with ES modules
- Node.js 22+ features
- Official MCP SDK
- pnpm package manager

### Building from Source
```bash
# Clone the repository
git clone https://github.com/ai-mapping/mcp-nextjs-dev.git
cd mcp-nextjs-dev

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test
```

### Project Structure
```
@ai-mapping/mcp-nextjs-dev/
├── src/
│   ├── server.ts          # Main MCP server
│   ├── cli.ts            # CLI entry point
│   ├── managers/         # Process and state management
│   └── types/            # TypeScript definitions
├── dist/                 # Compiled JavaScript
└── bin/                  # Executable scripts
```

## Troubleshooting

### Common Issues

**Port Already in Use:**
```bash
# Check what's using the port
lsof -i :3000
# Kill the process
kill -9 <PID>
```

**MCP Connection Issues:**
```bash
# Test MCP server directly
npx @modelcontextprotocol/inspector npx @ai-mapping/mcp-nextjs-dev
```

**Debug Mode:**
```bash
# Enable detailed logging
DEBUG=1 npx @ai-mapping/mcp-nextjs-dev --debug
```

### Getting Help

- 📚 [MCP Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- 🐛 [Report Issues](https://github.com/ai-mapping/mcp-nextjs-dev/issues)
- 💬 [Discussions](https://github.com/ai-mapping/mcp-nextjs-dev/discussions)

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- 🏠 [Homepage](https://github.com/ai-mapping/mcp-nextjs-dev)
- 📦 [NPM Package](https://www.npmjs.com/package/@ai-mapping/mcp-nextjs-dev)
- 🚀 [AI Mapping Organization](https://github.com/ai-mapping)

---

Made with ❤️ by the [AI Mapping](https://github.com/ai-mapping) team