DebugMCP (MCP-сервер) — предоставление AI-агентам возможностей оперативной отладки

Позвольте AI-агентам отлаживать ваш код прямо в VS Code — устанавливать точки останова, выполнять код по шагам, просматривать переменные и вычислять выражения. Работает с Codex, GitHub Copilot, GitHub Copilot CLI, Cline, Cursor, Windsurf, Roo Code и любым MCP-совместимым ассистентом. Совместим с любым языком программирования, поддерживаемым VS Code.

⭐ Если DebugMCP оказался полезным, пожалуйста, поставьте звезду репозиторию на GitHub! Это помогает другим узнать о проекте и мотивирует дальнейшее развитие.

📢 Уведомление для разработчиков: Это расширение поддерживается ozzafar@microsoft.com и orbarila@microsoft.com. Мы приветствуем обратную связь и вклад в улучшение этого расширения.

🎬 Посмотрите DebugMCP в действии — ваш AI-ассистент автономно устанавливает точки останова, выполняет код по шагам и просматривает переменные прямо в VS Code.

✨ Что нового

2.2

• Кросс-агентная установка навыка debug-live — систематический рабочий процесс отладки поставляется как Agent Skill и теперь устанавливается в стандартные каталоги навыков — ~/.agents/skills/ (кросс-агентное расположение, используемое совместимыми с навыками средами, включая режим агента VS Code) и ~/.copilot/skills/ при его наличии — так что он обнаруживается везде, а не копируется рядом с конфигом каждого агента, где его никто не сканирует (исправляет #105, где VS Code никогда не загружал навык). Сервер также рекламирует MCP instructions, а инструмент start_debugging указывает на навык для полного рабочего процесса.

• Пауза выполнения программ — новый инструмент pause_execution прерывает свободно выполняющуюся программу и останавливается в её текущем месте, даже без установленной точки останова (отлично подходит для бесконечных циклов и встроенных/голых металлических целей), так что вы можете затем просмотреть состояние или продолжить оттуда.

• Надёжная отладка через VS Code Testing API — start_debugging с testName использует VS Code Testing API для обнаружения и запуска теста, обеспечивая стабильные срабатывания точек останова внутри отдельных тестовых случаев в различных языковых тестовых раннерах (pytest, Jest/Vitest, Java, .NET, Go и т.д.).

Related MCP server: MCP Server for VS Code

🚀 Быстрая установка

Установите из VS Code Marketplace или используйте прямую ссылку: vscode:extension/ozzafar.debugmcpextension

Содержание

• Обзор

• Возможности

• Установка

• Быстрый старт

• Поддерживаемые AI-ассистенты

• Поддерживаемые языки

• Конфигурация

• FAQ

• Устранение неполадок

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

• Вклад в проект

• Лицензия

Обзор

DebugMCP — это MCP-сервер, который даёт AI-агентам кодирования полный контроль над отладчиком VS Code. Вместо чтения логов или догадок ваш AI-ассистент может автономно устанавливать точки останова, запускать сеансы отладки, выполнять код по строкам, просматривать значения переменных и вычислять выражения — точно так же, как это делал бы человек-разработчик. Он работает на 100% локально, не требует настройки и работает из коробки с любым MCP-совместимым AI-ассистентом.

Возможности

🔧 Инструменты

Примечание: MCP-сервер предоставляет инструменты для действий отладчика, а процедурные рекомендации по рабочему процессу (когда отлаживать, как структурировать расследование первопричины, особенности языков) находятся в сопутствующем Agent Skill. Описания инструментов остаются краткими и поведенческими; расширение устанавливает навык debug-live в стандартные каталоги навыков (~/.agents/skills/, а также ~/.copilot/skills/ при наличии), чтобы совместимые с навыками среды загружали полный рабочий процесс по требованию. Сервер также рекламирует MCP instructions, указывающие агентам на него перед отладкой.

🎯 Рекомендации по отладке

DebugMCP следует систематическим методам отладки для эффективного решения проблем:

• Начинайте с точек входа: Начинайте отладку с точек входа функций или основных путей выполнения

• Следуйте потоку выполнения: Используйте пошаговое выполнение, чтобы понять поток кода

• Анализ первопричины: Не останавливайтесь на симптомах — найдите основную причину

🛡️ Безопасность и надёжность

• Безопасная связь: Все MCP-коммуникации используют защищённые протоколы

• Локальная работа: MCP-сервер работает на 100% локально, без внешних коммуникаций и не требует учётных данных

• Проверка состояния: Надёжная проверка состояний отладки и операций

Установка

Быстрые варианты установки

Вариант 1: Прямая ссылка (самый быстрый)

• Нажмите на эту ссылку: vscode:extension/ozzafar.debugmcpextension

• Или скопируйте и вставьте в браузер: vscode:extension/ozzafar.debugmcpextension

Вариант 2: VS Code Marketplace

• Посетите: https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension

• Нажмите "Установить"

Вариант 3: Внутри VS Code

1. Откройте VSCode

2. Перейдите в Расширения (Ctrl+Shift+X / Cmd+Shift+X)

3. Найдите "DebugMCP"

4. Нажмите "Установить"

5. Расширение автоматически активируется и регистрируется как MCP-сервер

Проверка

После установки вы должны увидеть:

• Расширение DebugMCP в установленных расширениях

• MCP-сервер, автоматически запущенный на порту 3001 (настраивается)

• Инструменты отладки, доступные подключённым AI-ассистентам

📝 Примечание: Дополнительные инструкции по правилам отладки не требуются — расширение работает из коробки.

💡 Совет: Включите автоматическое одобрение для всех инструментов debugmcp в вашем AI-ассистенте, чтобы создать бесшовные рабочие процессы отладки без постоянных прерываний на одобрение.

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

1. Установите расширение (см. Установка)

2. Откройте ваш проект в VSCode

3. Попросите вашего AI отладить — теперь он может устанавливать точки останова, запускать отладку и анализировать ваш код!

Поддерживаемые AI-ассистенты

DebugMCP работает с любым MCP-совместимым AI-ассистентом. Он автоматически обнаруживает и предлагает зарегистрировать себя с:

Поддерживаемые языки

DebugMCP поддерживает отладку следующих языков с соответствующими расширениями VSCode:

Конфигурация

Конфигурация MCP-сервера (рекомендуется)

Расширение автоматически запускает MCP-сервер. Оно покажет сообщение с предложением автоматически зарегистрировать MCP-сервер в вашем AI-ассистенте.

Вы также можете запустить регистрацию вручную через палитру команд:

• DebugMCP: Show Agent Selection Popup

Ручная регистрация MCP-сервера (необязательно)

🔄 Автоматическая миграция: Если вы ранее настраивали DebugMCP с транспортом SSE, расширение автоматически перенесёт вашу конфигурацию на новый транспорт Streamable HTTP при активации.

Cline

Добавьте в настройки Cline или в cline_mcp_settings.json:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

Добавьте в настройки VS Code (settings.json):

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "description": "DebugMCP - Multi-language debugging support"
      }
    }
  }
}

