incident-mcp

**인시던트 발견(detection) → 분석(analysis)**을 돕는 Python MCP(Model Context Protocol) 서버입니다. 메트릭 시계열에서 이상 징후를 탐지하고, 상관 관계를 묶어 근본원인 후보와 권장 조치까지 제시합니다.

하나의 도구 계약(tool contract)을 두 개의 백엔드가 공유합니다:

서버	백엔드	용도
mock-incident-mcp	내장 합성 데이터 (결정론)	VM 없이 개발·데모·회귀테스트
vm-incident-mcp	실제 VictoriaMetrics HTTP API	운영/실측 인시던트 분석

두 서버의 도구 시그니처가 100% 동일하므로, mock으로 워크플로를 개발한 뒤 무중단으로 실제 VM 전환이 됩니다.

---

아키텍처

incident_mcp/
├── core/                    # 백엔드 무관 공통 로직 (순수 함수 → 테스트 용이)
│   ├── models.py            # Pydantic: Anomaly, IncidentAnalysis, Series ...
│   ├── datasource.py        # Protocol(인터페이스) — VM/Mock이 구현
│   ├── detection.py         # 이상탐지: zscore · spike · trend · threshold
│   └── analysis.py          # 상관분석 + 근본원인 휴리스틱
├── datasources/
│   ├── mock_ds.py           # 재현 가능한 합성 메트릭 + 주입된 인시던트 시나리오
│   └── vm_ds.py             # VictoriaMetrics(Prometheus 호환) HTTP 클라이언트
├── servers/
│   ├── mock_server.py       # B: mock 데이터소스 주입
│   └── vm_server.py         # A: VictoriaMetrics 데이터소스 주입
└── tools.py                 # 공통 MCP 도구 4종 (두 서버가 공유)

MCP 도구 4종

도구	설명
list_metrics	사용 가능한 메트릭 카탈로그
fetch_series	원시 시계열 조회 (확인/디버깅)
detect_anomalies	이상탐지 실행 (zscore/spike/trend)
analyze_incident	탐지→분석 원스텝 (근본원인 후보 + 권장조치)

---

빠른 시작

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 단위 테스트
pytest -q

# mock 서버로 종단(E2E) 데모 — mock 2개 시나리오 + 실제 VM
python examples/e2e_client.py

---

문서 (단계별)

• step1 — 설치와 실행
• step2 — 이상탐지 알고리즘
• step3 — Mock 백엔드와 시나리오
• step4 — VictoriaMetrics 실연동
• step5 — Claude Desktop / Hermes 등록

---

이상탐지 방법 (요약)

방법	잡는 패턴	예시 인시던트
zscore	평균에서 크게 벗어난 순간값	순간 스파이크
spike	직전 구간 대비 급격한 변화율	에러율 급증
trend	완만한 단조 증가/감소	메모리 누수 (zscore/spike로는 안 잡힘)
threshold	절대 임계치 위반	SLA 한계 초과

💡 메모리 누수처럼 "서서히 새는" 패턴은 순간값 기반(zscore/spike)으로는 탐지되지 않아 회귀 기울기 기반 trend 탐지기를 별도로 두었습니다. — step2 참고

라이선스

MIT