BSOD-DX

Windows 블루스크린·하드웨어 오류를 관리자 권한 없이, 네트워크 없이 진단하는 로컬 MCP 서버.

Windows에서 블루스크린이 발생하면 어떤 로그를 어떤 순서로 봐야 할지 판단하기 어렵고, 보통 커널 지식이 필요합니다. BSOD-DX는 관리자 권한 없이 안전하게 수집할 수 있는 크래시 증거(BugCheck 코드, WHEA 하드웨어 오류, 부팅 타임라인, 미니덤프, 메모리 진단, 디스크 헬스)를 모아 정규화하고, 핵심 신호를 코드로 계산해(환각 방지) 호스트 LLM의 분석을 뒷받침합니다. 데이터는 PC 밖으로 나가지 않습니다. 서버는 직접 추론하지 않으며, 원인 분류와 리포트 작성은 호스트 LLM이 내장 playbook과 lookup 자료를 근거로 수행합니다.

핵심 특징

• 부품 단위 특정. WHEA CPER를 디코딩해 고장 부품을 CPU 캐시·메모리·PCIe 수준까지 좁힙니다. 수집 기간 내 전체 레코드를 집계하므로 최근 일부 기록에 분류가 휘둘리지 않습니다.
• 코드로 계산한 결정론적 신호. 하드웨어·드라이버 지표, WHEA와 BSOD의 시간 상관, 서버가 산출한 신뢰도(confidence)와 근거(evidence_basis)를 모델의 기억이 아니라 코드로 계산합니다. 크래시가 없는 시스템에 거짓 지표를 만들지 않습니다.
• 하드웨어 확증 보조. Windows 메모리 진단 결과와 디스크 헬스(SMART)를 함께 수집해 하드웨어 가설을 뒷받침하거나 약화합니다.
• 안전 기본값. 읽기 전용·무관리자·무네트워크로 동작하며, 보안 기능(HVCI/VBS/Secure Boot) 비활성화를 권고하지 않습니다.
• 안전한 외부 전달. 지원팀 전달용 번들은 PII를 마스킹하고 파일별 SHA-256과 누출 항목 목록을 동봉하며, 실수를 막기 위해 미리보기(dry-run)를 먼저 거칩니다.

작동 방식

사용자가 /bsod-triage를 실행하면 MCP 클라이언트의 호스트 LLM이 분석을 주도합니다. bsod-dx 서버는 stdio로 연결되어 PowerShell 수집기를 자식 프로세스로 실행하고, 이벤트 로그·WMI/CIM·레지스트리·미니덤프에서 증거를 읽습니다. 서버는 수집·디코딩·정규화와 결정론 신호 계산을 담당하고, 추론과 리포트 작성은 호스트 LLM이 결정론 신호와 lookup 리소스를 근거로 수행합니다.

설치

BSOD-DX는 표준 MCP(stdio) 서버입니다. MCP를 지원하는 클라이언트라면 연결할 수 있으며, 진단 대상은 Windows여야 합니다.

Claude Desktop에서는 Releases에서 bsod-dx-X.Y.Z.mcpb를 받아 더블클릭하면 설치됩니다(SHA-256 체크섬 제공). 직접 빌드하려면:

npm install
npm run pack

Claude Code에서는 빌드 후 절대 경로로 등록합니다.

npm install
npm run build
claude mcp add bsod-dx -- node "<절대경로>/dist/index.js"

기타 MCP 클라이언트는 빌드 후 클라이언트의 MCP 서버 설정에 stdio 실행 명령을 등록합니다.

{ "command": "node", "args": ["<절대경로>/dist/index.js"] }

.mcpb 번들과 claude mcp add는 Claude용 편의 수단이며, 그 외 클라이언트는 위처럼 stdio 명령으로 직접 연결합니다. 도구·리소스·프롬프트는 모든 클라이언트에서 동일하게 노출됩니다.

도구

도구	언제 호출하나	무엇을 반환하나
collect_crash_evidence	진단을 시작할 때 가장 먼저	정규화 요약(환경, BugCheck 분포, WHEA 요약과 부품 분포, 요약 타임라인, 변경점, 무결성, 메모리 진단, 디스크 헬스, 비치명 복구(GPU TDR/LiveKernelReports), 결정론 신호와 신뢰도, 평문 verdict 카드)
decode_whea	whea.total > 0일 때	CPER 디코딩(severity, section 유형, 메모리 물리주소·ErrorType(단일/다중비트 ECC))과 component_distribution(placeholder 섹션은 미집계, cache←processor 계층 정리)
analyze_minidump	범인 모듈·드라이버를 특정할 때	상태값(status)과 안내. 디버거가 있으면 !analyze -v 요약, 없으면 헤더 BugCheck(흔한 코드는 파라미터 의미 디코딩). all=true면 여러 덤프의 재발 범인 집계
build_support_bundle	지원팀에 증거를 넘길 때(purpose:"support", 기본) 또는 임계값 보정에 기여할 때(purpose:"calibration")	support: dry_run=true(기본)는 포함 항목·누출 프로필 미리보기, dry_run=false로 zip 생성(파일별 SHA-256·누출 목록 동봉). calibration: 비식별 하드웨어 사실·신호 벡터만 화이트리스트로 추린 작은 보정 케이스(JSON) — 전송 없음, 사용자가 검토 후 선택 기여
drill_down	요약 너머 원본 레코드가 필요할 때	스트림별 원본 레코드(페이지 단위)
validate_report	리포트를 확정하기 직전(마지막)	초안 verdict(분류·신뢰도)를 새 수집으로 재도출한 결정론 신호와 대조해 valid·violations와 상한을 넘은 값의 클램프를 반환

