qwen-dap-mcp

Qwen Code에 진짜 네이티브 디버거를 제공하세요.

네이티브 런타임 디버깅, 크래시 분석, 제한된 자율 수정/검증 루프를 위한 디버거에 구애받지 않는 Debug Adapter Protocol (DAP) → Model Context Protocol (MCP) 브리지입니다.

npm에 @slp-dev1/qwen-dap-mcp로, 공식 MCP Registry에는 io.github.SLP-DEV1/qwen-dap-mcp로 게시되어 있습니다.

왜 필요한가

코딩 에이전트는 소스 읽기와 편집에 능숙하지만, 네이티브 크래시는 디버거만이 제공할 수 있는 증거를 필요로 하는 경우가 많습니다: 스택 프레임, 레지스터, 지역 변수, 디스어셈블리, 예외 상태, 메모리, 모듈, 크래시 덤프.

qwen-dap-mcp는 해당 증거를 MCP를 통해 노출하여 Qwen Code 및 기타 MCP 클라인트가 에이전트 내부에 디버거 프로토콜을 내장하지 않고도 네이티브 실패를 추론할 수 있게 합니다.

무엇을 할 수 있나

• 자율 크래시 디버깅 — 진단 → 소스 검사 → 수정 제안 → 수정 적용 → 빌드 → 재현 → 검증.

• 실제 네이티브 디버거 증거 — 스택, 레지스터, 지역 변수, 예외 상태, 모듈, 디스어셈블리, 메모리 및 소스 연관 관계.

• CodeLLDB 통합 — DAP를 통해 허가된 로컬 네이티브 대상을 시작하거나 연결할 수 있습니다.

• 업스트림 LLVM lldb-dap 통합 — lldb-dap을 CodeLLDB 별칭으로 취급하지 않고 일급 라이브 디버깅 및 코어 파일 검사를 제공합니다.

• Windows 미니덤프 / 사후 디버깅 — 기존 .dmp 파일을 열고 구조화된 증거를 복구합니다.

• 런타임 근본 원인 역추적 — 의심스러운 값을 제한된 호출자 프레임을 따라 프로젝트가 제어하는 것으로 보이는 생산자 후보 쪽으로 추적합니다.

• 검증 지문 — 수정됨, 동일 크래시, 실패 변경, 판정 불가 재현을 구분합니다.

• 안전 경계 — 임의 셸, 소스 작성 프리미티브, 일반 메모리 쓰기 프리미티브, MCP 서버 내부의 숨은 자율 상태가 없습니다.

Related MCP server: Debug-MCP

30초 예제

You: Debug why app.exe crashes with --repro

Qwen Code
  ↓
starts CodeLLDB or upstream lldb-dap through qwen-dap-mcp
  ↓
finds the native failure and first project-controlled frame
  ↓
correlates instruction operands ↔ registers ↔ locals
  ↓
backtracks runtime evidence toward a likely producer
  ↓
reads the relevant source
  ↓
applies a minimal evidence-backed fix
  ↓
builds and repeats the same reproduction
  ↓
verifies the original crash fingerprint no longer reproduces

Qwen Code에 설치

GitHub 릴리스에서 직접 설치:

qwen extensions install SLP-DEV1/qwen-dap-mcp

또는 게시된 scoped npm 확장을 설치합니다:

qwen extensions install @slp-dev1/qwen-dap-mcp

그런 다움 확장과 MCP 서버를 확입니다:

/mcp
/skills

qwen-dap-mcp MCP 서버와 번들된 native-runtime-debug Skill이 표시되어야 합니다.

GitHub 릴리스 아카이브는 자족적입니다: 런타임 npm 의존성이 dist/index.js에 번들되어 있습니다.

다른 stdio MCP 클라이언트에서 사용

로컬 stdio 명령을 수용하는 MCP 클라이언트의 경우, 게시된 npm 패키지를 다음과 같이 시작할 수 있습니다:

npx -y @slp-dev1/qwen-dap-mcp

일반적인 클라이언트 구성은 다음과 같습니다:

{
  "mcpServers": {
    "qwen-dap-mcp": {
      "command": "npx",
      "args": ["-y", "@slp-dev1/qwen-dap-mcp"]
    }
  }
}

Qwen Code가 기본 통합이며 프로젝트의 확장 패키징 및 릴리스 검증이 다루는 경로입니다. MCP 서버 자체는 로컬 stdio를 통해 통신합니다.

배포

디버거 어댑터

