leakguard-mcp

leakguard-mcp

バックテストのための警告装置です。 ローカルファーストの MCP サーバーで、エージェントが生成した Python コードを静的解析し、バックテスト実行前に先読みバイアスとデータリークを検出します。

時系列 ML コードなら何にでも使えます。クオンツ取引（暗号資産、株式、外国為替、先物）、 需要予測、エネルギー、天気、IoT センサーなど、誤った .shift() や グローバルな正規化によって結果がひそかに汚染されるあらゆるケースに対応します。

• ソースコードのみを解析（libcst）— コードがマシンの外に出ることはありません。API 呼び出しもありません。
• ヒューリスティックであり、証明ではありません。航空機の警告装置のように、重大度を分類します（🔴 エラー／🟡 警告）。
• フレームワークに依存しません。pandas／numpy／polars など、あらゆるスタックに対応します。
• MCP ネイティブ（stdio）です。Claude Code、Cursor、および MCP 対応のあらゆるエージェント内で直接動作します。
• 10 個のルールすべてを無料で利用できます — ライセンス不要、プラン分けなし、外部への通信もありません。

---

これが必要な理由

AI エージェント（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 は、バックテストの実行前に、同じエージェントのループ内でこれらを検出します。

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()

エージェントは検出内容と修正スニペットを読み、1回のターンで自ら修正します。人間によるレビューは不要です。

---

インストール

必要要件

• 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 を再起動します。これで、leakguard のツールをエージェントが利用できるようになります。

Cursor のセットアップ

Cursor の MCP 設定ファイルで、mcpServers の下に同じブロックを追加します。

---

MCP ツール

ツール	説明
lint_code(code)	コード文字列を解析し、検出結果を返します
lint_file(path)	ディスク上のファイルを解析します
lint_paths(glob)	glob に一致するすべてのファイルを解析します
list_rules()	重大度付きですべてのルールを一覧表示します
explain_rule(rule_id)	ルールの詳しい根拠と修正パターンを表示します

---

CLI

同じスキャナーを CLI からも利用できます。コミット前フックや 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	🟡	バーのタイムスタンプにおけるリサンプルの label/closed の不一致
LG010	🟡	訓練／テスト境界をまたぐ groupby().transform()/agg()

各検出項目には、呼び出し元のエージェントがすぐに自己修正できるよう、具体的な修正コード例が含まれています。

---

ベンチマーク

ラベル付きコーパス 2 件、合計 49 個のスニペットで測定しています。 uv run python -m benchmark.run で再現できます。

誠実性に関する注記： 取引コーパスはこのツールの作者が作成したものです。その数値は独立した検証結果ではなく、回帰テスト用の基準値として扱ってください。汎用 ML コーパスは、分野的に一歩距離があります（広く報告されているリークのアンチパターンを作者が再現したものであり、公開データセットをダウンロードしたものではありません）。このコーパスには、スキャナーが見逃すと分かっている敵対的なスニペットも意図的に含め、それらもスキャナーの誤検知・見逃しとして集計しています。

取引コーパス — 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

汎用 ML コーパス — 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）。
• ランタイム実行は行いません。実行時にのみ発生するパターンは検出できません。

貢献を歓迎します。新しいルールよりも、コーパスの新しいスニペット（特に実際に遭遇したバグ）のほうが、ベンチマークの強化につながります。