mcp-data-analysis

---

name: mcp-data-analysis description: Complete data analysis workflow including EDA, Table One, descriptive statistics, and correlation analysis using MCP AutoML tools. Use when analyzing CSV data, exploring datasets, generating summary statistics, or creating publication-ready Table One reports. Triggers: 分析資料, analyze data, EDA, 探索資料, 資料分析, describe data, 資料探索, 基本統計, summary statistics, Table One, 敘述統計, 看看資料, 快速分析, quick analysis, 分析一下, 幫我分析.

MCP Data Analysis 技能 (資料分析流程)

描述

使用 MCP 工具進行完整資料分析的標準流程，支援自動路徑轉換和智能工具選擇。

觸發條件

• 「分析這個資料」「分析 {dataset}」
• 「EDA」「探索資料」「資料分析」
• 「看看這個資料」「資料概覽」
• 「快速分析」「分析一下」「幫我分析」

---

🔄 路徑自動轉換（重要！）

黃金規則：MCP csv_path 永遠用 /data/ 開頭

使用者輸入	自動轉換為
iris.csv	/data/sample_data/iris.csv
sample_data/medical.csv	/data/sample_data/medical.csv
projects/study1/data.csv	/data/projects/study1/data.csv
/home/eric/.../sample_data/xxx.csv	/data/sample_data/xxx.csv
/home/eric/.../projects/study1/data.csv	/data/projects/study1/data.csv
uploads/my_data.csv	/data/uploads/my_data.csv

轉換邏輯：

def convert_to_container_path(user_path: str) -> str:
    """將任意路徑轉為 Container 路徑"""
    # 1. 已經是正確格式
    if user_path.startswith("/data/"):
        return user_path

    # 2. 只有檔名 → 預設 sample_data
    if "/" not in user_path:
        return f"/data/sample_data/{user_path}"

    # 3. 包含 projects → 保持專案結構
    if "projects" in user_path:
        return f"/data/projects/{user_path.split('projects/')[-1]}"

    # 4. 包含 sample_data
    if "sample_data" in user_path:
        return f"/data/sample_data/{user_path.split('sample_data/')[-1]}"

    # 5. 包含 uploads
    if "uploads" in user_path:
        return f"/data/uploads/{user_path.split('uploads/')[-1]}"

    # 6. Host 絕對路徑（無法判斷歸屬）→ 提示用戶確認
    if "/home/" in user_path:
        filename = os.path.basename(user_path)
        # 預設放 sample_data，但應提示用戶確認
        return f"/data/sample_data/{filename}"

    # 7. 預設
    return f"/data/sample_data/{user_path}"

⚠️ 注意： Host 路徑 /home/eric/... 如果沒有 projects/ 或 sample_data/ 關鍵字，會預設放到 sample_data，建議用戶明確指定目標位置。

---

🎯 分析流程總覽

┌─────────────────────────────────────────────────────────────────────┐
│                    Data Analysis Workflow                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   [1] 確認資料        →  list_available_files / direct_preview_data │
│         ↓                                                           │
│   [2] 快速統計        →  get_quick_stats / get_column_info          │
│         ↓                                                           │
│   [3] 深入分析        →  auto_analyze / generate_tableone_directly  │
│         ↓                                                           │
│   [4] 特定分析        →  compare_groups / analyze_correlations      │
│         ↓                                                           │
│   [5] 結果儲存        →  結果自動存到 Redis + MinIO                  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

📋 Step 1: 確認資料來源

1.1 列出可用檔案

# 使用 MCP 工具列出檔案
mcp_automl_list_available_files(
    directory="/data/sample_data"  # 或 "/data/projects"
)

常用資料目錄：

路徑	說明
/data/sample_data/	範例資料集
/data/projects/{project}/	使用者專案資料

1.2 預覽資料

# 預覽前幾行
mcp_automl_direct_preview_data(
    csv_path="/data/sample_data/iris.csv",
    n_rows=10
)

1.3 取得欄位資訊

# 取得欄位類型、缺失值等資訊
mcp_automl_get_column_info(
    csv_path="/data/sample_data/heart_disease.csv"
)

---

📋 Step 2: 快速統計

2.1 快速統計摘要

mcp_automl_get_quick_stats(
    csv_path="/data/sample_data/titanic.csv"
)

輸出包含：

• 總筆數、欄位數
• 各欄位類型
• 缺失值統計
• 數值欄位基本統計

2.2 檢查缺失值

mcp_automl_analyze_missing_values(
    csv_path="/data/sample_data/titanic.csv"
)

---

📋 Step 3: 深入分析

3.1 智能自動分析（推薦！）

# 系統自動判斷資料類型並執行適合的分析
mcp_automl_auto_analyze(
    csv_path="/data/sample_data/heart_disease.csv",
    target_column="target",  # 可選：指定目標欄位
    user_id="eric"
)

3.2 生成 Table One（臨床研究必備）

mcp_automl_generate_tableone_directly(
    csv_path="/data/sample_data/medical_study_200.csv",
    group_column="treatment",     # 分組欄位
    columns=["age", "gender", "bmi", "outcome"],  # 可選
    categorical=["gender"],       # 類別變數
    pval=True,                    # 計算 p-value
    user_id="eric"
)

3.3 快速 EDA 報告

mcp_automl_run_quick_eda(
    dataset_id="your-dataset-id",  # 需要先註冊資料集
    user_id="eric"
)

---

📋 Step 4: 特定分析

