Telco MCP

Локальный MCP-сервер только для чтения для управляемой аналитики удержания по снимку оттока телеком-клиентов (Telco Customer Churn), зафиксированному контрольными суммами. Claude Code или Codex интерпретирует бизнес-язык; серверу принадлежат определения метрик, ограниченные запросы, агрегатные вычисления, оговорки и данные о происхождении. На стороне сервера нет LLM и нет API-ключа модели.

Зачем это существует

Этот проект вдохновлён самообслуживаемым аналитическим процессом Anthropic: бизнес-пользователи должны иметь возможность запросить цифру, не прося модель выдумывать SQL или метрическую логику. Хост-модель интерпретирует намерение, а MCP-сервер предоставляет только выверенные семантические определения и детерминированные агрегатные операции. Это резко снижает риск галлюцинаций, но не утверждает, что маршрутизация хост-модели или итоговая формулировка никогда не могут быть ошибочными.

Related MCP server: spreadsheet-qa-kit MCP server

Самый быстрый старт: ручная установка через вашего агента

Откройте этот репозиторий в Claude Code или Codex и отправьте запрос:

Прочитай INSTALL.md, установи и проверь этот проект целиком и отчитайся по итоговому чек-листу. Соблюдай его стоп-условия; не изменяйте код приложения и несвязанную конфигурацию клиентов.

ВЕЩ — полное руководство по установке. Оно подготавливает зафиксированные данные, регистрирует MCP у выбранных клиентов, проверяет протокол из восьми инструментов и объясняет безопасное восстановление и удаление.

Прямая настройка

Предварительные требования: Git, uv, а также Claude Code и/или Codex. Python 3.12 и зафиксированные зависимости управляются через uv.

Это приложение уровня репозитория: клонируйте исходники и запускайте через uv. Установка отдельного wheel или через PyPI намеренно не поддерживается, потому что семантический каталог и манифест исходников — это governance-активы уровня репозитория.

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

Используйте только установленные клиенты, например --clients codex. Аутентификация клиента отделена от MCP; сам сервер не требует учётных данных модели.

Затем задайте клиенту вопрос:

Используя telco MCP, что такое churn? Назови знаменатель и ограничение снапшота.

Управляемый ответ начинается с выверенного значения по умолчанию и явно помещает альтернативу:

• 26.5370% = 1,869 / 7,043: сертифицированная доля оттока среди всех записей снапшота и значение по умолчанию для широкого вопроса.

• 28.3655% = 1,869 / 6,589: альтернативный прокси-показатель logo-уровня оттока с предполагаемой стартовой базой, использующий Stayed + Churned.

В answers обязательно сказать, что данные — это один Q3-снапшот, а не тренд.

Что даёт проект

• Восемь типизированных MCP-инструментов: бизнес-обзоры, контекст, поиск по каталогу, метрики, диагностика сегментов, аудит непредвзятости, зафиксированные причины оттока и структурированные указания о возможностях и отказах.

• Семантическая версия 4 с пятью бизнес-концепциями, 34 управляемыми метриками и 29 измерениями.

• Одномерные и двухмерные описательные срезы с ограниченными фильтрами и совокупностями.

• Агрегационный анализ начислений, накопительной выручки, возвратов, использования, удовлетворённости, сервиса и причин.

• Подготовка с закреплением контрольных сумм, DuckDB в режиме только для чтения, привязка результатов к источнику, проверяемый запуск по принципу fail-closed. Синтетический протоколный fixture существует только за явным opt-in.

• Опциональные зеркальные навыки Claude/Codex, улучшающие маршрутизацию, не заменяя контракт MCP.

Он намеренно не предоставляет: трендов, когорт, NRR/GRR, оттока выручки, прогнозов, предсказаний, каузальных утверждений, масштабирования, ROI, uplift, произвольного SQL и выгрузки на уровне клиентов.

Архитектура

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

Полное техническое и бизнес-описание — инструменты, данные, метрики, покрытие вопросов, ограничения, безопасность, проверенные примеры и ссылки — находится в [docs/PROJECT_GUIDE.md.

Частые команды

# 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

Примеры ручного восстановления есть в .mcp.json.example и .codex/config.toml.example. Предпочитайте setup: он резолвит точные пути и отказывает в конфликтующих регистрациях, если только явно не одобрен --replace.

Данные и конфиденциальность

Источник — вымышленный/симуляционный Q3-снапшот Калифорнии с 7 043 уникальными записями клиентов. Три исходных файла, ревизия и значения SHA-256 зафиксированы в data/source_manifest.json. Текстовые CSV и подготовленные артефакты DuckDB не фиксируются в репозитории, потому что права на ре-редакционную дистрибуцию не подтверждены. Прочитайте DATA_NOTICE.md перед загрузкой или использованием данных из вышележащего источника.

Сервис отдаёт только агрегированные результаты. Локальные окружения, рантайм-данные, конфигурация MCP, учётные данные, частные ключи, нативные трейсы и полные журналы оценых ответов исключены через .gitignore.

Опциональная оценка для разработчиков

Нативная оценка с Codex не входит в установку, настройку, doctor-проверку, тесты или CI. Она может потреблять токены использования модели и намеренно является opt-in. Полная процедура — ровно 15 «golden» вопросов. Каждый кейс использует одну новую сессию генерации ответа и отдельную сессию судьи; детерминированная проверка evidence является дополнительным «жёстким» барьером. Полный прогон запускает 30 сессий Codex:

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

Ранем печатает запланированное количество сессий ответа/судьи перед запуском и пишет локальные версии JSON и Markdown. Публикуйте только рецензированные и санитизированные артефакты.Последний завершённый отчёт показал 14/15 и выявил несогласованность дефолта fairness, исправленную в текущем коде. Повторный прогон после исправления был остановлен для контроля потребления токенов Codex, поэтому этот отчёт — явное доказательство до исправления, а не текущая сертификация. См. evals/README.md.

Лицензия

Код репозитория под лицензией MIT; права на исходный набор данных выделены отдельно. См. LICENSE, DATA_NOTICE.md, CONTRIBUTING.md и SECURITY.md.