MCP Servers

Product-MCP + Telegram Bot

Полный пример проекта, состоящего из MCP-сервера товаров и Telegram-бота, который использует OpenAI GPT-4o-mini и инструменты MCP.

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

• 📦 Управление каталогом товаров (SQLite база данных)
• 🔍 Поиск товаров по названию
• 🌐 Поиск информации в интернете (DuckDuckGo)
• 💱 Получение актуального курса валют
• 🧮 Калькулятор (базовый и расширенный с математическими функциями)
• 🌍 Переводчик текста (английский, немецкий, французский, русский)
• 💬 Контекстный диалог с историей сообщений
• ⌨️ Быстрое меню для быстрого доступа к функциям

Структура:

• mcp_server/ — MCP-совместимый сервер с SQLite-базой товаров и расширенными инструментами
• telegram_bot/ — Telegram-бот, который общается с MCP-сервером и моделью OpenAI

1. MCP SERVER (product-mcp)

Структура:

• server.py — FastAPI-сервер MCP
• db.py — работа с SQLite (products.db)
• tools.py — реализации MCP-инструментов и JSON Schema
• requirements.txt — зависимости для сервера
• products.db — база данных (создаётся автоматически при первом запуске)

Таблица products:

• id INTEGER PRIMARY KEY AUTOINCREMENT
• name TEXT
• category TEXT
• price REAL

При первом запуске:

• создаётся база products.db в директории mcp_server/ (если нет)
• создаётся таблица products (если нет)
• вставляется 100 реальных товаров с разными названиями, категориями и ценами (чай, молоко, яблоки, коньки и др.)

Инструменты MCP:

Каталог товаров:

• list_products() — возвращает список всех товаров с ID из базы данных
• find_product(name: string) — поиск товаров по подстроке имени (регистронезависимо, работает с кириллицей)
• add_product(name: string, category: string, price: float) — добавление товара

Вычисления:

• calculate(expression: string) — безопасный калькулятор для базовых операций (через Python AST, без eval)
• calculate_advanced(expression: string) — расширенный калькулятор с математическими функциями (sin, cos, sqrt, log, pi, e и др.)

Интернет и информация:

• search_web(query: string, max_results: int) — поиск информации в интернете через DuckDuckGo (использует библиотеку ddgs)
• get_currency_rates(base: string, currencies: array) — получение актуального курса валют через exchangerate-api.com (EUR/USD/RUB и другие)

Перевод:

• translate_text(text: string, target_language: string, source_language: string) — перевод текста на английский, немецкий, французский или русский (использует библиотеку deep-translator)

HTTP API:

• POST /run_tool — единая точка входа для вызова MCP-инструментов
• GET /schema — JSON Schema, описывающая доступные инструменты (MCP JSON schema)

Запуск MCP-сервера:

1. Перейти в каталог сервера:

   cd mcp_server
   

2. Создать и активировать виртуальное окружение (опционально, но рекомендуется):

   python -m venv .venv
   .\.venv\Scripts\activate       # Windows PowerShell
   # или
   # source .venv/bin/activate    # Linux / macOS
   

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

   pip install -r requirements.txt
   

   Важно: Убедитесь, что библиотека ddgs установлена для работы поиска в интернете. Если поиск не работает, проверьте, что сервер запущен из того же виртуального окружения, где установлены зависимости.

4. Запустить сервер:

   python server.py
   

По умолчанию сервер доступен на http://127.0.0.1:8000.

2. TELEGRAM BOT

Структура:

• bot.py — основной код Telegram-бота
• config.py — загрузка настроек из .env
• mcp_client.py — HTTP-клиент для вызова MCP-инструментов
• requirements.txt — зависимости для бота

Бот:

• работает на базе aiogram 3
• использует OpenAI GPT-4o-mini (ChatCompletions API) через официальный Python-клиент
• поддерживает ProxyAPI (настраивается через OPENAI_BASE_URL в .env)
• подключается к MCP-серверу по HTTP (/run_tool)
• LLM сама решает, нужно ли вызвать MCP-инструмент, с помощью механизма tools (function calling)
• поддерживает контекстный диалог — помнит историю последних 20 сообщений
• быстрое меню (inline keyboard) для быстрого доступа к функциям
• поддерживает естественные запросы на русском языке:
  • покажи все товары
  • найди чай
  • добавь товар яблоки 120 фрукт
  • посчитай (2 + 3) * 4
  • найди в интернете погода в Москве
  • покажи курс доллара
  • переведи на английский привет
• отвечает структурировано и вежливо
• при недостатке информации задаёт уточняющие вопросы
• показывает ID товаров вместо нумерации при выводе списка

Поддерживаемые инструменты (через LLM):

• list_products — показать все товары
• find_product — найти товары по названию
• add_product — добавить товар
• calculate — простой калькулятор
• calculate_advanced — расширенный калькулятор
• search_web — поиск в интернете
• get_currency_rates — курс валют
• translate_text — перевод текста

3. .env и настройки

Для Telegram-бота используется .env в каталоге telegram_bot/.

Пример файла telegram_bot/.env (можно скопировать из env-example):

TELEGRAM_API_TOKEN=ваш_telegram_bot_token
OPENAI_API_KEY=ваш_openai_api_key
OPENAI_BASE_URL=
OPENAI_MODEL=gpt-4o-mini
MCP_SERVER_URL=http://127.0.0.1:8000

