debug-mcp-server

Debug MCP Server

An MCP (Model Context Protocol) server that bridges web browsers and Claude Code for seamless debugging workflows.

Overview

This server receives debug data from browser widgets (console logs, error stacks, screenshots) and exposes it to Claude Code via the MCP protocol. It also facilitates interactive Q&A between Claude Code and browser users.

Features

• Debug Data Ingestion: HTTP endpoints to receive debug reports from browsers
• MCP Tools: Expose debug data to Claude Code through MCP protocol
• Interactive Q&A: WebSocket-based bidirectional communication for clarification questions
• File Storage: Organized filesystem storage for reports and screenshots
• Localhost Only: Secure local-only server for development use

Quick Start

Installation

# Global installation
npm install -g @yourco/debug-mcp-server

# Or use npx
npx @yourco/debug-mcp-server

Running the Server

# Start the server
debug-mcp-server

# Or with custom port
DEBUG_MCP_PORT=4000 debug-mcp-server

Configuration

Create ~/.debug-mcp/config.json:

{
  "port": 3000,
  "storagePath": "~/.debug-mcp",
  "retentionDays": 7
}

Or use environment variables:

• DEBUG_MCP_PORT - HTTP server port (default: 3000)
• DEBUG_MCP_STORAGE_PATH - Storage directory (default: ~/.debug-mcp)
• DEBUG_MCP_RETENTION_DAYS - Report retention period (default: 7)

MCP Integration

Connect Claude Code to Server

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "debug-reports": {
      "command": "node",
      "args": ["/path/to/debug-mcp-server/dist/index.js"]
    }
  }
}

Available MCP Tools

• submit_debug_report - Receive debug data from browser
• list_debug_reports - List all stored debug reports
• get_debug_report - Retrieve specific debug report by ID
• ask_user_questions - Send questions to browser and wait for answers
• clear_old_reports - Clean up old debug data

Available MCP Resources

• debug://reports/latest - Get most recent debug report
• debug://reports/{id} - Get specific report by ID
• debug://screenshots/{id} - Access screenshot files

API Endpoints

POST /api/debug

Receive debug data from browser widget.

Request Body:

{
  "logs": [
    { "level": "error", "message": "Error message", "timestamp": 1234567890 }
  ],
  "error": {
    "message": "TypeError: Cannot read property...",
    "stack": "Error stack trace..."
  },
  "screenshot": "data:image/png;base64,...",
  "comment": "User description of the issue",
  "url": "https://example.com/page",
  "timestamp": 1234567890
}

Response:

{
  "success": true,
  "data": {
    "reportId": "abc123",
    "timestamp": 1234567890
  }
}

POST /api/questions/answer

Receive answers from browser to Claude's questions.

Request Body:

{
  "sessionId": "session-123",
  "answers": [
    { "questionId": "q1", "answer": "User's answer" }
  ]
}

Development

Setup

# Clone the repository
git clone https://github.com/yourco/debug-mcp-server.git
cd debug-mcp-server

# Install dependencies
npm install

# Run in development mode
npm run dev

Project Structure

debug-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── mcp/                  # MCP server implementation
│   ├── http/                 # HTTP/WebSocket servers
│   ├── storage/              # File storage layer
│   ├── types/                # TypeScript types
│   └── config/               # Configuration
├── specs/                    # SpecKit specifications
├── tests/                    # Jest tests
└── logs/                     # Session logs

Testing

# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Run linter
npm run lint

Building

# Build for production
npm run build

# Output: dist/index.js

Architecture

┌─────────────────────┐
│  Browser Widget     │
│  (HTTP/WebSocket)   │
└──────────┬──────────┘
           │
           ↓
┌─────────────────────────────────────┐
│  Debug MCP Server                   │
│  ┌─────────────────────────────┐    │
│  │ HTTP Server (Express)       │    │
│  │  - POST /api/debug          │    │
│  │  - POST /api/questions      │    │
│  └─────────────────────────────┘    │
│  ┌─────────────────────────────┐    │
│  │ WebSocket Server            │    │
│  │  - Push questions to browser│    │
│  └─────────────────────────────┘    │
│  ┌─────────────────────────────┐    │
│  │ MCP Server                  │    │
│  │  - Tools & Resources        │    │
│  └─────────────────────────────┘    │
│  ┌─────────────────────────────┐    │
│  │ File Storage                │    │
│  │  - ~/.debug-mcp/            │    │
│  └─────────────────────────────┘    │
└──────────┬──────────────────────────┘
           │
           ↓
┌─────────────────────┐
│  Claude Code        │
│  (VS Code)          │
└─────────────────────┘

Storage Structure

~/.debug-mcp/
├── reports/
│   ├── 2025-11-26/
│   │   ├── report-abc123.json
│   │   └── report-def456.json
│   └── 2025-11-27/
│       └── report-ghi789.json
├── screenshots/
│   ├── screenshot-abc123.png
│   └── screenshot-def456.png
└── config.json

Troubleshooting

Server won't start

Check if port is already in use:

lsof -i :3000

Use a different port:

DEBUG_MCP_PORT=4000 debug-mcp-server

Claude Code can't connect

1. Verify server is running: curl http://localhost:3000/api/health
2. Check MCP configuration in Claude Code settings
3. Restart VS Code after config changes

Browser widget can't send data

1. Verify server is running on localhost:3000
2. Check browser console for CORS errors
3. Ensure browser has network access to localhost

Contributing

See CLAUDE.md for development guidelines and project constitution.

License

MIT

Support

For issues and feature requests, please open an issue on GitHub.