GitHub Copilot CLI

Добавьте в ~/.copilot/mcp-config.json (${COPILOT_HOME}/mcp-config.json, если задан COPILOT_HOME):

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "tools": ["*"]
    }
  }
}

Cursor

Добавьте в настройки MCP в Cursor:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Codex

Зарегистрируйте DebugMCP в Codex:

codex mcp add debugmcp --url http://localhost:3001/mcp

Или добавьте эквивалентную конфигурацию в ~/.codex/config.toml (${CODEX_HOME}/config.toml, если задан CODEX_HOME):

[mcp_servers.debugmcp]
url = "http://localhost:3001/mcp"

Windsurf

Добавьте в настройки MCP в Windsurf (~/.windsurf/mcp_settings.json или в рабочей области .windsurf/mcp_settings.json):

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Roo Code

Добавьте в настройки MCP в Roo Code:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Antigravity

Добавьте в настройки MCP в Antigravity:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Настройки расширения

Настройте поведение DebugMCP в настройках VSCode:

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180,
  "debugmcp.bindHost": ["127.0.0.1", "::1"]
}

Модель безопасности

DebugMCP предоставляет мощные примитивы отладчика (evaluate_expression, start_debugging, …) через неаутентифицированную локальную HTTP-точку. Чтобы сохранить этот интерфейс безопасным, сервер применяет четыре механизма контроля:

1. Привязка только к loopback. HTTP-сервер по умолчанию привязывается к адресам loopback IPv4 и IPv6 (127.0.0.1 и ::1), поэтому другие хосты в вашей сети не могут получить доступ к http://<ваш-ip>:3001/mcp. Привязка к обоим семействам адресов гарантирует, что клиенты, разрешающие localhost в любое из семейств, подключатся успешно. Настройка debugmcp.bindHost (строка или массив строк) позволяет выбрать другой интерфейс (например, при пробросе порта в удалённый контейнер), но это открывает неаутентифицированный отладчик для всего, что может маршрутизировать к этому адресу — не указывайте 0.0.0.0 или LAN-адрес в ненадёжной сети.

