1AQuantum/websee-mcp-server

WebSee MCP Server

Frontend Debugging Intelligence for AI Coding Assistants

56 MCP tools for debugging frontend applications with AI assistance. Works with Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, and OpenAI Codex.

Features

• Source Map Resolution - Transform minified stack traces to original source code
• Component Intelligence - Inspect React/Vue/Angular component state, props, and hierarchy
• Performance Profiling - Long tasks, memory leaks, Web Vitals, paint timing
• Timeline Recording - Session recording with screenshots, events, and replay
• State Evolution - Watch component state changes over time
• Network Analysis - Trace requests, timing, headers, and response bodies
• Error Intelligence - Comprehensive error context with AI-suggested causes
• Watch Mode - Proactive monitoring with configurable triggers
• Bundle Analysis - Webpack/Vite bundle size and dependency analysis

Quick Start

# Clone and setup
git clone https://github.com/1AQuantum/websee-mcp-server.git
cd websee-mcp-server
npm run setup

# Build for production
npm run build

Then configure your AI coding assistant using the instructions below.

Installation by Platform

Claude Code

Method 1: CLI (Recommended)

# Navigate to the websee directory
cd /path/to/websee-mcp-server

# Add the MCP server
claude mcp add websee -- node dist/mcp-server.js

# Verify installation
claude mcp list

Method 2: Project Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Then enable in .claude/settings.local.json:

{
  "enabledMcpjsonServers": ["websee"]
}

Cursor IDE

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Then go to Cursor Settings > Tools & Integrations > MCP and click refresh.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Requires the GitHub Copilot Chat extension with MCP support enabled.

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

macOS/Linux:

mkdir -p ~/.codeium/windsurf

Windows:

mkdir %USERPROFILE%\.codeium\windsurf

Add configuration:

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Open Windsurf Settings (Cmd/Ctrl + ,) > Cascade > Plugins (MCP servers) to verify.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp.servers.websee]
command = "node"
args = ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"]

[mcp.servers.websee.env]
BROWSER = "chromium"
HEADLESS = "true"

Or use the CLI:

codex mcp add websee -- node /path/to/websee-mcp-server/dist/mcp-server.js

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/absolute/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "chromium",
        "HEADLESS": "true"
      }
    }
  }
}

Restart Claude Desktop after saving.

Available Tools (56 Total)

Workflow Tools (6)

High-level debugging workflows that combine multiple capabilities:

Component Intelligence (8)

Performance Intelligence (5)

Error Intelligence (5)

Network Intelligence (6)

Timeline Intelligence (8)

State Intelligence (4)

Watch Mode (2)

Build Intelligence (5)

Source Intelligence (7)

Configuration Options

Environment Variables

Example with Environment Variables

{
  "mcpServers": {
    "websee": {
      "command": "node",
      "args": ["/path/to/websee-mcp-server/dist/mcp-server.js"],
      "env": {
        "BROWSER": "firefox",
        "HEADLESS": "false"
      }
    }
  }
}

Usage Examples

Once configured, ask your AI assistant:

"Debug the login form at https://example.com - check for JavaScript errors"

"Analyze performance of https://myapp.com/dashboard - find slow API calls"

"Inspect the UserProfile component state at https://app.com"

"Start recording a session on https://shop.com and capture user interactions"

"Watch https://myapp.com for any console errors or network failures"

"Profile memory usage on https://dashboard.com to find leaks"

Development

# Install dependencies
npm install

# Install browsers
npx playwright install chromium

# Build
npm run build

# Run tests
npm test

# Start MCP server directly
npm run mcp:serve

Project Structure

websee-mcp-server/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── mcp-server.ts            # MCP server implementation
│   ├── tools/                   # MCP tool implementations
│   │   ├── component-intelligence-tools.ts
│   │   ├── performance-intelligence-tools.ts
│   │   ├── error-intelligence-tools.ts
│   │   ├── network-intelligence-tools.ts
│   │   ├── timeline-intelligence-tools.ts
│   │   ├── state-intelligence-tools.ts
│   │   ├── watch-mode-tools.ts
│   │   ├── build-intelligence-tools.ts
│   │   └── source-intelligence-tools.ts
│   ├── timeline/                # Timeline recording system
│   ├── source-map-resolver.ts   # Source map resolution
│   ├── component-tracker.ts     # Component inspection
│   └── network-tracer.ts        # Network tracing
├── dist/                        # Compiled output
├── examples/                    # Configuration examples
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

MCP Server Not Appearing

1. Verify the path is absolute (not relative)
2. Ensure you ran npm run build
3. Restart your AI coding assistant
4. Check MCP logs in your tool's settings

Browser Launch Fails

# Install browsers with dependencies
npx playwright install --with-deps chromium

Source Maps Not Found

• Ensure your app generates source maps
• Source maps must be accessible (same origin or CORS enabled)
• Check browser DevTools Network tab for .map files

Component Tracking Not Working

• React: Must be in development mode
• Vue: Requires Vue DevTools concepts enabled
• Angular: Requires development mode

Requirements

• Node.js 18.0.0 or higher
• Operating System: macOS, Linux, or Windows
• Browsers: Chromium, Firefox, or WebKit (installed via Playwright)

License

MIT - See for details.

Links

• Model Context Protocol - MCP Specification
• Playwright - Browser Automation
• GitHub Repository

Ready to debug with AI? Clone, build, and connect to your favorite AI coding assistant!