4.1 組間比較

# 比較兩組或多組的數值差異
mcp_automl_compare_groups(
    csv_path="/data/sample_data/heart_disease.csv",
    numeric_column="age",        # 要比較的數值欄位
    group_column="target",       # 分組欄位
    save_result=True,
    user_id="eric"
)

會自動選擇統計方法：

• 2 組 + 常態分佈 → t-test
• 2 組 + 非常態 → Mann-Whitney U
• 3+ 組 + 常態 → ANOVA
• 3+ 組 + 非常態 → Kruskal-Wallis

4.2 相關性分析

mcp_automl_analyze_correlations(
    csv_path="/data/sample_data/diabetes.csv",
    columns=["age", "bmi", "blood_pressure", "glucose"],  # 可選
    method="pearson",   # pearson, spearman, kendall
    save_result=True,
    user_id="eric"
)

4.3 多重共線性檢查 (VIF)

mcp_automl_check_multicollinearity(
    csv_path="/data/sample_data/boston.csv",
    columns=["rm", "lstat", "ptratio", "tax"],  # 可選
    vif_threshold=5.0   # VIF > 5 視為有問題
)

---

📋 Step 5: 結果處理

5.1 結果會自動儲存

支援結果儲存的工具會返回：

{
  "result_id": "stat_compare_groups_abc12345",
  "result_path": "automl-results/eric/compare_groups/20251216_...",
  "summary": { ... },
  "details": { ... }
}

5.2 列出已儲存的結果

mcp_automl_list_analysis_results(
    user_id="eric",
    analysis_type="compare_groups"  # 可選
)

5.3 取回之前的結果

mcp_automl_get_analysis_result(
    result_id="stat_compare_groups_abc12345"
)

---

🎯 常見分析場景

場景 1：臨床研究基準分析

User: "分析 medical_study_200.csv，按 treatment 分組"

Agent 執行順序：
1. direct_preview_data → 預覽資料結構
2. get_column_info → 確認欄位類型
3. generate_tableone_directly → 生成 Table 1

場景 2：探索性資料分析

User: "探索 heart_disease.csv"

Agent 執行順序：
1. get_quick_stats → 基本統計
2. analyze_missing_values → 缺失值分析
3. analyze_correlations → 相關性分析
4. auto_analyze → 智能分析

場景 3：ML 前置分析

User: "準備用 titanic.csv 做 ML，先看看資料"

Agent 執行順序：
1. get_column_info → 欄位資訊
2. analyze_missing_values → 缺失值
3. check_multicollinearity → VIF 檢查
4. compare_groups(target) → 目標變數分布

---

📊 可用範例資料集

資料集	路徑	適合分析
iris.csv	/data/sample_data/iris.csv	分類、聚類
titanic.csv	/data/sample_data/titanic.csv	二元分類
heart_disease.csv	/data/sample_data/heart_disease.csv	二元分類、Table One
diabetes.csv	/data/sample_data/diabetes.csv	迴歸、相關性
breast_cancer.csv	/data/sample_data/breast_cancer.csv	二元分類
medical_study_200.csv	/data/sample_data/medical_study_200.csv	Table One、組間比較
rossi_recidivism.csv	/data/sample_data/rossi_recidivism.csv	存活分析
stanford_heart.csv	/data/sample_data/stanford_heart.csv	存活分析

---

⚠️ 常見錯誤

路徑錯誤

# ❌ 錯誤：使用 Host 路徑
csv_path="/home/eric/workspace251204/sample_data/iris.csv"

# ✅ 正確：使用 Container 路徑
csv_path="/data/sample_data/iris.csv"

# ✅ 更簡單：只提供檔名（自動轉換到 sample_data）
csv_path="iris.csv"  # → /data/sample_data/iris.csv

# ✅ 專案內檔案：保持專案結構
csv_path="projects/my_study/data/raw/patient_data.csv"
# → /data/projects/my_study/data/raw/patient_data.csv

# ✅ Host 專案路徑會自動識別
csv_path="/home/eric/workspace251204/projects/study1/data.csv"
# → /data/projects/study1/data.csv（保持專案結構）

欄位名稱錯誤

# 先確認欄位名稱
info = mcp_automl_get_column_info(csv_path="...")
# 再使用正確的欄位名稱

忘記指定 user_id

# 需要儲存結果時，必須提供 user_id
mcp_automl_compare_groups(
    ...,
    save_result=True,
    user_id="eric"  # 必要！
)

---

📝 預設參數

# 除非使用者指定，自動帶入：
DEFAULT_PARAMS = {
    "user_id": "eric",
    "storage_mode": "temporary",
    "method": "auto",
    "pval": True,
    "n_rows": 10,
}

---

🎯 工具選擇決策樹

使用者需求
    │
    ├─→ 「看看資料」「概覽」
    │       └─→ quick_preview / direct_preview_data
    │
    ├─→ 「分析這個資料」
    │       └─→ smart_analyze（推薦！整合 stats + tableone + correlations）
    │
    ├─→ 「比較兩組」「治療效果」
    │       └─→ compare_treatment_groups / compare_groups
    │
    ├─→ 「相關性」「變數關係」
    │       └─→ analyze_correlations
    │
    ├─→ 「Table One」「臨床基準表」
    │       └─→ generate_tableone_directly
    │
    ├─→ 「VIF」「共線性」
    │       └─→ check_multicollinearity
    │
    └─→ 「醫學研究完整分析」
            └─→ analyze_medical_study