2. Проверка заголовков Host / Origin. Каждый запрос должен содержать заголовок Host, указывающий на loopback-адрес (localhost, 127.0.0.1 или [::1]); любой суффикс порта в Host также должен совпадать с портом прослушивания сервера. Запросы с любым другим Host — включая те, что приходят через DNS-ребдинг со вредоносной веб-страницы — отклоняются с HTTP 403. Та же проверка loopback применяется к заголовку Origin, если он присутствует.

3. Просмотр переменных с минимальными привилегиями. get_variables_values требует явный список variableNames (максимум 50, без подстановочных знаков) и возвращает только эти переменные. Он больше не выгружает все переменные в области видимости, что ранее передавало агенту несвязанное состояние процесса, которое он не запрашивал. Используйте list_variable_names, чтобы узнать, что существует; этот инструмент возвращает только имена и типы и никогда не читает значения.

4. Редактирование секретов при просмотре переменных. Значения с именами, указывающими на учётные данные, или значения, соответствующие известному шаблону учётных данных, заменяются на <redacted: possible secret> до того, как ответ покинет расширение. Результат вычисления, возвращаемый evaluate_expression, также покрывается. Когда get_variables_values или evaluate_expression раскрывает сложное значение, дочерние элементы перечисляются только по имени и типу. Используйте evaluate_expression с точным путём к дочернему элементу, когда нужно его значение. Рекурсивное раскрытие ограничено 100 дочерними полями на ответ. Нулевые значения (None, undefined, '') никогда не редактируются, чтобы ошибки вида «мой токен пуст» оставались отлаживаемыми. Редактирование всегда включено и не может быть отключено.

FAQ

DebugMCP работает с любым MCP-совместимым AI-ассистентом, включая GitHub Copilot, GitHub Copilot CLI, Cline, Cursor, Codex, Windsurf, Roo Code, Antigravity и другие. Если ваш ассистент поддерживает Model Context Protocol, он может использовать DebugMCP.

Да. DebugMCP работает как расширение VS Code с extensionKind: workspace, поэтому оно активируется в удалённой среде, где находится ваш код. MCP-сервер запускается на localhost в этом удалённом контексте.

Нет. DebugMCP автоматически генерирует подходящие конфигурации отладки на основе языка/расширения файла. Если у вас есть launch.json, он автоматически выберет наиболее подходящую конфигурацию.

Нет. DebugMCP работает на 100% локально. MCP-сервер запускается на localhost, и никакой код, переменные или данные отладки не отправляются во внешние сервисы. AI-ассистент взаимодействует с MCP-сервером полностью в пределах вашей локальной машины.

Измените порт в настройках VS Code: "debugmcp.serverPort": 3002 (или любой доступный порт). Затем обновите конфигурацию MCP в вашем AI-ассистенте, чтобы использовать новый порт.

Да. Передайте параметр testName в start_debugging, чтобы отладить конкретный тестовый метод. DebugMCP настроит сеанс отладки так, чтобы он запускался и останавливался на точках останова внутри этого теста.

Убедитесь, что DebugMCP зарегистрирован в настройках MCP вашего AI-ассистента. Расширение должно автоматически обнаружить и предложить зарегистрировать себя. Если этого не произошло, см. раздел Ручная регистрация MCP-сервера. Также включите автоматическое подтверждение для инструментов DebugMCP для более плавного рабочего процесса.

Да. DebugMCP поддерживает файлы .cs и файлы проектов .csproj для отладки C#/.NET, включая приложения ASP.NET.

Устранение неполадок

Частые проблемы

MCP-сервер не запускается

• Симптом: AI-ассистент не может подключиться к DebugMCP

• Решение:

  • Проверьте, доступен ли порт 3001

  • Перезапустите VSCode

  • Убедитесь, что расширение установлено и активировано

Сеанс отладки не останавливается на точках останова

• Симптом: Точки останова установлены, но выполнение не приостанавливается

• Решение:

  • Убедитесь, что отлаживается правильный файл

  • Проверьте, что номер строки точки останова корректен

  • Убедитесь, что установлено соответствующее расширение отладчика для языка

Другое окно VS Code перехватывает фокус при остановке отладки

