mcp-debugger

MCP-сервер для многоязычной отладки — дайте вашим ИИ-агентам суперспособности в отладке 🚀

🎯 Обзор

mcp-debugger — это сервер протокола Model Context Protocol (MCP), который предоставляет инструменты отладки в виде структурированных вызовов API. Он позволяет ИИ-агентам выполнять пошаговую отладку на нескольких языках программирования с использованием протокола Debug Adapter Protocol (DAP).

🆕 Версия 0.19.0: Отладка Java через мост JDI с режимами запуска и подключения! Плюс отладка Go с помощью Delve.

🆕 Версия 0.17.0: Поддержка отладки Rust! Отлаживайте программы на Rust с помощью CodeLLDB на Linux/macOS, включая проекты Cargo, асинхронный код и полную инспекцию переменных — кроме того, команды пошагового выполнения теперь возвращают активный контекст исходного кода, чтобы агенты автоматически сохраняли свое местоположение.

🔥 Версия 0.16.0: Поддержка отладки JavaScript/Node.js! Полные возможности отладки с использованием встроенного js-debug, поддержка TypeScript и отсутствие зависимостей времени выполнения благодаря улучшенному распространению через npx.

🎬 Демонстрационное видео: Посмотрите на отладчик в действии!

Запись в процессе — здесь будет показано, как ИИ-агент обнаруживает и исправляет ошибку обмена переменными в режиме реального времени

✨ Основные возможности

• 🌐 Многоязычная поддержка — чистый паттерн адаптера для любого языка

• 🐍 Отладка Python через debugpy — полная поддержка протокола DAP

• 🟨 Отладка JavaScript (Node.js) через js-debug — проверенный отладчик VSCode

• 🦀 Отладка Rust через CodeLLDB — отладка проектов Rust и Cargo (Linux/macOS/Windows с набором инструментов GNU)

• 🐹 Отладка Go через Delve — полная поддержка DAP для программ на Go

• ☕ Отладка Java через мост JDI — режимы запуска и подключения с JDK 21+

• 🔷 Отладка .NET/C# через netcoredbg — отладка приложений .NET с полной поддержкой DAP

ВНИМАНИЕ: В Windows используйте набор инструментов GNU для полной инспекции переменных. Запустите mcp-debugger check-rust-binary <путь-к-exe> для проверки сборки и см. Отладка Rust в Windows для получения подробных инструкций. ПРИМЕЧАНИЕ: Опубликованный пакет npm поставляется с исполняемой средой CodeLLDB для Linux x64, чтобы не превышать лимиты размера реестра. В macOS или Windows укажите переменную окружения CODELLDB_PATH на существующую установку CodeLLDB (например, из расширения VSCode) или клонируйте репозиторий и выполните pnpm --filter @debugmcp/adapter-rust run build:adapter для локальной сборки бинарных файлов вашей платформы.

Скрипт настройки Rust для Windows

Если вы используете Windows и хотите максимально быстро настроить набор инструментов GNU + dlltool, выполните:

pwsh scripts/setup/windows-rust-debug.ps1

Скрипт устанавливает набор инструментов stable-gnu (через rustup), настраивает dlltool.exe (предпочитая MSYS2/MinGW, если доступно, или используя автономную копию rustup), собирает входящие в комплект примеры Rust и по умолчанию запускает дымовые тесты Rust. Добавьте -SkipTests, чтобы пропустить выполнение тестов. Добавьте -UpdateUserPath, если хотите, чтобы путь к dlltool был сохранен в ваших переменных окружения PATH/DLLTOOL.

Скрипт также попытается подготовить набор инструментов MinGW-w64 на базе MSYS2 (через winget + pacman), чтобы у cargo +stable-gnu был полнофункциональный стек dlltool/ld/as. Если MSYS2 уже установлен, он просто использует его; в противном случае он поможет вам его установить (или предупредит, чтобы вы могли установить его вручную).

• 🧪 Фиктивный адаптер для тестирования — тестирование без внешних зависимостей

• 🔌 Режимы транспорта STDIO и SSE — работает с любым клиентом MCP

• 📦 Отсутствие зависимостей времени выполнения — автономные пакеты через esbuild + tsup

