Frontline Copilot

KI-gestützte Triage von Kundenbewertungen für Filialleiter im Einzelhandel.

Ein ständig aktives System, das Kundenbewertungen aus beliebigen Quellen aufnimmt, sie mithilfe von Claude nach Kategorie und Schweregrad klassifiziert und handlungsrelevante Bewertungen an die Airtable-Aufgabenliste des Filialleiters weiterleitet — mit Echtzeit-Slack-Alerts für kritische Vorfälle (Lebensmittelsicherheit, Mitarbeiterverhalten, Gesundheitsrisiken).

Es wird außerdem als MCP-Server ausgeliefert, sodass Filialleiter über Claude Desktop per Konversation abfragen und priorisieren können.

Inspiriert von der aufkommenden Kategorie der KI-Copiloten für den Filialbetrieb.

Das Problem

Filialleiter bei Einzelhandelsketten mit mehreren Standorten ertrinken in einer Flut von Kundenbewertungen. Die meisten sind Rauschen (Lob oder kleinere Beschwerden). Einige wenige sind dringend (Lebensmittelsicherheit, Diskriminierung, Verletzungsrisiko). Die meisten Tools verlangen vom Manager, alles zu lesen, um die wenigen relevanten Bewertungen zu finden — ein aussichtsloser Kampf bei großem Volumen.

Frontline Copilot dreht das um. Claude liest alles; der Manager sieht nur, was Maßnahmen erfordert.

Related MCP server: Shopify MCP Server

So funktioniert es

┌────────────┐   ┌──────────────┐   ┌────────────┐   ┌────────────┐
│  Reviews   │──▶│ Classifier   │──▶│  Airtable  │──▶│   Slack    │
│  (JSON /   │   │ (Claude API, │   │  (task     │   │  (critical │
│   Google)  │   │  tool use)   │   │  tracker)  │   │   alerts)  │
└────────────┘   └──────────────┘   └────────────┘   └────────────┘
                        │
                        ▼
                 ┌──────────────┐
                 │  MCP server  │◀── Claude Desktop, Cursor, ...
                 │  (3 tools)   │
                 └──────────────┘

Jede Bewertung wird in eine von neun Kategorien eingeordnet, mit einem Schweregrad von 1 (positiv) bis 5 (kritisch). Bewertungen mit Schweregrad ≥ 3 werden zu Airtable-Aufgaben; ab Schweregrad ≥ 4 wird zusätzlich ein Slack-Alert ausgelöst.

Screenshots

End-to-End-Pipeline-Lauf

21 Bewertungen in ~60 Sekunden verarbeitet. 7 Aufgaben erstellt, 4 kritische Echtzeit-Alerts.

Airtable — Aufgaben-Board

Aufgaben nach Schweregrad sortiert, nach Kategorie eingefärbt. Das ist es, was ein Filialleiter sieht.

Airtable — Kanban-Ansicht

Dieselben Daten, nach Kategorie gruppiert. Verteilung der Themen auf einen Blick.

Slack — kritische Echtzeit-Alerts

Block-Kit-Karten mit handlungsorientiertem Layout und direktem Link zur Airtable-Aufgabe.

Tech-Stack

• Python 3.10+ — dataclasses, Union-Typen wie str | None, pathlib

• Anthropic Claude API — Klassifizierung per Tool-Use (claude-haiku-4-5)

• Airtable REST API — Aufgaben-Tracker, direkt mit requests aufgerufen

• Slack Incoming Webhooks — Block Kit für umfangreiche Alert-Karten

• MCP (Model Context Protocol) — konversationelle Schnittstelle über FastMCP

• Adapter-Muster für Bewertungsquellen (Mock wird mitgeliefert; Google Places als Stub vorhanden)

Nur drei Drittanbieter-Abhängigkeiten: anthropic, requests, mcp. Alles andere ist Standardbibliothek.

Schnellstart

# 1. Clone and install
git clone https://github.com/miguelpomarm/frontline-copilot
cd frontline-copilot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets
cp .env.example .env
# ... edit .env with your keys (see setup section below)

# 3. Run the pipeline
python triage.py

# 4. Launch as an MCP server (optional)
python mcp_server.py

Einrichtung (einmalig, ~10 Minuten)

1. Anthropic-API-Schlüssel

Einen erhalten Sie unter https://console.anthropic.com/. Das kostenlose Kontingent reicht für Demo-Läufe — 21 Bewertungen kosten ~0,03 $.

2. Airtable-Base

Erstellen Sie eine neue Base mit einer Tabelle namens Tasks und diesen Feldern (exakte Namen):

Erstellen Sie dann unter https://airtable.com/create/tokens ein persönliches Zugriffstoken mit den Scopes data.records:read und data.records:write für Ihre Base. Kopieren Sie das Token und die Base-ID (beginnt mit app..., zu finden in der URL Ihrer Base).

