# 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](https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude): 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`](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`](https://docs.astral.sh/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.

```bash
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

```text
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`](docs/PROJECT_GUIDE.md).

## Common commands

```bash
# 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`](.mcp.json.example) and
[`.codex/config.toml.example`](.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`](data/source_manifest.json). Raw CSVs and prepared DuckDB artifacts are
not committed because redistribution rights have not been confirmed. Read
[`DATA_NOTICE.md`](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`](.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:

```bash
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](evals/results/golden-15-pre-fix/report.md)
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`](evals/README.md).

## License

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