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/ (있는 경우) — 에 설치되므로 각 에이전트의 구성 옆에 복사되어 아무도 스캔하지 않는 곳에 두는 대신 어디서나 발견할 수 있습니다 (VS Code가 스킬을 로드하지 않던 #105 수정). 서버는 또한 MCP instructions를 광고하고 start_debugging 도구가 전체 워크플로를 위해 스킬을 가리킵니다.

• 실행 중인 프로그램 일시 중지 — 새로운 pause_execution 도구가 자유롭게 실행 중인 프로그램을 중단하고 중단점이 설정되지 않은 경우에도 현재 위치에서 멈춥니다 (바쁜 루프 및 임베디드/베어메탈 대상에 유용). 그런 다음 상태를 검사하거나 그 지점부터 단계별로 실행할 수 있습니다.

• VS Code Testing API를 통한 강력한 디버깅 — testName과 함께 start_debugging을 사용하면 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는 AI 코딩 에이전트에게 VS Code 디버거에 대한 완전한 제어권을 제공하는 MCP 서버입니다. 로그를 읽거나 추측하는 대신 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

• "Install" 클릭

옵션 3: VS Code 내에서

1. VSCode 열기

2. 확장 프로그램으로 이동 (Ctrl+Shift+X / Cmd+Shift+X)

3. "DebugMCP" 검색

4. 설치 클릭

5. 확장 프로그램이 자동으로 활성화되고 MCP 서버로 등록됨

확인

설치 후 다음을 확인해야 합니다:

• 설치된 확장 프로그램에 DebugMCP 표시

• MCP 서버가 포트 3001에서 자동 실행 (구성 가능)

• 연결된 AI 어시스턴트가 디버그 도구 사용 가능

📝 참고: 추가 디버깅 규칙 지침이 필요 없습니다 - 확장 프로그램이 즉시 작동합니다.

💡 팁: AI 어시스턴트에서 모든 debugmcp 도구에 대해 자동 승인을 활성화하면 지속적인 승인 중단 없이 원활한 디버깅 워크플로를 만들 수 있습니다.

빠른 시작

1. 확장 프로그램 설치 (설치 참조)

2. VSCode에서 프로젝트 열기

3. AI에게 디버깅 요청 - 이제 중단점 설정, 디버깅 시작, 코드 분석이 가능합니다!

지원되는 AI 어시스턴트

DebugMCP는 모든 MCP 호환 AI 어시스턴트와 작동합니다. 자동으로 감지하여 다음에 등록을 제안합니다:

지원 언어

DebugMCP는 각각의 VSCode 확장 프로그램과 함께 다음 언어의 디버깅을 지원합니다:

구성

MCP 서버 구성 (권장)

이 확장 프로그램은 MCP 서버를 자동으로 실행합니다. AI 어시스턴트에 MCP 서버를 자동 등록하라는 메시지가 표시됩니다.

명령 팔레트를 통해 수동으로 등록을 트리거할 수도 있습니다:

• DebugMCP: Show Agent Selection Popup

수동 MCP 서버 등록 (선택 사항)

🔄 자동 마이그레이션: 이전에 SSE 전송으로 DebugMCP를 구성한 경우, 확장 프로그램은 활성화 시 구성이 새 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이 설정된 경우 ${COPILOT_HOME}/mcp-config.json):

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

Cursor

Cursor의 MCP 설정에 추가하세요:

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

Codex

Codex에 DebugMCP를 등록하세요:

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

또는 동일한 구성을 ~/.codex/config.toml에 추가하세요 (CODEX_HOME이 설정된 경우 ${CODEX_HOME}/config.toml):

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

Windsurf