• ⚡ Готовность к npx — запуск напрямую через npx @debugmcp/mcp-debugger — установка не требуется

• 📊 1266+ пройденных тестов — проверено в реальных условиях

• 🐳 Docker и пакеты npm — развертывание где угодно

• 🤖 Создано для ИИ-агентов — структурированные JSON-ответы для легкого парсинга

• 🛡️ Проверка путей — предотвращает сбои из-за несуществующих файлов

• 📝 Контекст строки с учетом ИИ — интеллектуальная расстановка точек останова с контекстом кода

🚀 Быстрый старт

Для клиентов MCP (Claude Desktop и др.)

Добавьте в конфигурацию настроек MCP:

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "node",
      "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

Для CLI Claude Code

Для пользователей Claude Code мы предоставляем автоматический скрипт установки:

Предварительное условие: CLI Claude должен быть установлен и доступен в вашем PATH перед запуском скрипта установки. См. документацию Claude Code для получения инструкций по установке.

# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list

Важно: Аргумент stdio необходим, чтобы вывод консоли не повреждал протокол JSON-RPC. См. CLAUDE.md для подробной настройки и устранения неполадок.

Использование Docker

docker run -v $(pwd):/workspace debugmcp/mcp-debugger:latest

⚠️ Образ Docker поставляется с адаптерами для Python, JavaScript, Go, Java и .NET. Отладка Rust требует локального развертывания, SSE или упакованных версий, где адаптер работает рядом с вашим набором инструментов. Обратите внимание: адаптеры загружаются динамически во время выполнения — только те, чей набор инструментов установлен и обнаружен, будут сообщены как доступные через list_supported_languages.

Использование npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

Или используйте без установки через npx:

npx @debugmcp/mcp-debugger --help

📚 Как это работает

mcp-debugger предоставляет операции отладки в виде инструментов MCP, которые можно вызывать со структурированными JSON-параметрами:

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "javascript", "rust", "go", "java", "dotnet", or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

🛠️ Доступные инструменты

🏗️ Архитектура: Динамическая загрузка адаптеров

Версия 0.10.0 представляет чистый паттерн адаптера, который отделяет независимую от языка базовую функциональность от реализаций для конкретных языков:

┌─────────────┐     ┌────────────────┐     ┌──────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
└─────────────┘     └────────────────┘     └──────────────┘     └─────────────────┘
                            │                      │
                            ▼                      ▼
                    ┌──────────────┐      ┌─────────────────┐
                    │ ProxyManager │◀─────│ Language Adapter│
                    └──────────────┘      └─────────────────┘
                                                   │
                          ┌──────────────┴──────────────────────────────────────────┐
                          │                                                          │
              ┌───────────┼───────────┬───────────┬───────────┬───────────┐          │
              │           │           │           │           │           │          │
        ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
        │Python    ││JavaScript││Rust      ││Go        ││Java      ││Dotnet    ││Mock      │
        │Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   │
        └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────���───┘

Добавление поддержки языка

Хотите добавить поддержку отладки для вашего любимого языка? Ознакомьтесь с Руководством по разработке адаптеров!

💡 Пример: Отладка кода Python

Вот пример полной сессии отладки:

# buggy_swap.py
def swap_variables(a, b):
    a = b  # Bug: loses original value of 'a'
    b = a  # Bug: 'b' gets the new value of 'a'
    return a, b

Шаг 1: Создание сессии отладки

// Tool: create_debug_session
// Request:
{
  "language": "python",
  "name": "Swap Bug Investigation"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: Swap Bug Investigation"
}

Шаг 2: Установка точек останова

// Tool: set_breakpoint
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "file": "buggy_swap.py",
  "line": 2
}
// Response:
{
  "success": true,
  "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2,
  "verified": false,
  "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}

Шаг 3: Начало отладки

// Tool: start_debugging
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scriptPath": "buggy_swap.py"
}
// Response:
{
  "success": true,
  "state": "paused",
  "message": "Debugging started for buggy_swap.py. Current state: paused",
  "data": {
    "message": "Debugging started for buggy_swap.py. Current state: paused",
    "reason": "breakpoint"
  }
}

Шаг 4: Инспекция переменных

