aigroup-quant-mcp

aigroup-quant-mcp - Roo-Code量化分析MCP服务

🎯 专为Roo-Code设计的MCP量化分析服务 - 提供LightGBM/XGBoost/sklearn机器学习建模，无需torch依赖

---

🚀 快速开始（Roo-Code用户）

一键启动MCP服务

# 使用uvx快速启动（推荐，无需安装）
uvx aigroup-quant-mcp

就这么简单！ MCP服务会自动：

• ✅ 下载最新版本
• ✅ 配置轻量级依赖（仅~100MB）
• ✅ 启动并连接到Roo-Code
• ✅ 提供8个专业量化工具

配置Roo-Code

方式：手动配置

如果需要手动配置RooCode的MCP服务，请在RooCode的设置中添加以下配置：

{
  "mcpServers": {
    "aigroup-quant-mcp": {
      "command": "uvx",
      "args": [
        "aigroup-quant-mcp"
      ],
      "env": {},
      "alwaysAllow": [
        "preprocess_data",
        "calculate_factor",
        "generate_alpha158",
        "merge_factor_data",
        "evaluate_factor_ic",
        "apply_processor_chain",
        "train_ml_model",
        "predict_ml_model",
        "list_factors"
      ]
    }
  }
}

配置说明：

• command: 使用uvx运行，无需本地安装
• args: 启动参数
• alwaysAllow: 允许访问的工具列表
• env: 环境变量（可留空）

配置完成后，RooCode将自动连接到aigroup-quant-mcp服务，您可以直接使用以下工具：

---

📦 安装方式

方式1：uvx（推荐，无需安装）

# 直接运行最新版本
uvx aigroup-quant-mcp

# 或指定版本
uvx aigroup-quant-mcp@1.0.17

优点：

• ⚡ 快速启动（几秒钟）
• 🔄 自动获取最新版本
• 💾 无需本地安装
• 🎯 轻量级依赖（~100MB，包含机器学习库）

方式2：pip安装

# 基础安装（包含机器学习功能，无torch）
pip install aigroup-quant-mcp

# 完整安装（包含深度学习）
pip install aigroup-quant-mcp[full]

# 或只安装深度学习依赖
pip install aigroup-quant-mcp[dl]

# 运行
aigroup-quant-mcp

依赖说明

• 核心依赖（默认）：pandas, numpy, scipy, mcp, lightgbm, xgboost, scikit-learn
• [dl]：torch（深度学习，需要时再装）
• [full]：所有功能（适合完整开发）

💡 推荐：直接使用基础安装，包含所有机器学习功能，无需额外安装torch！

---

✨ 核心特性

1️⃣ 智能数据预处理

• ✅ 自动清洗：自动处理缺失值和异常值
• ✅ 智能导出：清洗后数据自动保存
• ✅ 质量评估：自动生成数据质量报告

2️⃣ Alpha158因子库

• 📊 158个技术指标：Qlib级专业因子库
• 🎯 分类清晰：K线(9) + 价格(5) + 成交量(5) + 滚动统计(139)
• 🔧 灵活配置：支持自定义窗口和因子组合
• 💾 导出支持：可导出CSV/JSON便于查看

3️⃣ 因子评估

• 📈 IC分析：Spearman/Pearson相关性分析
• 📊 ICIR计算：信息比率评估因子稳定性
• 📝 报告生成：自动生成Markdown评估报告
• 🎯 质量评级：智能评估因子有效性

4️⃣ 智能标准化

• 🤖 自动识别：单商品/多商品自动适配
• 🔄 智能切换：CSZScoreNorm自动优化
• ✅ 避免NaN：单商品自动使用ZScoreNorm
• 📊 透明化：明确告知调整原因

5️⃣ 机器学习建模

• 🤖 三模型支持：LightGBM/XGBoost/sklearn
• ⚡ 无需torch：轻量级机器学习解决方案
• 📊 完整评估：MSE/MAE/R²/IC等指标
• 🎯 特征分析：自动特征重要性分析
• 🔮 批量预测：支持导出预测结果

6️⃣ 深度学习建模

• 🧠 三模型支持：LSTM/GRU/Transformer
• 📈 序列建模：专门处理时间序列数据
• 🔧 灵活配置：序列长度、隐藏层、层数可调
• 💾 内存优化：自动GPU/CPU切换
• 📊 专业评估：损失曲线、预测精度分析

---

📋 工具详细说明

preprocess_data

加载CSV数据并自动清洗

参数：

• file_path：CSV文件路径
• data_id：数据唯一标识
• auto_clean：是否自动清洗（默认true）
• export_path：导出路径（可选）

返回：

• 数据摘要（行数、列数、日期范围）
• 数据质量评估
• 清洗详情
• 导出信息

