leakguard-mcp

leakguard-mcp

回测的故障警报。 一款本地优先的 MCP 服务，可对 Agent 生成的 Python 代码进行静态分析，并在回测运行之前标记前视偏差和数据泄漏。

适用于任何时间序列机器学习代码——量化交易（加密货币、股票、外汇、期货）、 需求预测、能源、天气、IoT 传感器等；任何 .shift() 用错或全局归一化会悄然污染结果的场景。

• 纯源码分析（libcst）——代码绝不会离开本机，不会调用 API。
• 基于启发式，而非严格证明：提供严重性等级（🔴错误 / 🟡警告），如同航空故障警报。
• 与框架无关：适用于 pandas / numpy / polars 等任何技术栈。
• 原生支持 MCP（stdio）：可直接在 Claude Code、Cursor 和任何兼容 MCP 的 Agent 中使用。
• 全部 10 条规则均免费提供——无需许可证，没有分级限制，也不会向外发送数据。

---

为什么需要它

AI Agent（Claude Code、Cursor）编写特征工程和策略代码的速度，比人工审核更快。但它们也会大规模引入前视偏差——细微的时间边界错误，在回测中表现完美，却会在实盘交易或生产环境中造成灾难性后果：

# Agent writes this — looks fine, is catastrophically wrong
df['momentum'] = df['close'].shift(-5)   # uses FUTURE prices as a feature
df['vol_norm'] = (df['close'] - df['close'].mean()) / df['close'].std()  # leaks future mean

leakguard 会在同一 Agent 工作流中捕获这些问题——在回测运行之前：

LG001 🔴 line 2: Future shift used as feature — shift(-5) references 5 bars ahead.
  Fix: df['momentum'] = df['close'].shift(5)   (lag, not lead)

LG003 🔴 line 3: Global-fit normalization — mean/std computed over the full series
  before any train/test split, leaking future statistics into the past.
  Fix: df['vol_norm'] = (df['close'] - df['close'].expanding().mean()) / df['close'].expanding().std()

Agent 会读取发现的问题和修复代码片段，并在一个回合内自行纠正。无需人工审核。

---

安装

要求

• Python 3.11+
• uv（推荐）或 pip

从 PyPI 安装

pip install leakguard-mcp

从源码安装

git clone https://github.com/doazvjettu/leakguard-mcp
cd leakguard-mcp
uv sync

---

使用 Claude Code 进行设置

将以下内容添加到 MCP 配置（~/.claude/claude_desktop_config.json，或项目中的 .claude/settings.json）：

{
  "mcpServers": {
    "leakguard": {
      "command": "python",
      "args": ["-m", "leakguard.server"]
    }
  }
}

如果通过 uv 安装，也可以使用：

{
  "mcpServers": {
    "leakguard": {
      "command": "uv",
      "args": ["run", "python", "-m", "leakguard.server"]
    }
  }
}

重启 Claude Code。现在 Agent 就可以使用 leakguard 的工具了。

使用 Cursor 进行设置

将相同的配置块添加到 Cursor MCP 设置文件中的 mcpServers 下。

---

MCP 工具

工具	描述
lint_code(code)	分析代码字符串并返回发现的问题
lint_file(path)	分析磁盘上的文件
lint_paths(glob)	分析所有匹配的文件
list_rules()	列出所有规则及其严重性
explain_rule(rule_id)	提供规则的完整原理说明和修复模式

---

命令行工具

同一款扫描器也可通过命令行使用，适合用作提交前钩子或 CI 步骤（发现泄漏时返回非零退出码）：

uv run leakguard path/to/strategy.py
# or, installed:  leakguard path/to/strategy.py

它会打印每个发现的问题及其严重性、行号/列号和具体的修复代码片段——与上方演示中显示的输出相同。

---

规则

全部 10 条规则均已启用，不分等级：

