Factor Miner MCP

A 股量化因子挖掘工具集的独立 MCP（Model Context Protocol）服务。从 Athena 的 py-sidecar 中抽取 factor 域，让任何 MCP 客户端（Claude Desktop、Kimi Code、Cursor、自研 Agent）都能直接驱动完整的「因子挖掘 → 评估 → 回测 → 上线巡检」流水线。

工具清单（15 个）

因子挖掘

ML

因子评估与组合

重负载工具提交即入队返回 job_id，轮询 GET /jobs/<id> 拿结果， 不占 HTTP 连接。

实现说明与算法出处

• factor_tearsheet 手写 pandas 而非依赖 alphalens 本体：alphalens 已半停维护（上游多年无实质更新），其依赖链与 pandas>=2 冲突频发； 分位数收益 / IC / 换手率逻辑本身很短，手写可控、可测、零额外依赖。

• HRP — López de Prado (2016), Building Diversified Portfolios that Outperform Out-of-Sample（相关距离 → 层次聚类 → 拟对角化 → 递归二分）。

• EWMA — RiskMetrics (1996), J.P. Morgan Technical Document，λ=0.94， 多期预测平坦外推。

• PELT — Killick et al. (2012), Optimal Detection of Changepoints With a Linear Computational Cost, JASA（可选增强，内置为 CUSUM（Page 1954）

  • 二分分割）。

• HMM — GaussianHMM（收益率 + 滚动波动率两特征，可选增强，内置为规则 状态机）。

• 全部 5 个工具：纯 numpy/pandas/scipy 路径开箱可用，重库 （pypfopt / hmmlearn / ruptures / arch）惰性导入做可选增强，输出 method 字段标注实际实现。

Related MCP server: FactorHub MCP Server

快速开始

pip install -r requirements.txt
python3 server.py --port 50053

验证：

curl http://127.0.0.1:50053/health
curl http://127.0.0.1:50053/tools

接入 MCP 客户端（以 Claude Desktop / Kimi Code 为例）：

# mcp 配置
factor:
  url: http://127.0.0.1:50053/mcp

Docker 部署

无需本地 Python 环境，一条命令起服务：

docker compose up -d        # 构建镜像 + 启动容器（首次构建约 3-5 分钟）
docker compose ps           # 查看状态
docker compose logs -f      # 跟踪日志

验证：

curl http://127.0.0.1:50053/health
curl http://127.0.0.1:50053/tools   # 应返回 15 个工具

说明与限制：

• 镜像不含 pyqlib（PyPI 无 linux/aarch64 wheel，arm64 需源码编译）， 因此 factor_backtest / gen_data / update_data 等回测/数据工具 在容器内不可用；纯 pandas 工具（compute_factors / predict / factor_recent_ic 等）开箱即用。h5 数据集可通过 volume 挂载： - ./data:/app/data 并设 FACTOR_MINER_DATA_DIR=/app/data/factor_mining。

• lightgbm 已随镜像安装（linux wheel 自带 OpenMP 运行时）， ml_train_rolling / ml_predict 可用。

• Redis 缓存（dfactor:* 写入）可选：设置 REDIS_URL 指向可达的 Redis，缺失时自动降级跳过缓存写入。

license 鉴权（可选）：在 docker-compose.yml 中取消注释，把宿主机 licenses.json 挂进容器并设置 MCP_LICENSE_FILE：

environment:
  MCP_LICENSE_FILE: /app/licenses/licenses.json
volumes:
  - ./licenses.json:/app/licenses/licenses.json:ro

数据准备（回测类工具需要）

factor_execute / factor_backtest / factor_oos_check 依赖 qlib cn_data 导出的日频量价 h5 数据集：

pip install pyqlib  # arm64 Linux 需从 GitHub 源码编译，见 requirements.txt 注释
python3 -m factor_miner.update_data          # qlib cn_data 增量更新
python3 -m factor_miner.gen_data --debug     # 调试集（100 股 × 2 年）
python3 -m factor_miner.gen_data --full      # 全量（回测用）

factor_recent_ic / compute_factors / predict 纯 pandas 实现， 不依赖 qlib，开箱即用。

鉴权与额度（可选）

默认开放模式（本地/内网）。设置环境变量后强制 license key 鉴权：

export MCP_LICENSE_FILE=/path/to/licenses.json
python3 server.py --port 50053
# 客户端请求头：X-License-Key: <key>

license JSON 格式与额度语义见 mcp_gateway.py docstring。GET /quota 查余量，GET /queue-stats 看队列。

端点一览

GET  /health        健康检查
GET  /tools         工具 JSON schema 列表
POST /mcp           MCP JSON-RPC（initialize / tools/list / tools/call）
GET  /jobs/<id>     异步任务状态/结果
GET  /quota         license 额度余量（鉴权模式）
GET  /queue-stats   队列概况

沙箱安全模型

factor_execute 等执行用户提交的 factor.py 时在子进程沙箱中运行： AST import 白名单（仅 pandas/numpy 等）、rlimit 资源限制、120s 超时、 隔离工作目录。实现见 factor_miner/sandbox.py。

致谢

• factor_miner/gen_data.py 移植自 microsoft/RD-Agent（MIT）

• factor_miner/qlib_dump_bin.py 裁剪自 microsoft/qlib v0.9.6（MIT）

• 本项目主体来自 Athena

License

MIT