Funnel Calibrator

MCP-сервер, который перекалибрует рекламные решения на основе того, что воронка продаж делает на самом деле, — а не того, что ей приписывают.

⚠️ Статус: работа в процессе. Каркас и дизайн зафиксированы; реализация MCP-сервера появится 24 августа 2026 года. Защита: 25 августа 2026 года.

KSE AI Agentic Lab — индивидуальное лабораторное задание (неделя 7, интеграция MCP).

Какую проблему решает проект

Проект построен на реальном украинском e-commerce бизнесе с оплатой при доставке (COD), который продаёт женскую одежду через рекламу в Meta. Его воронка состоит из пяти этапов:

Meta ads ──► Lead ──► Call-centre approval ──► Shipment ──► Buyout at post office ──► Profit

Поскольку оплата происходит при доставке, результат рекламной кампании неизвестен в момент, когда деньги потрачены. Он становится известен через две-четыре недели, когда клиент либо забирает посылку, либо нет. Бизнес закрывает этот разрыв двумя константами на уровне всего портфеля — 65% долей подтверждения и 52,5% долей выкупа — и использует их, чтобы для каждого товара рассчитать максимальную стоимость лида, при которой товар всё ещё работает в ноль (Stop CPL), и целевую стоимость, к которой нужно оптимизировать (Goal CPL).

Эти константы являются средними по портфелю, но применяются к отдельным товарам, и отдельные товары очень сильно от них отклоняются. Вот измеренные примеры из реального бизнеса: товары одного производителя выкупаются по 37% против входных 52,5%; у одного товара доля подтверждения составила 53% против принятых 65%; доля выкупа сильно коррелирует с ценовым сегментом: от примерно 93% в категории 690–790 ₴ до примерно 55% в категории выше 1290 ₴.

Когда реальные показатели товара хуже исходных выводах трактовы правда ниже, чем цифра, на которую ориентируется бизнес: реальная точка безубыточности по CPL ниже расчётной. Поэтому рекламная цель может находиться выше истинной точки безубыточности. В рекламном кабинете трафик выглядит здоровым, а каждый лид приносит убыток — и этот убыток становится виден только на закрытии месяца, спустя недели.

Это разомкнутая система без обратной связи: измерение никогда не возвращается в решение. Funnel Calibrator замыкает контур управления.

Related MCP server: KrystalView MCP Server

Что он делает

Сервер измеряет собственные показатели воронки каждого товара на основе исторических данных по заказам, пересчитывает истинные границы CPL этого товара и сверяет предлагаемых рекламных решений с исправленными цифрами — то есть возвращает структурированные доказательства, а не версовое решение, сказанное «на веру».

Две проблемы осложняют эту задачу, и обе явно учтены в контрактах инструментов:

• Цензурирование. Свежие заказы ещё не завершены — посылка в пути это ни выкуп, ни возврат. Наивный подсчёт таких заказов искусственно закладывает показатели. Сервер исключает когорты, воздушие выбранного окна созревания, и показывает, сколько заказов он отложил.

• Небольшие выборки. При последовательном по собеседению, по самому товару, по его размеру и цвету численность групп опасно уменьшается. Каждое измерение сопровождается отчётные размера выборки и флагом надёжности, а сервер при снижении ниже настраиваемого порога не делает выводы, вместо того чтобы выдавать несорамерную шумовой результат за уверенный.

Архитектура

┌─────────────────────────────────────────────────────────────┐
│  Agent  (Claude Agent SDK)                                  │
│                                                             │
│    ├── MCP ──► Obsidian Local REST API      [existing]      │
│    │           decision journal: reads the day's objective  │
│    │           and prior conclusions, writes calibrated      │
│    │           verdicts back as a durable record            │
│    │                                                         │
│    └── MCP ──► Funnel Calibrator            [custom]        │
│                measure → recalibrate → recommend → audit    │
│                        │                                     │
│                        ▼                                     │
│                 local snapshot dataset                       │
│                 (anonymised order cohorts + unit economics)  │
└─────────────────────────────────────────────────────────────┘

Кастомный MCP-сервер работает как отдельный процесс и обменивается по протоколу, поверх stdio, и его можно запускать независимо от агента.

Поток работы агента

1. Читает из хранилища Obsidian сегодняшнюю рекламную задачу и вчерашние выводы.

2. Измеряет в снапшоте наблюдаемые показатели воронки для каждого товара (с учётом цензурирования и размеров выборки).

3. Пересчитывает для товара его настоящие границы Stop/Goal CPL и расхождение с исходно принятой константой.

4. Не указывает процедуру, почему товар работает плохо — правильный ответ зависит от причины — и рекомендует следующее действие.

5. Сверяет предложенную на сегодня рекламные решения с исправленными границами.

6. Записывает по калlibrированного заключения и всю цепочку доказательств назад в хранилище.

В каждый шаг использует выход предыдущего шага: содержимое хранилища определяет, что измеряем, намерение определяют исправленные границы, а границы определяют, сколько действия принято или состоянии своей силы.

Пользовательские инструменты (Prompty strings?)

Полные входные/выходные схемы, коды ошибок, внешние эффекты и развёрнутые примеры: docs/tool-contracts.md.

Почему эти четыре инструмента, почему они находились именно на границе между MCP и, и чем проект сознательно не поумнет: docs/design-rationale.md.

Данные

Локальный анонимизированный «сдельный» набор данных — история когоорт заказов, оказание из CRM бизнеса с помощью скрипта scripts/export_snapshot.py. Для запуска не требуется ни авторизация, ни доступа в сеть, поэтому демонстрация строго детерминирована и воспроизводима всегда.

При экспорте удаляются все идентификационные данные личности: имя, номер мобильного, адреса, номера отправлений. В срезе данных это только то, что требуется для калибровки: код товара, статус заказа, время, суммы и юнит-экономика. Политика анонимизации и схема данных описаны в data/README.md.

Быстрый запуск

Предварительные требования: Python ≥ 3.11 и uv. Obsidian и плагин Local REST API нужны только для агентского сценария, но не для работы самого сервера.

git clone https://github.com/denkor1015-debug/funnel-calibrator.git
cd funnel-calibrator
uv sync

Запустите MCP-сервер автономно (сервер общается по протоколу MCP через stdio и ожидает появления клиента):

uv run funnel-calibrator

Просмотрите отстрutiбельноیه موجود инструменты с помощью MCP Inspector:

npx @modelcontextprotocol/inspector uv run funnel-calibrator

Конфигурация читается из переменных окружения; скопируйте шаблон и отредактируйте:

cp .env.example .env

Интеграция агента для обоих MCP-подключений: agent/mcp_config.example.json.

Структура репозитория

src/funnel_calibrator/   MCP server: tool definitions, calibration math, policy engine
scripts/                 snapshot exporter (CRM ──► anonymised local dataset)
data/                    snapshot dataset + anonymisation policy
docs/                    tool contracts, design rationale, defence checklist
agent/                   MCP client configuration for both connections
tests/                   unit tests for calibration and policy logic

План разработки

• Каркас репозитория, архитектура и rationale проекта

• Экспорттер снапшотов в честное удаление PII

• measure_sku_funnel — цензурrollup и фильтр по размеру выборки

• recalibrate_cpl_bounds — перекомпановка юнит-экономики

• recommend_next_action — диагностика типа неисприй, leading

• audit_ad_verdict — проверка решений по адекватности

• Интеграция Obsidian MCP и полная связка агента

• Обработка сценариев сбоя и демонстрация

• Документация контрактов инструментов и сценарий защиты

Матрица требований задания

Licence

MIT — см. LICENSE.