venue-ops-mcp

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

You: is anything leaking this week?

Claude: Eixample (BCN-01) — voided tickets have drifted from 1.55% of gross
to 4.60% over the last seven days, against a 28-day baseline. That is
799.16 EUR over the window. It is not a spike on one shift; it is a slope
across the whole week, which is the shape a till problem makes.

Зачем это нужно

Большинство инструментов отчетности отвечают на вопрос, который все и так задают: что мы продали? Продажи — легкая цифра. Они есть в кассе, на панели управления, в WhatsApp-группе к десяти минутам после полуночи.

Цифры, определяющие прибыльность точки — это скидки, комплименты и аннулированные чеки (контрольный блок) — и они почти никогда не попадают в ежедневный отчет. Повышение доли аннулированных чеков с 1% до 4% за три недели незаметно в рамках одного вечера. Это выглядит как плохой вторник, затем тихий четверг. Проблема становится очевидной только при сравнении одного периода с предыдущим, что и делает этот сервер.

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

Инструменты

Каждый инструмент доступен только для чтения, аннотирован как таковой и принимает response_format: "markdown" для человека или "json" для программы.

Два типа аномалий

venue_ops_find_anomalies сравнивает последние 7 дней с 28 предшествующими и сообщает о двух разных явлениях, так как они имеют разное значение:

• Дрейф — весь последний период сместился. Неисправленный график, проблема с кассой, менеджер, начавший делать комплименты для поддержания мира. Это дорогостоящая проблема, и ее никто не замечает.

• Всплеск — один день, сильно выбивающийся из базового уровня. Обычно незарегистрированная акция. Дешево объяснить, стоит подтвердить.

Отклонения менее 40 EUR отбрасываются. Они реальны, но не стоят телефонного звонка, а отчет, который кричит "волк", перестают читать к третьей неделе.

Данные

data/operations.json является синтетическим. Три точки, 182 дня, сгенерированы scripts/generate_data.py с фиксированным зерном для воспроизводимости результатов. Это не реальный бизнес, и никакой реальный бизнес по нему не идентифицируется.

Цифры вымышлены, но структура — нет. Сезонность по дням недели, соотношение dine-in / delivery, уровень скидок и аннулирования, а также процент трудозатрат находятся в пределах диапазонов, наблюдаемых в casual dining.

Три аномалии внесены намеренно, чтобы детектор нашел что-то реальное, и чтобы каждый мог проверить его работу:

Чтобы подключить это к реальной POS-системе, замените загрузчик в venue_ops_mcp/data.py. Уровень инструментов не заботится о происхождении строк.

Установка

pip install -r requirements.txt
python scripts/generate_data.py

Использование с Claude Desktop

Добавьте это в claude_desktop_config.json:

{
  "mcpServers": {
    "venue-ops": {
      "command": "python",
      "args": ["-m", "venue_ops_mcp.server"],
      "cwd": "/absolute/path/to/venue-ops-mcp"
    }
  }
}

Перезапустите Claude Desktop. Затем задавайте такие вопросы:

• Какие точки у нас есть?

• Как дела у Gran Via в прошлую субботу по сравнению с предыдущими субботами?

• Проверь Барселону на проблемы за неделю, закончившуюся 5 июля.

• Каковы итоги сети за июль?

Проверка

python scripts/smoke_test.py    # every tool, and the planted anomalies
python scripts/stdio_check.py   # the MCP handshake a real client performs

smoke_test.py проверяет, что дрейф в Барселоне все еще обнаруживается, и что чистый период не дает результатов. Детектор, срабатывающий на все подряд, хуже, чем отсутствие детектора, поэтому проверяются оба направления.

Создано с помощью

Python 3.10+, MCP Python SDK (MCPServer, stdio transport), Pydantic v2 для валидации входных данных. Нет внешних сервисов, нет учетных данных, нет сетевых вызовов — сервер только читает локальный файл.

Лицензия

MIT.