Telco MCP

Ein lokaler, schreibgeschützter MCP-Server für kontrollierte Kundenbindungsanalysen auf Basis eines per Prüfsumme fixierten Telco-Customer-Churn-Snapshots. Claude Code oder Codex interpretiert Geschäftssprache; der Server verwaltet Metrikdefinitionen, begrenzte Abfragen, Aggregatausführungen, Hinweise und Herkunftsnachweise. Es gibt kein serverseitiges LLM und keinen Modell-API-Schlüssel.

Warum es das gibt

Dieses Projekt ist inspiriert von Anthropic’s Self-Service-Analytics-Workflow: Fachanwender sollen eine Kennzahl abfragen können, ohne ein Modell zu beauftragen, SQL oder Metriklogik selbst zu erfinden. Das Hostmodell interpretiert die Absicht, während der MCP nur geprüfte semantische Definitionen und deterministische Aggregatoperationen bereitstellt. Das reduziert das Halluzinationsrisiko erheblich, behauptet aber nicht, dass das Routing des Hostmodells oder die endgültige Formulierung niemals falsch sein können.

Related MCP server: spreadsheet-qa-kit MCP server

Schnellster Einstieg: manuelle Installation mit Ihrem Agenten

Öffnen Sie dieses Repository in Claude Code oder Codex und senden Sie:

Lesen Sie INSTALL.md, installieren und verifizieren Sie dieses Projekt vollständig und melden Sie die abschließende Checkliste. Befolgen Sie seine Stoppbedingungen; ändern Sie weder den Anwendungscode noch nicht zusammenhängende Client-Konfigurationen.

INSTALL.md ist das vollständige Installationshandbuch. Es bereitet die per Prüfsumme fixierten Daten vor, registriert den MCP bei den ausgewählten Clients, verifiziert das Acht-Tool-Protokoll und erläutert sichere Wiederherstellung und Deinstallation.

Direkte Einrichtung

Voraussetzungen: Git, uv sowie Claude Code und/oder Codex. Python 3.12 und die in der Lock-Datei festgelegten Abhängigkeiten werden von uv verwaltet.

Dies ist eine auf das Repository begrenzte Anwendung: Klonen Sie das Repository und führen Sie es mit uv aus. Eigenständige Wheel- oder PyPI-Installationen werden bewusst nicht unterstützt, weil der semantische Katalog und das Quellmanifest Governance-Assets auf Repository-Ebene sind.

uv run --frozen telco-mcp setup --clients claude,codex
uv run --frozen telco-mcp doctor --clients claude,codex

Verwenden Sie nur installierte Clients, zum Beispiel --clients codex. Die Client-Authentifizierung ist vom MCP getrennt; der Server selbst benötigt keine Modell-Anmeldedaten.

Fragen Sie den Client dann:

Verwenden Sie das Telco-MCP. Was ist Churn? Nennen Sie den Nenner und die Snapshot-Einschränkung.

Eine kontrollierte Antwort beginnt mit dem geprüften Standardwert und kennzeichnet die Alternative:

• 26,5370 % = 1.869 / 7.043: zertifizierter Churn-Anteil an allen Snapshot-Datensätzen und Standardwert für allgemeine Fragen.

• 28,3655 % = 1.869 / 6.589: ein alternativer Proxy für die Logo-Churn-Rate mit angenommener Startbasis, berechnet aus Stayed + Churned.

Die Antwort muss angeben, dass die Daten aus einem einzelnen Q3-Snapshot stammen und keinen Trend darstellen.

Was das Projekt bietet

• Acht typisierte MCP-Tools für Geschäftsübersichten, Kontext, Katalog, Metriken, Segmentdiagnose, Fairness-Audits, erfasste Churn-Gründe und strukturierte Hinweise zu Fähigkeiten und Ablehnungen.

• Semantische Version 4 mit fünf Geschäftskonzepten, 34 kontrollierten Metriken und 29 Dimensionen.

• Deskriptive Aufschlüsselungen nach einer und zwei Dimensionen mit begrenzten Filtern und Populationen.

• Aggregierte Analyse von Gebühren, kumulierten Umsätzen, Erstattungen, Nutzung, Zufriedenheit, Service und Gründen.

• Prüfsummenfixierte Vorbereitung, schreibgeschütztes DuckDB, quellenbezogene Ergebnisherkunft und ein abgesicherter Start im Fail-closed-Modus. Ein synthetisches Protokoll-Fixture existiert nur bei ausdrücklichem Opt-in.

