Funnel Calibrator

セールスファネルが実際にどう機能しているかに照らして、広告の意思決定を再調整するMCPサーバーです——想定上の機能に照らすのではなく。

⚠️ ステータス: 作業中です。 スキャフォールディングと設計はコミット済みです。MCPサーバーの実装は2026年8月24日に公開されます。ディフェンス: 2026年8月25日。

KSE AI Agentic Lab — 個別ラボ課題（第7週、MCP Integration）

このプロジェクトが解決する問題

このプロジェクトは、現在稼働中のウクライナの代金引換（COD）eコマース事業に基づいています。その事業はMeta広告を通じて女性向けの服を販売しており、ファネルは5つの段階で構成されています:

Meta ads ──► Lead ──► Call-centre approval ──► Shipment ──► Buyout at post office ──► Profit

支払いは配達時に行われるため、広告キャンペーンの成果はお金を費やした時点では分かりません。それが判明するのは2〜4週間後、顧客が荷物を受け取るか受け取らないかが決まったときです。この事業は、このギャップをポートフォリオ全体の2つの定数——65%の承認率と52.5%の買取率——で埋め、それらを用いて、各商品について、その商品がまだ損益分岐する最大リード単価（Stop CPL）と、最適化の目標とすべき数値（Goal CPL）とを計算しています。

この定数はポートフォリオ平均であり、それを個々の商品に適用しても、個々の商品はそこから大きくかい離します。 もとになる事業での実測例: あるメーカーの商品は、想定の52.5%に対し買取率が37%。ある商品の承認率は、想定の65%に対し53%でした。買取率は価格帯と強く相関しており、690～790₴では約93%であるのに対し、1290₴超では約55%です。

商品の実際の率が想定よりも悪い場合、その商品の真の損益分岐CPLは、事業が目安としている数字より低くなります。つまり、広告の目標数値が真の損益分岐点を上回る位置に置かれ得るのです。広告ダッシュボードではトラフィックが健全に見える一方で、すべてのリードが赤字を生み、その赤字は数週後の月次財務締めになるまで表面化しません。

これはオープンループ制御システムです。測定結果が意思決定に戻らないのです。Funnel Calibrator はこのループを閉じます。

Related MCP server: KrystalView MCP Server

機能

サーバーは、履歴オーダーデータから各商品自身のファネル率を測定し、その商品の真のCPL境界値を再計算し、提案された広告の意思決定を修正後の数値に照らして監査します。判断を圧縮的に受け入れるのではなく、構造化されたエビデンスを返すという形で。

これら2つの問題が難しさを高めており、両方ともツール契約の中で明示的に処理されています。

• 打ち切り（ア度制）。 最近の注文はまだ解決していません——配達中の荷物は、買取でも返品でもありません。このような注文を単純に加算すると、測定値が下方で引き出されます。サーバーは、設定可能なマチュリティ・ウィンドウよりも若いコホートを除外し、差し引いた注文数を報告します。

• 小サンプル。商品、サイズ、場合によっては色がそれぞれ細かくなり、カウント数はすぐに少なくなります。すべての測定にはサンプルサイズと信頼性フラグが付き、サーバーは設定可能なしきい値を下回る場合には、自信に騒いで観測結果を報告するのではなく、結論を下すことを拒否します。

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│  Agent  (Claude Agent SDK)                                  │
│                                                             │
│    ├── MCP ──► Obsidian Local REST API      [existing]      │
│    │           decision journal: reads the day's objective  │
│    │           and prior conclusions, writes calibrated      │
│    │           verdicts back as a durable record            │
│    │                                                         │
│    └── MCP ──► Funnel Calibrator            [custom]        │
│                measure → recalibrate → recommend → audit    │
│                        │                                     │
│                        ▼                                     │
│                 local snapshot dataset                       │
│                 (anonymised order cohorts + unit economics)  │
└─────────────────────────────────────────────────────────────┘

カスタムサーバーは独立したプロセスとして実行され、stdioで通信します。エージェントとは関係なく単独で起動できます。

エージェントのフロー

1. Obsidian の保管庫（ボールト）から、今日の広告目標と昨日の結論を読み取る。

2. スナップショットから各商品の実測ファネル率を測定する（サンプルとサンプルサイズを考慮）。

3. その商品の真のStop/Goal CPLと、想定ベースラインに対する乖離を再計算する。

4. 商品が土台と結果が悪い場合なぜが悪いかを診断する（対処法は原因ごとに異ります）し、次の一手を提案する。

5. 今日提案された広告の決定内容を、修正後の境界に対して監査する。

6. 修正された判定書と、その根拠となる日本のエビデンスチェーンをボールトに書き戻す。

各手順は前段の出力を使います。ボールトにあるものが何を検証させるかを決め、その測定結果が修正済みの範囲を決め、修正済みの範囲が提案された決定が維持なのか覆るのかを決定します。

カスタムツール

完全な入出力スキーマ、エラー条件、副作用、具体例は: docs/tool-contracts.md。

なぜこの4つが選ばれ、なぜMCP境界に置くのか、設計が何を諦めているのか: docs/design-rationale.md。

データソース

ローカルで匿名化されたスナップショット・データセットを、過去の注文コホートからインポートされたものではなく、scripts/export_snapshot.py によって事業CRMからエクスポートしています。実行時に認証やネットワークアクセスが不要なため、デモは決定論的で再現可能です。

顧客名・電話番号・住所・傳票番号など、個人を特定できる情報はすべてエクスポート時に除外されます。スナップショットには、較正タグに必要な情報のみが残ます: 商品コード、注文ステータス、タイムスタンプ、金額、単位あたりの経済性（単位経済性）です。匿名化ポリシーとスキーマは data/README.md を参照してください。

クイックスタート

前提条件: Python ≥ 3.11 と uv。Local REST API プラグインを導入した Obsidian はエージェントフローのみで必要であり、サーバーの実行には不要です。

git clone https://github.com/denkor1015-debug/funnel-calibrator.git
cd funnel-calibrator
uv sync

MCPサーバーをスタンドアロンで実行します（stdioでMCPを話し、クライアントを待ちます）:

uv run funnel-calibrator

MCP Inspector を使い、公開されたツールを対話的に確認します:

npx @modelcontextprotocol/inspector uv run funnel-calibrator

設定は環境変数から読み取されます。テンプレートをコピーして編集してください:

cp .env.example .env

両方のMCP接続のためのエージェント配線: agent/mcp_config.example.json。

リポジトリ構成

src/funnel_calibrator/   MCP server: tool definitions, calibration math, policy engine
scripts/                 snapshot exporter (CRM ──► anonymised local dataset)
data/                    snapshot dataset + anonymisation policy
docs/                    tool contracts, design rationale, defence checklist
agent/                   MCP client configuration for both connections
tests/                   unit tests for calibration and policy logic

ビルド・プラン

• リポジトリのスキャフォールディング、アーキテクチャ、設計根拠

• PII除去付きスナップショットエクスポーター

• measure_sku_funnel — 打ち切りとサンプルサイズ・ゲート

• recalibrate_cpl_bounds — 単位経済の再計算

• recommend_next_action — 失敗モードの診断

• audit_ad_verdict — 意思決定の監査

• Obsidian MCP連携とエンド・ツー・エンドのエージェントフロー

• 障害系の処理とデモ

• ツール契約のドキュメントとディフェンス用スクリプト

課題要件マップ

ライセンス

MIT — LICENSE をご覧ください。