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

Этот раздел описывает, как подготовить окружение и запустить все три сервиса PrimeAI локально: MCP‑сервер (mcp-server/), Telegram‑бот (telegram-bot/) и SIP Hook (sip-hook/). Текст рассчитан на разработчика, который впервые видит проект и хочет развернуть его «с нуля».

Предварительные требования

Для работы потребуется актуальная версия Python (рекомендуется 3.11 или новее), установленный сервер MariaDB или MySQL и доступ к OpenAI API. Ключ OPENAI_API_KEY должен позволять использовать Responses API (для текстового бота) и Realtime API (для SIP‑интеграции). Для интеграции с Lardi нужен токен LARDI_API и базовый URL LARDI_BASE_URL. Если планируется передавать данные в 1С, потребуется также ONEC_DISPATCH_URL с нужной авторизацией.

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

В каталоге PrimeAI находятся три сервиса и документация. MCP‑сервер (mcp-server/) реализует доменную логику и инструменты MCP. Telegram‑бот (telegram-bot/) использует Responses API и инструменты MCP для текстового общения. SIP Hook (sip-hook/) принимает webhook‑события от Realtime и стартует голосовой раннер. Документация к проекту хранится в primeai-docs/. Для каждого сервиса обычно создаётся своё виртуальное окружение (venv), а зависимости описаны в собственном файле requirements.txt.

Шаг 1. Подготовка базы данных MariaDB

Сначала нужно создать общую базу данных.

Important

В текущей версии sip-hook SQL‑запросы обращаются к таблицам с явным именем схемы ailogist (например, ailogist.users).
Поэтому база данных должна называться ailogist (и значение MYSQL_DATABASE у всех сервисов должно совпадать с этим именем).

Например:

CREATE DATABASE ailogist CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Затем создайте пользователя и выдайте ему права на эту базу:

CREATE USER 'primeai'@'%' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON ailogist.* TO 'primeai'@'%';
FLUSH PRIVILEGES;

После этого настройте переменные окружения подключения, которые будут использовать все три сервиса: MYSQL_HOST (адрес сервера, например 127.0.0.1), MYSQL_PORT (обычно 3306), MYSQL_USER, MYSQL_PASSWORD и MYSQL_DATABASE (должно быть ailogist). Эти значения читаются:

в MCP‑сервере — из mcp-server/prime_lardi/db.py;
в Telegram‑боте — из telegram-bot/services/mysql_memory.py;
в SIP Hook — из sip-hook/db.py.

Схема таблиц описана в коде моделей: для MCP‑сервера это файл mcp-server/prime_lardi/models.py, для Telegram‑бота — telegram-bot/services/mysql_memory.py. Миграций в проекте сейчас нет: обычно мы работаем с пустой базой, и если схема меняется, проще пересоздать таблицы, чем «перекатывать» данные.

Warning

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

Note

Для сохранения служебного состояния Telegram‑бота (роль, previous_response_id, doc‑flow) нужна таблица user_state. Её DDL лежит в telegram-bot/scripts/20260113_user_state.sql. Если таблицы нет — бот продолжит работать, но будет «забывать» часть состояния после перезапуска.

Если вы хотите только поднять бота и проверить базовый диалог — таблица необязательна. Если тестируете роли, продолжение цепочки Responses (previous_response_id) или сценарии с документами — создайте user_state, иначе состояние будет сбрасываться при перезапуске, и поведение может меняться от запуска к запуску.

Шаг 2. Общие переменные окружения

Часть переменных окружения общая для всех сервисов. Это, прежде всего:

настройки MariaDB (MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE=ailogist);
параметры доступа к Lardi (LARDI_API, LARDI_BASE_URL) — используются в mcp-server;
ключ OpenAI (OPENAI_API_KEY);
адрес MCP‑сервера:
MCP_SERVER_URL — для Responses API (Telegram‑бот) и для SIP Hook (Agents SDK);
MCP_LOCAL_URL — для локального клиента fastmcp в Telegram‑боте (вызов verify_user).

В каталоге каждого сервиса есть пример файла конфигурации: mcp-server/.env.example, telegram-bot/env.example, sip-hook/.env.example. Проще всего скопировать эти файлы в .env и заполнить значениями, согласованными между сервисами.

Шаг 3. Установка зависимостей

Для каждого сервиса создайте виртуальное окружение и установите зависимости. Пример для MCP‑сервера:

cd mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Аналогично для Telegram‑бота:

cd telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

И для SIP Hook:

cd sip-hook
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Шаг 4. Настройка MCP‑сервера

Далее настройте MCP‑сервер. В каталоге mcp-server/ создайте .env на основе .env.example. В этом файле указываются параметры подключения к базе (MYSQL_*), настройки Lardi (LARDI_API, LARDI_BASE_URL), параметры интеграции с 1С (ONEC_DISPATCH_URL, опционально ONEC_DISPATCH_AUTH), а также URL сервисов‑получателей для уведомлений и документов (TG_SERVICE_URL, SIP_SERVICE_URL).

Здесь же можно включить JWT‑аутентификацию для MCP: секрет MCP_AUTH_SECRET, алгоритм MCP_AUTH_ALGORITHM (например, HS256), при необходимости MCP_AUTH_ISSUER, MCP_AUTH_AUDIENCE и список обязательных scopes в MCP_AUTH_SCOPES. Логирование управляется переменной LOG_LEVEL (например, DEBUG или INFO).

JWT на MCP: когда включать

