DotnetDebugMcp
Автор: Дмитрий Каратаев (Dmitry Karataev)
MCP-сервер для отладки .NET (C#) через DAP (netcoredbg): брейкпоинты, запуск, стек, переменные, шаги, continue/stop.
Требования
- .NET 10
- netcoredbg; путь в переменной
NETCOREDBG_PATHили в параметре netcoredbg_path при launch.
Сборка и запуск
cd dotnet-debug-mcp
dotnet build
dotnet runСервер работает по stdio (MCP-клиент запускает процесс и общается через stdin/stdout).
Публикация exe (для MCP в Cursor)
Быстрый локальный publish (рекомендуется)
publish-and-deploy.ps1 делает publish self-contained win-x64, зеркалит в фиксированный путь (по умолчанию D:\dotnet-debug-mcp) и гасит процесс, если он лочит файлы:
.\publish-and-deploy.ps1Релизы (zip + GitLab upload)
scripts/publish-release-win.ps1 — мультиплатформенный сценарий (win/linux/osx): упаковка в zip и загрузка в GitLab Generic Packages/Release.
dotnet publish DotnetDebugMcp.csproj -c Release -o publishВ конфиге MCP укажи command — путь к DotnetDebugMcp.exe в папке publish, args — [].
Каталог тулов (автогенерация)
Полный список имён и текстов description — в docs/MCP-TOOLS.md; машиночитаемый манифест — mcp-tools.manifest.json. Обновление из корня репозитория dotnet-debug-mcp:
dotnet run --project tools/ExportMcpManifest -- --writeИнструменты
| Инструмент | Описание |
|---|---|
| debug_ping | Проверка доступности сервера. |
| debug_set_breakpoints | Записать брейкпоинты: workspace_path, target_path (.dll/.exe), breakpoints[] (file_path, line; опционально condition). Файл .dotnet-debug-mcp-breakpoints.json в workspace. |
| debug_list_breakpoints | Показать сохранённые брейкпоинты (по workspace, опционально по target_path). |
| debug_clear_breakpoints | Удалить брейкпоинты (по workspace или по target_path). |
| debug_launch | Запустить отладку: workspace_path, target_path; опционально netcoredbg_path, program_args (массив строк — аргументы для целевой программы). Загружает брейкпоинты, передаёт в DAP setBreakpoints, ждёт первого события stopped (до 5 с). |
| debug_attach | Подключиться к уже запущенному .NET-процессу по process_id (PID). workspace_path обязателен; опционально target_path (путь к .dll/.exe процесса) — тогда загружаются сохранённые брейкпоинты для этого target. |
| debug_continue | Продолжить выполнение (DAP continue). |
| debug_step_over | Шаг через строку (DAP next). |
| debug_step_into | Шаг в вызов (DAP stepIn). |
| debug_step_out | Шаг из кадра (DAP stepOut). |
| debug_stop | Завершить сессию (dispose клиента). |
| debug_stack_trace | Стек вызовов текущего потока (DAP stackTrace). При необходимости сервер ждёт остановки (до 5 с) и повторяет запрос при временных ошибках. |
| debug_variables | Переменные кадра (frame_index=0 по умолчанию). Сначала запрос scopes по frameId, затем variables по variablesReference каждого scope (netcoredbg отдаёт переменные через scopes); при ошибке — fallback на variables(frameId). |
Рекомендации по отладке
- Собирай цель в Debug, не Release: путь к
bin/Debug/net10.0/YourApp.dllв target_path и при set_breakpoints. Иначе брейкпоинты могут не срабатывать (пути в PDB). - Пути:
file_pathв брейкпоинтах иtarget_pathмогут быть относительными — они разрешаются относительно workspace_path, чтобы совпадать с путями в PDB при сборке из этого каталога. - Условный брейкпоинт: в
debug_set_breakpointsу каждого брейкпоинта можно указать condition — выражение на C# (напримерi > 10,name == "test"). Остановка только когда условие истинно; удобно для цикла или часто вызываемого метода. - Если целевая программа без аргументов сразу выходит — передай program_args (например
["dummy"]), чтобы выполнение дошло до нужной строки.
Пример сценария
debug_set_breakpoints— workspace_path, target_path (путь к .dll), breakpoints: [{ file_path, line: 7 }].debug_launch— те же workspace_path, target_path; при необходимости program_args.debug_stack_trace→ стек.debug_variables→ переменные (Locals и др. по scopes).debug_step_over→ следующий шаг.debug_continue→ продолжить.debug_stop→ завершить сессию.
Поведение
- После debug_launch сервер ждёт первое событие stopped (до 5 с); при таймауте пробует получить threadId через запрос threads.
- При вызове debug_stack_trace, debug_variables, debug_step_* без остановки сервер ждёт следующее stopped (до 5 с).
- При временных ошибках DAP (например «target is running», 0x80004005) запросы повторяются до 3 раз с паузой 250 ms.
- Событие continued сбрасывает «текущий поток»; следующий stack_trace/variables снова ждут stopped.
Отпускание приложения
- Чтобы приложение снова выполнялось после остановки на брейкпоинте — вызывай debug_continue. После этого можно снова вызывать stack_trace/variables (сервер будет ждать следующего stopped до 5 с).
- debug_stop перед отключением отправляет continue целевой программе, чтобы она не оставалась зависшей. После stop сессия завершена; для новой отладки нужен снова debug_launch.
- Перед пересборкой целевого проекта вызывай debug_stop: netcoredbg держит открытыми exe/dll и PDB целевого процесса; пока сессия активна, копирование PDB при сборке может падать (файл занят netcoredbg.exe).
- В глубоких стеках debug_step_over / debug_step_into иногда могут оставить приложение без ответа; в таком случае вызови debug_stop (он сделает continue и отключится) или заверши процесс netcoredbg снаружи. При обрыве netcoredbg сервер сбрасывает сессию (OnConnectionLost) и не падает.
Планы (что не покрыто)
- ~~Проверить debug_step_into и debug_step_out, а также debug_stop после step~~ Проверено: step_into заходит в вызов (Main → Foo → Bar), step_out возвращает в вызывающий кадр (Bar → Foo → Main). debug_stop после step отрабатывает: continue и dispose без зависания.
- ~~Прогнать на практике условный брейкпоинт~~ Проверено: condition передаётся в DAP, остановка только при истинном условии (например
i == 2в цикле). При желании — прогнать program_args при launch. - При желании — таймаут/отмена для DAP-запросов; уточнить в доке про параллельные вызовы stack_trace/variables.
Лицензия
MIT. См. LICENSE.