CodeLLDB와 업스트림 LLVM lldb-dap는 모두 일급 어댑터 경로입니다. 기존 CodeLLDB 워크플로는 계속 지원되며, LLVM 자체가 제공하는 디버거 어댑터를 원할 때는 debug_this_crash(mode="lldb-dap")를 사용하세요. lldb-dap 경로는 라이브 시작/연결과 dumpAdapter="lldb-dap"를 통한 읽기 전용 코어 파일 분석을 지원합니다.

발견은 명시적인 adapterPath, LLDB_DAP_PATH, 정식 또는 버전이 있는 PATH 바이너리, 일반 LLVM 체인 디렉터리 / LLVM_HOME, 그리고 macOS의 xcrun --find lldb-dap를 지원합니다. 예제, 사후 동작, 수동 전체 툴셋 도우미는 docs/lldb-dap.md를 참조하세요.

자율 크래시 디버깅

고수준 debug_this_crash 워크플로는 제한된 자율 디버깅 사이클을 구동할 수 있습니다:

Diagnose
  ↓
select project frame
  ↓
operand ↔ register ↔ variable evidence
  ↓
call-chain / runtime provenance backtrack
  ↓
inspect source
  ↓
propose minimal fix
  ↓
apply fix
  ↓
build
  ↓
reproduce
  ↓
verify fingerprint + evidence quality
  ├── fixed → stop
  ├── same crash → revise fix
  ├── changed crash → re-baseline active failure
  ├── inconclusive → finish reproduction, do not edit
  └── budget exhausted / weak evidence → stop and report

자율 사이클 시작:

debug_this_crash(
  mode="codelldb",
  program="C:\\build\\app.exe",
  args=["--repro"],
  cwd="C:\\repo\\app",
  analysis={
    projectRoots:["C:\\repo\\app"],
    projectModules:["app.exe"],
    callerDepth:3
  },
  workflow={
    stage:"autonomous",
    maxIterations:3
  }
)

첫 번재 호출은 명시적으로 직렬화 가능한 상태, 의존성을 고려한 nextActions, 루트 및 활성 크래시 지문, 제한된 기록, 런타임 역추적 증거, 검증 품질, 중지/계속 상태를 포함한 workflow.autonomousAgent를 반환합니다.

서버는 숨은 자율 루프 메모리를 유지하지 않습니다. Qwen Code는 요청된 소스 편집, 빌드, 테스트, 소스 제어 작업을 일반적인 승인된 도구를 통해 수행합니다.

자율 상태

지능적 진단

진단 계층은 원시 디버거 사실과 추론을 분리하여 보고합니다:

• classification — 현재 크래시/중지 계열,

• faultLocation — 말 그대로의 디버거 중지 프레임,

• projectFrame — 가능성이 높은 첫 번째 애플리케이션 제어 프레임,

• frameSelection — 점수화된 스택 프레임 증거 및 런타임/시스템 제외,

• operandAnalysis — 명령어 피연산자, 참조 레지스터, 메모리 피연산자 및 레지스터↔지역 변수 바인딩,

• callChain — 프로젝트 호출자, 런타임 경계, 반복 프레임 및 출처 단서,

• hypotheses — 명시적 신뢰도와 함께 순위가 매겨진 설명,

• fixWorkflow — 후보 소스 위치 및 증거에 기반한 좁은 수정 방향,

• verificationBaseline — 간결한 실패 시그니처,

• rootCauseBacktrack — 생산자 후보를 향한 제한된 런타임 출처 추적,

• verificationQuality — 검증 후 디버거 증거 강도.

높은 프로젝트 프레임 점수는 "프로젝트 코드일 가능성이 높음"을 의미하지 "입증된 근본 원인"을 의미하지 않습니다. 인과 주장은 여전히 예외 상태, 피연산자/레지스터/지역 변수, 호출자 출처, 소스 확 및 재현과 연결되어야 합니다.

크래시 덤프 / 미니덤프

하나의 고수준 호출로 기존 덤프를 열고 진단합니다:

debug_this_crash(
  mode="dump",
  dumpPath="C:\\crashes\\app.dmp",
  program="C:\\build\\app.exe",
  sourceMap={"D:/agent/_work/project/src":"C:/work/project/src"},
  analysis={projectRoots:["C:\\repo\\app"]}
)

덤프 세션은 고정/읽기 전용입니다. 과거 덤프는 캡처된 실패에 대한 증거를 확립할 수 있지만, 소스 수정은 여전히 검증을 위해 재빌드된 라이브 재현 또는 새로 생성된 덤프가 필요합니다.

