metric-shift-mcp-server

「先週から売上(予約件数)が落ちた。どこで?」に答えるMCPサーバー。

CSVを渡すと、基準期間から曜日補正つきの予測値を作り、対象期間の実績との乖離がどの属性組合せに集中しているかを特定します。

例: 「全体で12%減。うち75%は チャネル=web の減少、35%は 火曜の夜 の減少で説明できます」

完全ローカル・読み取り専用・外部送信なし・APIキー不要・機械学習の訓練不要。

⚠️ このツールがやらないこと(先に読んでください)

• 因果関係の証明はしません。 出力は「変化がどの属性組合せに集中しているか」という相関に基づく絞り込みです。「なぜそこが減ったのか」(施策変更・障害・競合・天候など)の解釈と確認は人の仕事です。
• 予測はしません。異常検知の常時監視もしません。1回の「比較して分解する」分析だけをします。
• 変化が小さく(全体±2%未満)データが少ない場合、原理的に検出できません。その場合は「有意な変化なし」と答えます。

クイックスタート

1. インストール

git clone https://github.com/h-kazuki-pixel/metric-shift-mcp-server.git
cd metric-shift-mcp-server
npm install
npm run build

2. Claude Desktop への登録

claude_desktop_config.json に追加:

{
  "mcpServers": {
    "metric-shift": {
      "command": "node",
      "args": ["/絶対パス/metric-shift-mcp-server/dist/index.js"]
    }
  }
}

3. 使う

Claudeにこう頼みます:

/Users/you/reservations.csv を見て。6月は普通だったのに、6/29の週から予約が減った気がする。どこで減ってるか調べて。

Claudeが metric_shift_inspect_data でデータを確認し、metric_shift_localize で要因分解します。

データの形式

ヘッダー行つきのCSV(UTF-8、BOM可)。1行=1レコード(1予約、1注文など)。

日時,チャネル,店舗,金額
2026-06-01 10:30,web,A店,1200
2026-06-01 11:00,phone,A店,800

• 日時列: ISO 8601 / YYYY-MM-DD / YYYY/MM/DD(時刻付き可)。列は自動推定、明示指定も可
• 非対応: 和暦、Excelシリアル値(45678のような数値)。Excelからは「日付」列を文字列形式でCSVエクスポートしてください
• 少量データ(1,000行以下)はファイルを作らず直接渡すことも可能

ツール

metric_shift_inspect_data

分析前のデータ確認。列一覧、日時列の推定結果、日付範囲、次元(切り口)候補、指標候補を返します。

metric_shift_localize

要因分解の本体。

引数	説明
file_path / rows	CSVパス、または直接データ(排他)
measure	"count"(件数)または数値列名(合計を分析)
dimensions	切り口1〜6個。列名、または予約語 __weekday__(曜日)/ __timeband__(時間帯: 朝6-11/昼11-17/夜17-22/深夜22-6、境界は変更可)
baseline_period	基準期間(正常だった頃)。1週間以上を推奨。対象期間との重複はエラー
target_period	対象期間(変化が起きた期間)
max_candidates	原因候補の最大数(既定3)
merge_rare_categories	希少カテゴリを「その他」に自動集約(既定ON、次元ごとに上位10保持。集約された値は警告で明示)
response_format	markdown(既定)/ json

仕組み

1. 予測値の生成: 基準期間の曜日別1日あたり平均 × 対象期間の曜日構成で、属性組合せ(葉)ごとの「本来ならこうなるはず」を作る(曜日補正つき・決定論的)
2. 異常な葉の絞り込み: 偏差分布の knee point 法で閾値を自動決定
3. クラスタリング: 偏差スコアのヒストグラム密度クラスタリングで「同じ原因の影響を受けた葉の群れ」を分離(ripple effect 仮説)
4. 局在化: クラスタごとに属性組合せの空間を浅い層から探索し、GPS(汎用ポテンシャルスコア)で「その組合せが原因だとしたら観測データをどれだけうまく説明できるか」を評価。簡潔性(オッカムの剃刀)とのバランスで代表候補を選ぶ

アルゴリズムについて

本実装は以下の論文のアルゴリズムに基づく独自のTypeScript実装です(公式実装のコードは使用していません):

• Z. Li et al., "Generic and Robust Localization of Multi-Dimensional Root Causes" (Squeeze), ISSRE 2019
• R. Bhagwan et al., "Adtributor: Revenue Debugging in Advertising Systems", NSDI 2014(先行研究として設計時に参照)

公式実装(NetManAIOps/Squeeze)のREADMEに著者自身が記載している既知バグ2件を修正済みです:

• バグ1(期待値の計算): 論文の定義どおり、部分集合の実測/予測の合計比で期待値を計算。さらにGPSの計算対象を「当該クラスタの葉+正常な葉」に限定し、他クラスタの異常葉による汚染を防止
• バグ2(簡潔性重みの負値): 重み C を下限0でクリップし、負値による誤った順位付けを防止

これに加えて、原著の必要条件(「原因に属する属性組合せは子孫葉の大半が同一クラスタ内にある」)の明示的な実装、クラスタ被覆制約、兄弟候補の統合、影響量フィルタを追加しています。

小規模データへの適応(本実装の独自拡張)

Squeeze は大規模なサービス監視データ向けに設計されています。小さい店舗のデータ(週数百件)に多次元を指定すると、薄く広がった原因が葉レベルのノイズに埋もれることがあります。本実装は:

• 疎らさの警告: 属性組合せあたりの件数が少なすぎる場合に警告し、次元削減・期間延長を提案
• 拡散原因の安全網: 次元単体の合計レベルでも乖離を検査し、「候補には出ていないが単体で大きな乖離のある値」があれば、次元を絞った再実行を提案

制約(v0.1)

• 次元は最大6個。inline データは最大1,000行(超える場合はCSVファイルで)
• 期間の重複は不可。基準期間は1週間以上を推奨(曜日補正のため)
• 時間帯の既定区切りは日本の飲食・サービス業を想定(変更可能)
• タイムゾーン変換はしない(日時は書かれたまま解釈)
• 祝日は考慮しない(v1.0で jp-dates 連携を予定)

セキュリティ

• 読み取り専用。ファイルの書き込み・削除は一切しない
• 完全ローカル動作。ネットワーク通信なし・外部送信なし
• システム領域(/etc など)へのアクセスは拒否

ロードマップ

• v0.1(現在): コア分析(count/数値列、file/inline、曜日補正、要因分解)
• v0.5: 派生指標(キャンセル率など)、移動平均ベースの予測値
• v1.0: 予約データ用プリセット、jp-dates 連携(祝日補正)

ライセンス

MIT

作者

@h-kazuki-pixel — 無人スペース運営 × AI自動化。現場で使って効果のあった自動化ツールを汎用化してOSSとして公開しています。