Frontline Copilot

ИИ-ассистент для сортировки отзывов в розничных сетях.

Постоянно работающая система, которая собирает отзывы клиентов из любых источников, использует Claude для классификации по категориям и уровню важности, и направляет требующие реакции отзывы в список задач Airtable менеджера магазина — с мгновенными оповещениями в Slack о критических проблемах (безопасность продуктов, поведение персонала, здоровье клиентов).

Также доступен в виде MCP-сервера, чтобы менеджеры магазинов могли работать с отзывами в диалоговом режиме через Claude Desktop.

Вдохновлено новой категорией ИИ-ассистентов для управления магазинами.

Проблема

Менеджеры магазинов в розничных сетях тонут в потоке отзывов клиентов. Большинство из них — шум (похвала или мелкие замечания). Некоторые — срочные (безопасность продуктов, дискриминация, риск для здоровья). Большинство инструментов требуют, чтобы менеджер читал всё, чтобы найти важное — проигрышная битва в масштабе сети.

Frontline Copilot меняет подход. Claude читает всё; менеджер видит только то, что требует действий.

Related MCP server: Shopify MCP Server

Как это работает

┌────────────┐   ┌──────────────┐   ┌────────────┐   ┌────────────┐
│  Reviews   │──▶│ Classifier   │──▶│  Airtable  │──▶│   Slack    │
│  (JSON /   │   │ (Claude API, │   │  (task     │   │  (critical │
│   Google)  │   │  tool use)   │   │  tracker)  │   │   alerts)  │
└────────────┘   └──────────────┘   └────────────┘   └────────────┘
                        │
                        ▼
                 ┌──────────────┐
                 │  MCP server  │◀── Claude Desktop, Cursor, ...
                 │  (3 tools)   │
                 └──────────────┘

Каждый отзыв классифицируется по одной из девяти категорий с уровнем важности от 1 (позитивный) до 5 (критический). Отзывы с важностью ≥ 3 попадают в задачи Airtable; отзывы с важностью ≥ 4 дополнительно запускают оповещение в Slack.

Скриншоты

Полный цикл обработки

21 отзыв обработан за ~60 секунд. Создано 7 задач, 4 критических оповещения в реальном времени.

Airtable — доска задач

Задачи отсортированы по важности, цветовая кодировка по категориям. Так выглядит рабочий стол менеджера магазина.

Airtable — вид Канбан

Те же данные, сгруппированные по категориям. Распределение проблем с первого взгляда.

Slack — оповещения о критических проблемах

Карточки Block Kit с приоритетным отображением и прямой ссылкой на задачу в Airtable.

Технологический стек

• Python 3.10+ — dataclasses, str | None union types, pathlib

• Anthropic API — классификация через инструменты (claude-haiku-4-5)

• Airtable REST API — трекер задач, вызовы через requests

• Slack Incoming Webhooks — Block Kit для информативных карточек оповещений

• MCP (Model Context Protocol) — диалоговый интерфейс через FastMCP

• Паттерн «Адаптер» для источников отзывов (встроенный Mock; заглушка для Google Places)

Всего три сторонние зависимости: anthropic, requests, mcp. Всё остальное — стандартная библиотека.

Быстрый старт

# 1. Clone and install
git clone https://github.com/miguelpomarm/frontline-copilot
cd frontline-copilot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets
cp .env.example .env
# ... edit .env with your keys (see setup section below)

# 3. Run the pipeline
python triage.py

# 4. Launch as an MCP server (optional)
python mcp_server.py

Настройка (одноразовая, ~10 минут)

1. Ключ Anthropic API

Получите ключ на https://console.anthropic.com/. Бесплатного тарифа достаточно для демонстрации — 21 отзыв обойдётся примерно в ~$0.03.

2. База Airtable

Создайте новую базу с таблицей Tasks и следующими полями (точные названия):

