Funnel Calibrator

Ein MCP-Server, der Werbeentscheidungen gegen das neu kalibriert, was ein Sales-Funnel tatsächlich tut — nicht dagegen, was ihm unterstellt wird.

⚠️ Status: in Arbeit. Grundgerüst und Design sind committet; die Implementierung des MCP-Servers folgt am 24. August 2026. Verteidigung: 25. August 2026.

KSE AI Agentic Lab — Individuelle Lab-Aufgabe (Woche 7, MCP-Integration).

Das Problem, das dieses Projekt löst

Das Projekt basiert auf einem laufenden ukrainischen E-Commerce-Geschäft mit Zahlung bei Lieferung (Cash-on-Delivery, COD), das Damenmode über Meta Ads verkauft. Der Funnel hat fünf Stufen:

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

Weil die Bezahlung erst bei Lieferung erfolgt, ist das Ergebnis einer Werbekampagne in dem Moment, in dem das Geld ausgegeben wird, nicht bekannt. Es ist erst zwei bis vier Wochen später bekannt — wenn der Kunde das Paket annimmt oder nicht. Das Unternehmen überbrückt diese Lücke mit zwei portfolio-weltweit geltenden Konstanten — einer Annahmequote von 65 % und einer Abholquote von 52,5 % — und berechnet damit für jedes Produkt den maximalen Cost-per-Lead, bei dem das Produkt noch kostendeckend ist (Stop CPL), und das Ziel, auf das es optimiert werden soll (Goal CPL).

Diese Konstanten sind Portfolio-Durchschnittswerte, die auf einzelne Produkte angewendet werden — und einzelne Produkte weichen deutlich von ihnen ab. Gemessene Beispiele aus dem zugrunde liegenden Unternehmen: Produkte eines Herstellers wurden zu 37 % abgeholt statt der angenommenen 52,5 %; die Annahmequote eines Produkts wurde mit 53 % gemessen statt der angenommenen 65 %; die Abholquote korreliert stark mit der Preisklasse und bewegt sich zwischen rund 93 % bei 690–790 ₴ und rund 55 % oberhalb von 1290 ₴.

Wenn die tatsächlichen Quoten eines Produkts schlechter sind als angenommen, liegt sein tatsächlicher Break-even-CPL niedriger als die Kennzahl, an der das Unternehmen sich ausrichtet — das Werbeziel kann also über der tatsächlichen Gewinnschwelle liegen. Im Werbeanzeigen-Dashboard sieht der Traffic gesund aus, während jeder Lead Geld verdient — und verkauft den Verlust erst beim monatlichen Abschluss, also Wochen später. Das ist ein Regelkreis mit offener Steuerung: Die Messung fließt nie zurück in die Entscheidung. Funnel Calibrator schließt den Kreis.

Related MCP server: KrystalView MCP Server

Was er tut

Der Server misst die eigenen Funnel-Quoten jedes Produkts aus dem historischen Bestelldaten, berechnet die tatsächlichen CPL-Werte des Produkts neu und prüft vorgeschlagene Werbeentscheidungen gegen die korrigierten Zahlen — er liefert strukturierte Belege zurück, statt ein Urteil, das man glauben soll.

Zwei Probleme machen das schwieriger als üblich, und beide sind in den Tool-Verträgen ausdrücklich behandelt:

• Zensierung. Neuere Bestellungen sind noch nicht aufgelöst — ein Paket unterwegs ist weder eine Abholung noch eine Retoure. Wenn man sie naiv mitzählt, wird die gemessene Quote niedriger. Der Server schließt Kohorten aus, die jünger sind als ein konfigurierbares Reifefenster, und meldet, wie viele Bestellungen er zurückgestellt hat.

• Kleine Stichproben. Pro Produkt, pro Größe, pro Farbe werden die Fallzahlen schnell klein. Jede Messung trägt ihre Stichprobengröße und ein Zuverlässigkeits-Flag mit sich, und der Server macht unterhalb einer konfigurierbaren Schwelle keine konkreten Aussagen, statt selbstbewusstes Rauschen zu melden.

