jdwp-mcp

Отладка работающих JVM через JDWP — из любого MCP-совместимого агента.

Подключайтесь к запущенному Java-процессу, приостанавливайте потоки, исследуйте стеки и объекты, устанавливайте точки останова и оценивайте состояние — с помощью естественного языка. Один промпт запускает цикл диагностики под управлением агента с использованием данных о работе программы в реальном времени.

Работает с Claude Code, Codex, Cursor или любым другим MCP-совместимым агентом.

Посмотрите на это в действии

Сервисный запрос завис. Найдите первопричину:

> Attach to localhost:5005 and find out why a query is stuck.

Агент подключается, приостанавливает все потоки и сканирует их на наличие проблемы:

connected localhost:5005
paused
24 threads, 2 blocked

Thread pool-3-thread-7 is waiting for a monitor lock:
#0 RolapResult.loadMembers:142
  monitor=@3f2a  state=BLOCKED
#1 RolapResult.execute:89

Lock is held by pool-3-thread-2, which is running:
#0 SqlStatement.execute:218
  sql="SELECT ... FROM fact_table"   -- full scan on 36M rows

Root cause: the query bypassed the aggregate table and fell back to
a full fact-table scan. Thread-7 is waiting for thread-2 to finish.

Один промпт. Шесть вызовов инструментов. Конфликт блокировок и первопричина выявлены.

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

1. Установка

pip install jdwp-mcp

# Pre-built binary
curl -fsSL https://raw.githubusercontent.com/dronsv/jdwp-mcp/main/install.sh | sh

# Cargo (requires Rust)
cargo install --git https://github.com/dronsv/jdwp-mcp

# From source
git clone https://github.com/dronsv/jdwp-mcp && cd jdwp-mcp && cargo build --release

2. Настройка вашего агента

claude mcp add jdwp jdwp-mcp

Для Codex, Cursor или других MCP-совместимых агентов добавьте в .mcp.json:

{
  "mcpServers": {
    "jdwp": {
      "command": "jdwp-mcp"
    }
  }
}

3. Запустите ваше Java-приложение с JDWP

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

4. Отладка

Attach to localhost:5005 and set a breakpoint at com.example.MyService line 42

5. Автоматическое подтверждение (опционально)

Отладка включает множество быстрых вызовов инструментов. Автоматическое подтверждение устраняет запросы на подтверждение:

# Allow all jdwp tools for this project
claude config set --project allowedTools 'mcp__jdwp__*'

claude config set allowedTools 'mcp__jdwp__*'

Включайте только для проектов, которым вы доверяете — инструменты jdwp могут приостанавливать потоки, изменять переменные и вызывать методы в целевой JVM.

Пакеты промптов

Выберите пакет, соответствующий вашей ситуации:

Приложение зависает или работает медленно

Attach to localhost:5005
Pause the JVM and find all blocked or waiting threads
Show the stack for the blocked thread with variables
Who holds the lock? Show their stack too

Исключение в логах

Attach to localhost:5005
Set an exception breakpoint for NullPointerException
Wait for the exception to fire
Show the stack and all local variables at the throw site

Нужно понять путь выполнения кода

Attach to localhost:5005
Trace method calls on com.example.service
[send your HTTP request]
Show the trace result — which methods were called?

Отладка с использованием точек останова

Attach to localhost:5005
Find classes matching UserService
List methods of UserService with line numbers
Set a breakpoint at UserService line 45
When it hits, show the stack with all variables
Step over to the next line

Команды Claude Code

Если вы клонируете этот репозиторий, вы получите готовые команды с косой чертой:

• /investigate-hang — диагностика зависшей JVM (приостановка, поиск заблокированных потоков, отслеживание блокировок)

• /investigate-exception — перехват активного исключения и исследование места его возникновения

• /trace-request — отслеживание методов, через которые проходит запрос

А также автономный агент-исследователь (.claude/agents/jdwp-investigator.md), который можно запустить для диагностики зависаний, взаимных блокировок, исключений и неожиданных путей выполнения кода.

См. .claude/settings.example.json для рекомендуемой конфигурации автоматического подтверждения и проверки обновлений.

Лучшие сценарии использования

• Зависшие запросы и взаимные блокировки

• Заблокированные пулы потоков

• Подозрительный SQL или несоответствие состояния во время выполнения

• Диагностика с помощью точек останова без доступа к IDE

• Удаленная отладка через kubectl port-forward

Почему это лучше, чем jstack или IDE?

• Работает внутри вашего агента — нет переключения между инструментами, нет отдельного окна отладчика

• Объединяет подключение + инспекцию + рассуждение в одном цикле — агент сам решает, что исследовать дальше

• Разговорный интерфейс — опишите проблему, агент запустит сеанс отладки

• Источник истины для больших кодовых баз — в сложных проектах с глубокими стеками фреймворков (Spring, Hibernate, OLAP-движки) агенты могут запутаться при статическом отслеживании путей кода. Живая отладка дает агенту фактическое состояние во время выполнения: какой поток удерживает блокировку, какой SQL был сгенерирован, какое значение переменная имеет прямо сейчас

Инструменты

Подключение и управление attach, disconnect, pause, continue, step into/over/out

Точки останова и события set_breakpoint (с условиями), clear, list, exception_breakpoint, watch (модификация поля), wait_for_event

Инспекция get_stack (автоматическое разрешение объектов), get_variable, inspect, eval, set_value, snapshot, find_class, list_methods, list_threads, vm_info

Трассировка trace (включение трассировки на уровне методов в пакете), trace_result (получение пути вызова)

Не используйте для

• Посмертного анализа кучи (heap analysis)

• Постоянного наблюдения за продуктовой средой

• Сред, где подключение JDWP или приостановка потоков операционно небезопасны

Операционное примечание

JDWP изменяет поведение во время выполнения. Приостановка потоков и установка точек останова могут нарушить работу. Используйте осторожно в продуктовой среде; отдавайте предпочтение промежуточным средам (staging) или контролируемым окнам обслуживания.

Сценарии развертывания

См. docs/deploy.md для настройки с Maven, Gradle, Tomcat, Docker, Kubernetes (port-forward) и SSH-туннелями.

Примеры

• Отладка зависшего запроса — полное пошаговое руководство: конфликт блокировок, анализ потоков, выявление первопричины

• Отладка наблюдаемости — исследование проблем с Spring Boot ObservationRegistry

Архитектура

Agent  -->  MCP Server  -->  JDWP Client  -->  TCP  -->  JVM
              |
        Translates tool calls to JDWP,
        tracks session state, summarizes
        runtime objects for the agent.

Сборка из исходного кода

cargo build --release
cargo test

Лицензия

MIT