Если MCP‑сервер доступен только из приватной сети и вы доверяете контуру — обычно проще оставить его без JWT: меньше настроек и меньше причин внезапно получить 401.

Если MCP доступен извне (или из «чужих» сетей/контуров) — включайте JWT и передавайте токен клиентам.

Warning

Включили JWT на MCP‑сервере — не забудьте проставить MCP_AUTH_TOKEN в telegram-bot и sip-hook.
Иначе начнут падать вызовы verify_user и MCP‑инструментов (обычно это выглядит как 401/403 в логах клиентов).

Запуск локально:

cd mcp-server
source venv/bin/activate
./run.sh

По умолчанию MCP‑сервер запускается на 0.0.0.0:8082, а MCP‑эндпоинт доступен по адресу http://<host>:8082/mcp. Этот URL нужно указать в переменных окружения других сервисов: для Telegram‑бота — в MCP_SERVER_URL (MCP‑инструменты в Responses API) и MCP_LOCAL_URL (локальный вызов verify_user через fastmcp), для SIP Hook — в MCP_SERVER_URL.

Шаг 5. Настройка Telegram‑бота

Настройка Telegram‑бота начинается с создания .env на основе env.example в каталоге telegram-bot/. В этом файле задаются токен бота (BOT_TOKEN), внешний базовый URL (WEBHOOK_BASE_URL), секретный путь (WEBHOOK_SECRET_PATH), параметры HTTP‑сервера (APP_HOST, APP_PORT), а также параметры БД и OpenAI.

Для интеграции с MCP используются две переменные:

MCP_SERVER_URL — URL MCP‑сервера для Responses API (MCP‑инструменты внутри OpenAI);
MCP_LOCAL_URL — URL MCP‑сервера для локального вызова verify_user (класс MCPIdentityResolver).

Если MCP_SERVER_URL не задан, бот может работать в текстовом режиме без MCP‑инструментов, но MCP_LOCAL_URL нужен для корректного сопоставления tg_id → user_id (без него MCPIdentityResolver не сможет вызвать verify_user, и обработка входящих сообщений фактически ломается).

Запуск локально:

cd telegram-bot
source venv/bin/activate
python main.py

При запуске бот поднимает aiohttp‑приложение, регистрирует обработчик webhook и с помощью WebhookService настраивает URL webhook в Telegram (WEBHOOK_URL = WEBHOOK_BASE_URL + WEBHOOK_SECRET_PATH). Важно, чтобы внешний прокси (nginx, reverse‑proxy, туннель и т. п.) корректно прокидывал запросы Telegram на указанный хост и порт.

Warning

Если вы публикуете весь порт Telegram‑бота наружу (например, через туннель), вместе с webhook станут доступны /cargo-assigned и /cargo-docx — без авторизации.
Обычно наружу открывают только WEBHOOK_SECRET_PATH (и иногда /health), а служебные эндпоинты оставляют доступными только из приватной сети.

Шаг 6. Настройка SIP Hook

Для SIP Hook нужно задать те же базовые параметры OpenAI (OPENAI_API_KEY) и секрет для проверки подписи webhook (OPENAI_WEBHOOK_SECRET). Flask‑приложение слушает порт PORT (по умолчанию 8000).

Через MCP_SERVER_URL (и, при необходимости, MCP_AUTH_TOKEN) задаётся адрес MCP‑сервера для вызова инструментов во время звонка.
Блок MYSQL_* используется для чтения/записи общей истории диалога в ailogist.dialogue_history (см. sip-hook/db.py и sip_hook_app/history_sync.py).

Параметры онлайн‑транскрипции Realtime настраиваются переменными ONLINE_TRANSCRIPTION_MODEL, ONLINE_TRANSCRIPTION_LANGUAGE, ONLINE_TRANSCRIPTION_PROMPT (см. sip-hook/sip_hook_app/config.py).

Дополнительно в SIP Hook есть эндпоинт POST /cargo-assigned для отправки SMS через шлюз Dinstar (настройки DINSTAR_GATEWAY_URL, DINSTAR_GATEWAY_USER, DINSTAR_GATEWAY_PASS).

Запуск локально:

cd sip-hook
source venv/bin/activate
python sip_hook.py

При запуске SIP Hook поднимает Flask‑сервер с двумя маршрутами: POST /sip-hook для приёма событий Realtime и GET /health для проверки статуса. Адрес /sip-hook должен быть указан в настройках Realtime SIP‑интеграции на стороне OpenAI.

Warning

/sip-hook должен быть доступен OpenAI (обычно это означает «публичный URL»).
При этом /cargo-assigned — внутренний маршрут без авторизации. Не публикуйте его наружу: закройте на уровне reverse‑proxy/ACL или выделите отдельный внутренний сервис/порт.

Проверка связности

Когда все три сервиса запущены, имеет смысл выполнить несколько простых проверок. Для MCP‑сервера полезно вызвать инструмент ping_probe из клиента, который умеет работать с MCP (например, через Responses API). Для Telegram‑бота достаточно отправить тестовое сообщение в бизнес‑чат и убедиться, что tg_id успешно сопоставляется с user_id (в логах нет ошибок verify_user), а в таблице dialogue_history появляются строки с каналом telegram. Для SIP Hook можно инициировать тестовый звонок через Realtime SIP и проверить, что номер корректно распознаётся и нормализуется, MCP‑инструмент verify_user находит или создаёт запись в users, а история диалога пополняется событиями с каналом sip. Если на каком‑то шаге возникают проблемы, первым делом стоит посмотреть логи соответствующего сервиса и значения переменных окружения.