Architektur

┌─────────────────────────────────────────────────────────────┐
│  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)  │
└─────────────────────────────────────────────────────────────┘

Der eigene MCP-Server läuft als separater Prozess, kommuniziert über stdio und lässt sich unabhängig vom Agenten starten.

Agenten-Ablauf

1. Das Werbeziel des Tages und die Schlussfolgerungen von gestern aus dem Obsidian-Vault lesen.

2. Die beobachteten Funnel-Quoten jedes Produkts aus dem Snapshot messen (zensur- und stichprobena-aware),.

3. Den tatsächlichen Stop/Goal-CPL für dieses Produkt neu berechnen und die Drift gegenüber der angenommenen Ausgangsbasis ermitteln.

4. Diagnose, warum ein Produkt leistet — die Ursache unterscheidet sich — und eine nächste Maßnahme empfehlen.

5. Die Tagesseits gegen die korrigierten Grenzen prüfen.

6. Das kalibrierte Urteil mit der Belegkette zurück in den Vault schreiben.

Jeder Schritt baut auf dem Ergebnis des vorherigen auf: Der Inhalt des Vaults bestimmt, was gemessen wird; die Messung bestimmt die angepassten Grenzen; die Grenzen bestimmen, ob eine vorgeschlagene Entscheidung bestehen bleibt oder gekippt wird.

Benutzerdefinierte Tools

Vollständige Ein-/Ausgabe-Schemas, Fehlerfälle, Seiteneffekte und ausgearbeitete Beispiele: docs/tool-contracts.md.

Warum genau diese vier, warum sie an der MCP-Schnittstelle liegen und was das Design dafür eintauscht: docs/design-rationale.md.

Datenquelle

Ein lokaler, anonymisierter Snapshot-Datensatz historischer Bestellkohorte, von scripts/export_snapshot.py aus dem CRM des Unternehmens exportiert. Zur Laufzeit sind keine Authentifizierung und keine Netzwerk hin erforderlich, macht die Demonstration deterministisch und reproduzierbar.

Alle personenbezogenische Informationen — Kundennamen, Telefonnummern, Adressen, Frachtbriefnummern — werden beim Export entfernt. Der Snapshot enthält nur das, was die Kalibrierung braucht: Produktcode, Bestellstatus, Zeitstempel, Beträge und Unit-Ökonomie. Die Anonymisierungssystem und das Schema siehe data/README.md.

Schnellstart

Voraussetzungen: Python ≥ 3.11 und uv. Obsidian mit dem Local-REST-API-Plugin wird nur für den Agenten-Ablauf benötigt, nicht für den Serverbetrieb.

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

Den MCP-Server eigenständig starten (er spricht MCP über stdio und wartet auf einen Client):

uv run funnel-calibrator

Die bereitgestellten Tools interaktiv mit dem MCP Inspector inspizieren:

npx @modelcontextprotocol/inspector uv run funnel-calibrator

Die Konfiguration wird aus Umgebungsvariablen gelesen; die Vorlage kopieren und anpassen:

cp .env.example .env

Agent-Anbindung für beide MCP-Verbindungen: agent/mcp_config.example.json.

Repository-Aufbau

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

Bauplan

• Repository-Scaffolding, Architektur und Design-Rationale

• Snapshot-Exporter mit PII-Entfernung

• measure_sku_funnel — Zensoring und Measurement-Gating

• recalibrate_cpl_bounds — Neuberechnung der Unit-Ökonomie

• recommend_next_action — Diagnose der Fehlerursache

• audit_ad_verdict — Prüfung der Anzeigenentscheidung

• Obsidian-MCP-Integration und End-to-End-Agenten-Ablauf

• Fehlerpfadbehandlung und Demonstration

• Tool-Vertragsdokumentation und Verteidigungsskript

Anforderungs-Karte der Aufgabe

Lizenz

MIT — liche LICENSE.