browser-x-mcp/docs/legacy/CURSOR_MCP_TROUBLESHOOTING.md

AI-Powered Browser Automation with Advanced Form Testing - A Model Context Provider (MCP) server that enables intelligent browser automation with form testing, element extraction, and comprehensive logging

# Cursor MCP Troubleshooting Guide

## ✅ РЕШЕНИЕ: Daemon режим устраняет повторные запуски браузера

### 🔧 Исправление повторных запусков браузера:

**Проблема:** MCP сервер запускал новый браузер при каждом вызове инструмента.

**Решение:** Создан daemon-режим с постоянно работающим браузером.

#### Новая архитектура:
- ✅ `src/server/daemon.js` - долгоживущий сервер
- ✅ Браузер запускается один раз и остается активным
- ✅ Конфигурация `.cursor/mcp.json` обновлена для daemon

#### Текущий статус:
```bash
# Проверить что daemon работает:
ps aux | grep "daemon.js" | grep -v grep

# Результат:
# v.matiyasevich   41590   0.2  0.8 node src/server/daemon.js
```

---

## Проблема: В Cursor не видны инструменты @/browser-x-mcp

### Статус проверки:
- ✅ MCP daemon запущен (PID: 41590)
- ✅ Конфигурация `.cursor/mcp.json` обновлена для daemon
- ✅ 9 инструментов доступны в сервере
- ✅ Браузер не перезапускается между вызовами
- ❌ Инструменты все еще не видны в Cursor chat

### Пошаговая диагностика:

#### 1. Перезапуск Cursor
**ВАЖНО:** Полностью закройте Cursor и запустите заново:
```bash
# Убедитесь что Cursor полностью закрыт
pkill -f "Cursor"
# Запустите Cursor снова
open -a Cursor
```

#### 2. Проверка настроек MCP в Cursor
1. Откройте Cursor Settings через `Cmd + Shift + J` (НЕ `Cmd + ,`)
2. Найдите вкладку **"MCP"** в настройках
3. Проверьте что `browser-x-mcp` сервер:
   - Отображается в списке
   - Имеет статус "Active" или "Running"
   - Показывает количество инструментов > 0

#### 3. Текущая конфигурация (daemon режим)

**Актуальная конфигурация (`.cursor/mcp.json`):**
```json
{
  "mcpServers": {
    "browser-x-mcp": {
      "command": "node",
      "args": ["/Users/v.matiyasevich/Documents/GitHub/browser-x-mcp/src/server/daemon.js"],
      "env": {
        "BROWSER_X_MCP_DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}
```

#### 4. Альтернативные конфигурации

**Альтернативная #1 (через npx):**
```json
{
  "mcpServers": {
    "browser-x-mcp": {
      "command": "npx",
      "args": ["--yes", "node", "/Users/v.matiyasevich/Documents/GitHub/browser-x-mcp/src/server/daemon.js"],
      "env": {
        "BROWSER_X_MCP_DEBUG": "true"
      }
    }
  }
}
```

**Альтернативная #2 (относительный путь):**
```json
{
  "mcpServers": {
    "browser-x-mcp": {
      "command": "node",
      "args": ["src/server/daemon.js"],
      "env": {
        "BROWSER_X_MCP_DEBUG": "true"
      },
      "cwd": "/Users/v.matiyasevich/Documents/GitHub/browser-x-mcp"
    }
  }
}
```

#### 5. Проверка версии Cursor
Убедитесь что у вас версия Cursor 0.46+ с поддержкой MCP:
```
Version: 0.46.11+
```

#### 6. Проверка разрешений файла
```bash
ls -la ~/.cursor/mcp.json
# Должно быть читаемо пользователем
chmod 644 ~/.cursor/mcp.json
```

#### 7. Очистка кэша Cursor
```bash
# Удалите кэш Cursor
rm -rf ~/Library/Application\ Support/Cursor/User/workspaceStorage
rm -rf ~/Library/Application\ Support/Cursor/CachedExtensions
```

#### 8. Ручное тестирование MCP daemon
```bash
cd /Users/v.matiyasevich/Documents/GitHub/browser-x-mcp
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node src/server/daemon.js
```

#### 9. Проверка логов Cursor
1. Откройте Developer Tools: `Cmd + Option + I`
2. Проверьте Console на ошибки MCP
3. Ищите сообщения типа "MCP server failed" или "connection error"

### Управление daemon:

#### Запуск daemon:
```bash
cd /Users/v.matiyasevich/Documents/GitHub/browser-x-mcp
node src/server/daemon.js &
```

#### Остановка daemon:
```bash
pkill -f "daemon.js"
```

#### Проверка статуса:
```bash
ps aux | grep "daemon.js" | grep -v grep
```

### Если ничего не помогает:

#### Глобальная конфигурация
Попробуйте глобальный файл конфигурации:
```bash
# Создайте глобальную конфигурацию
mkdir -p ~/.cursor
echo '{
  "mcpServers": {
    "browser-x-mcp": {
      "command": "node",
      "args": ["/Users/v.matiyasevich/Documents/GitHub/browser-x-mcp/src/server/daemon.js"]
    }
  }
}' > ~/.cursor/mcp.json
```

#### Использование UI настроек
1. Откройте Cursor Settings (`Cmd + Shift + J`)
2. Перейдите в MCP tab
3. Нажмите "Add new global MCP server"
4. Заполните:
   - Name: `browser-x-mcp`
   - Command: `node`
   - Args: `/Users/v.matiyasevich/Documents/GitHub/browser-x-mcp/src/server/daemon.js`

### Успешный результат:
После исправления вы должны увидеть:
- Инструменты `@/browser-x-mcp` доступны в chat
- В настройках MCP показывается "9 tools available"
- Можно вызывать: `start_browser`, `navigate_browser`, `extract_virtual_canvas`, etc.
- **Браузер остается запущенным между вызовами инструментов**

### Преимущества daemon режима:
- 🚀 **Быстрее**: Браузер не перезапускается
- 🔄 **Стабильнее**: Сохраняется состояние между вызовами
- 💾 **Эффективнее**: Меньше потребление ресурсов
- 🎯 **Точнее**: Сохраняется контекст страниц

### Контакты для поддержки:
- Cursor Community Forum: https://forum.cursor.com/
- MCP Documentation: https://modelcontextprotocol.io/