• Optionale gespiegelte Claude/Codex-Skills verbessern das Routing, ohne den MCP-Vertrag zu ersetzen.

Es werden bewusst keine Trends, Kohorten, NRR/GRR, Umsatz-Churn, Prognosen, Vorhersagen, Kausalaussagen, Szenario-/Jahreswirkung, ROI, Uplift, beliebige SQL-Abfragen oder Exporte auf Kundenebene bereitgestellt.

Architektur

Business question
  → Claude Code / Codex (+ optional Skill)
  → eight typed MCP tools
  → governed semantic layer
  → bounded parameterized compiler
  → read-only DuckDB
  → aggregate evidence + caveats + provenance
  → business-language answer

Die vollständige technische und fachliche Erläuterung – einschließlich Tools, Daten, Metriken, Fragenabdeckung, Einschränkungen, Datensicherheit, verifizierten Beispielen und Quellenverweisen – finden Sie in docs/PROJECT_GUIDE.md.

Häufige Befehle

# Prepare or refresh the verified local artifact
uv run --frozen telco-mcp prepare

# Show the installed application version
uv run --frozen telco-mcp --version

# Register and verify selected clients
uv run --frozen telco-mcp setup --clients claude,codex
uv run --frozen telco-mcp doctor --clients claude,codex

# Run deterministic engineering checks
uv run --frozen pytest
uv run --frozen ruff check .
uv run --frozen mypy src scripts evals
uv audit --frozen

# Remove only this project's registrations; keep prepared data
uv run --frozen telco-mcp uninstall --clients claude,codex

Beispiele für manuelle Reparaturen finden Sie in .mcp.json.example und .codex/config.toml.example. Bevorzugen Sie setup, da es exakte Pfade auflöst und widersprüchliche Registrierungen ablehnt, sofern nicht ausdrücklich --replace erlaubn wird.

Daten und Datenschutz

Die Datenquelle ist ein fiktiver/simulierter Q3-Snapshot des Kalifornischen Staates mit 7.043 eindeutigen Kundendatensätzen. Die drei Quelldateien, ihre Revision und die SHA-256-Werte sind in data/source_manifest.json festgeschrieben. Rohdaten-CSVs und vorbereitete DuckDB-Artefakte werden nicht committet, da die Rechte zur Weitergabe nicht bestätigt wurden. Lesen Sie DATA_NOTICE.md, bevor Sie die Daten verwenden oder verlinken.

Der Dienst liefert ausschließlich aggregierte Ergebnisse. Lokale Umgebungen, Laufzeitdaten, MCP-Konfiguration, Zugangsdaten, private Schlüssel, native Traces und vollständige Evaluierungsantworten sind durch .gitignore ausgeschlossen.

Optionale Entwickler-Evaluierung

Die native Codex-Evaluation ist nicht Teil von Installation, setup, doctor, Tests oder CI. Sie kann Modellverbrauch erzeugen und ist bewusst reines Opt-in. Die vollständige Evaluierung besteht aus genau 15 Golden Questions. Jeder Fall verwendet eine frische Antwort-Sitzung und eine separate Judge-Sitzung; deterministische Belegprüfungen sind eine zusätzliche harte Hürde. Ein vollständiger Lauf erzeugt daher 30 Codex-Sitzungen:

uv run --frozen python evals/run_native_matrix.py \
  --output-root evals/results/golden-15-new-run

Der Runner gibt die geplante Anzahl an Antwort- und Judge-Sitzungen vor dem Start aus und schreibt lokale JSON- und Markdown-Urteile. Veröffentlichen Sie ausschließlich Artefakte, die geprüft und bereinigt wurden. Der letzte abgeschlossene Bericht erzielte 14/15 und deckte eine Inkonsistenz der Fairness-Voreinstellung auf, die im aktuellen Code behoben ist. Ein erneuter Lauf nach dem Fix wurde abgebrochen, um den Codex- Verbrauch zu begrenzen. Daher ist jener Bericht ausdrücklich ein Nachweis vor dem Fix und keine aktuelle Zertifizierung. Siehe evals/README.md.

Lizenz

Der Repository-Code ist MIT-lizenziert; die Rechte am Quelldatensatz sind getrennt. Siehe Zulassung, DATA_NOTICE.md, CONTRIBUTING.md und SECURITY.md.