Causal MCP

A 股因果分析工具集的独立 MCP（Model Context Protocol）服务。从 Athena 的 py-sidecar 中抽取 causal 域，让任何 MCP 客户端（Claude Desktop、Kimi Code、Cursor、自研 Agent）都能直接做「事件研究 → 反事实验证 → 因果图学习」的完整因果推断链路。

与 causal-memory.com 公网服务的关系：本项目是 其同源方法论的本地/自托管版本，数据不出本机，无需账号即可使用； 公网服务提供托管的多租户 + license 额度体系，本项目也内置了同一套 mcp_gateway.py 鉴权/额度模块供私有化部署选用。

工具清单（8 个）

8 个工具均为秒级同步调用，直接返回结果。server 内置异步任务队列 （mcp_gateway.py JobQueue），后续接入重负载工具时无需改架构。

Related MCP server: cn-financial-mcp

快速开始

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

验证：

curl http://127.0.0.1:50057/health
curl http://127.0.0.1:50057/tools

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

# mcp 配置
causal:
  url: http://127.0.0.1:50057/mcp

Docker 部署

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

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

验证：

curl http://127.0.0.1:50057/health
curl http://127.0.0.1:50057/tools   # 应返回 8 个工具

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

可选重库（FULL 镜像）：默认镜像不含 pycausalimpact / tigramite / econml，对应工具走内置 fallback（输出 method 字段标注）。需要真 BSTS / PCMCI / LinearDML 路径时：

docker compose build --build-arg FULL=true   # 或编辑 compose 中 args.FULL
docker compose up -d

调用示例

event_study — 单事件研究

curl -s http://127.0.0.1:50057/mcp -d '{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {"name": "event_study", "arguments": {
    "symbol": "002371",
    "event_date": "2026-04-17",
    "klines": [{"date": "2026-01-05", "close": 100.0}, ...],
    "benchmark": [{"date": "2026-01-05", "close": 3200.0}, ...]
  }}}'

返回（JSON 字符串）：

{"car_1d": 0.032, "car_3d": 0.041, "car_5d": 0.038, "car_pre1d": -0.002,
 "alpha": 0.0003, "beta_market": 1.21, "r_squared": 0.42, "sigma": 0.014,
 "t_stat": 2.31, "p_value": 0.024, "is_significant": true,
 "direction": "UP", "impact_score": 0.0327, "confidence": 0.81, "status": "ok"}

约定：klines/benchmark 按日期升序；事件日要求之后至少还有 6 个交易日 （CAR (0,5) 窗口），不足时诚实返回 status: "insufficient post-event data"； 提供 sector_benchmark 时自动切换为市场+板块双因子模型（多返回 beta_sector）。

event_study_batch — 批量

{"events": [{"event_id": 1, "symbol": "002371", "event_date": "2026-04-17",
             "klines": [...], "benchmark": [...]},
            {"event_id": 2, "symbol": "sh600519", "event_date": "2026-04-18",
             "klines": [...], "benchmark": [...], "sector_benchmark": [...]}]}

返回 {"results": [{event_id, symbol, event_date, car_1d, ...}, ...]}， 单事件失败不影响其他事件。

refute — 反事实验证

入参为 event_study 的产出（CAR 三窗口 + p_value）：

{"chain": {"symbol": "sh600519", "car_1d": 0.019, "car_3d": 0.025,
           "car_5d": 0.031, "p_value": 0.042, "direction": "up"}}

返回：

{"refutations": [
   {"method": "placebo_treatment", "result": "robust", "p_value": 0.03, "interpretation": "..."},
   {"method": "random_common_cause", "result": "robust", "interpretation": "..."},
   {"method": "data_subset", "result": "robust", "interpretation": "..."}],
 "passed": 3, "failed": 0, "grade": "A",
 "recommendation": "Strong evidence: all refutation tests passed"}

评级语义：A 全部通过 / B 多数通过 / C 喜忧参半 / D 多数失败 / F 疑似伪相关。 CAR 全窗口绝对值 < 0.005 时直接跳过（事件影响可忽略，无因果主张可验）。

