incident-mcp
Enables incident detection and analysis by identifying anomalies in metric time series and surfacing root-cause candidates and recommended actions. Supports both mock (synthetic) and VictoriaMetrics backends with identical MCP tool contracts for seamless development-to-production switching.
README
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
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
Neon Database
MCP server for interacting with Neon Management API and databases
E2B
Using MCP to run code via e2b.
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.