ai-debug-local-mcp/AI-CODING-ASSISTANT-INTEGRATION.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 Coding Assistant Integration Guide

## Complete setup instructions for Claude Code, Cursor, Windsurf, Cline, and more

This guide provides step-by-step instructions for integrating the enhanced AI-Debug MCP server (v2.27.1) with all major AI coding assistants. The server provides **258+ debugging tools**, **visual workflow validation**, **framework-aware testing**, and **sub-agent orchestration**.

---

## 🚀 Quick Install (All Platforms)

```bash
npm install -g ai-debug-local-mcp@latest
```

---

## 🎯 Claude Code / Claude Desktop Integration

**Note**: Claude Code (claude.ai/code) and Claude Desktop are the same application.

### ⚡ Automated Setup (Recommended)
```bash
npx ai-debug-setup claude
```

### 📝 Manual Setup

1. **Locate your Claude config file:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Add AI-Debug MCP server:**
```json
{
  "mcpServers": {
    "ai-debug": {
      "command": "ai-debug-mcp",
      "args": [],
      "env": {
        "AI_DEBUG_MODE": "enhanced",
        "VISUAL_VALIDATION": "true"
      }
    }
  }
}
```

3. **Restart Claude Desktop**

4. **Verify installation in Claude Code:**
```javascript
// Test basic functionality
await inject_debugging({ url: "http://localhost:3000" })

// Test visual workflow capabilities
await create_workflow_template({
  workflow: {
    name: "test-integration",
    visualValidation: true,
    steps: [
      {
        name: "capture-homepage",
        action: "take_screenshot",
        data: { filename: "integration-test" }
      }
    ]
  }
})
```

### 🎯 Claude Code Specific Features
- **Sub-agent orchestration**: Automatic delegation to specialized debugging agents
- **Context preservation**: Keeps detailed debugging output in sub-agent contexts
- **Visual workflow validation**: AI can "see" and validate each workflow step
- **Framework detection**: Automatic optimization for Phoenix, React, Flutter, etc.

---

## 🎯 Cursor Integration 

### ⚡ Automated Setup (Recommended)
```bash
npx ai-debug-setup cursor
```

### 📝 Manual Setup

1. **Open Cursor settings:**
   - Press `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux)
   - Navigate to **Extensions** → **MCP Settings**

2. **Add MCP server configuration:**
```json
{
  "mcp.servers": {
    "ai-debug": {
      "command": "ai-debug-mcp",
      "args": [],
      "description": "AI-Debug Enhanced Visual Workflow Validation",
      "capabilities": ["debugging", "testing", "visual-validation", "framework-detection"]
    }
  }
}
```

3. **Alternative: Via settings.json**
   - Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
   - Search: "Preferences: Open Settings (JSON)"
   - Add the configuration above

4. **Restart Cursor**

5. **Verify in Cursor:**
   - Open a web project
   - In chat, ask: "Use AI-Debug to test my application"
   - Should see 258+ tools available

### 🎯 Cursor Specific Benefits
- **Inline debugging**: Visual validation results displayed inline with code
- **Multi-file workflows**: Test complex user journeys across multiple components
- **Framework optimization**: Automatic detection and optimization for your stack

---

## 🎯 Windsurf Integration

### ⚡ Automated Setup (Recommended)
```bash
npx ai-debug-setup windsurf
```

### 📝 Manual Setup

1. **Open Windsurf preferences:**
   - **macOS**: `Windsurf` → `Preferences`
   - **Windows/Linux**: `File` → `Preferences`

2. **Navigate to MCP Settings:**
   - Go to **Extensions** → **Model Context Protocol**

3. **Add AI-Debug server:**
   - **Server Name**: `ai-debug`
   - **Command**: `ai-debug-mcp`
   - **Arguments**: (leave empty)
   - **Working Directory**: (optional - your project directory)

4. **Advanced configuration (optional):**
```json
{
  "mcp": {
    "servers": {
      "ai-debug": {
        "command": "ai-debug-mcp",
        "args": [],
        "env": {
          "AI_DEBUG_VISUAL_MODE": "true",
          "FRAMEWORK_DETECTION": "auto"
        }
      }
    }
  }
}
```

5. **Restart Windsurf**

### 🎯 Windsurf Specific Features
- **Visual workflow builder**: GUI for creating complex testing workflows
- **Real-time debugging**: Live debugging session management
- **Team collaboration**: Share debugging sessions and visual evidence

---

## 🎯 Cline (VS Code Extension) Integration

### 📝 Setup Instructions

1. **Install Cline extension** in VS Code

2. **Configure MCP servers** in VS Code settings:
   - Open **Settings** (`Cmd+,` / `Ctrl+,`)
   - Search for "cline mcp"
   - Or edit `settings.json` directly:

```json
{
  "cline.mcpServers": {
    "ai-debug": {
      "command": "ai-debug-mcp",
      "args": [],
      "description": "AI-Debug Enhanced Debugging with Visual Validation"
    }
  }
}
```

3. **Restart VS Code**

4. **Verify in Cline:**
   - Open Cline panel
   - Ask: "Use AI-Debug to analyze my web application"
   - Should see enhanced debugging capabilities

### 🎯 Cline Specific Benefits
- **VS Code integration**: Native integration with VS Code debugging tools
- **Terminal workflow**: Seamless integration with VS Code terminal
- **Extension ecosystem**: Works with other VS Code debugging extensions

---

## 🎯 Continue.dev Integration

### 📝 Setup Instructions

1. **Create/edit Continue config:**
   - Location: `~/.continue/config.json`

```json
{
  "mcpServers": {
    "ai-debug": {
      "command": "ai-debug-mcp",
      "args": [],
      "capabilities": {
        "visualWorkflows": true,
        "frameworkDetection": true,
        "subAgentOrchestration": true
      }
    }
  }
}
```

2. **Restart your editor**

3. **Test integration:**
   - Ask Continue: "Debug my React application with visual validation"

---

## 🎯 Aider Integration

### 📝 Setup Instructions

1. **Configure Aider with MCP support:**
```bash
# Set environment variable
export AIDER_MCP_SERVERS='{"ai-debug": {"command": "ai-debug-mcp", "args": []}}'

