📚 Библиотека — MCP-проект

MCP-проект для управления каталогом книг, состоящий из MCP-сервера, CLI-клиента и Telegram-бота.

📋 Содержание

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

• Установка

• Запуск

• MCP-инструменты

• CLI-клиент

• Telegram-бот

• API Endpoints

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

• Технологии

Related MCP server: MCP Open Library & File Search Server

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

├── .env.example          # Пример конфигурации
├── .gitignore            # Игнорируемые файлы
├── requirements.txt      # Зависимости Python
├── README.md             # Этот файл
├── TEST_RESULTS.md       # Результаты тестирования
├── TEST_PLAN_v1.2.0.md   # План тестирования LLM-контекста (v1.2.0)
├── ProgressOfWork.md     # Журнал работы
├── mcp_server/
│   ├── __init__.py
│   ├── server.py         # FastAPI сервер
│   ├── db.py             # Работа с SQLite
│   ├── tools.py          # MCP-инструменты
│   └── library.db        # База данных (создаётся автоматически)
├── cli_client.py         # CLI-клиент для тестирования
└── telegram_bot/
    ├── __init__.py
    ├── bot.py            # Telegram-бот (словарь команд + state machine)
    ├── llm.py            # LLM fallback (GPT с историей диалога)
    ├── config.py         # Загрузка .env
    └── mcp_client.py     # Вызов MCP-инструментов

🛠 Установка

1. Создайте виртуальное окружение:

   python -m venv venv

2. Активируйте виртуальное окружение:

   • Windows:

     venv\Scripts\activate

   • Linux/macOS:

     source venv/bin/activate

3. Установите зависимости:

   pip install -r requirements.txt

4. Настройте переменные окружения:

   copy .env.example .env    # Windows
   cp .env.example .env      # Linux/macOS

   Отредактируйте .env, указав свои значения API-ключей и токена бота.

🚀 Запуск

1. MCP-сервер

python mcp_server/server.py

Сервер запускается на http://localhost:8000. Логи записываются в mcp_server/library.log.

2. CLI-клиент

python cli_client.py

Клиент подключается к запущенному MCP-серверу и работает через интерактивное нумерованное меню.

3. Telegram-бот

python telegram_bot/bot.py

Бот запускается и ожидает сообщения от пользователей.

⚠️ Если бот не запускается с ошибкой Read timed out — Telegram API недоступен в вашей сети. Укажите прокси в .env:

TELEGRAM_PROXY_URL=http://127.0.0.1:8080

Также можно увеличить таймаут: TELEGRAM_TIMEOUT=60

🧰 MCP-инструменты

💻 CLI-клиент

CLI-клиент использует структурированное нумерованное меню для взаимодействия с сервером.

Возможности:

• 📚 Показать все книги — каталог с пагинацией

• 🔍 Найти книгу по названию — поиск по ключевым словам

• 👤 Найти книгу по автору — поиск по имени автора

• 📖 Найти книгу по жанру — выбор из списка доступных жанров

• ➕ Добавить книгу — пошаговый ввод (название → автор → жанр → год)

• 🧮 Калькулятор — вычисление математических выражений

• 📊 Статистика — общее количество книг и жанров

• 🧹 Очистка БД — удаление всех книг (с подтверждением)

Пример работы:

📚 Библиотека — CLI клиент

Выберите действие:
1. 📚 Показать все книги
2. 🔍 Найти книгу по названию
3. 👤 Найти книгу по автору
4. 📖 Найти книгу по жанру
5. ➕ Добавить книгу
6. 🧮 Калькулятор
7. 📊 Статистика
8. 🧹 Очистить БД
0. Выйти

📖 > 1

🤖 Telegram-бот

Telegram-бот использует гибридный подход:

• Детерминированные команды — словарь точных команд (быстро, без API-запросов)

• LLM fallback — если команда не распознана, фраза отправляется в GPT вместе с историей диалога (понимает свободную речь и контекст)

• Память диалога — бот помнит последние 10 сообщений, умеет показывать историю (/history) и повторять последнее действие («ещё раз»)

Возможности:

• 📚 Показать все книги — текстовый список

• 🔍 Найти книгу по названию — с обложкой (из Open Library API)

• 👤 Найти книгу по автору — текстовый список

• 📖 Найти книгу по жанру — выбор из списка жанров или ввод текстом

• ➕ Добавить книгу — пошаговый ввод (название → автор → жанр с кнопками → год)

• 🧮 Калькулятор — вычисление выражений

• 🗑️ Очистить историю — сброс состояния

• 🚪 Выйти — остановка бота

Приветствие бота:

👋 Привет! Я бот для работы с базой данных книг.

Я могу помочь Вам:
▪️ Показать все книги
▪️ Найти книгу по названию
▪️ Найти книгу по автору
▪️ Найти книгу по жанру
▪️ Добавить новую книгу
▪️ Выполнить математические вычисления

