# MCP 统计分析服务器 (mcp-stats-engine)

[![CI](https://github.com/wzx11223344/mcp-stats-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/wzx11223344/mcp-stats-engine/actions/workflows/ci.yml)

一个基于 Model Context Protocol (MCP) 的统计分析服务器，提供 30 个专业统计工具，涵盖描述性统计、假设检验、回归分析和时间序列分析四大模块。所有工具返回 Markdown 格式的分析报告，数组参数以逗号分隔字符串传递，便于 AI 代理直接调用和展示。

## 特性

- **30 个专业统计工具**: 覆盖统计分析全流程
- **Markdown 输出**: 所有工具返回格式化的 Markdown 字符串，包含表格、统计量和结论解读
- **FastMCP 框架**: 基于 `mcp.server.fastmcp.FastMCP` 和 `@mcp.tool()` 装饰器
- **科学计算引擎**: 使用 scipy.stats 和 statsmodels 实现统计计算
- **简洁的参数设计**: 数组参数以逗号分隔字符串传递，多组数据以分号分隔
- **自动结论解读**: 每个工具都包含基于 p 值和效应量的自动统计结论

## 安装方法

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

依赖包列表:
- `mcp>=1.0.0` - MCP 协议框架
- `scipy` - 科学计算
- `statsmodels` - 统计建模
- `numpy` - 数值计算
- `pandas` - 数据处理

### 2. 配置 MCP 客户端

在 MCP 客户端配置文件中添加以下配置（以 Claude Desktop 为例）:

```json
{
  "mcpServers": {
    "stats-engine": {
      "command": "python",
      "args": ["path/to/mcp-stats-engine/server.py"]
    }
  }
}
```

### 3. 启动服务器

```bash
python server.py
```

## 使用示例

### 描述性统计

```
工具: descriptive_statistics_tool
参数: data = "12,15,14,10,18,20,17,16,13,19"
```

### 双样本 t 检验

```
工具: two_sample_ttest_tool
参数:
  group1 = "25,28,30,32,35,27,29,31,33,26"
  group2 = "20,22,24,26,28,21,23,25,27,22"
  equal_var = true
```

### 单因素方差分析

```
工具: anova_test_tool
参数: groups_data = "1,2,3,4,5;2,4,6,8,10;3,5,7,9,11"
```

### OLS 线性回归

```
工具: ols_regression_tool
参数:
  y_data = "1,2,3,4,5,6,7,8,9,10"
  x_data = "2,4,5,7,9,11,12,14,15,17"
```

### ARIMA 预测

```
工具: arima_forecast_tool
参数:
  data = "30,28,32,35,33,31,29,27,30,33,36,34,32,30,33,36,38,35,33,31"
  order = "1,0,1"
  forecast_steps = 5
```

### 正态性检验

```
工具: normality_test_tool
参数:
  data = "12,15,14,10,18,20,17,16,13,19,22,25"
  method = "shapiro"
```

## 工具列表

### 辅助工具 (4个)

| 工具 | 说明 |
|---|---|
| `parse_data_string_tool` | 数据解析（逗号分隔字符串转数值列表） |
| `confidence_interval_tool` | 置信区间计算（基于 t 分布） |
| `effect_size_tool` | 效应量计算（Cohen's d / Glass's delta） |
| `power_analysis_tool` | 功效分析（样本量计算） |

### 描述性统计 (6个)

| 工具 | 说明 |
|---|---|
| `descriptive_statistics_tool` | 描述性统计（均值/中位数/众数/方差/偏度/峰度/四分位数） |
| `frequency_distribution_tool` | 频数分布表 |
| `five_number_summary_tool` | 五数概括（Min/Q1/Median/Q3/Max） |
| `correlation_analysis_tool` | 相关分析（Pearson/Spearman/Kendall） |
| `covariance_matrix_tool` | 协方差矩阵 |
| `outlier_detection_tool` | 异常值检测（IQR/Z-score） |

### 假设检验 (8个)

| 工具 | 说明 |
|---|---|
| `one_sample_ttest_tool` | 单样本 t 检验 |
| `two_sample_ttest_tool` | 双样本 t 检验（含 Welch's t 检验） |
| `paired_ttest_tool` | 配对 t 检验 |
| `chi_square_test_tool` | 卡方检验（拟合优度） |
| `anova_test_tool` | 单因素方差分析 (ANOVA) |
| `mann_whitney_test_tool` | Mann-Whitney U 检验（非参数） |
| `wilcoxon_test_tool` | Wilcoxon 符号秩检验（非参数配对） |
| `normality_test_tool` | 正态性检验（Shapiro-Wilk/K-S） |

### 回归分析 (6个)

| 工具 | 说明 |
|---|---|
| `ols_regression_tool` | OLS 线性回归（一元） |
| `multiple_regression_tool` | 多元线性回归 |
| `logistic_regression_tool` | Logistic 回归（统计视角） |
| `weighted_regression_tool` | 加权最小二乘回归 (WLS) |
| `residual_analysis_tool` | 残差分析（正态性/独立性/同方差性） |
| `multicollinearity_check_tool` | 多重共线性检验 (VIF) |

### 时间序列分析 (6个)

| 工具 | 说明 |
|---|---|
| `decompose_timeseries_tool` | 时间序列分解（趋势/季节/残差） |
| `acf_pacf_analysis_tool` | ACF/PACF 分析 |
| `adf_test_tool` | ADF 单位根检验 |
| `kpss_test_tool` | KPSS 平稳性检验 |
| `arima_forecast_tool` | ARIMA 预测 |
| `granger_causality_tool` | Granger 因果检验 |

## 技术栈

| 技术 | 用途 |
|---|---|
| [MCP](https://modelcontextprotocol.io/) | Model Context Protocol 通信框架 |
| [FastMCP](https://github.com/jlowin/fastmcp) | MCP Python 服务器框架 |
| [SciPy](https://scipy.org/) | 科学计算与统计检验 (scipy.stats) |
| [Statsmodels](https://www.statsmodels.org/) | 统计建模 (OLS/WLS/Logit/ARIMA/时间序列) |
| [NumPy](https://numpy.org/) | 数值计算 |
| [Pandas](https://pandas.pydata.org/) | 数据处理 |

## 项目结构

```
mcp-stats-engine/
├── server.py              # 主入口，FastMCP 服务器
├── descriptive_tools.py   # 描述性统计工具（6个）
├── hypothesis_tools.py    # 假设检验工具（8个）
├── regression_tools.py    # 回归分析工具（6个）
├── timeseries_tools.py    # 时间序列工具（6个）
├── utils.py               # 辅助函数（4个工具）
├── README.md              # 项目文档
├── SKILL.md               # SkillHub 技能描述
└── requirements.txt       # 依赖
```

## 测试

运行单元测试：

```bash
pip install pytest flake8
pytest tests/ -v --tb=short
```

代码质量检查：

```bash
flake8 . --count --max-line-length=120 --statistics
```

## 许可证

MIT License