리소스: playbook(진단 방법론), bugcheck-codes(코드에서 이름·원인), whea-section-guids(CPER section GUID에서 부품).

프롬프트: bsod-triage — 클라이언트에서 /bsod-triage로 노출됩니다.

임계값 보정 기여(선택). 결정론 신호의 임계값은 실데이터가 없어 보정되지 않았습니다(아래 알려진 제약). build_support_bundle의 purpose:"calibration"은 PII 표면을 화이트리스트로 최소화한 작은 신호 벡터(JSON)만 만들고 아무것도 전송하지 않습니다. 원하면 직접 검토한 뒤 Calibration case 이슈 폼에 붙여넣어 확인된 원인 라벨과 함께 기여할 수 있습니다 — 수신 워크플로가 누출 스캔·스키마 검증 후 사람 검토용 PR을 열며, 자동 머지는 없습니다.

사용법

/bsod-triage를 실행하면 다음 순서로 진행됩니다.

1. collect_crash_evidence로 증거를 수집합니다.
2. WHEA가 있으면 decode_whea, 최신 덤프가 있으면 analyze_minidump를 호출합니다.
3. playbook과 lookup 리소스를 근거로 의미를 해석합니다.
4. 사실과 추정을 분리하고, 신뢰도·증거 인용·단계별 권고를 담은 구조적 리포트 초안을 작성합니다.
5. 확정 직전 validate_report로 초안의 분류·신뢰도를 결정론 신호와 대조하고(상한 초과 시 클램프), 사용자 언어로 최종 리포트를 제출합니다.

알려진 제약

설계상·환경상의 제약입니다. 배경은 ARCHITECTURE.md를 참고하세요.

• analyze_minidump는 관리자 권한이 없으면 제한적입니다. C:\Windows\Minidump가 관리자 전용이라, 권한이 없으면 모듈·스택 분석 대신 상태값(unavailable_no_admin 등)과 권한 상승 복사 명령을 안내합니다. BugCheck 코드와 derived_signals.suspect_drivers(GPU TDR·CodeIntegrity 차단·최근 드라이버 변경을 교차참조한 무관리자 드라이버 용의자)는 collect_crash_evidence가 권한 없이 제공하므로, 스택 확정만 못 할 뿐 진단이 막히지는 않습니다.
• 결정론 신호의 임계값은 휴리스틱입니다. 레이블된 데이터셋이 없어 절대 기준은 보정되지 않았으며, confidence·evidence_basis·caveats와 크래시 게이팅으로 과신을 억제합니다. 지표는 참고용 사전확률로 보고 증거와 함께 해석하는 것이 좋습니다.
• collect_crash_evidence 출력은 세션 내에서 마스킹되지 않습니다. 분석에 필요하므로 PC명·드라이버명 등이 호스트로 그대로 전달됩니다. 외부 전달이 목적이라면 마스킹과 누출 목록을 제공하는 build_support_bundle을 사용하세요.

개발

npm install
npm run build        # tsc 컴파일, ps/resources를 dist로 복사, manifest 버전 stamp
npm run dev          # tsx watch
npm run lint         # eslint (src TS + 테스트/스크립트 mjs)
npm run inspect      # MCP Inspector로 수동 점검
npm test             # node 테스트(test/**/*.test.mjs 자동 디스커버리): signals / redact / util / tools / 서버 스모크
npm run test:ps      # Pester: CPER 디코더 골든 픽스처 (Windows)
npm run test:all     # node와 Pester
npm run schemas      # 도구 입력 스키마를 schemas/*.json 으로 export
npm run calibrate    # 신호 임계값 보정: 코퍼스 드리프트 점검 + 민감도 스윕

수집기는 PowerShell 자식 프로세스입니다(pwsh 7+ 우선, 없으면 powershell.exe 폴백). 모든 출력은 UTF-8 JSON으로 stdout에만 씁니다. CI는 ci.yml(windows-latest)에서 typecheck·lint·build·스키마 드리프트·node·Pester·.mcpb pack을 검증하고, v* 태그를 푸시하면 체크섬을 동봉한 .mcpb를 GitHub Release로 발행합니다. 기여 방법은 CONTRIBUTING.md를 참고하세요.

라이선스

MIT © HAENAM PARK

Windows 전용입니다(비-Windows에서는 각 도구가 명확한 메시지로 거부합니다). 크래시 자료에는 PII가 포함될 수 있으니 공유 전에 dry_run으로 확인하세요.