# Log Monitoring & MCP Server

에버다임 IT 인프라를 위한 **통합 로그 모니터링 및 MCP(Model Context Protocol) 서버** 프로젝트입니다.

Loki 기반 로그 수집·조회, Grafana 시각화, 메일 스팸 관리, 전자결재(EP) 문서 처리 등을 하나의 플랫폼에서 제공하며, MCP 프로토콜을 통해 AI 어시스턴트(Claude 등)와 직접 연동할 수 있습니다.

## 서비스 소개

- **로그 수집 및 조회** — Syslog-ng → Vector → Loki 파이프라인으로 인프라 로그를 수집하고, LogQL로 즉시 검색
- **보안 위협 모니터링** — AhnLab MDS/EPP/EDR 위험 로그를 실시간 수집·필터링
- **메일 스팸 관리** — 스팸 차단/해제 요청 조회, 메일 로그 검색, 스팸 판정 처리
- **전자결재 연동** — 문서 목록 조회, 승인/반려/취소 액션, 결재선 자동 반복 취소
- **Grafana 대시보드** — 사전 구성된 대시보드와 알림 규칙으로 인프라 상태 시각화
- **MCP 서버** — 12개 도구를 AI 어시스턴트에 노출하여 자연어로 운영 업무 수행

## 아키텍처

```
┌─────────────────────────────────────────────────────────────────┐
│                     Inbound Adapters                           │
│  HTTP (POST /rpc)  │  MCP JSON-RPC  │  Stdio Transport         │
└────────┬───────────┴───────┬────────┴───────────┬──────────────┘
         │                   │                    │
┌────────▼───────────────────▼────────────────────▼──────────────┐
│                   Application Layer                            │
│  McpApplicationService · ToolCatalogService (AJV 검증)         │
│                                                                │
│  12 Tool Usecases:                                             │
│   Loki (5) · Everdigm Mail (4) · Everdigm EP (2)              │
│   + everdigm_mail.mail_logs                                    │
└────────┬───────────────────┬────────────────────┬──────────────┘
         │                   │                    │
┌────────▼───────────────────▼────────────────────▼──────────────┐
│                   Outbound Adapters                            │
│  LokiClient        EverdigmMailClient       EverdigmEpClient  │
└────────┬───────────────────┬────────────────────┬──────────────┘
         ▼                   ▼                    ▼
      [Loki]          [Mail API/UI]          [EP System]
```

### 인프라 구성

```
┌──────────┐    ┌─────────┐    ┌──────┐    ┌─────────┐
│ Syslog-ng│───▶│ Vector  │───▶│ Loki │◀───│ Grafana │
│ :5514    │    │ :8686   │    │ :3100│    │ :3033   │
└──────────┘    └────┬────┘    └──────┘    └─────────┘
                     │
                     ▼
                ┌─────────┐    ┌─────────┐
                │ API     │    │ MCP     │
                │ :3031   │    │ :5000   │
                └─────────┘    └─────────┘
```

## MCP 도구 목록

### Loki 로그 조회 (5개)

| 도구 | 설명 |
|------|------|
| `loki_query` | LogQL 즉시 쿼리 |
| `loki_query_range` | 시간 범위 기반 LogQL 쿼리 |
| `loki_mds_risk_logs` | AhnLab MDS 위험 로그 조회 |
| `loki_epp_risk_logs` | AhnLab EPP 위험 로그 조회 |
| `loki_risk_detail_logs` | 서비스·IP·위험도별 유연한 필터링 |

### Everdigm 메일 관리 (4개)

| 도구 | 설명 |
|------|------|
| `everdigm_mail_unspam_requests` | 스팸 해제 요청 목록 |
| `everdigm_mail_spam_detail` | 스팸 메일 상세 정보 |
| `everdigm_mail_spam_action` | 스팸 판정 처리 (통과/거부/신규) |
| `everdigm_mail_logs` | 메일 송수신 로그 검색 |

### Everdigm 전자결재 (2개)

| 도구 | 설명 |
|------|------|
| `everdigm_ep_documents` | 문서 목록 조회 (결재선 정보 포함) |
| `everdigm_ep_document_action` | 문서 승인/반려/취소 (자동 반복 취소 지원) |

## 기술 스택

