# KETI FLOW MCP

송풍기/펌프 운전점 데이터를 서버 시작 시마다 학습하고, 에이전트가 MCP tool로 최적 제어값을 조회할 수 있게 하는 독립 MCP 서버입니다.

## 구조

```text
KETI_FLOW_MCP/
├─ src/
│  ├─ train/
│  ├─ mcp_server/
│  └─ utils/
├─ data/
├─ tests/
├─ config/
│  └─ config.json
├─ main.py
├─ pyproject.toml
├─ uv.lock
├─ README.md
└─ .gitignore
```

`src/mcp/`는 Python MCP SDK의 `mcp` 패키지명과 충돌할 수 있어 사용하지 않습니다.

## 설치

```powershell
cd C:\Users\keti\workspace\KETI_FLOW_MCP
uv sync
```

가상환경은 `.venv/`에 생성됩니다.

## 데이터

학습 데이터는 `data/` 아래에 둡니다. 이 폴더는 기밀 데이터 위치이므로 git에서 추적하지 않습니다.

기본 설정은 다음 파일을 사용합니다.

```text
data/blower/fan_training.csv
data/pump/pump_training.csv
```

기본 CSV 컬럼은 다음과 같습니다.

```csv
Flowrate,Head,Power,Angle,Speed
```

현재 MCP tool은 요구 유량 `Flowrate`를 입력받아 `Power`가 최소가 되는 `Angle` 값을 찾습니다.

## 설정

설정 파일은 `config/config.json`입니다.

주요 항목:

- `data.base_dir`: 학습 데이터 기준 폴더
- `machines.<name>.data_file`: 장비별 CSV 경로
- `flow_column`: 유량 컬럼
- `control_column`: 최적화할 제어값 컬럼
- `target_column`: 최소화 또는 최대화할 목표 컬럼
- `optimization`: `minimize` 또는 `maximize`
- `candidate_count`: 실시간 탐색 후보 개수
- `respect_control_flow_range`: 제어값별 학습 유량 범위를 엄격히 적용할지 여부

## 실행

```powershell
uv run python main.py
```

서버는 실행 시 다음 순서로 동작합니다.

1. `config/config.json` 로딩
2. `data/`의 CSV 로딩
3. 송풍기/펌프 모델 메모리 학습
4. MCP stdio 서버 시작

모델 파일과 LUT 파일은 생성하지 않습니다.

## MCP Tools

### `get_optimal_blower_angle`

입력:

```json
{
  "required_flow": 500.0
}
```

응답 예:

```text
해당 유량에서 적절한 각도 제어 값은 49 입니다. 예측 Power: 2.739 kW
```

범위 밖 응답 예:

```text
해당 유량은 학습 데이터 범위 내 값이 아닙니다. 지원 범위: 500 ~ 900
```

### `get_optimal_pump_control`

입력:

```json
{
  "required_flow": 5.0
}
```

## MCP Resources

### `keti-flow://training-status`

현재 서버 프로세스에 학습된 모델 상태, 데이터 파일, 행 수, 유량 범위를 반환합니다.

## Codex 등록 예시

Codex MCP 설정에서 다음 형태로 등록합니다.

```json
{
  "mcpServers": {
    "keti-flow": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\keti\\workspace\\KETI_FLOW_MCP",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

## Claude 등록 예시

Claude Desktop 설정 파일의 `mcpServers`에 다음 항목을 추가합니다.

```json
{
  "mcpServers": {
    "keti-flow": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\keti\\workspace\\KETI_FLOW_MCP",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

## 로컬 검증

`tests/`는 로컬 검증용 폴더이며 git에서 추적하지 않습니다.

간단한 smoke 검증:

```powershell
uv run python -c "from src.mcp_server.server import build_runtime; r=build_runtime(); print(r.status())"
```

송풍기 예측 확인:

```powershell
uv run python -c "from src.mcp_server.server import build_runtime, optimal_control_text; r=build_runtime(); print(optimal_control_text(r, 'blower', 500))"
```

## git 추적 제외

다음 항목은 git에 포함하지 않습니다.

- `data/`
- `tests/`
- `.venv/`
- 모델 산출물 파일
- 로그와 로컬 출력물