Поля:

• TELEGRAM_API_TOKEN — токен Telegram-бота от @BotFather (обязательно)
• OPENAI_API_KEY — API-ключ OpenAI или ProxyAPI (обязательно)
• OPENAI_BASE_URL — Base URL для ProxyAPI (опционально, если используется ProxyAPI)
• OPENAI_MODEL — модель OpenAI (по умолчанию gpt-4o-mini)
• MCP_SERVER_URL — URL MCP-сервера (по умолчанию http://127.0.0.1:8000)

config.py автоматически загружает .env и валидирует наличие обязательных токенов.

4. Установка зависимостей и запуск проекта

4.1. Установка зависимостей MCP-сервера

Важно: Виртуальное окружение должно быть создано в корне проекта или в папке mcp_server. Рекомендуется использовать одно виртуальное окружение для всего проекта.

# Рекомендуемый вариант: виртуальное окружение в корне проекта
cd D:\Python\Git_Local\MCP
python -m venv .venv
.\.venv\Scripts\activate          # Windows
cd mcp_server
pip install -r requirements.txt

# Альтернативный вариант: отдельное виртуальное окружение для mcp_server
cd mcp_server
python -m venv .venv
.\.venv\Scripts\activate          # Windows
pip install -r requirements.txt

Зависимости MCP-сервера:

• fastapi, uvicorn — веб-сервер
• ddgs — поиск в интернете через DuckDuckGo
• deep-translator — перевод текста
• requests — HTTP-запросы для альтернативного поиска
• openai, mcp-spec — спецификация MCP

4.2. Запуск MCP-сервера

Важно: Убедитесь, что запускаете сервер из того же виртуального окружения, где установлены зависимости. Это критично для работы поиска в интернете (библиотека ddgs).

# Если виртуальное окружение в корне проекта:
cd D:\Python\Git_Local\MCP
.\.venv\Scripts\activate
cd mcp_server
python server.py

# Или если виртуальное окружение в mcp_server:
cd mcp_server
.\.venv\Scripts\activate
python server.py

Примечание: Если при запуске вы видите предупреждение о том, что библиотека ddgs не найдена, убедитесь, что:

1. Виртуальное окружение активировано
2. Библиотека установлена: pip install ddgs
3. Сервер запущен из того же окружения, где установлена библиотека

После запуска:

• сервер слушает на http://127.0.0.1:8000
• создаётся products.db в папке mcp_server/ (если его не было)
• таблица products заполняется 100 реальными товарами (только при первом запуске)
• проверяется доступность библиотек для расширенного функционала:
  • ddgs — для поиска в интернете (если не найдена, поиск будет использовать альтернативный метод)
  • googletrans — для перевода текста

4.3. Установка зависимостей Telegram-бота

В новом терминале (можно использовать то же виртуальное окружение или создать отдельное):

# Вариант 1: Использовать то же виртуальное окружение (если оно в корне проекта)
cd D:\Python\Git_Local\MCP
.\.venv\Scripts\activate
cd telegram_bot
pip install -r requirements.txt

# Вариант 2: Создать отдельное виртуальное окружение для бота
cd telegram_bot
python -m venv .venv
.\.venv\Scripts\activate          # Windows
pip install -r requirements.txt

Создать файл .env:

cd telegram_bot
notepad .env   # или любой другой редактор

И вставить значения по образцу выше.

4.4. Запуск Telegram-бота

Важно: Убедитесь, что MCP-сервер уже запущен и доступен на http://127.0.0.1:8000.

Затем:

# Если используете виртуальное окружение из корня проекта:
cd D:\Python\Git_Local\MCP
.\.venv\Scripts\activate
cd telegram_bot
python bot.py

# Или если отдельное виртуальное окружение для бота:
cd telegram_bot
.\.venv\Scripts\activate
python bot.py

При запуске бот:

• проверяет доступность MCP-сервера
• выводит информацию о модели и сервере
• готов к работе

Теперь можно написать сообщение вашему боту в Telegram.

5. Примеры использования бота

Каталог товаров:

• покажи все товары — показать весь каталог с ID товаров
• найди чай — найти товары по названию
• найди яблоки — поиск работает независимо от регистра
• добавь товар яблоки 120 фрукты — добавить новый товар

Вычисления:

• посчитай (2 + 3) * 4 - 5 — простой калькулятор
• посчитай sqrt(16) + sin(pi/2) — расширенный калькулятор с функциями

Интернет:

• найди в интернете погода в Москве — поиск через DuckDuckGo
• найди информацию о Python — поиск в интернете

Курс валют:

• покажи курс доллара — курс USD к EUR и RUB
• курс EUR к RUB — курс евро к рублю
• курс валют — получить актуальные курсы

Перевод:

• переведи на английский привет — перевод на английский
• переведи на немецкий спасибо — перевод на немецкий
• переведи на французский добро пожаловать — перевод на французский

Быстрое меню:

• В каждом ответе бота доступно быстрое меню с кнопками для быстрого доступа к функциям

Особенности:

• Бот помнит контекст диалога (история последних 20 сообщений)
• При выводе списка товаров показываются ID из базы данных
• Поиск товаров работает с кириллицей независимо от регистра
• Бот задаёт уточняющие вопросы, если не хватает данных