ID	严重程度	模式
LG001	🔴	将未来偏移作为特征：shift(-n) / diff(-n) / pct_change(-n)
LG002	🔴	居中窗口：rolling(center=True)
LG003	🔴	全局拟合缩放：StandardScaler().fit(full_df) / 划分前手动计算均值和标准差
LG004	🔴	打乱时间序列划分：train_test_split 默认行为、KFold、cross_val_score(cv=n)
LG005	🔴	标签泄漏：将基于未来数据生成的目标列再次用作特征
LG006	🟡	使用全历史聚合值作为特征：对完整序列使用 .max() / .mean()
LG007	🔴	向后填充插补：bfill() / fillna(method='bfill')
LG008	🔴	向前 asof 联接：merge_asof(direction='forward'/'nearest')
LG009	🟡	bar 时间戳上的重采样标签／闭合区间不匹配
LG010	🟡	跨越训练集／测试集边界的 groupby().transform()/agg()

每项发现都附有一段具体的修复代码，调用方 Agent 可立即据此自行修正。

---

基准测试

在两个带标签语料库上测得，共 49 段代码。 使用 uv run python -m benchmark.run 复现。

**诚信说明：**交易语料库由本工具的作者编写——请将其中的数据视为回归测试样例，而非独立验证。通用机器学习语料库在领域上有所区隔（由作者编写，复现了有广泛文献记录的泄漏反模式，并非从公开数据集下载）。语料库有意纳入扫描器已知可能漏检的对抗性代码片段，并将其计入扫描器的错误。

交易语料库 — 39 段代码（23 段存在泄漏，16 段干净代码及难以判定的负例）：

规则	精确率	召回率	TP	FP	FN
LG001	75%	100%	6	2	0
LG002	100%	100%	5	0	0
LG003	75%	100%	3	1	0
LG004	100%	100%	4	0	0
LG005	100%	100%	5	0	0
LG006	100%	100%	5	0	0
LG007	100%	100%	5	0	0
LG008	100%	100%	2	0	0
LG009	75%	100%	3	1	0
LG010	100%	100%	2	0	0
总计	91%	100%	40	4	0

通用机器学习语料库 — 10 段代码（LG003/LG004/LG010）： 精确率 88%，召回率 100%（TP 7 / FP 1 / FN 0）。

合并结果：精确率 90.4%，召回率 100%（TP 47 / FP 5 / FN 0）。

在此语料库上，召回率为 100%——发现的每个对抗性漏检问题都已修复（常量传播、手动实现的归一化、cv=<int>、基于 drop 的选择）。 语料库尚未覆盖的泄漏模式仍会漏检——请参阅下文的“已知限制”。

已知误报（被标记的干净代码）

• **LG001：**使用负偏移构造向前收益标签，且仅将其用作 y — 纯 AST 无法区分目标列和特征。
• **LG003：**拟合发生在划分调用位置上方定义的辅助函数中——行序启发式会将定义顺序误认为执行顺序。
• **LG004：**对真正的非时间数据进行打乱划分——目前尚无日期时间索引推断。
• **LG009：**为报告／绘图而非特征进行重采样——静态分析无法识别意图。

已知漏报（尚未覆盖的泄漏模式）

• **LG004：**未提供 cv 的 cross_val_score(...)（默认使用 KFold）。
• **LG005：**通过 df.loc[:, 'col'] = ... 或 df.assign(col=...) 传播污点。
• **所有规则：**值经由函数调用、字典或非恒定变量传递——没有跨函数数据流分析。

这些集合固定在 tests/test_benchmark.py 中：任何新增漏报或静默修复都会导致测试套件失败，直到文档和语料库更新并与之匹配。

---

开发

uv sync --extra dev
uv run pytest                              # 96 tests
uv run python -m leakguard.server          # stdio MCP server
uv run leakguard demo/strategy_leaky.py    # CLI on the demo file
uv run python -m benchmark.run             # precision/recall tables + FP/FN lists

扫描器核心位于 leakguard/core/（纯代码，不导入 MCP）；server.py 和 cli.py 是轻量封装。每条规则都在 tests/fixtures/ 下有一对测试样例。

---

限制（v1）

• 启发式静态分析——可检测约 90% 的常见模式，但无法覆盖 100%。
• 仅支持单个文件——不进行跨模块污点跟踪。
• 仅支持 Python（pandas / numpy / polars）。
• 不执行运行时分析——无法检测只在运行时才出现的模式。

欢迎贡献：新增语料片段（尤其是你遇到过的真实 Bug）比新增规则更能增强基准测试。