KETI FLOW MCP

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

구조

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

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

설치

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

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

데이터

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

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

data/blower/fan_training.csv
data/pump/pump_training.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: 제어값별 학습 유량 범위를 엄격히 적용할지 여부

실행

uv run python main.py

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

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

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

MCP Tools

get_optimal_blower_angle

입력:

{
  "required_flow": 500.0
}

응답 예:

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

범위 밖 응답 예:

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

get_optimal_pump_control

입력:

{
  "required_flow": 5.0
}

get_training_status

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

Codex 등록 예시

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

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

Claude 등록 예시

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

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

로컬 검증

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

간단한 smoke 검증:

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

송풍기 예측 확인:

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

git 추적 제외

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

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