# 명화공업 보전일보 MCP 서버

설비 보전 일보을 기반으로 **상황 파악 · 분석**을 지원하는 MCP (Model Context Protocol) 서버
Node.js / Express / TypeScript / MSSQL 기반 / StreamableHTTP(MCP) 방식

---

## 기술 스택

| 항목 | 버전 |
|------|------|
| Node.js | v22 이상 |
| TypeScript | 5.x |
| Express | 5.x |
| MSSQL | mssql v11 |
| MCP SDK | @modelcontextprotocol/sdk |
| Logger | pino + pino-pretty |
| 스키마 검증 | zod |

---

## 프로젝트 구조

```
src/
├── index.ts                          # 진입점
├── server/
│   └── McpServer.ts                  # MyunghwaMcpServer (StreamableHTTP MCP 서버)
├── database/
│   └── DatabaseManager.ts            # MSSQL 연결 풀 
├── logger/
│   └── Logger.ts                     # Pino 로거 
├── repositories/
│   ├── BaseRepository.ts            # 공통 쿼리 실행 (SQL Injection 방지)
│   ├── EquipTroubleRepository.ts    # 보전 일보 검색 · 상세 · 이력 · 주기 쿼리
│   ├── TroubleCountRepository.ts    # 고장 발생 빈도 집계 쿼리
│   ├── TroubleCauseRepository.ts    # 고장 원인 TOP N 쿼리
│   └── AnalysisRepository.ts        # MTBF · 수리비용 분석 쿼리
└── tools/
    ├── BaseTool.ts                   # McpTool 인터페이스 · 공통 스키마 · 헬퍼
    ├── ToolRegistry.ts               # 툴 인스턴스 등록 목록
    ├── EquipTroubleTool.ts           # 1. 사업장 목록 · 일보 검색
    ├── EquipTroubleDetailTool.ts     # 2. 설비 고장 상세 · 이력 · 주기
    ├── TroubleCountTool.ts           # 3. 고장 발생 빈도
    ├── TroubleCauseTool.ts           # 4. 고장 원인 TOP N
    └── AnalysisTools.ts              # 추가 기능 (MTBF · 수리비용)
scripts/
├── _helpers.ts                       # 공통 헬퍼
├── test-query-search.ts              # 보전 일보 검색 쿼리 테스트
├── test-query-detail.ts              # 설비 고장 상세 쿼리 테스트
├── test-query-count.ts               # 고장 빈도 쿼리 테스트
├── test-query-cause.ts               # 고장 원인 쿼리 테스트
└── test-query-analysis.ts            # MTBF · 수리비용 분석 쿼리 테스트
```

---

## 환경변수 설정

`.env.example`을 복사하여 `.env` 파일을 생성하고 DB 접속 정보를 입력합니다.

```bash
cp .env.example .env
```

| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `HOST` | 서버 호스트 | `0.0.0.0` |
| `PORT` | 서버 포트 | `3000` |
| `TOKEN` | Bearer 토큰 인증 (미설정 시 인증 비활성화) | - |
| `DB_HOST` | MSSQL 서버 주소 | `localhost` |
| `DB_PORT` | MSSQL 포트 | `1433` |
| `DB_NAME` | 데이터베이스 이름 | - |
| `DB_USER` | DB 사용자 | - |
| `DB_PASSWORD` | DB 비밀번호 | - |
| `LOG_LEVEL` | 로그 레벨 (trace/debug/info/warn/error) | `info` |

> `LOG_LEVEL=debug` 설정 시 실행된 SQL 쿼리와 결과 건수가 로그에 출력됩니다.

---

## 실행 방법

### 1. 의존성 설치

```bash
npm install
```

### 2. 빌드

```bash
npm run build
```

### 3. 서버 시작

```bash
# 프로덕션
npm start

# 개발 모드 (코드 변경 시 자동 재시작)
npm run dev
```

---

## 쿼리 테스트

DB 연결 및 각 쿼리를 서버 없이 단독으로 테스트할 수 있습니다.

```bash
# 기능별 스크립트를 직접 실행 (상단 TEST 파라미터를 실제 값으로 수정 후 실행)
npx tsx scripts/test-query-search.ts    # 보전 일보 검색
npx tsx scripts/test-query-detail.ts    # 설비 고장 상세/이력/주기
npx tsx scripts/test-query-count.ts     # 고장 발생 빈도
npx tsx scripts/test-query-cause.ts     # 고장 원인 TOP N
npx tsx scripts/test-query-analysis.ts  # MTBF · 수리비용 분석
```

---

## 지원 툴 목록

### 1. 보전 일보 검색

| 툴명 | 설명 |
|------|------|
| `plant_list` | 등록된 사업장(플랜트) 코드와 명칭 목록 조회 |
| `equip_list` | 설비명으로 설비 코드(equipId)와 사업장 코드 검색 |
| `ban_list` | 사업장별 공장(fac) 및 반(ban) 정보 조회 |
| `line_group_list` | 사업장별 라인 그룹(workShopGroupId) 목록 조회 |
| `equip_trouble_list` | 기간·사업장·설비·라인·고장계통·부품·현상·원인 등 다중 조건 검색 |

---

### 2. 설비 고장

| 툴명 | 설명 |
|------|------|
| `equip_trouble_detail` | 특정 고장 이력의 상세 내역 (보전 작업 내용 포함) |
| `equip_trouble_history` | 특정 설비의 고장 이력 목록 |
| `equip_trouble_cycle` | 동일 계통/부품 고장 발생 주기 분석 |

---

### 3. 고장 발생 빈도

| 툴명 | 설명 |
|------|------|
| `trouble_count_by_werks` | 플랜트(사업장)별 고장 건수 및 총/평균 수리 시간 |
| `trouble_count_by_equip` | 설비별 고장 건수 및 총/평균 수리 시간 |
| `trouble_count_by_work_shop` | 라인별 고장 건수 및 총/평균 수리 시간 |
| `trouble_count_by_make_supplier` | 제조사별 고장 건수 (제조사 신뢰성 분석) |
| `trouble_count_by_equip_age` | 설비 설치년도별 고장 건수 (노후화 분석) |
| `trouble_count_by_part` | 부품별 고장 건수 및 총/평균 수리 시간 |

---

### 4. 고장 원인

| 툴명 | 설명 |
|------|------|
| `top_trouble_reason` | 설비별 주요 고장 원인 TOP N |

---

## 인증

Bearer 토큰 인증을 사용합니다. `TOKEN` 환경변수 미설정 시 인증 없이 실행됩니다.

```
Authorization: Bearer your-token-here
```

---

## AI 클라이언트 연결

- [배포하기](https://docs.cloudtype.io/guide/welcome/intro)

- [MCP 연결하기](https://docs.getporter.ai/ko/mcp)

---