jdwp-mcp

JDWP를 통해 실행 중인 JVM 디버깅 — 모든 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.

단 하나의 프롬프트. 6번의 도구 호출. 잠금 경합 및 근본 원인 식별 완료.

빠른 시작

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. JDWP로 Java 앱 시작

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 (호출 경로 가져오기)

사용하지 말아야 할 경우

• 사후 힙 분석

• 상시 운영 관찰 가능성

• JDWP 연결이나 스레드 일시 중지가 운영상 안전하지 않은 환경

운영 참고 사항

JDWP는 런타임 동작을 변경합니다. 스레드를 일시 중지하고 중단점을 설정하는 것은 운영에 지장을 줄 수 있습니다. 운영 환경에서는 주의해서 사용하고, 가급적 스테이징 환경이나 통제된 유지보수 시간에 사용하세요.

배포 시나리오

Maven, Gradle, Tomcat, Docker, Kubernetes(포트 포워딩) 및 SSH 터널을 사용한 설정은 docs/deploy.md를 참조하세요.

예시

• 응답 없는 쿼리 디버깅 — 전체 과정: 잠금 경합, 스레드 분석, 근본 원인 식별

• 관찰 가능성 디버깅 — 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