generate_alpha158

生成Alpha158因子集

参数：

• data_id：数据源ID
• result_id：结果ID
• kbar：是否生成K线因子（默认true）
• price：是否生成价格因子（默认true）
• volume：是否生成成交量因子（默认true）
• rolling：是否生成滚动统计因子（默认true）
• rolling_windows：窗口大小列表
• export_path：导出路径（可选）

返回：

• 因子数量和分类统计
• 数据质量评估
• 导出信息

merge_factor_data

⭐ 新增于v1.0.24 - 合并因子数据和价格数据

功能说明：

解决了因子数据无法直接用于 train_ml_model的问题。将Alpha158等因子数据与原始价格数据合并，生成包含所有因子列和close列的完整数据集。

参数：

• factor_data_id：因子数据ID（如alpha158_normalized）
• price_data_id：原始价格数据ID（必须包含close列）
• result_id：合并后数据的唯一标识
• export_path：导出路径（可选）
• export_format：导出格式csv/json（可选）

返回：

• 合并数据信息（因子数+close列）
• 数据质量评估
• 导出信息（如果指定）

典型用法：

{
  "factor_data_id": "alpha158_normalized",
  "price_data_id": "stock_data_2023",
  "result_id": "merged_for_training"
}

详细文档：docs/MERGE_FACTOR_DATA_GUIDE.md

evaluate_factor_ic

评估因子IC并生成报告

参数：

• factor_name：因子名称
• data_id：数据源ID
• method：计算方法（spearman/pearson）
• report_path：报告保存路径（可选，新增于v1.0.16）

返回：

• IC指标（IC均值、IC标准差、ICIR、IC正值占比）
• 因子质量评级
• 预测方向和预测能力分析
• 使用建议

新增功能（v1.0.16）：

• ✨ 自动生成Markdown格式评估报告
• 📊 包含详细的指标解读
• 💡 提供后续步骤指引

apply_processor_chain

智能数据标准化

参数：

• data_id：数据源ID
• result_id：结果ID
• processors：处理器配置列表

特点：

• 🤖 自动识别单商品/多商品
• 🔄 CSZScoreNorm自动优化
• ✅ 避免单商品100% NaN问题

推荐用法：

{
  "processors": [
    {"name": "CSZScoreNorm"}
  ]
}

系统会自动判断并选择最佳标准化方法。

list_factors

列出所有已加载的数据和因子

参数：无

返回：

• 数据列表
• 因子列表
• 每个因子的类型和形状

train_ml_model

训练机器学习模型

参数：

• data_id：数据源ID（必须包含close列）
• model_id：模型唯一标识
• model_type：模型类型（lightgbm/xgboost/linear）
• train_start：训练开始日期
• train_end：训练结束日期
• test_start：测试开始日期
• test_end：测试结束日期
• params：模型参数（可选）

返回：

• 训练和测试性能指标（MSE/MAE/R²/IC）
• 特征重要性分析
• 模型质量评估

train_lstm_model

训练LSTM深度学习模型

参数：

• data_id：数据源ID
• model_id：模型唯一标识
• sequence_length：序列长度（默认60）
• hidden_size：隐藏层大小（默认64）
• num_layers：LSTM层数（默认2）
• learning_rate：学习率（默认0.001）
• epochs：训练轮数（默认100）
• batch_size：批次大小（默认32）
• train_start：训练开始日期
• train_end：训练结束日期
• test_start：测试开始日期
• test_end：测试结束日期

返回：

• 训练和测试损失曲线
• 预测精度评估
• 模型配置信息
• 训练时间统计

train_gru_model

训练GRU深度学习模型

参数：

• data_id：数据源ID
• model_id：模型唯一标识
• sequence_length：序列长度（默认60）
• hidden_size：隐藏层大小（默认64）
• num_layers：GRU层数（默认2）
• learning_rate：学习率（默认0.001）
• epochs：训练轮数（默认100）
• batch_size：批次大小（默认32）
• train_start：训练开始日期
• train_end：训练结束日期
• test_start：测试开始日期
• test_end：测试结束日期

返回：

• 训练和测试损失曲线
• 预测精度评估
• 模型配置信息
• 训练时间统计

train_transformer_model

训练Transformer深度学习模型

参数：

• data_id：数据源ID
• model_id：模型唯一标识
• sequence_length：序列长度（默认60）
• d_model：模型维度（默认64）
• nhead：注意力头数（默认4）
• num_layers：编码器层数（默认2）
• learning_rate：学习率（默认0.001）
• epochs：训练轮数（默认100）
• batch_size：批次大小（默认32）
• train_start：训练开始日期
• train_end：训练结束日期
• test_start：测试开始日期
• test_end：测试结束日期

返回：

