Telco MCP

A local, read-only MCP server for governed retention analytics over a checksum-pinned Telco Customer Churn snapshot. Claude Code or Codex interprets business language; the server owns metric definitions, bounded queries, aggregate execution, caveats, and provenance. There is no server-side LLM and no model API key.

Why this exists

This project is inspired by Anthropic's self-service analytics workflow: business users should be able to ask for a number without asking a model to invent SQL or metric logic. The host model interprets intent, while the MCP exposes only reviewed semantic definitions and deterministic aggregate operations. This sharply reduces hallucination risk, but it does not claim that host-model routing or final wording can never be wrong.

Fastest start: hand installation to your agent

Open this repository in Claude Code or Codex and send:

Read INSTALL.md, install and verify this project end to end, and report the final checklist. Follow its stop conditions; do not modify application code or unrelated client configuration.

INSTALL.md is the complete installation runbook. It prepares the pinned data, registers the MCP with the selected clients, verifies the eight-tool protocol, and explains safe recovery and uninstall.

Direct setup

Prerequisites: Git, uv, and Claude Code and/or Codex. Python 3.12 and locked dependencies are managed by uv.

This is a repository-scoped application: clone the source and run it with uv. Standalone wheel or PyPI installation is intentionally unsupported because the semantic catalog and source manifest are repository-level governance assets.

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

Use only installed clients, for example --clients codex. Client authentication is separate from the MCP; the server itself needs no model credentials.

Then ask the client:

Using the telco MCP, what is churn? State the denominator and the snapshot limitation.

A governed answer leads with the reviewed default and labels the alternative:

• 26.5370% = 1,869 / 7,043: certified churned share of all snapshot records and the broad-question default.
• 28.3655% = 1,869 / 6,589: an alternative assumed-starting-base logo churn-rate proxy using Stayed + Churned.

It must say that the data is one Q3 snapshot, not a trend.

What the project provides

• Eight typed MCP tools for business overviews, context, catalog discovery, metrics, segment diagnosis, fairness auditing, recorded churn reasons, and structured capability/refusal guidance.
• Semantic version 4 with five business concepts, 34 governed metrics, and 29 dimensions.
• One- and two-dimensional descriptive breakdowns with bounded filters and populations.
• Aggregate charge, cumulative-revenue, refund, usage, satisfaction, service, and reason analysis.
• Checksum-pinned preparation, read-only DuckDB, source-bound result provenance, and fail-closed verified startup. A synthetic protocol fixture exists only behind explicit opt-in.
• Optional mirrored Claude/Codex Skills that improve routing without replacing the MCP contract.

It intentionally does not provide trends, cohorts, NRR/GRR, revenue churn, forecasts, prediction, causal claims, scenario/annualized impact, ROI, uplift, arbitrary SQL, or customer-level exports.

Architecture

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

The full technical and business explanation—including tools, data, metrics, question coverage, limitations, security, verified examples, and source references—is in docs/PROJECT_GUIDE.md.

Common commands

# 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

Manual repair examples are available in .mcp.json.example and .codex/config.toml.example. Prefer setup because it resolves exact paths and refuses conflicting registrations unless --replace is explicitly approved.

Data and privacy

The source is a fictional/simulated Q3 California snapshot with 7,043 unique customer records. The three source files, revision, and SHA-256 values are pinned in data/source_manifest.json. Raw CSVs and prepared DuckDB artifacts are not committed because redistribution rights have not been confirmed. Read DATA_NOTICE.md before downloading or using the upstream data.

The service exposes aggregate results only. Local environments, runtime data, MCP configuration, credentials, private keys, native traces, and full evaluation response records are excluded by .gitignore.

Optional developer evaluation

Native Codex evaluation is not part of installation, setup, doctor, tests, or CI. It can consume model usage and is intentionally opt-in. The complete evaluation is exactly 15 golden questions. Each case uses one fresh answer session and a separate judge session; deterministic evidence checks are an additional hard gate. A full run therefore launches 30 Codex sessions:

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

The runner prints the planned answer/judge count before starting and writes local JSON and Markdown verdicts. Publish only artifacts that have been reviewed and sanitized. The last completed report scored 14/15 and exposed a fairness-default inconsistency that is fixed in the current code. A post-fix rerun was stopped to control Codex token usage, so that report is explicitly pre-fix evidence rather than current certification. See evals/README.md.

License

Repository code is MIT licensed; source-dataset rights are separate. See LICENSE, DATA_NOTICE.md, CONTRIBUTING.md, and SECURITY.md.