# 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` | 탐지→분석 원스텝 (근본원인 후보 + 권장조치) |

---

## 빠른 시작

```bash
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 — 설치와 실행](docs/step1-install.md)
- [step2 — 이상탐지 알고리즘](docs/step2-detection.md)
- [step3 — Mock 백엔드와 시나리오](docs/step3-mock-backend.md)
- [step4 — VictoriaMetrics 실연동](docs/step4-victoriametrics.md)
- [step5 — Claude Desktop / Hermes 등록](docs/step5-mcp-clients.md)

---

## 이상탐지 방법 (요약)

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

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

## 라이선스

MIT