• 训练和测试损失曲线
• 预测精度评估
• 模型配置信息
• 训练时间统计

predict_with_model

使用深度学习模型进行预测

参数：

• model_id：模型ID
• data_id：预测数据ID
• export_path：导出路径（可选）

返回：

• 预测结果统计
• 预测值预览
• 导出信息（如果指定）

predict_ml_model

使用训练好的模型进行预测

参数：

• model_id：模型ID
• data_id：预测数据ID
• export_path：导出路径（可选）

返回：

• 预测结果统计
• 预测值预览
• 导出信息（如果指定）

---

📚 高级使用（Python API）

如果您需要在Python脚本中使用，可以直接导入：

from quantanalyzer.data import DataLoader
from quantanalyzer.factor import Alpha158Generator, FactorEvaluator

# 加载数据
loader = DataLoader()
data = loader.load_from_csv("stock_data.csv")

# 生成因子
generator = Alpha158Generator(data)
factors = generator.generate_all(rolling_windows=[5, 10, 20])

# 评估因子
returns = data['close'].groupby(level=1).pct_change().shift(-1)
evaluator = FactorEvaluator(factors, returns)
ic_metrics = evaluator.calculate_ic(method='spearman')

print(f"IC均值: {ic_metrics['ic_mean']:.4f}")
print(f"ICIR: {ic_metrics['icir']:.4f}")

更多Python API示例请查看 examples/ 目录。

---

📂 项目结构

aigroup-quant-mcp/
├── quantanalyzer/              # 核心包
│   ├── mcp/                    # MCP服务
│   │   ├── server.py          # MCP服务器
│   │   ├── handlers.py        # 工具处理函数
│   │   ├── schemas.py         # 工具Schema定义
│   │   └── ...
│   ├── data/                   # 数据层
│   ├── factor/                 # 因子层
│   │   ├── alpha158.py        # Alpha158因子
│   │   ├── evaluator.py       # 因子评估
│   │   └── library.py         # 基础因子
│   ├── model/                  # 模型层
│   └── backtest/               # 回测层
├── examples/                   # 示例脚本
├── exports/                    # 导出数据目录
├── reports/                    # 评估报告目录
├── .roo/                       # RooCode配置
│   └── mcp.json               # MCP服务配置示例
├── pyproject.toml             # 项目配置
├── CHANGELOG.md               # 更新日志
└── README.md                  # 本文档

---

🔧 故障排除

uvx安装卡住

问题：uvx aigroup-quant-mcp 卡住不动

解决：

1. 确保使用v1.0.17或更高版本
2. 检查网络连接
3. 尝试清除缓存：uvx --no-cache aigroup-quant-mcp

因子评估返回错误

问题：evaluate_factor_ic返回NoneType

解决：

1. 升级到v1.0.16或更高版本
2. 确保因子已正确生成
3. 使用list_factors查看可用因子

单商品数据标准化后全是NaN

问题：使用CSZScoreNorm后数据全是NaN

解决：

1. 升级到v1.0.14或更高版本
2. 系统会自动切换为ZScoreNorm
3. 或手动使用ZScoreNorm处理器

机器学习模型训练失败

问题：train_ml_model返回错误

解决：

1. 确保数据包含close列用于生成标签
2. 检查时间范围参数是否正确
3. 确认数据格式与训练时一致
4. 查看详细错误信息和建议

模型预测结果异常

问题：predict_ml_model返回异常值

解决：

1. 确保预测数据特征与训练时一致
2. 检查数据是否正确标准化
3. 确认模型已正确训练
4. 查看模型评估指标判断质量

RooCode中无法使用MCP工具

问题：在RooCode中看不到aigroup-quant-mcp工具

解决：

1. 确保配置了正确的MCP服务配置
2. 检查uvx是否正常工作：uvx --version
3. 重启RooCode
4. 查看RooCode的MCP服务日志

MCP服务连接失败

问题：MCP服务启动失败或连接超时

解决：

1. 检查网络连接
2. 尝试使用 uvx --no-cache aigroup-quant-mcp清除缓存
3. 确保Python版本>=3.8
4. 查看详细错误日志

---

🤝 贡献

欢迎提交Issue和Pull Request！

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 开启Pull Request

---

📄 许可证

MIT License - 查看 LICENSE 了解详情

---

🙏 鸣谢

• Qlib - 量化分析框架
• MCP - 模型上下文协议
• Roo-Code - AI编程助手

---

📞 支持

• 💬 提交 jackdark425/aigroup-quant-mcp: Quant Analyzer package with Alpha158 factors and deep learning models
• 📧 邮件：jackdark425@gmail.com
• 📚 文档：查看项目文档和示例

---

立即开始: uvx aigroup-quant-mcp 🚀