DataMineAna

数学建模 MCP 工具包 -- 为大模型/Agent 提供数据预处理、数据分析、数学建模、数据可视化能力。

架构

+-----------------------------------------------+
|            Modeling Skill (上层)               |
+-----------------------------------------------+
|         MCP Client (中层)                      |
|    - 与大模型交互                              |
|    - 智能文档传递（先常用，再全量）            |
|    - 工具调用解析与转发                        |
+-----------------------------------------------+
|         MCP Server (底层)                      |
|    - 工具注册与分发（37 个工具）               |
|    - 数据预处理（38 个方法）                   |
|    - 数据分析（29 个方法）                     |
|    - 数学建模（47 个方法）                     |
|    - 数据可视化（10 种图表）                   |
|    - 高级扩展（动态方法创建）                  |
|    - 数据档案追踪（核心）                      |
|    - 缓存管理                                  |
+-----------------------------------------------+
|         UI Module (可选)                       |
|    - 交互式数据建模工作台                      |
|    - 逐步向导：加载->预处理->分析->可视化->建模->报告 |
|    - Gradio Web UI                             |
|    - 基于 MCP Server（非直接调用）             |
+-----------------------------------------------+

核心特性

插件化方法架构

每个方法类继承 BaseMethod，通过 MethodLoader 加载和执行。方法类不对外暴露，仅通过 Interface 访问。

module/
  methods/           # 方法类（隐藏）
    cleaning.py      # 相关方法分组
    transformation.py
  loader.py          # MethodLoader 子类（注册所有方法）
  interface.py       # 公开接口（集成 tracker）

数据档案追踪系统（核心）

• 每次函数调用前后自动记录输入/输出信息
• 维护全局数据档案（形状、列、类型、缺失值、统计量、列详情）
• 从数据加载到建模结束全程追踪
• get_pipeline_report 生成完整调用步骤（用于写论文）

智能文档传递

1. 初始传递：MCP_USAGE.md + COMMON_API.md（20 个常用工具）
2. 按需传递：FULL_API.md（37 个工具 + 114 个方法）

return_mode 控制返回

每个工具支持 return_mode 参数控制返回内容：

• summary（默认）、full、data、head、tail、sample、path

动态方法扩展

• 高级扩展：通过 create_method 传入 Python 代码字符串，动态创建新方法
• 外部扩展：在 src/advanced/methods/ 或 cache/advanced/ 放入方法类文件，自动加载
• UI 自定义：UI 用户也可以在界面编写自定义方法

数据可视化

• 10 种图表类型：分布图、箱线图、散点图、热力图、混淆矩阵、ROC 曲线等
• 支持前后对比（处理前 vs 处理后）
• 图片自动保存到 cache/plotting/

目录结构

DataMineAna/
  src/
    common/              # 公共函数库
      base_method.py     # 方法基类（ParameterDef 支持 UI 自动表单）
      method_loader.py   # 方法加载器
      types.py           # 类型定义
      validators.py      # 参数校验
      json_utils.py      # JSON 工具
    tracker/             # 数据档案与追踪系统（核心）
      data_profile.py    # 数据档案
      profile_manager.py # 档案管理器
      call_tracker.py    # 调用追踪器
    cache_manager/       # 缓存管理
    preprocessing/       # 数据预处理（38 个方法）
    analysis/            # 数据分析（29 个方法）
    modeling/            # 数学建模（47 个方法）
    plotting/            # 数据可视化（10 种图表）
      plotter.py         # 核心绘图引擎
      interface.py       # 可视化接口
    advanced/            # 高级扩展
      loader.py          # 动态方法加载器
      template.py        # 扩展模板
      methods/           # 内置扩展方法
    mcp_server/          # MCP Server（底层接口）
    mcp_client/          # MCP Client（中层）
    ui/                  # 交互式 UI 模块
      app.py             # Gradio 主应用
      state.py           # 会话状态（基于 MCP Server）
      pages/
        page_load.py     # 1. 数据加载
        page_preprocess.py # 2. 数据预处理
        page_analysis.py # 3. 数据分析
        page_plot.py     # 4. 数据可视化
        page_model.py    # 5. 模型构建
        page_report.py   # 6. 流水线报告
        components.py    # 共享 UI 组件
  cache/                 # 临时文件目录
    preprocessing/       # 预处理临时文件
    analysis/            # 分析临时文件
    modeling/            # 建模临时文件
    plotting/            # 图表临时文件
    advanced/            # 动态方法文件
    tracker/             # 追踪临时文件
    ui/                  # UI 临时文件
  docs/                  # 文档
  test.py               # 集成测试（20 个测试）
  run_ui.py             # UI 启动入口

快速开始

MCP Server（供 Agent 使用）

from src.mcp_server import MCPServer

server = MCPServer()

# 加载数据
r = server.call_tool("load_data", path="data.csv")

# 数据清洗
r = server.call_tool("clean_data", dataset_id="ds_xxx", missing_strategy="mean")

# 数据可视化
r = server.call_tool("plot_distribution", dataset_id="ds_xxx")
r = server.call_tool("plot_box", dataset_id="ds_xxx")

# 建模
r = server.call_tool("regression", dataset_id="ds_xxx", target_column="y")

# 获取完整报告
r = server.call_tool("get_pipeline_report")

交互式 UI（供人类使用）

python run_ui.py              # 默认端口 7860
python run_ui.py --port 8080  # 自定义端口
python run_ui.py --no-open    # 不自动打开浏览器

UI 工作流：

1. Load Data - 上传数据文件
2. Preprocess - 清洗、变换、降维、拆分
3. Analyze - 描述统计、相关性、分布、假设检验
4. Visualize - 分布图、箱线图、散点图、热力图、前后对比
5. Model - 回归/分类/聚类/交叉验证/网格搜索
6. Report - 生成完整流水线报告

方法数量统计

模块	方法数	工具数
数据预处理	38	9
数据分析	29	6
数学建模	47	8
数据可视化	10	6
高级扩展	动态	2
系统工具	-	6
合计	124+	37

扩展方法

方式 1：继承 BaseMethod

from src.common.base_method import BaseMethod, MethodResult, ParameterDef

class MyMethod(BaseMethod):
    @property
    def name(self): return "my_method"
    @property
    def description(self): return "My custom method"
    @property
    def category(self): return "custom"
    @property
    def parameters(self):
        return [
            ParameterDef(name="threshold", type="float", default=0.5, description="Threshold value"),
        ]

    def execute(self, df, **kwargs):
        threshold = kwargs.get("threshold", 0.5)
        # your logic here
        return MethodResult(df=df, success=True, message="done")

方式 2：动态创建（通过 MCP）

server.call_tool("create_method", code='''
class MyMethod(BaseMethod):
    @property
    def name(self): return "my_method"
    @property
    def description(self): return "My custom method"
    def execute(self, df, **kwargs):
        return MethodResult(df=df, success=True, message="done")
''', module="preprocessing")

方式 3：放入高级扩展目录

将方法文件放入 src/advanced/methods/（持久化）或 cache/advanced/（临时），自动加载。

依赖

• Python >= 3.10
• pandas >= 2.0
• numpy >= 1.24
• scikit-learn >= 1.3
• scipy >= 1.11
• matplotlib >= 3.7
• seaborn >= 0.12
• gradio >= 4.0 (UI 模块)

许可证

MIT License