# Or create .aider.conf.yml
mcp_servers:
  ai-debug:
    command: ai-debug-mcp
    args: []
```

2. **Run Aider with MCP support:**
```bash
aider --mcp
```

---

## 🎯 Universal MCP Setup (Any Assistant)

For AI assistants that support MCP but aren't specifically mentioned:

### 📝 Generic MCP Configuration

```json
{
  "mcpServers": {
    "ai-debug": {
      "command": "ai-debug-mcp",
      "args": [],
      "transport": "stdio",
      "capabilities": [
        "debugging",
        "visual-validation", 
        "framework-detection",
        "workflow-automation",
        "performance-analysis",
        "accessibility-testing"
      ]
    }
  }
}
```

---

## 🔧 Troubleshooting & Verification

### ✅ Verify Installation

1. **Check AI-Debug is installed:**
```bash
ai-debug-mcp --version
# Should output: 2.27.1 or higher
```

2. **Test MCP server directly:**
```bash
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | ai-debug-mcp
# Should return list of 258+ tools
```

3. **Check for visual workflow tools:**
```bash
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | ai-debug-mcp | grep -i "visual\|workflow\|screenshot"
```

### 🐛 Common Issues

**Issue**: "ai-debug-mcp command not found"
```bash
# Solution: Reinstall globally
npm uninstall -g ai-debug-local-mcp
npm install -g ai-debug-local-mcp@latest
```

**Issue**: "No tools available"
```bash
# Solution: Check MCP configuration syntax
# Verify JSON is valid and restart your AI assistant
```

**Issue**: "Visual validation not working"
```bash
# Solution: Ensure browser dependencies
npx playwright install chromium
```

### 🔍 Advanced Diagnostics

```bash
# Check all installed AI-Debug tools
ai-debug-mcp --list-tools

# Run comprehensive diagnostics
ai-debug-mcp --diagnose

# Check sub-agent capabilities
ai-debug-mcp --sub-agent-status
```

---

## 🎯 Enhanced Capabilities Overview

Once integrated, you'll have access to:

### 🚀 Core Debugging (258+ Tools)
- **inject_debugging**: Start debugging sessions with automatic framework detection
- **monitor_realtime**: Real-time application monitoring
- **run_audit**: Comprehensive quality audits (performance, accessibility, security)
- **analyze_with_ai**: AI-powered analysis and recommendations

### 📸 Visual Workflow Validation
- **create_workflow_template**: Design complex user journey tests
- **execute_user_journey**: Run workflows with visual validation
- **take_workflow_screenshot**: Capture and analyze UI states
- **visual_workflow_validation**: AI-powered visual regression testing

### 🎯 Framework-Specific Tools
- **Flutter**: `flutter_quantum_interact`, `flutter_widget_tree`, `flutter_performance_monitor`
- **Phoenix LiveView**: `phoenix_liveview_debug`, `phoenix_connection_monitor`
- **Next.js**: `nextjs_performance_analyzer`, `nextjs_bundle_inspector`
- **React/Vue/Angular**: Universal workflow tools with framework detection

### 🤖 Sub-Agent Orchestration
- **Automatic delegation**: AI routes tasks to specialized agents
- **Context preservation**: Keeps detailed debugging output separate
- **Token optimization**: Saves 1000-7500 tokens per complex debugging session

### 🧪 Automatic Test Generation
- **"Debug Once, Test Forever"**: Every debugging session generates enterprise-quality tests
- **Failure learning**: Tests generated from both successes AND failures
- **Domain-specific**: Performance tests, accessibility tests, error prevention tests

---

## 🎉 Success Metrics

After integration, expect:

- **📸 Complete Visual Documentation**: Every workflow captured with screenshots
- **🤖 AI-Powered Insights**: Intelligent analysis of application behavior
- **⚡ Faster Debugging**: Framework-aware optimization and sub-agent efficiency  
- **🎯 Better Test Coverage**: Automatic test generation from debugging sessions
- **🔍 Proactive Issue Detection**: AI identifies potential problems before they occur

---

## 💡 Integration Tips

1. **Start with automated setup** for your primary AI assistant
2. **Test with a simple web application** first
3. **Use visual workflows** for complex user journeys
4. **Enable sub-agent orchestration** for token efficiency
5. **Set up multiple assistants** for different use cases

**Your AI coding assistant is now equipped with revolutionary visual debugging capabilities!**