BitDive 트레이스 분석, 요청 재현 및 회귀 관리를 위한 Python MCP 서버

BitDive 트레이스 (trace) 분석, 요청 재현 (request reproduction), 그리고 회귀 관리 (regression management)를 위한 Python MCP 서버입니다.

이 저장소는 BitDive 모니터링 및 QA 운영 기능을 Cursor, Claude Desktop 및 기타 에이전트 런타임 (agent runtimes)과 같은 MCP 클라이언트에 노출합니다. 구현체는 server.py에 있으며, BitDive 모니터링 API에 연결하는 동시에 자체적인 포맷팅 (formatting), 정규화 (normalization), 그리고 비교 로직 (comparison logic)을 추가합니다.

이 저장소는 python-mcp-server 브랜치를 사용하여 사용하세요.

YouTube에서 BitDive 제품 데모를 시청하세요:

이 서버는 단순한 API 프록시 (proxy)가 아닙니다.

BitDive API 엔드포인트 (endpoints)를 래핑 (wrap)하여 에이전트 워크플로우 (agent workflows)에서 사용할 수 있도록 만듭니다:

• 탐색을 위한 컴팩트한 히트맵 (heatmap) 요약
• 단순한 원시 JSON 대신 읽기 쉬운 트레이스 (trace) 요약
• 캡처된 요청으로부터 생성된 Bash 및 PowerShell 재현 명령
• 페이로드 (payload) 및 컨트랙트 드리프트 (contract drift) 보고를 포함한 전/후 트레이스 비교
• 노이즈가 심한 차이 (diffs)를 줄이기 위한 SQL 정규화 및 휘발성 필드 (volatile-field) 필터링
• 트레이스 경로에서의 자동 비밀 정보 삭제 (secret redaction) 및 연대순 자식 호출 (child-call) 정렬
• 테스트 그룹 (test-group) 조사 및 회귀 관리 (regression-management) 흐름

AI 에이전트나 개발자가 다음과 같은 작업이 필요할 때 이 서버를 사용하세요:

• 어떤 모듈, 서비스, 클래스 또는 엔트리포인트 (entrypoint)가 활성화되어 있는지 탐색
• 최근 또는 과거의 트레이스 가져오기
• BitDive JSON을 수동으로 파싱 (parsing)하지 않고 트레이스 조사
• 캡처된 웹 요청을 로컬에서 재현
• 코드 변경 후 두 개의 트레이스 비교
• 여러 실행에 걸쳐 동작이 어떻게 진화했는지 추적
• BitDive 테스트 그룹 조사 및 업데이트

현재 서버는 24개의 MCP 도구 (tools)를 노출합니다.

도구 이름은 그 의도를 따릅니다: 탐색 (discovery) 도구 (아직 id가 없는 경우)는 get_*_heatmap / list_* / find_* / search_*로 시작합니다; 조사 (inspect) 도구 (call_id가 이미 있는 경우)는 get_trace*로 시작합니다; 비교 (compare) 도구는 트레이스 간의 차이 (diff)를 구합니다.

그룹	도구	사용 시점
탐색 (히트맵) (Discovery (heatmaps))	get_system_heatmap , get_module_heatmap , get_service_heatmap	아직 어디를 살펴봐야 할지 모를 때; 클래스/메서드 및 해당 지표를 찾을 때
탐색 (호출/메서드) (Discovery (calls/methods))	list_recent_calls , find_calls_by_method , search_methods , search_methods_detailed	call_id를 얻거나 키워드로 메서드를 찾을 때
조사 (Inspect)	get_trace_overview , get_trace , get_trace_raw , get_trace_subtree	단일 트레이스 조사 (call_id 필요); 이미 알고 있는 트레이스 읽기: 개요(overview) → 전체 노이즈 제거(full de-noised) → 원시 데이터(raw) → 단일 서브트리(single subtree) 순서
비교 (Compare)	compare_traces , compare_traces_over_time	전/후 차이(diff) 비교, 또는 시간 순서에 따른 시리즈 비교
재현 (Reproduce)	get_replay_command	요청을 재현하기 위한 curl/PowerShell 명령어를 다시 구축할 때
유틸리티 (Utility)	resolve_call_ids	call_id를 짧은 Class.method 이름으로 매핑할 때
테스트 (Tests)	create_test_group , list_test_groups , list_test_group_classes , list_test_group_methods , build_test_payload , delete_test_group , set_test_group_enabled , regenerate_test , get_test_results	기록 및 재현 (record-and-replay) 테스트 그룹을 관리하고 조사할 때

탐색 (Discover)—get_system_heatmap 또는 list_recent_calls를 사용하여 메서드나 최신 call_id를 찾으세요.

조사 (Inspect)—빠른 트리 확인을 위해 get_trace_overview를 사용하고, 전체 노이즈 제거된 페이로드(deep analysis의 기본값)를 보려면 get_trace를 사용하세요.

