MFlowy 数据建模分析工作流

MFlowy 是一个 MCP-native 的模块化 ML 工作流引擎：基于 DAG 分层执行，配置驱动，支持从数据处理、模型训练到可视化分析的可跟踪、可追溯工作流。

核心特性

• MCP-native：全部能力以 MCP 工具（pyfunc）暴露，同一套工具经三种入口调用——MCP server（stdio）、JSON runner CLI（cmd）、直接 import（宿主内嵌）
• DAG 工作流编排：支持复杂的有向无环图（DAG）拓扑结构，灵活定义任务依赖关系
• 配置驱动：通过 YAML 配置文件定义工作流，无需编写代码
• 装饰器注册：纯函数 + @handler 装饰器自动注册，新增功能只需创建 .py 文件
• 中间件系统：责任链模式处理横切关注点（数据注入、mlflow 记录、错误即停、各类日志）
• 数据血缘：MLflow tag（mflowy.input_steps）自动记录步骤间输入依赖
• 可观测执行：MLflow 全量追踪（参数/指标/模型/产物）+ 结构化 WorkflowResult（逐节点 run_id/状态/输出）；过程日志绑定 stderr，终端模式下按级别着色
• 可扩展执行策略：JobProvider 契约抽象 compute 工具的执行环境，内置本地实现，远程执行由自定义实现接入（见 docs/REMOTE_MODELING.md）

架构与调用方式

MFlowy 以 MCP 为架构主体：src/mflowy/mcp/tools.py 定义全部 compute 工具（eda / modeling / explanation / predict / inverse_optimization 等），经三种入口调用：

入口	命令	场景
MCP server（stdio）	mcpSrv	MCP 客户端（Claude Code、Cursor 等）接入
JSON runner（CLI）	cmd <tool> '<json args>'	命令行、K8s Job 容器、subprocess
直接 import	mflowy.mcp.tools pyfunc	宿主程序内嵌调用

CLI（cmd）是 MCP 工具层的命令行通道，与 MCP server 共享同一套工具实现与 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": "..."}'  # 建模工具

环境变量

变量	用途	示例
MLFLOW_TRACKING_URI	Tracking server URI（未设置时 workflow 与查询工具同落固定库 ~/.mflowy/mlflow.db）	postgresql://user:pwd@host:5432/mlflow
MFLOWY_JOB_PROVIDER	JobProvider 解析：local（默认）或 module:Class（自定义实现）	my_pkg.job_provider:MyRemoteProvider
PYTHONPATH	自定义 JobProvider 模块的包根	/srv/my-provider
MFLOWY_TELEMETRY	遥测模式：ask（默认，首次工具调用时询问）/ on / off（显式设置覆盖 settings.json，见下方「遥测」）	on

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 spec：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 引擎架构