• Симптом: При нескольких открытых окнах VS Code окно, в котором выполняется отладка, выходит на передний план при достижении точки останова или завершении шага

• Решение: Отключите встроенное поведение VS Code «фокус при остановке» в настройках пользователя или рабочей области:

  {
    "debug.focusWindowOnBreak": false,
    "debug.focusEditorOnBreak": false
  }

  debug.focusWindowOnBreak предотвращает перехват фокуса операционной системы окном отладки. Дополнительная настройка debug.focusEditorOnBreak также предотвращает перемещение фокуса VS Code в остановленный редактор исходного кода. DebugMCP не изменяет эти постоянные настройки автоматически.

Конфигурация не обнаружена автоматически

• Симптом: Расширение не предлагает выполнить регистрацию с вашим ИИ-ассистентом

• Решение:

  • Выполните DebugMCP: Show Agent Selection Popup из палитры команд (Ctrl+Shift+P / Cmd+Shift+P)

  • Вручную добавьте конфигурацию (см. Ручная регистрация MCP-сервера)

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

Архитектура

AI Agent (Copilot/Cline/Cursor/Codex) → MCP/Streamable HTTP → DebugMCPServer → DebuggingHandler → VS Code Debug API

Интеграция конфигурации запуска

Расширение интеллектуально обрабатывает конфигурации отладки:

• Существующий launch.json: Если файл .vscode/launch.json существует, он:

  • Найдет соответствующую конфигурацию

  • Учтет configurationName, если он явно указан агентом

  • Поддержит JSONC (JSON с комментариями и висячими запятыми)

• Конфигурация по умолчанию: Если configurationName не указан или не найдена подходящая именованная конфигурация, создается соответствующая конфигурация по умолчанию для каждого языка на основе определения расширения файла.

Требования

• VSCode с установленными соответствующими языковыми расширениями:

  • Python: расширение Python для файлов .py

  • JavaScript/TypeScript: Встроенный отладчик Node.js или расширение JavaScript Debugger

  • Java: Extension Pack for Java

  • C#/.NET: расширение C#

  • C/C++: расширение C/C++

  • Go: расширение Go

  • Rust: расширение rust-analyzer

  • PHP: расширение PHP Debug

  • Ruby: расширение Ruby с поддержкой отладки

• MCP-совместимый ИИ-ассистент (Copilot, Cline, Cursor, Codex, Windsurf, Roo Code и т.д.)

Разработка

Чтобы собрать расширение:

npm install
npm run compile

Чтобы запустить линтинг:

npm run lint

Чтобы запустить тесты:

npm test

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

Этот проект приветствует вклад и предложения. Большинство вкладов требует вашего согласия с Лицензионным соглашением участника (CLA), подтверждающим, что вы имеете право и действительно предоставляете нам права на использование вашего вклада. Подробности см. на https://cla.opensource.microsoft.com.

Когда вы отправляете pull request, бот CLA автоматически определит, нужно ли вам предоставить CLA, и соответствующим образом оформит PR (например, проверка статуса, комментарий). Просто следуйте инструкциям бота. Вам нужно будет сделать это только один раз для всех репозиториев, использующих наше CLA.

Этот проект принял Кодекс поведения Microsoft Open Source. Дополнительную информацию см. в FAQ по Кодексу поведения или свяжитесь с opencode@microsoft.com по любым дополнительным вопросам или комментариям.

Безопасность

О уязвимостях безопасности следует сообщать в соответствии с руководством на https://aka.ms/SECURITY.md. Пожалуйста, не сообщайте об уязвимостях безопасности через публичные проблемы GitHub.

Товарные знаки

Этот проект может содержать товарные знаки или логотипы проектов, продуктов или услуг. Авторизованное использование товарных знаков или логотипов Microsoft подлежит и должно соответствовать Руководству по товарным знакам и брендам Microsoft. Использование товарных знаков или логотипов Microsoft в модифицированных версиях этого проекта не должно вызывать путаницу или подразумевать спонсорство Microsoft. Любое использование товарных знаков или логотипов третьих лиц подчиняется политике этих третьих лиц.

⭐ Поддержка DebugMCP

Если DebugMCP помог вам отлаживать быстрее, пожалуйста, рассмотрите возможность поставить ему звезду на GitHub! Звезды помогают проекту получить видимость и привлечь участников.

⭐ Поставьте звезду DebugMCP на GitHub

История звезд

Лицензия

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

Это расширение было создано Oz Zafar, Ori Bar-Ilan и Karin Brisker.