Затем создайте персональный токен на https://airtable.com/create/tokens с правами data.records:read и data.records:write для вашей базы. Скопируйте токен и ID базы (начинается с app..., указан в URL вашей базы).

3. Входящий вебхук Slack

Создайте приложение Slack на https://api.slack.com/apps. Включите Incoming Webhooks, добавьте вебхук, указывающий на канал, куда должны приходить критические оповещения, и скопируйте URL вебхука.

4. Заполните .env

ANTHROPIC_API_KEY=sk-ant-...
AIRTABLE_API_KEY=pat...
AIRTABLE_BASE_ID=app...
AIRTABLE_TABLE_NAME=Tasks
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

5. Первый запуск

python triage.py --limit 3 --dry-run   # sanity check, no side effects
python triage.py --limit 3             # small live run
python triage.py                       # full 21 reviews

Интеграция с MCP (Claude Desktop)

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) и перезапустите Claude Desktop:

{
  "mcpServers": {
    "frontline-copilot": {
      "command": "python",
      "args": ["/absolute/path/to/frontline-copilot/mcp_server.py"]
    }
  }
}

Затем в Claude Desktop:

«Как обстоят дела в Aurora Times Square?»

Claude вызовет get_health("times_square"), обратится к Airtable и ответит актуальной сводкой — открытые задачи, критические проблемы, основные категории.

Архитектурные решения

Обдуманный выбор, о котором стоит рассказать ревьюеру:

Фиксированная таксономия + категория Other Категории — это фиксированный enum, а не свободная форма. Это гарантирует единообразие маршрутизации и метрик. Категория Other — страховочный вариант, который периодически пересматривается для расширения таксономии на основе реальных данных, а не предположений.

Использование инструментов вместо промпт-инжиниринга Claude возвращает структурированный результат через схему инструмента с контролем enum. Это исключает ошибки парсинга и предотвращает «галлюцинации» модели с категориями вне таксономии.

Haiku 4.5 как модель по умолчанию Для узкой задачи классификации Haiku достаточно быстр (доли секунды), дёшев (~$0.001 за отзыв) и точен. В production это решение экономит тысячи долларов в месяц при умеренном трафике.

Паттерн «Адаптер» для источников отзывов ReviewSource — абстрактный интерфейс. В комплекте идёт MockSource и документированная заглушка GooglePlacesSource. Подключение Trustpilot, Yelp или собственного источника — это новый подкласс, остальной конвейер не меняется.

Идемпотентность по ID отзыва Повторная обработка одних и тех же отзывов не создаёт дубликатов задач. Перед созданием выполняется проверка в Airtable.

Пороги важности как настраиваемые константы ACTION_THRESHOLD и ALERT_THRESHOLD — константы уровня модуля. Другим клиентам с иными требованиями достаточно изменить два числа, а не код.

Синхронность для MVP 21 отзыв обрабатывается последовательно за ~40 секунд. Асинхронный вариант — это замена ~15 строк (AsyncAnthropic + asyncio.gather с семафором для ограничения частоты запросов). При таком объёме читаемость кода важнее скорости.

Текст важнее звёзд В промпте явно указано: модель оценивает текст отзыва, а не рейтинг. Отзыв на 4 звезды с упоминанием безопасности продуктов получает важность 5, а не 2.

Планы развития (не реализовано)

• FastAPI вебхук (POST /webhook/review) — обработка отзывов в реальном времени вместо пакетных запусков.

• GooglePlacesSource — интерфейс адаптера готов, реализация займёт ~1 час: интеграция с API + логика повторов.

• Асинхронная пакетная обработка с учётом лимитов — для больших объёмов.

• End-to-end тесты (Playwright / pytest с записанными взаимодействиями с API), проверяющие работу с Airtable и Slack.

• Настраиваемые пороги для каждого клиента через config.yaml.

Лицензия

MIT — см. LICENSE.

Создано Miguel Pomar Martínez как техническое портфолио-проект.