ai-debug-local-mcp/core/packages/ai-debug-mcp-server/README.md

🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh

# @ai-debug/mcp-server

Pure MCP (Model Context Protocol) debugging server for AI-powered debugging tools. This package provides a clean, minimal implementation of debugging tools that can be used by any MCP-compatible client.

## Features

- **Frontend Debugging**: Launch debugging sessions, capture screenshots, monitor console logs
- **Performance Auditing**: Run comprehensive performance audits with Lighthouse
- **Accessibility Testing**: Automated accessibility audits
- **User Interaction Simulation**: Click, type, scroll, and navigate programmatically
- **Network Mocking**: Mock API responses and simulate network conditions
- **AI-Powered Analysis**: Analyze debugging sessions with AI (requires API key)
- **Framework Detection**: Auto-detects React, Vue, Angular, Next.js, and more

## Installation

```bash
npm install @ai-debug/mcp-server
```

## Usage

### As an MCP Server

The package can be run as a standalone MCP server:

```bash
npx @ai-debug/mcp-server
```

### Programmatic Usage

```typescript
import { AiDebugMcpServer } from '@ai-debug/mcp-server';

const server = new AiDebugMcpServer();
await server.start();
```

### Available Tools

#### Debug Tools
- `inject_debugging` - Launch a debugging session for a URL
- `close_debugging` - Close an active debugging session

#### Screenshot Tools
- `take_screenshot` - Capture a screenshot of the current page
- `compare_screenshots` - Compare two screenshots for visual differences

#### Audit Tools
- `run_audit` - Run a comprehensive quality audit
- `accessibility_audit` - Run accessibility checks
- `performance_audit` - Run performance benchmarks

#### Monitoring Tools
- `monitor_realtime` - Monitor page activity in real-time
- `get_console_logs` - Retrieve console logs from the page
- `get_network_activity` - Get network request details

#### Interaction Tools
- `simulate_user_action` - Simulate clicks, typing, scrolling
- `fill_form` - Automatically fill form fields
- `navigate_to` - Navigate to a different URL

#### Report Tools
- `get_debug_report` - Generate a comprehensive debugging report
- `export_session` - Export session data for analysis

#### Analysis Tools
- `analyze_with_ai` - AI-powered analysis of debugging data
- `detect_issues` - Automatically detect common issues

#### Network Tools
- `mock_network` - Mock API responses
- `throttle_network` - Simulate slow network conditions

## Configuration

The server supports the following environment variables:

- `AI_DEBUG_API_KEY` - API key for AI-powered features
- `DEBUG_PORT` - Port for the debugging server (default: 9222)
- `HEADLESS` - Run browser in headless mode (default: true)

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
```

## Architecture

The server is built with:
- TypeScript for type safety
- Playwright for browser automation
- MCP SDK for protocol implementation
- Modular architecture for easy extension

## License

MIT