3. Slack-Incoming-Webhook

Erstellen Sie unter https://api.slack.com/apps eine Slack-App. Aktivieren Sie Incoming Webhooks, fügen Sie einen neuen Webhook hinzu, der auf den Kanal zeigt, der kritische Alerts erhalten soll, und kopieren Sie die Webhook-URL.

4. .env ausfüllen

ANTHROPIC_API_KEY=sk-ant-...
AIRTABLE_API_KEY=pat...
AIRTABLE_BASE_ID=app...
AIRTABLE_TABLE_NAME=Tasks
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

5. Erster Start

python triage.py --limit 3 --dry-run   # sanity check, no side effects
python triage.py --limit 3             # small live run
python triage.py                       # full 21 reviews

MCP-Integration (Claude Desktop)

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hinzu und starten Sie Claude Desktop neu:

{
  "mcpServers": {
    "frontline-copilot": {
      "command": "python",
      "args": ["/absolute/path/to/frontline-copilot/mcp_server.py"]
    }
  }
}

Anschließend in Claude Desktop:

„Wie läuft es gerade bei Aurora Times Square?"

Claude ruft get_store_health("times_square") auf, greift auf Airtable zu und antwortet mit der aktuellen Momentaufnahme — offene Aufgaben, Anzahl kritischer Fälle, häufigste Kategorie.

Design-Entscheidungen

Bewusste Entscheidungen, die es wert sind, einem Reviewer genannt zu werden:

Geschlossene Taxonomie + Other-Kategorie

Die Kategorien sind ein festes Enum, nicht frei formulierbar. Das gewährleistet konsistentes Routing und konsistente Metriken. Other ist die Notluke — sie wird regelmäßig überprüft, um die Taxonomie auf Basis realer Daten zu erweitern, statt im Voraus zu raten.

Tool-Use statt Prompt-Engineering

Claude gibt strukturierte Ausgaben über ein Tool-Schema mit Enum-Erzwingung zurück. Das eliminiert Parsing-Fehler und verhindert, dass das LLM eine Kategorie außerhalb der Taxonomie halluziniert.

Haiku 4.5 als Standardmodell

Für eine klar abgegrenzte Klassifikationsaufgabe ist Haiku schnell (unter einer Sekunde), günstig (~0,001 $ pro Bewertung) und genau genug. In der Produktion spart allein diese Entscheidung bei moderatem Volumen Tausende von Dollar pro Monat.

Adapter-Muster für Bewertungsquellen

ReviewSource ist ein abstraktes Interface. Mitgeliefert werden MockSource und ein dokumentierter GooglePlacesSource-Stub. Der Wechsel zu Yelp, TrustPilot oder einem proprietären Feed ist eine neue Unterklasse — der Rest der Pipeline bleibt unberührt.

Idempotenz über die Review-ID

Die erneute Verarbeitung derselben Bewertungen erzeugt keine doppelten Aufgaben. Vor jedem Anlegen wird Airtable geprüft.

Schweregrad-Schwellenwerte als justierbare Konstanten

ACTION_THRESHOLD und ALERT_THRESHOLD stehen auf Modulebene. Kunden mit anderen Toleranzen ändern zwei Zahlen, keinen Code.

Sync statt Async für das MVP

Verarbeitet 21 Bewertungen sequenziell in ~40 Sekunden. Die Async-Variante ist in ~15 Zeilen austauschbar (AsyncAnthropic + asyncio.gather mit einem Semaphor für Rate Limits). Bei diesem Volumen gewinnt Lesbarkeit gegenüber Geschwindigkeit.

Text statt Sterne

Der Prompt weist Claude ausdrücklich an, den Bewertungstext stärker zu gewichten als die Sternebewertung. Eine 4-Sterne-Bewertung, die Lebensmittelsicherheit erwähnt, ist Schweregrad 5, nicht 2.

Roadmap (nicht implementiert)

• FastAPI-Webhook-Endpunkt (POST /webhook/review) für die Echtzeit-Erfassung statt Batch-Läufen.

• GooglePlacesSource — das Adapter-Interface ist fertig, die Live-Implementierung ist ~1 Stunde API-Integration + Retry-Logik.

• Async-Batching mit Berücksichtigung von Rate Limits für die Produktion mit hohem Volumen.

• End-to-End-Tests (Playwright / pytest mit aufgezeichneten API-Interaktionen), die die Airtable/Slack-Seiteneffekte verifizieren.

• Pro Kunde konfigurierbare Schwellenwerte über config.yaml.

Lizenz

MIT — siehe LICENSE.

Erstellt von Miguel Pomar Martínez als technisches Portfolio-Projekt.