MFlowy 데이터 모델링 분석 워크플로우

MFlowy는 MCP-native 모듈형 ML 워크플로우 엔진입니다. DAG 기반 계층 실행과 구성 기반(configuration-driven) 방식을 지원하며, 데이터 처리부터 모델 학습, 시각화 분석에 이르는 추적 가능하고 이력 검증이 가능한 워크플로우를 지원합니다.

핵심 기능

• MCP-native: 모든 기능이 MCP 도구(pyfunc)로 노출되며, 동일한 도구 집합을 MCP server(stdio), JSON runner CLI(cmd), 직접 import(호스트 내장)의 세 가지 진입점으로 호출할 수 있습니다.

• DAG 워크플로우 오케스트레이션: 복잡한 방향성 비순환 그래프(DAG) 토폴로지 구조를 지원하여 작업 의존 관계를 유연하게 정의할 수 있습니다.

• 구성 기반(configuration-driven): YAML 구성 파일로 워크플로우를 정의하며 코드 작성이 필요하지 않습니다.

• 데코레이터 등록: 순수 함수 + @handler 데코레이터로 자동 등록되며, 새 기능은 .py 파일을 생성하기만 하면 됩니다.

• 미들웨어 시스템: 책임 연쇄 패턴으로 횡단 관심사(데이터 주입, mlflow 기록, 오류 발생 즉시 중지, 각종 로그)를 처리합니다.

• 데이터 계보(Data Lineage): MLflow tag(mflowy.input_steps)가 단계 간 입력 의존 관계를 자동으로 재기록합니다.

• 관측 가능한 실행: MLflow 전체 추적(파라미터/메트릭/모델/아티팩트) + 구조화된 WorkflowResult(노드별 run_id 및 상태,

행)을 제공합니다. 프로세스 로그는 stderr에 바인딩되며 터미널 모드에서는 레벨에 따라 색상이 놓입니다.

• 확장 가능한 실행 전략: JobProvider 계약이 compute 도구의 실행환경을 추상화하며, 로컬 구현이 내장되고 원격 실행은 사용자가 맞춤 구현으로 연결합니다. (docs/REMOTE_MODELING.md 참고)

Related MCP server: Procesio MCP Server

구조 및 호출 방식

MFlowy는 MCP를 아키텍처의 중심으로 사용합니다. mflowy/mcp/tools.py는 모든 compute 도구(eda / modeling / explanation / predict / inverse_optimization 등)를 정의하며 세 가지 진입점을 통해 호출합니다.

CLI(cmd)는 MCP 도구 레이어의 커뮤인드라인 채널로, MCP 서버와 동일한 도구 구현 및 JobProvider 관장을 공유하는 독립 아키텍처가 아닙니다. 기존의 독립 CLI(mflowy run/validate/list-modules 등)는 폐기되었습니다. 만약에

빠른 시작

# 构建 wheel（→ dist/mflowy-<version>-py3-none-any.whl）
make build-whl

# MCP server (stdio) — 完全体（数据分析 + 建模）；<whl> 为 wheel 绝对路径（见下方说明）
uvx --index-strategy unsafe-best-match \
    --default-index https://mirrors.aliyun.com/pypi/simple/ \
    --index https://download.pytorch.org/whl/cpu \
    --from "mflowy[modeling] @ file://<whl绝对路径>" \
    mcpSrv

# JSON runner（CLI）— 本地调试
uv run cmd list_modules                                       # 查看支持的步骤及模块列表（base，无数据栈）
uv run cmd list_modules '{"step":"load"}'                     # 查看 load 步骤的模块列表
uv run cmd get_module_info '{"step":"load","module":"csv"}'   # 查看 load 步骤的 csv 模块信息
uv run --extra stats cmd data_profile '{"file_path": "..."}'           # 数据分析工具
uv run --extra modeling cmd modeling '{"modeling_steps_yaml": "...", "name": "...", "desc": "..."}'  # 建模工具

환경 변수

MCP 클라이언트 구성 예

{
  "mcpServers": {
    "mflowy": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--index-strategy", "unsafe-best-match",  // torch CPU 索引必需（见下方说明）
        "--default-index", "https://mirrors.aliyun.com/pypi/simple/",  // 可选：包索引镜像（网络可达 PyPI 时省略）
        "--index", "https://download.pytorch.org/whl/cpu",  // [modeling] 需要；仅 [stats] 可省略
        "--from", "mflowy[modeling] @ file:///path/to/mflowy-<version>-py3-none-any.whl",
        "mcpSrv"
      ],
      "env": {
        // "PYTHONPATH": "/path/to/custom_module_parent",
        // "MFLOWY_JOB_PROVIDER": "<custom_module>:<class>",
        // "MLFLOW_TRACKING_URI": "postgresql://user:pwd@host:5432/mlflow"
      }
    }
  }
}

시작 참고 사항

• 진입점 이름 mcpSrv: mcp SDK가 기본 제공하는 동일 이름의 mcp CLI(mcp.cli:app)를 의도적으로 회피합니다. uvx가 mcp 명령을 열파싱할 때 SDK 쪽이 맞는 경우 시작 실패가 발생할 수 있습니다.

• extras는 --from 스펙에 인라인: uvx의 --extra는 uv 버전 요구가 있어 인라인 방식이 가장 호환성이 좋습니다.

• <whl>은 절대 절대경로: make build-whl 진행 시 dist/mflowy-<version>-py3-none-any.whl이 생성되며, 버전 번호 변경되면 함께 갱신해야 합니다.

• torch CPU 인덱스(--index pytorch-cpu + --index-strategy unsafe-best-match)는 [modeling]에 필수입니다. uvx는 pyproject의 [tool.uv.sources]를 로드하지 않으므로, 기본 설정 시 torch가 CUDA 번들(2–3GB)로 해석됩니다. unsafe-best-match는 pytorch 인덱스와 함께 사용해야 합니다. 그렇지 않으면 first-index 전략이 해당 인덱스의 구버전 requests 로 인해 해석에 실패합니다.

• 개발 상태에서는 wheel 생략 가능: 저장소 루트에 있는 .mcp.json.example은 소스 경로 형식으로 항상 최신입니다.

텔레메트리(Telemetry)

MCP 도구 호출 진단 수집이며, 동의제, 기본값은 ask입니다. 엔드포인트에 도달할 수 없는 경우에도 완전히 투명하며 도구 호출에는 영향이없고 MCP 진입점에만 한정됩니다. 개인정보 보호 계약은 PRIVACY.md, 연동 및 설정 상세는 docs/TELEMETRY.md를 참고하세요.

기여

어떤 형태의 기여(기능, 버그, 문서, 사례)도 환영합니다. CONTRIBUTING.md(개발 프로세스와 규약), CODE_OF_CONDUCT.md, PRIVACY.md(개인정보 및 텔레메트리 규약), SECURITY.md(취약성 소유)을 읽어 주세요.

라이선스

이 프로젝트는 MIT License를 기반으로 오픈소스로 제공됩니다.

문서

• 아키텍처 및 기여 가이드

• 아키텍처 결정 기록

• 연구 흐름 방법론

• 로드맵

• 원격 처리 연동

• 텔레메트리

• DAG 엔진 아키텍처