Просто напишите мне, что Вы хотите сделать, например:
▪️ /all_books или "покажи все книги"
▪️ /find_book или "найди книгу по названию"
▪️ /find_author или "найди книгу по автору"
▪️ /find_genre или "найди книгу по жанру"
▪️ /add_book или "добавь новую книгу"
▪️ /calc 10*5 или "сколько будет 10*5"

Команды бота:

Как работают команды:

📚 Просмотр каталога:

• \/all_books — мгновенно показывает список всех книг

🔍 Поиск:

• \/find_book → бот просит ввести название → показывает результат с обложкой

• \/find_author → бот просит ввести имя автора → показывает список

• \/find_genre → бот показывает кнопки с жанрами из БД → выбираете жанр

➕ Добавление книги:

• \/add_book → пошаговый ввод: название → автор → жанр (кнопки) → год (опционально)

• Или одной фразой через LLM: добавь книгу Метро 2033, Глуховский, фантастика, 2002

🧮 Калькулятор:

• \/calc → введите математическое выражение (например: 10 * 5 + 3)

• Или сразу: сколько будет 2+2*3, calc 10*5, просто 2+2*3

📜 История диалога:

• \/history — показать последние 10 сообщений

• ещё раз / повтори — повторить последнее действие

⚙️ Управление:

• \/clear — сбросить текущую операцию

• \/exit — завершить работу бота

• \/help — показать полную справку

Свободная речь (LLM):

Если фраза не входит в словарь команд, бот отправляет её в GPT вместе с историей диалога. LLM возвращает JSON с действием, бот выполняет его через MCP-инструменты:

💡 Известные команды обрабатываются словарём без обращения к LLM — мгновенно и без расхода API.

Текстовые команды:

Помимо команд с /, бот понимает обычные текстовые команды на русском и английском:

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

1. Пользователь получает главное меню при /start

2. Команды из словаря обрабатываются мгновенно (без LLM)

3. Свободные фразы отправляются в LLM с историей диалога (контекст помнит 10 сообщений)

4. При поиске по названию бот показывает обложку книги (через Open Library API)

5. Если обложка не найдена — показывается дефолтная обложка с emoji 📕

6. Состояние диалога отслеживается для многошаговых операций (добавление книги)

7. Поиск в БД не зависит от регистра и падежей («войну» найдёт «Война»)

8. Все команды регистрируются в Telegram автоматически при запуске (set_my_commands)

🔌 API Endpoints

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

1. Подготовка

• ✅ Убедитесь, что все зависимости установлены: pip install -r requirements.txt

• ✅ Проверьте, что файл .env создан и содержит корректные ключи

• ✅ База данных library.db создаётся автоматически при первом запуске сервера

2. Тестирование MCP-сервера

Запуск:

python mcp_server/server.py

Проверки:

• ✅ Сервер запускается без ошибок

• ✅ В папке mcp_server/ создаётся файл library.db

• ✅ Документация FastAPI доступна по адресу: http://127.0.0.1:8000/docs

• ✅ Эндпоинты /tools/* возвращают данные в формате JSON

• ✅ Эндпоинт /health возвращает {"status": "ok"}

• ✅ Логи записываются в mcp_server/library.log

3. Тестирование CLI-клиента

Запуск:

python cli_client.py

Тестовые запросы:

Результат: CLI-клиент работает корректно, все 21 тест пройден.

4. Тестирование Telegram-бота

Запуск:

python telegram_bot/bot.py

Команды:

Текстовые команды:

Функции:

• ✅ Текстовые команды (рус/англ) + свободная речь через LLM

• ✅ Контекст диалога (/history, «ещё раз»)

• ✅ Пошаговый ввод параметров + добавление одной фразой

• ✅ Обложки книг (Open Library API)

• ✅ Дефолтная обложка при отсутствии

• ✅ Состояние диалога (state machine)

• ✅ Кнопки выбора жанра

• ✅ Работа через прокси (TELEGRAM_PROXY_URL)

5. Проверка логирования

• ✅ Логи записываются в mcp_server/library.log

• ✅ Логи содержат информацию о запуске, инициализации БД и запросах

• ✅ Консольный вывод минимизирован (только запуск/остановка сервера)

📋 Чек-лист результатов

💻 Технологии

• Python 3.11+

• FastAPI — веб-фреймворк

• SQLite — база данных

• pyTelegramBotAPI — Telegram-бот

• OpenAI API (ProxyAPI) — LLM fallback для свободной речи

• requests — HTTP-запросы

• colorama — цветной вывод в CLI

📝 Примечания

• База данных автоматически инициализируется при первом запуске сервера (30 тестовых книг)

• Telegram-бот требует настроенного токена в .env

• LLM fallback использует OPENAI_API_KEY из .env (ProxyAPI); без ключа бот работает в детерминированном режиме

• Если api.telegram.org недоступен напрямую — укажите TELEGRAM_PROXY_URL в .env

• Обложки книг подтягиваются из Open Library API (covers.openlibrary.org)

• При отсутствии обложки показывается дефолтная SVG-обложка с emoji 📕

• Логи хранятся в mcp_server/library.log