Windsurf의 MCP 설정(~/.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

Roo Code의 MCP 설정에 추가하세요:

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

Antigravity

Antigravity의 MCP 설정에 추가하세요:

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

확장 프로그램 설정

VSCode 설정에서 DebugMCP 동작을 구성하세요:

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

보안 모델

DebugMCP는 인증되지 않은 로컬 HTTP 엔드포인트를 통해 강력한 디버거 프리미티브(evaluate_expression, start_debugging 등)를 노출합니다. 해당 표면을 안전하게 유지하기 위해 서버는 네 가지 제어를 적용합니다:

1. 루프백 전용 바인딩. HTTP 서버는 기본적으로 IPv4 및 IPv6 루프백 주소(127.0.0.1 및 ::1)에 바인딩되므로 네트워크의 다른 호스트는 http://<your-ip>:3001/mcp에 도달할 수 없습니다. 두 주소 계열을 모두 바인딩하면 localhost를 어느 계열로든 해석하는 클라이언트가 성공적으로 연결할 수 있습니다. debugmcp.bindHost 설정(문자열 또는 문자열 배열)을 사용하면 다른 인터페이스를 선택할 수 있지만(예: 원격 컨테이너로 포트를 전달할 때), 이렇게 하면 해당 주소로 라우팅할 수 있는 모든 항목에 인증되지 않은 디버거가 노출됩니다. 신뢰할 수 없는 네트워크에서 0.0.0.0 또는 LAN 주소를 가리키지 마십시오.

2. Host / Origin 헤더 검증. 모든 요청은 루프백 주소(localhost, 127.0.0.1 또는 [::1])를 지정하는 Host 헤더를 포함해야 합니다. Host의 포트 접미사도 서버의 수신 포트와 일치해야 합니다. 다른 Host가 있는 요청(악성 웹페이지의 DNS 리바인딩을 통해 도착하는 요청 포함)은 HTTP 403으로 거부됩니다. Origin 헤더가 있는 경우에도 동일한 루프백 검사가 적용됩니다.

3. 최소 권한 변수 검사. get_variables_values는 명시적인 variableNames 목록(최대 50개, 와일드카드 없음)을 요구하며 해당 변수만 반환합니다. 더 이상 범위 내의 모든 변수를 덤프하지 않습니다. 이전에는 에이전트가 요청하지 않은 관련 없는 프로세스 상태를 넘겨주었습니다. list_variable_names를 사용하여 존재하는 항목을 확인하세요. 이 도구는 이름과 유형만 반환하며 값을 읽지 않습니다.

4. 변수 검사 시 비밀 값 편집. 자격 증명과 관련된 이름 또는 알려진 자격 증명 형태와 일치하는 값을 가진 값은 응답이 확장 프로그램을 떠나기 전에 <redacted: possible secret>으로 대체됩니다. evaluate_expression이 반환한 평가 결과도 포함됩니다. get_variables_values 또는 evaluate_expression이 복잡한 값을 확장할 때 하위 항목은 이름과 유형으로만 나열됩니다. 값이 필요한 경우 정확한 하위 경로로 evaluate_expression을 사용하세요. 재귀 확장은 응답당 총 100개의 하위 필드로 제한됩니다. Null과 유사한 값(None, undefined, '')은 편집되지 않으므로 "내 토큰이 비어 있음" 버그는 계속 디버깅할 수 있습니다. 편집은 항상 켜져 있으며 끌 수 없습니다.

FAQ

DebugMCP는 GitHub Copilot, GitHub Copilot CLI, Cline, Cursor, Codex, Windsurf, Roo Code, Antigravity 등을 포함한 모든 MCP 호환 AI 어시스턴트와 작동합니다. 어시스턴트가 Model Context Protocol을 지원한다면 DebugMCP를 사용할 수 있습니다.

네. DebugMCP는 extensionKind: workspace로 VS Code 확장 프로그램으로 실행되므로 코드가 있는 원격 환경에서 활성화됩니다. MCP 서버는 해당 원격 컨텍스트 내의 localhost에서 실행됩니다.

아니요. DebugMCP는 파일의 언어/확장자에 따라 적절한 디버그 구성을 자동으로 생성합니다. launch.json이 있는 경우 가장 관련성 높은 구성을 자동으로 선택합니다.

아니요. DebugMCP는 100% 로컬에서 실행됩니다. MCP 서버는 localhost에서 실행되며 코드, 변수 또는 디버그 데이터는 외부 서비스로 전송되지 않습니다. AI 어시스턴트는 로컬 머신 내에서 완전히 MCP 서버와 통신합니다.

VS Code 설정에서 포트를 변경하세요: "debugmcp.serverPort": 3002 (또는 사용 가능한 포트). 그런 다음 AI 어시스턴트의 MCP 구성을 새 포트를 사용하도록 업데이트하세요.

네. start_debugging에 testName 매개변수를 전달하여 특정 테스트 메서드를 디버깅하세요. DebugMCP는 디버그 세션을 구성하여 해당 테스트 내의 중단점에서 실행하고 일시 중지합니다.

DebugMCP가 AI 어시스턴트의 MCP 설정에 등록되어 있는지 확인하세요. 확장 프로그램은 자동으로 감지하여 등록을 제안해야 합니다. 그렇지 않은 경우 수동 MCP 서버 등록 섹션을 참조하세요. 또한 더 원활한 워크플로를 위해 DebugMCP 도구에 대한 자동 승인을 활성화하세요.

네. DebugMCP는 ASP.NET 애플리케이션을 포함한 C#/.NET 디버깅을 위해 .cs 파일 및 .csproj 프로젝트 파일을 지원합니다.

문제 해결

일반적인 문제

MCP 서버가 시작되지 않음

• 증상: AI 어시스턴트가 DebugMCP에 연결할 수 없음

• 해결 방법:

  • 포트 3001이 사용 가능한지 확인

  • VSCode 다시 시작

  • 확장 프로그램이 설치 및 활성화되었는지 확인

디버그 세션이 중단점에서 멈추지 않음

• 증상: 중단점이 설정되었지만 실행이 일시 중지되지 않음

• 해결 방법:

  • 올바른 파일이 디버깅되고 있는지 확인

  • 중단점 줄 번호가 올바른지 확인

  • 해당 언어 디버거 확장 프로그램이 설치되었는지 확인

디버깅이 중지될 때 다른 VS Code 창이 포커스를 가져감

• 증상: 여러 VS Code 창이 열려 있을 때 디버깅 중인 창이 중단점에 도달하거나 단계를 완료하면 전경으로 나타남

• 해결 방법: 사용자 또는 작업 공간 설정에서 VS Code의 기본 포커스-온-브레이크 동작을 비활성화하세요:

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

  debug.focusWindowOnBreak는 디버깅 중인 창이 운영 체제 포커스를 가져가지 못하게 합니다. 선택적 debug.focusEditorOnBreak 설정은 VS Code가 중지된 소스 편집기로 포커스를 이동하지 못하게 합니다. DebugMCP는 이러한 지속적인 기본 설정을 자동으로 변경하지 않습니다.

구성이 자동 감지되지 않음

• 증상: 확장 프로그램이 AI 어시스턴트에 등록하라는 메시지를 표시하지 않습니다

• 해결 방법:

  • 명령 팔레트(Ctrl+Shift+P / Cmd+Shift+P)에서 DebugMCP: Show Agent Selection Popup 실행

  • 구성을 수동으로 추가합니다(수동 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: .py 파일용 Python 확장 프로그램

  • JavaScript/TypeScript: 기본 제공 Node.js 디버거 또는 JavaScript Debugger 확장 프로그램

  • Java: Java용 확장 팩

  • C#/.NET: C# 확장 프로그램

  • C/C++: C/C++ 확장 프로그램

  • Go: Go 확장 프로그램

  • Rust: rust-analyzer 확장 프로그램

  • PHP: PHP Debug 확장 프로그램

  • Ruby: 디버그 지원이 포함된 Ruby 확장 프로그램

• MCP 호환 AI 어시스턴트(Copilot, Cline, Cursor, Codex, Windsurf, Roo Code 등)

개발

확장 프로그램을 빌드하려면:

npm install
npm run compile

린팅을 실행하려면:

npm run lint

테스트를 실행하려면:

npm test

기여

이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 기여를 사용할 권리를 당사에 부여할 수 있고 실제로 부여함을 선언하는 기여자 라이선스 계약(CLA)에 동의해야 합니다. 자세한 내용은 https://cla.opensource.microsoft.com을 방문하세요.

풀 리퀘스트를 제출하면 CLA 봇이 CLA를 제공해야 하는지 자동으로 판단하고 PR을 적절하게 표시합니다(예: 상태 확인, 댓글). 봇이 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 당사의 CLA를 사용하는 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트는 Microsoft 오픈 소스 행동 강령을 채택했습니다. 자세한 내용은 행동 강령 FAQ를 참조하거나 추가 질문이나 의견이 있으면 opencode@microsoft.com으로 문의하세요.

보안

보안 취약점은 https://aka.ms/SECURITY.md의 지침에 따라 보고해야 합니다. 공개 GitHub 이슈를 통해 보안 취약점을 보고하지 마세요.

상표

이 프로젝트에는 프로젝트, 제품 또는 서비스에 대한 상표 또는 로고가 포함될 수 있습니다. Microsoft 상표 또는 로고의 승인된 사용은 Microsoft 상표 및 브랜드 지침을 따르고 준수해야 합니다. 이 프로젝트의 수정된 버전에서 Microsoft 상표 또는 로고를 사용하는 것은 혼동을 일으키거나 Microsoft의 후원을 암시해서는 안 됩니다. 제3자 상표 또는 로고의 사용은 해당 제3자의 정책을 따릅니다.

⭐ DebugMCP 지원

DebugMCP가 더 빠르게 디버그하는 데 도움이 되었다면 GitHub에서 별표를 눌러 주세요! 별표는 프로젝트의 가시성을 높이고 기여자를 유치하는 데 도움이 됩니다.

⭐ GitHub에서 DebugMCP 별표 누르기

별표 기록

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 참조

이 확장 프로그램은 Oz Zafar, Ori Bar-Ilan, Karin Brisker가 만들었습니다.