아키텍처

Qwen Code / MCP client
        │
        │ MCP over stdio
        ▼
   qwen-dap-mcp
        │
        ├── lifecycle/concurrency guard
        ├── bounded DAP snapshot layer
        ├── crash classification
        ├── project-frame scoring
        ├── operand/register/local correlation
        ├── call-chain provenance
        ├── runtime root-cause backtracking
        ├── verification fingerprints + quality scoring
        └── autonomous action state machine
        │
        │ DAP over stdio
        ▼
 CodeLLDB / lldb-dap / DAP adapter
        │
        ├── authorized live target
        └── crash dump / core file

MCP 서버에는 HTTP 리스너가 없습니다. 어댑터는 셸 없이 로컬에서 생성되며 stdio를 통해 통신합니다.

MCP 툴셋

기본 agent 툴셋은 코딩 에이전트가 모든 저수준 디버거 프리미티브에 컨텍스트를 소비하지 않도록 의도적으로 아래의 9가지 고수준 도구만 노출합니다. 전체 수동 DAP 표면이 의도적으로 필요할 때 QWEN_DAP_MCP_TOOLSET=full을 설정하세요. docs/toolsets.md를 참조하세요.

기본 agent 도구

full 셋은 추가로 수동 브레이크포인트/와치포인트 관리, 스테핑, 평개, 스레드/스택/스코프/변수, 모듈, 디스어셈블리, 제한된 메모리 읽기, 예외 제어, 일반 DAP 시작/연결, 그리고 CodeLLDB / lldb-dap 수명 주기 프리미티브를 노출합니다.

검증 모델

검증은 의도적으로 디버거 증거를 빌드 성공, 프로젝트 테스트, 정확한 재현 입려과 같은 외부 보장과 분리합니다.

판정:

• fixed — 전체 재현이 깨끗하게 성공적인 종료 결과에 도달함,

• not-fixed — 동일한 크래시 계열/시그니처가 재현됨,

• changed-failure — 실해이 여전히 크래시했지만 활성 실패 시그니처가 변경됨,

• inconclusive — 성공 또는 실패를 주장하기에 증거가 불충분함.

브레이크포인트, 진입 중지, 일시 중지, 스텝 또는 구성된/최초 발생 예외 중지는 의도적으로 수정의 증거가 아닙니다.

실제 Windows 검증

저장소에는 Windows에서 실제 CodeLLDB 스모크 워크플로가 포함되어 있습니다. 미니덤프 스모크 경로:

1. PDB 심볼로 MSVC C++ 크래시 대상을 컴파일하고,

2. 의도적으로 액세스 위반을 트리거하고,

3. MiniDumpWriteDump로 실제 .dmp를 작성하고,

4. 실제 CodeLLDB를 시작하고,

5. DAP를 통해 덤프를 열고,

6. 스택/소스/레지스터/모듈/디스어셈블리 복구를 검증하고,

7. 지능적 프로젝트 프레임 진단을 실행하고,

8. 실제 덤프에서 자율 상태/지문/액션 생성을 검증합니다.

개발

요구 사항:

• Node.js 20+

• npm

전체 검사를 실행합니다:

npm ci --ignore-scripts
npm run check

npm run check는 TypeScript 빌드, 테스트, 확장 패키지 스테이징을 수행합니다. CI는 Node 20과 22에서 실행됩니다.

안전 모델

• 로컬 stdio MCP 전송만 사용,

• 내장 원격 HTTP 디버거 서비스 없음,

• 임의 셸/소스 작성 MCP 프리미티브 없음,

• 임의 메모리 쓰기 MCP 프리미티브 없음,

• 외부 증거 없이 자동 소스 롤백 없음,

• 라이브 연결은 승인된 로컬 대상에만 의도됨,

• 사후 덤프는 실행 제어 작업에 대해 고정됨,

• 결정적 중지 조건을 갖춘 제한된 자율 수정 예산,

• 약하거나 불충분한 증거는 추가 소스 편집을 트리거하지 않음,

• 최초 발생/구성된 예외 중지는 치명적 상황으로 취급되지 않음.

기여

이슈와 풀 리퀘스트를 환영합니다. 개발 지침은 CONTRIBUTING.md를 참조하세요.

프로젝트가 유용하시다면, 저장소에 스타를 남겨 주시면 다른 Qwen Code 및 MCP 사용자들이 이 프로젝트를 발견하는 데 도움이 됩니다.

라이선스

Apache License 2.0. LICENSE를 참조하세요.