venue-ops-mcp

Ein MCP-Server, der Claude oder jedem MCP-Client direkten, schreibgeschützten Zugriff auf die täglichen Geschäftszahlen einer Restaurantgruppe mit mehreren Standorten bietet – und, was noch wichtiger ist, auf die Zahlen, bei denen Geld abfließt, ohne dass es jemand aufschreibt.

You: is anything leaking this week?

Claude: Eixample (BCN-01) — voided tickets have drifted from 1.55% of gross
to 4.60% over the last seven days, against a 28-day baseline. That is
799.16 EUR over the window. It is not a spike on one shift; it is a slope
across the whole week, which is the shape a till problem makes.

Warum es das gibt

Die meisten Berichtswerkzeuge beantworten die Frage, die sich ohnehin jeder stellt: Was haben wir verkauft? Umsatz ist die einfache Zahl. Sie steht auf der Kasse, auf dem Dashboard, in der WhatsApp-Gruppe um zehn nach zwölf.

Die Zahlen, die darüber entscheiden, ob ein Standort Geld verdient, sind Rabatte, gratis ausgegebene Artikel und stornierte Belege – der Kontrollblock – und sie schaffen es fast nie in einen Tagesbericht. Eine Stornoquote, die über drei Wochen von 1 % auf 4 % steigt, sieht an keinem einzelnen Abend nach etwas aus. Sie sieht nach einem schlechten Dienstag aus, dann nach einem ruhigen Donnerstag. Sie sieht erst dann wie ein Problem aus, wenn man einen Zeitraum mit dem davor vergleicht – genau das tut dieser Server.

Die Schwellenwerte hier sind nicht aus einem Statistiklehrbuch kopiert. Sie stammen aus der Praxis des Betriebs von Standorten.

Werkzeuge

Jedes Werkzeug ist schreibgeschützt, entsprechend gekennzeichnet und akzeptiert response_format: "markdown" für eine Person oder "json" für ein Programm.

Die zwei Formen von Anomalien

venue_ops_find_anomalies vergleicht die letzten 7 Tage mit den 28 Tagen davor und meldet zwei verschiedene Dinge, weil sie Verschiedenes bedeuten:

• Drift – das gesamte aktuelle Zeitfenster hat sich verschoben. Ein nicht korrigierter Dienstplan, ein Kassenproblem, ein Manager, der angefangen hat, Artikel zu kompensieren, um den Frieden zu wahren. Das ist das teure Problem und das, das niemand bemerkt.

• Spike – ein Tag weit außerhalb der Basislinie. Meist eine Aktion, die niemand protokolliert hat. Einfach zu erklären, eine Bestätigung wert.

Ergebnisse unter 40 EUR werden verworfen. Sie sind real, aber keinen Anruf wert, und ein Bericht, der falschen Alarm schlägt, wird in der dritten Woche ignoriert.

Die Daten

data/operations.json ist synthetisch. Drei Standorte, 182 Tage, erzeugt von scripts/generate_data.py mit einem festen Seed, sodass die Ergebnisse reproduzierbar sind. Es ist kein echtes Unternehmen, und kein reales Unternehmen ist daraus identifizierbar.

Die Zahlen sind erfunden; die Form nicht. Wochentagssaisonalität, das Verhältnis von Vor-Ort-Verzehr zu Lieferung, Rabatt- und Stornoquoten und die Personalkostenquote bewegen sich innerhalb der Bänder, die man im Casual Dining sieht.

Drei Anomalien sind absichtlich eingebaut, damit die Erkennung etwas Echtes zu finden hat und jeder prüfen kann, dass sie funktioniert:

Um das auf ein echtes Kassensystem auszurichten, ersetzen Sie den Loader in venue_ops_mcp/data.py. Die Werkzeugebene kümmert sich nicht darum, woher die Zeilen kommen.

Installation

pip install -r requirements.txt
python scripts/generate_data.py

Verwendung mit Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "venue-ops": {
      "command": "python",
      "args": ["-m", "venue_ops_mcp.server"],
      "cwd": "/absolute/path/to/venue-ops-mcp"
    }
  }
}

Starten Sie Claude Desktop neu. Fragen Sie dann zum Beispiel:

• Welche Standorte haben wir?

• Wie war Gran Via letzten Samstag im Vergleich zu den Samstagen davor?

• Prüfe Barcelona auf Probleme in der Woche bis zum 5. Juli.

• Wie hat sich die Gruppe im Juli geschlagen?

Verifizieren

python scripts/smoke_test.py    # every tool, and the planted anomalies
python scripts/stdio_check.py   # the MCP handshake a real client performs

smoke_test.py prüft, dass die Barcelona-Drift weiterhin erkannt wird und dass ein sauberes Fenster keine Ergebnisse liefert. Ein Detektor, der bei allem anschlägt, ist schlimmer als kein Detektor, daher werden beide Richtungen getestet.

Entwickelt mit

Python 3.10+, das MCP Python SDK (MCPServer, stdio-Transport), Pydantic v2 zur Eingabevalidierung. Keine externen Dienste, keine Anmeldedaten, keine Netzwerkaufrufe – der Server liest nur eine lokale Datei.

Lizenz

MIT.