Sistema MCP de Retail Agéntico

Una aplicación de inteligencia artificial full-stack que implementa un servidor de Protocolo de Contexto de Modelo (MCP) conectado de forma segura a una base de datos Firebase Firestore, controlado a través de una interfaz de chat de Streamlit y potenciado por gpt-4o de OpenAI.

Arquitectura del sistema

Este proyecto está construido utilizando un patrón de microservicios desacoplados:

1. Servidor Backend MCP (src/server.py): Un servidor Python fastmcp que expone herramientas específicas de Retail ['check_inventory', 'calculate_elasticity', 'get_demand_forecast']. Se conecta directamente a Google Cloud Firestore.

2. Frontend de IA con Streamlit (src/client.py): Una interfaz web asíncrona que se comunica con su servidor backend utilizando Server-Sent Events (SSE) persistentes. Analiza las entradas de las herramientas y las integra dinámicamente en las llamadas a funciones de OpenAI.

Related MCP server: E-commerce MCP Server

Requisitos previos y configuración

Antes de ejecutar cualquier script, debe configurar su archivo .env en la raíz del proyecto.

Cree un archivo .env y defina las siguientes variables:

# 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"

(Si FIREBASE_CREDENTIALS_PATH se deja en blanco, el sistema intentará utilizar las credenciales predeterminadas de la aplicación de Google Cloud de forma nativa).

Instalación

Este proyecto utiliza uv como gestor de dependencias de paquetes de Python ultrarrápido.

Ejecute lo siguiente dentro del directorio raíz para asegurarse de que las dependencias estén asignadas a Python >= 3.11:

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

Inicialización de la base de datos (Datos de prueba)

Si tiene una instancia de Firebase Firestore nueva, puede utilizar las herramientas de carga integradas para poblar su base de datos con 100 productos minoristas de muestra.

1. Genere las estructuras de datos de prueba CSV estáticas:

   uv run python generate_data.py

2. Transmita los datos CSV generados directamente a su base de datos NoSQL de Firebase:

   uv run python seed_db.py

Ejecución de la aplicación

Debido a que la interfaz web y el servidor de herramientas se comunican a través de un bucle de red local aislado, debe ejecutar ambos procesos en paralelo en dos pestañas de terminal separadas.

1. Inicie el servidor de herramientas backend

Esto levanta una aplicación ASGI Uvicorn en el puerto 8000 que maneja todas las solicitudes de ejecución de herramientas de forma nativa a través de HTTP Server Sent Events.

uv run python src/server.py

2. Inicie el cliente de Streamlit

En una nueva ventana de terminal, inicie el agente conversacional de Streamlit:

uv run streamlit run src/client.py 

Se abrirá automáticamente una pestaña del navegador en http://localhost:8501. Ahora puede hacer preguntas como "¿Cuál es el nivel de stock del producto P1002?" o "Analiza las proyecciones de elasticidad de precios para P1100".

Despliegues en la nube (Google Cloud Run)

Si desea trasladar su agente de IA y su infraestructura de backend permanentemente a la nube, he configurado Dockerfiles avanzados diseñados explícitamente para el despliegue sin servidor (serverless) en Google Cloud Run.

Consulte la guía de documentación completa DEPLOYMENT.md para obtener instrucciones sobre cómo enviar ambos contenedores a la web.