| 분류 | 기술 |
|------|------|
| Runtime | ![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white) ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white) |
| Framework | ![NestJS](https://img.shields.io/badge/NestJS-E0234E?style=flat&logo=nestjs&logoColor=white) |
| 로그 수집 | ![Grafana Loki](https://img.shields.io/badge/Loki-F46800?style=flat&logo=grafana&logoColor=white) ![Vector](https://img.shields.io/badge/Vector-000000?style=flat&logoColor=white) ![Syslog-ng](https://img.shields.io/badge/syslog--ng-333333?style=flat&logoColor=white) |
| 시각화 | ![Grafana](https://img.shields.io/badge/Grafana-F46800?style=flat&logo=grafana&logoColor=white) |
| 컨테이너 | ![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat&logo=docker&logoColor=white) |
| 프로토콜 | MCP (Model Context Protocol) · JSON-RPC 2.0 |

## 폴더 구조

```
log_monitoring/
├── apps/
│   ├── mcp/                        # MCP 서버 (Model Context Protocol)
│   │   └── src/
│   │       ├── main.ts             # 진입점 (HTTP/stdio 전환)
│   │       ├── application/        # 애플리케이션 레이어
│   │       │   ├── mcp/            # MCP 서비스 (도구 목록, 호출)
│   │       │   └── tools/          # 12개 유스케이스
│   │       ├── inbound/            # 인바운드 어댑터
│   │       │   ├── http/           # HTTP RPC 컨트롤러
│   │       │   ├── mcp/            # MCP 요청 핸들러
│   │       │   └── stdio/          # Stdio 전송
│   │       ├── outbound/           # 아웃바운드 어댑터
│   │       │   ├── loki/           # Loki API 클라이언트
│   │       │   ├── everdigm-mail/  # 메일 API 클라이언트
│   │       │   └── everdigm-ep/    # 전자결재 API 클라이언트
│   │       └── shared/             # 공유 타입 정의
│   │
│   └── api/                        # REST API 서버
│       └── src/
│           ├── main.ts             # 진입점 (포트 3001)
│           ├── grafana/            # Grafana/Zabbix 프록시
│           ├── everdigm-mail/      # 메일 관리 모듈
│           ├── everdigm-ep/        # 전자결재 모듈
│           ├── webhooks/           # 웹훅 핸들러
│           └── common/             # 공통 유틸리티
│
├── infra/                          # 인프라 설정
│   ├── loki/                       # Loki 서버 설정
│   ├── vector/                     # 로그 포워딩 설정
│   ├── grafana/                    # Grafana 프로비저닝
│   │   ├── provisioning/           # 데이터소스·대시보드·알림
│   │   └── dashboards/             # 대시보드 JSON
│   └── syslog/                     # Syslog-ng 설정
│
├── docker-compose.yml              # 전체 스택 (6개 서비스)
├── .env.example                    # 환경변수 템플릿
└── AGENTS.md                       # 코딩 에이전트 워크플로우 규칙
```

## 시작하기

### 사전 요구사항

- Docker & Docker Compose
- Node.js 18+ (로컬 개발 시)

### 설치 및 실행

```bash
# 1. 저장소 클론
git clone <repository-url>
cd log_monitoring

# 2. 환경변수 설정
cp .env.example .env
# .env 파일을 편집하여 필요한 값 입력

# 3. Docker Compose로 전체 스택 실행
docker compose up -d

# 4. 서비스 상태 확인
docker compose ps
```

### 서비스 접속 정보

| 서비스 | URL | 설명 |
|--------|-----|------|
| MCP Server | `http://localhost:5000/rpc` | MCP JSON-RPC 엔드포인트 |
| API Server | `http://localhost:3031` | REST API |
| Grafana | `http://localhost:3033` | 대시보드 |
| Loki | `http://localhost:3100` | 로그 API (내부용) |

### 로컬 개발 (MCP 서버)

```bash
cd apps/mcp
npm install
npm run start:dev    # ts-node로 실행
```

### Claude Code 연동

`claude_desktop_config.json` 또는 `.claude/settings.local.json`에 MCP 서버를 등록합니다:

```json
{
  "mcpServers": {
    "log-mcp-server": {
      "url": "http://localhost:5000/rpc"
    }
  }
}
```

## 환경변수

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `MCP_TRANSPORT` | `http` | 전송 모드 (`http` / `stdio` / `both`) |
| `MCP_PORT` | `5000` | MCP 서버 포트 |
| `LOKI_BASE_URL` | `http://loki:3100` | Loki API 주소 |
| `LOKI_TENANT_ID` | - | Loki 멀티테넌트 ID |
| `LOKI_BEARER_TOKEN` | - | Loki 인증 토큰 |
| `EVERDIGM_MAIL_BASE_URL` | - | 메일 시스템 URL |
| `EVERDIGM_MAIL_API_BASE_URL` | `http://api:3001` | 메일 API URL |
| `EVERDIGM_EP_BASE_URL` | - | 전자결재 시스템 URL |
| `GRAFANA_BASE_URL` | - | Grafana URL |
| `GF_SECURITY_ADMIN_PASSWORD` | - | Grafana 관리자 비밀번호 |