비교 (Compare)—전/후 비교에는 compare_traces를 사용하세요. 차이점에 대한 페이로드 증거가 필요한 경우 get_trace를 엽니다.

재현 (Reproduce)—get_replay_command를 실행하고 약 45초를 기다린 다음, 다시 list_recent_calls를 실행하세요.

도구 이름에는 의도가 담겨 있습니다: call_id가 아직 없는 경우에는 탐색(discovery) 도구를 사용하고, call_id가 있는 경우에는 get_trace*를 사용합니다.

단순히 백엔드 API로 위임하는 것이 아니라, 여러 중요한 동작들이 server.py 내부에 구현되어 있습니다.

get_trace_overview는 읽기 쉬운 실행 트리(execution tree)를 구축하며, get_trace는 전체 트리를 높은 충실도(fidelity)로 반환하되 원시 Jackson/타입 래퍼(type-wrapper) 노이즈를 제거합니다 (일반적으로 get_trace_raw보다 50-65% 더 작습니다).

, secrets redacted, child calls ordered chronologically)get_trace_raw 및 get_trace_subtree 또한 정보가 가려집니다(redacted). 원본 형태 그대로의 구조나 단일 메서드 경계가 필요한 경우에만 사용하세요. - SQL, REST, 큐 호출(queue calls), 타이밍(timings), 반환 값(return values) 및 에러가 MCP 출력에 적합하도록 포맷팅됩니다.

compare_traces는 메서드 경로 드리프트(method-path drift)를 감지합니다.

• Java 직렬화(Java-serialized) 구조를 정규화(normalizing)한 후 페이로드(payload) 및 계약(contract) 변경 사항을 비교합니다.

• ID, UUID, 타임스탬프(timestamps), traceId, callId와 같은 휘발성 필드(volatile fields)는 더 깔끔한 차이점(diffs)을 위해 무시할 수 있습니다.

• SQL 실행 델타(deltas)는 그룹화 및 정규화되어 N+1 패턴을 쉽게 파악할 수 있도록 합니다.

• 캡처된 요청 URL은 정규화되어 내부 Docker 호스트 이름(hostnames)을 호스트 셸(host shell)에서 다시 실행(replay)할 수 있습니다.

• 기록된 헤더(headers), 메서드(method), URL 및 바디(body)로부터 curl 및 PowerShell 명령어가 생성됩니다.

• 직접적인 헬퍼 데이터(helper data)를 사용할 수 없는 경우, 서버는 MCP로 접근 가능한 API를 통해 대체 페이로드를 재구성할 수 있습니다.

• 테스트 그룹 검사(test-group inspection)는 원시 응답(raw response)을 직접 탐색하는 대신 에이전트가 빠르게 사용할 수 있도록 포맷팅됩니다.

계층 (Layer)	책임 (Responsibility)
BitDive backend	트레이스(traces), 모니터링 데이터 및 테스트 메타데이터를 저장
mcp-server	MCP 도구(tools)를 노출하고 비교, 정규화 및 포맷팅 로직을 추가
MCP client	도구를 호출하는 Cursor, Claude Desktop 또는 기타 런타임

• Python 3.11+
• httpx
• mcp
• 유효한 BitDive MCP 토큰

의존성 설치:

pip install -r requirements.txt

변수 (Variable)	용도 (Purpose)	기본값 (Default)
BITDIVE_MCP_TOKEN	도구 호출 시 mcp_token이 전달되지 않을 때 사용하는 기본 토큰	none
BITDIVE_API_URL	BitDive 모니터링 API의 기본 URL	https://cloud.bitdive.io/monitoring-api
BITDIVE_SKIP_VERIFY	true로 설정 시 TLS 인증서 검증을 비활성화	false
MCP_TRANSPORT	MCP 전송 모드 (transport mode)	stdio
MCP_HOST	HTTP 모드용 호스트	0.0.0.0
MCP_PORT	HTTP 모드용 포트	8000

모든 도구는 선택 사항인 mcp_token 파라미터를 허용합니다. 이 파라미터가 생략되면 서버는 BITDIVE_MCP_TOKEN을 대신 사용합니다.

python server.py

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 python server.py

{
"mcpServers": {
"bitdive": {
...

경로 (Path)	용도 (Purpose)
server.py	MCP 서버 구현 (MCP server implementation)
requirements.txt	Python 의존성 (Python dependencies)

• MCP 토큰을 사용할 수 없는 경우 서버는 즉시 종료(fail fast)됩니다.
• 재현 (replay) 직후에는 새로운 트레이스 (traces)가 핫 캐시 (hot cache)에 즉시 나타나지 않을 수 있습니다. 내장된 워크플로 (workflow)는 최근 호출을 다시 확인하기 전에 짧은 대기 시간을 갖도록 설계되었습니다.
• 이 리포지토리 (repository)는 MCP 브리지 (bridge) 및 트레이스 인텔리전스 (trace-intelligence) 레이어입니다. 이 자체로 JVM 이벤트를 캡처하거나 JUnit 재현 테스트를 직접 실행하지는 않습니다.