Агентная розничная MCP-система

Полнофункциональное приложение с искусственным интеллектом, реализующее сервер протокола контекста модели (MCP), безопасно подключенный к базе данных Firebase Firestore, управляемое через чат-интерфейс Streamlit и работающее на базе gpt-4o от OpenAI.

Архитектура системы

Этот проект построен с использованием паттерна разделенных микросервисов:

1. Сервер MCP-бэкенда (src/server.py): Python-сервер на базе fastmcp, предоставляющий инструменты для розничной торговли: ['check_inventory', 'calculate_elasticity', 'get_demand_forecast']. Подключается напрямую к Google Cloud Firestore.

2. ИИ-фронтенд на Streamlit (src/client.py): Асинхронный веб-интерфейс, который взаимодействует с вашим бэкенд-сервером с использованием постоянных событий, отправляемых сервером (Server-Sent Events, SSE). Анализирует входные данные инструментов и динамически включает их в вызовы функций OpenAI.

Related MCP server: E-commerce MCP Server

Предварительные требования и конфигурация

Перед запуском любых скриптов необходимо настроить файл .env в корне проекта.

Создайте файл .env и определите следующие переменные:

# Your OpenAI API Key for the GPT-4o Agent
OPENAI_API_KEY="sk-proj-YOUR-KEY-HERE"

# The absolute path to your Firebase Service Account JSON key
FIREBASE_CREDENTIALS_PATH="./firebase-key.json"

(Если оставить FIREBASE_CREDENTIALS_PATH пустым, система попытается использовать учетные данные Google Cloud по умолчанию).

Установка

В этом проекте используется uv — молниеносно быстрый менеджер зависимостей Python.

Запустите следующую команду в корневом каталоге, чтобы убедиться, что зависимости сопоставлены с Python >= 3.11:

uv init
uv add mcp pydantic firebase-admin python-dotenv openai streamlit

Инициализация базы данных (тестовые данные)

Если у вас есть чистый экземпляр Firebase Firestore, вы можете использовать встроенные инструменты для заполнения базы данных 100 образцами розничных товаров.

1. Создайте статические структуры тестовых данных в формате CSV:

   uv run python generate_data.py

2. Загрузите сгенерированные данные CSV напрямую в вашу NoSQL-базу данных Firebase:

   uv run python seed_db.py

Запуск приложения

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

1. Запуск бэкенд-сервера инструментов

Это запускает приложение ASGI Uvicorn на порту 8000, обрабатывающее все запросы на выполнение инструментов через HTTP Server Sent Events.

uv run python src/server.py

2. Запуск клиента Streamlit

В новом окне терминала запустите диалогового агента Streamlit:

uv run streamlit run src/client.py 

Вкладка веб-браузера автоматически откроется по адресу http://localhost:8501. Теперь вы можете задавать вопросы, например: "Каков уровень запасов товара P1002?" или "Проанализируй прогнозы эластичности цен для P1100".

Развертывание в облаке (Google Cloud Run)

Если вы хотите перенести своего ИИ-агента и бэкенд-инфраструктуру в облако на постоянной основе, я настроил расширенные Docker-файлы, разработанные специально для бессерверного развертывания в Google Cloud Run.

Пожалуйста, обратитесь к полному руководству в документации DEPLOYMENT.md для получения инструкций по отправке обоих контейнеров в сеть.