DevServer MCP

An MCP server that monitors development server logs in real-time, categorizes errors by type and severity, and provides Claude Code with immediate error notifications via Server-Sent Events (SSE).

DevServer MCP:

• Real-time notifications: Instant error alerts via SSE transport
• Intelligent parsing: Recognizes TypeScript, Svelte, Vite error patterns
• Error correlation: Links errors to recent file changes
• Severity classification: Critical vs warning vs info
• Multiple client support: Connect multiple Claude Code instances simultaneously
• AI integration: Claude Code receives structured error data instead of raw logs

Quick Start

# Install and build
pnpm install && pnpm build

# Start monitoring with SSE server (uses default port 9338)
node dist/server.js --monitor pnpm run dev

# Connect Claude Code (port stays consistent across restarts)
claude mcp add --transport sse devserver-mcp http://127.0.0.1:9338/sse

Now Claude Code receives immediate notifications when errors occur!

Core Workflow

Traditional debugging:

1. Notice something broken → 2. Scroll through terminal → 3. Find relevant error → 4. Google it

With DevServer MCP:

1. Error occurs → 2. Instant notification in Claude Code → 3. Get categorized errors with file locations → 4. Ask "How do I fix this?"

MCP Tools

• get_dev_server_status - Current server health and error counts
• get_error_summary - Errors grouped by type/severity
• get_error_history - Chronological error list with filtering
• get_file_errors - Errors for a specific file
• suggest_monitoring_setup - Project-specific setup recommendations

Port Configuration

Default Port (9338):

# Start with default port
node dist/server.js --monitor pnpm run dev

# Connect Claude Code  
claude mcp add --transport sse devserver-mcp http://127.0.0.1:9338/sse

Custom Port Per Project:

# Frontend project on port 9339
node dist/server.js --port 9339 --monitor pnpm run dev

# Backend project on port 9340  
node dist/server.js --port 9340 --monitor npm run dev:api

# Connect to specific projects
claude mcp add --transport sse frontend-devserver http://127.0.0.1:9339/sse
claude mcp add --transport sse backend-devserver http://127.0.0.1:9340/sse

Benefits:

• ✅ Consistent ports - same port every restart, no need to re-add MCP server
• ✅ Per-project ports - run multiple projects simultaneously
• ✅ Conflict detection - helpful error messages if port is already in use

Architecture

SSE-Based Real-Time System:

• Monitor mode (--monitor): Spawns dev server, parses logs, broadcasts errors via SSE
• HTTP server: Serves /sse endpoint for Claude Code connections on specified port
• Error buffering: Maintains recent error history for newly connected clients
• Multi-client support: Multiple Claude Code instances can connect simultaneously

Real-time error streaming means Claude Code gets notified within 1-2 seconds of any dev server issue.

Error Categories

Built-in patterns for:

• TypeScript compilation errors
• Svelte component warnings
• Vite build failures
• Network/API errors
• Runtime JavaScript errors
• Accessibility issues

Configuration

Create devserver-mcp.config.json:

{
    "processPatterns": ["pnpm run dev", "npm run dev"],
    "historyLimit": 1000,
    "correlationWindow": 5000,
    "watchPaths": ["src", "lib"],
    "excludePaths": ["node_modules", ".git"],
    "patterns": [
        {
            "name": "custom-error",
            "pattern": "CUSTOM: (.+)",
            "category": "runtime",
            "severity": "critical"
        }
    ]
}

Development

pnpm install     # Install deps
pnpm build       # Build project
pnpm dev         # Watch mode
pnpm test        # Run tests
pnpm typecheck   # Type checking

Troubleshooting

Connection Failed

# Check if monitoring server is running
ps aux | grep "node.*server.js"

# Restart monitoring server (default port 9338)
node dist/server.js --monitor pnpm run dev

# Verify connection
claude mcp add --transport sse devserver-mcp http://127.0.0.1:9338/sse

Port Already in Use

# Error: Port 9338 is already in use!
# Solution: Use a different port
node dist/server.js --port 9339 --monitor pnpm run dev

# Then connect with the new port
claude mcp add --transport sse devserver-mcp http://127.0.0.1:9339/sse

No Real-Time Notifications

# Check MCP connection status
claude mcp list

# Remove and reconnect if needed
claude mcp remove devserver-mcp
claude mcp add --transport sse devserver-mcp http://127.0.0.1:9338/sse

Multiple Projects

# Each project should use a different port
# Project A
node dist/server.js --port 9338 --monitor pnpm run dev

# Project B  
node dist/server.js --port 9339 --monitor npm run dev

# Connect both in Claude Code with different names
claude mcp add --transport sse project-a http://127.0.0.1:9338/sse
claude mcp add --transport sse project-b http://127.0.0.1:9339/sse

License

MIT