learn_graph — 因果图学习

{"data": {"columns": ["sh600519", "sz000858", "sh600036"],
          "rows": [[1700.0, 185.0, 35.5], [1715.0, 187.0, 36.0], ...]},
 "method": "pc", "alpha": 0.05}

返回 {"edges": [{"from", "to", "weight", "direction"}], "nodes": [...], "metrics": {"n_edges", "sparsity", "avg_weight"}}。至少 2 列 5 行数据。

causal_impact — 事件反事实影响评估

{"symbol": "002371", "event_date": "2026-04-17",
 "klines": [{"date": "2026-01-05", "close": 100.0}, ...],
 "benchmark": [{"date": "2026-01-05", "close": 3200.0}, ...]}

事件日前为估计窗、事件日起为影响窗。返回：

{"cumulative_impact": 0.319, "avg_daily_impact": 0.029, "p_value": 0.0,
 "ci_95": [0.284, 0.367], "significant": true, "method": "bsts",
 "alpha": -0.0009, "beta": 1.13, "r_squared": 0.66, "n_pre": 59, "n_post": 11}

method 标注实际实现："bsts"（装了 pycausalimpact，走 Google CausalImpact 同款贝叶斯结构时序）或 "ols_hedge"（fallback：事件前窗口 OLS 对冲回归 外推反事实，经验 p 值为事件前残差同长度滚动窗口累计的双侧置换分位）。

granger_te — 两序列 lead-lag 因果

{"x": [0.001, -0.002, ...], "y": [0.002, 0.001, ...], "max_lag": 5}

输入收益率序列。返回：

{"granger": {"x_causes_y": {"best_lag": 2, "p_value": 0.0, "p_by_lag": {...}},
             "y_causes_x": {"best_lag": 1, "p_value": 0.72, "p_by_lag": {...}}},
 "transfer_entropy": {"x_to_y": 0.76, "y_to_x": 0.84},
 "lead_lag": "x_leads"}

Granger 用 statsmodels grangercausalitytests 双向 F 检验；传递熵为纯 numpy 分位数分箱实现。lead_lag：单向显著取该侧，双向显著取 p 更小侧，均不显著 时看 TE 相对强弱（>20% 差），否则 "none"。

pcmci_discover — 多变量时序因果发现

{"data": {"columns": ["X1", "X2", "X3"], "rows": [[...], ...]},
 "max_lag": 3, "alpha": 0.05}

返回 {"edges": [{"from", "to", "lag", "strength", "p_value"}], "method": ...}。 method 为 "pcmci"（装了 tigramite，ParCorr 条件独立检验）或 "granger_fallback"（纯 numpy：对每对变量、每个滞后做 MCI 风格条件偏相关

• Fisher z 检验，条件集 = 目标自身滞后 + 其他变量全部滞后）。

dml_cate — 异质处理效应

{"treatment": [1, 0, 1, ...], "outcome": [0.03, -0.01, ...],
 "features": {"feature_A": [...], "feature_B": [...]}}

面板数据：treatment 为事件哑变量或因子暴露（非二元自动按中位数二分， 输出标注 treatment_binarized），outcome 如事件后前瞻收益，features 为 标的属性。返回：

{"cate_summary": {"mean": 0.014, "std": 0.014, "top_decile_mean": 0.040,
                  "bottom_decile_mean": -0.010},
 "feature_importance": [{"feature": "feature_A", "importance": 0.95}, ...],
 "method": "dml", "n": 600, "n_treated": 293, "n_control": 307}

method 为 "dml"（装了 econml，LinearDML 双重机器学习）或 "t_learner" （sklearn GradientBoosting 双模型预测差）。top/bottom 十分位 CATE 差异 + 特征重要性排序用于识别"哪类标的对处理反应更强"。

依赖说明

必需：numpy scipy pandas statsmodels scikit-learn （纯科学计算栈，无 qlib/redis/DB）。

