Customer Review MCP Assistant

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

Описание

Проект состоит из двух независимых частей:

1. MCP Server — HTTP-сервер с инструментами (tools) для работы с отзывами в SQLite.
2. Telegram Bot — бот, который принимает обычный текст от пользователя, через LLM выбирает нужный инструмент и вызывает MCP-сервер.

Зачем MCP-style архитектура

В уроке по MCP показан паттерн разделения ответственности:

• Сервер знает только про данные и бизнес-логику (отзывы, статистика, черновики).
• Бот знает только про интерфейс с пользователем и маршрутизацию запросов.
• LLM решает, какой инструмент вызвать, но не имеет прямого доступа к базе данных.
• Инструменты описаны через JSON Schema — единый контракт между сервером и клиентом.

Это упрощённая учебная реализация без полноценного MCP SDK: HTTP endpoints /tools и /call_tool имитируют поведение MCP для понимания идеи.

Структура проекта

customer-review-mcp-assistant/
├── README.md
├── requirements.txt    # Общие зависимости проекта
├── .env.example
├── .gitignore
├── mcp_server/
│   ├── server.py       # FastAPI приложение
│   ├── db.py           # SQLite и тестовые данные
│   └── tools.py        # Инструменты и JSON schema
└── telegram_bot/
    ├── bot.py          # Telegram bot (aiogram 3)
    ├── config.py       # Настройки из .env
    ├── mcp_client.py   # HTTP-клиент к MCP-серверу
    └── llm_router.py   # OpenAI маршрутизатор

MCP Tools

Инструмент	Описание
list_reviews	Последние отзывы
find_reviews	Поиск по тексту или имени клиента
find_reviews_by_rating	Отзывы с конкретной оценкой
find_negative_reviews	Негативные отзывы (оценка 1–2)
add_review	Добавить новый отзыв
get_review_stats	Статистика по отзывам
draft_reply	Черновик ответа (rule-based)
calculate	Безопасный калькулятор

Установка

# Клонировать репозиторий и перейти в папку проекта
cd customer-review-mcp-assistant

# Создать виртуальное окружение в корне проекта
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Скопировать и заполнить переменные окружения
copy .env.example .env

На Linux/macOS вместо Activate.ps1 используйте: source .venv/bin/activate

Заполните в .env:

• TELEGRAM_BOT_TOKEN — токен от @BotFather
• OPENAI_API_KEY — ключ OpenAI API
• OPENAI_MODEL — модель для маршрутизации запросов, по умолчанию gpt-4o-mini
• MCP_SERVER_URL — адрес MCP-сервера, по умолчанию http://127.0.0.1:8008

Запуск MCP Server

Терминал 1 (MCP-сервер должен быть запущен до бота):

.\.venv\Scripts\Activate.ps1
cd mcp_server
python server.py

Сервер будет доступен по адресу: http://127.0.0.1:8008

Проверка:

• http://127.0.0.1:8008/ — статус сервиса
• http://127.0.0.1:8008/tools — список инструментов

Запуск Telegram Bot

Терминал 2 (из корня проекта активируйте venv, затем запустите бота):

.\.venv\Scripts\Activate.ps1
cd telegram_bot
python bot.py

Примеры запросов в Telegram

Запрос пользователя	Что произойдёт
покажи последние отзывы	list_reviews
найди отзывы про доставку	find_reviews с query «доставка»
покажи негативные отзывы	find_negative_reviews
добавь отзыв: Анна, Telegram, 2, доставка задержалась на три дня	add_review
подготовь ответ на отзыв 5 в тёплом тоне	draft_reply
покажи статистику отзывов	get_review_stats
посчитай 15% от 1200	calculate

API MCP Server (учебный)

GET /tools

Возвращает JSON schema всех инструментов.

POST /call_tool

{
  "tool": "list_reviews",
  "arguments": {"limit": 5}
}

Ответ при успехе:

{
  "ok": true,
  "tool": "list_reviews",
  "result": [...]
}

Статус проекта

Проект реализован как учебный MVP:

• MCP-style сервер запускается локально через FastAPI;
• SQLite-база создаётся автоматически и заполняется тестовыми отзывами;
• Telegram-бот подключается к серверу через HTTP;
• LLM используется для выбора подходящего инструмента;
• реальные ключи хранятся в .env и не добавляются в репозиторий.

Что можно улучшить дальше

• Подключить настоящий MCP SDK вместо HTTP-обёртки
• Добавить аутентификацию для MCP-сервера
• Реализовать пагинацию и фильтры по дате
• Сохранять историю диалогов в боте
• Использовать OpenAI для генерации ответов в draft_reply (опционально)
• Добавить Docker Compose для одной команды запуска
• Покрыть tools unit-тестами
• Добавить webhook-режим для Telegram в production

Лицензия

Учебный проект — свободное использование в портфолио и обучении.