Сначала получите области видимости:

// Tool: get_scopes
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "frameId": 3
}
// Response:
{
  "success": true,
  "scopes": [
    {
      "name": "Locals",
      "variablesReference": 5,
      "expensive": false,
      "presentationHint": "locals",
      "source": {}
    },
    {
      "name": "Globals", 
      "variablesReference": 6,
      "expensive": false,
      "source": {}
    }
  ]
}

Затем получите локальные переменные:

// Tool: get_variables
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scope": 5
}
// Response:
{
  "success": true,
  "variables": [
    {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
    {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  ],
  "count": 2,
  "variablesReference": 5
}

📖 Документация

• 📘 Справочник инструментов — полная документация API

• 🚦 Руководство по началу работы — первая настройка

• 🏗️ Обзор архитектуры — многоязычный дизайн

• 🔧 Разработка адаптеров — добавление новых языков

• 🔌 Архитектура динамической загрузки — обнаружение во время выполнения, ленивая загрузка, кэширование

• 🧩 Справочник API адаптеров — контракты адаптера, фабрики, загрузчика и реестра

• 🔄 Руководство по миграции — обновление до v0.15.0 (динамическая загрузка)

• 🐍 Руководство по отладке Python — функции для Python

• 🟨 Руководство по отладке JavaScript — функции JavaScript/TypeScript

• 🐹 Руководство по отладке Go — отладка Go с помощью Delve

• ☕ Руководство по отладке Java — отладка Java с мостом JDI

• Отладка Rust в Windows — требования к набору инструментов и устранение неполадок

• 🔧 Устранение неполадок — распространенные проблемы и решения

🤝 Участие в разработке

Мы приветствуем вклад! См. CONTRIBUTING.md для получения рекомендаций.

# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Install dependencies and vendor debug adapters
pnpm install
# All debug adapters (JavaScript js-debug, Rust CodeLLDB) are automatically downloaded

# Build the project
pnpm build

# Run tests
pnpm test

# Check adapter vendoring status
pnpm vendor:status

# Force re-vendor all adapters (if needed)
pnpm vendor:force

Вендоринг адаптеров отладки

Проект автоматически включает адаптеры отладки во время pnpm install:

• JavaScript: Загружает js-debug от Microsoft из релизов GitHub

• Rust: Загружает бинарные файлы CodeLLDB для текущей платформы

• Среда CI: Установите SKIP_ADAPTER_VENDOR=true, чтобы пропустить вендоринг

Для ручного управления адаптерами:

# Check current vendoring status
pnpm vendor:status

# Re-vendor all adapters
pnpm vendor

# Clean and re-vendor (force)
pnpm vendor:force

# Clean vendor directories only
pnpm clean:vendor

Запуск тестов контейнера локально

Мы используем Act для локального запуска рабочих процессов GitHub Actions:

# Build the Docker image first
docker build -t mcp-debugger:local .

# Run tests with Act (use WSL2 on Windows)
act -j build-and-test --matrix os:ubuntu-latest

См. tests/README.md для получения подробных инструкций по тестированию.

📊 Статус проекта

• ✅ Готов к производству: v0.19.0 с шестью языковыми адаптерами и отлаженным многоязычным дистрибутивом

• ✅ Чистая архитектура с паттерном адаптера

• ✅ JavaScript/Node.js: Полный цикл отладки через js-debug

• ✅ Go: Полная поддержка отладки через Delve DAP

• ✅ Java: Режимы запуска и подключения через мост JDI

• 🦀 Rust: Полная поддержка на Linux/macOS/Windows (Windows требует набор инструментов GNU; MSVC не поддерживается CodeLLDB)

• 📈 Активная разработка: Регулярные обновления и улучшения

📄 Лицензия

Лицензия MIT — подробности см. в LICENSE.

👥 Участники

• @swinyx — адаптер Go (Delve)

• @roofpig95008 — адаптер Java (мост JDI)

🙏 Благодарности

Создано с использованием:

• Model Context Protocol от Anthropic

• Debug Adapter Protocol от Microsoft

• debugpy для отладки Python

Дайте вашему ИИ возможность отлаживать как разработчик — на любом языке! 🎯