可选（全部惰性导入，未装不影响服务启动，有 fallback 的工具自动降级并在 返回的 method 字段标注实际实现）：

• pycausalimpact — causal_impact 的真 BSTS 路径（Google CausalImpact 的 Python 移植）；未装走 OLS 对冲回归 fallback（method="ols_hedge"）

• tigramite — pcmci_discover 的真 PCMCI 路径；未装走纯 numpy lagged 条件偏相关 fallback（method="granger_fallback"）

• econml — dml_cate 的 LinearDML 路径；未装走 sklearn T-learner fallback（method="t_learner"）

• dowhy / networkx — 完整 DoWhy 反事实管线。本项目的 refute 是 DoWhy 三种 refuter 方法论的纯 numpy 自包含实现，不依赖 dowhy 包

方法学出处

• 事件研究 / OLS 对冲：市场模型（Sharpe 1964）；CausalImpact fallback 沿用同框架外推反事实

• CausalImpact (BSTS)：Brodersen et al., "Inferring causal impact using Bayesian structural time-series models", Annals of Applied Statistics, 2015（Google）；Python 移植 pycausalimpact

• Granger 因果：Granger, "Investigating causal relations by econometric models and cross-spectral methods", Econometrica, 1969（statsmodels 实现）

• 传递熵：Schreiber, "Measuring information transfer", Physical Review Letters 85(2), 2000（本项目为分位数分箱的纯 numpy 实现）

• PCMCI：Runge et al., "Detecting and quantifying causal associations in large nonlinear time series datasets", Science Advances 5(11), 2019 （tigramite 实现；fallback 为 同思想的条件偏相关保守版）

• DML / CATE：Chernozhukov et al., "Double/debiased machine learning for treatment and structural parameters", Econometrics Journal 21(1), 2018 （EconML LinearDML；fallback 为 sklearn T-learner）

鉴权与额度（可选）

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

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

license JSON 格式与额度语义见 mcp_gateway.py docstring（与 factor-miner-mcp 相同）。 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   队列概况

方法学说明

• 事件研究：估计窗 (-60,-6) 内做市场模型（或多因子）OLS，事件窗内 预测正常收益，AR = 实际 - 预测，CAR 为窗口 AR 求和；t 检验标准误按 primary 窗口实际天数缩放（σ·√N），不跨窗口求和

• 反事实验证：CAR 三窗口反推日度 AR 序列后跑三种 refuter—— 安慰剂（随机事件日 100 次置换）、随机共因（50 次噪声扰动稳定性）、 数据子集（50 次 70% bootstrap 方向一致性）

• 因果图：PC 算法从全连接图出发，用偏相关 + Fisher z 检验按条件集 大小（≤3）迭代删除条件独立边；NOTEARS 为 Ridge 回归简化版

• 因果影响：fallback 用事件前窗口对基准收益做 OLS 对冲回归，外推 事件后反事实，经验 p 值为事件前残差同长度滚动窗口累计的双侧置换分位， 95% 区间按 σ·√N·√(1+1/n_pre) 含外推不确定性；BSTS 路径直接取 pycausalimpact 的 post_cum_effects 与 p_value

• lead-lag：Granger 双向 F 检验取逐滞后最小 p；传递熵按分位数 8 分箱 离散化后计算条件概率比的对数和

• 时序因果发现：fallback 对每对变量每个滞后做 MCI 风格条件偏相关 （条件集 = 目标自身滞后 + 其他变量全部滞后）+ Fisher z；PCMCI 路径用 tigramite ParCorr

• 异质效应：T-learner 对处理/对照组各拟合 GradientBoosting，同一样本 预测差为 CATE，特征重要性取两模型均值；DML 路径用 econml LinearDML， 重要性取 |coef| 归一化

致谢

• 本项目主体来自 Athena （multi-agent 量化交易系统）的 py-sidecar causal 域

• mcp_gateway.py 与 factor-miner-mcp 共用

• refuter 设计参考 DoWhy 的 refutation 方法论（MIT）

License

MIT