에이전트형 리테일 MCP 시스템

Firebase Firestore 데이터베이스에 안전하게 연결되고, Streamlit 채팅 인터페이스를 통해 제어되며, OpenAI의 gpt-4o로 구동되는 Model Context Protocol(MCP) 서버를 구현한 풀스택 인공지능 애플리케이션입니다.

시스템 아키텍처

이 프로젝트는 분리된 마이크로서비스 패턴을 사용하여 구축되었습니다:

1. MCP 백엔드 서버 (src/server.py): 리테일 전용 도구인 ['check_inventory', 'calculate_elasticity', 'get_demand_forecast']를 노출하는 fastmcp 파이썬 서버입니다. Google Cloud Firestore에 직접 연결됩니다.

2. AI Streamlit 프론트엔드 (src/client.py): 지속적인 Server-Sent Events (SSE)를 사용하여 백엔드 서버와 통신하는 비동기 웹 UI입니다. 도구 입력을 파싱하고 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 >= 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 데이터를 Firebase NoSQL 데이터베이스로 직접 스트리밍합니다:

   uv run python seed_db.py

애플리케이션 실행

웹 인터페이스와 도구 서버는 격리된 로컬 네트워크 루프를 통해 통신하므로, 두 프로세스를 두 개의 별도 터미널 탭에서 병렬로 실행해야 합니다.

1. 백엔드 도구 서버 부팅

HTTP Server Sent Events를 통해 모든 도구 실행 요청을 기본적으로 처리하는 포트 8000의 ASGI Uvicorn 앱을 실행합니다.

uv run python src/server.py

2. Streamlit 클라이언트 부팅

새 터미널 창에서 Streamlit 대화형 에이전트를 시작합니다:

uv run streamlit run src/client.py 

웹 브라우저 탭이 http://localhost:8501에서 자동으로 열립니다. 이제 "제품 P1002의 재고 수준은 얼마인가요?" 또는 *"P1100에 대한 가격 탄력성 예측을 분석해줘"*와 같은 질문을 할 수 있습니다.

클라우드 배포 (Google Cloud Run)

AI 에이전트와 백엔드 인프라를 클라우드로 영구적으로 이전하려면 Google Cloud Run에서의 서버리스 배포를 위해 특별히 설계된 고급 Dockerfile을 구성해 두었습니다.

두 컨테이너를 웹으로 푸시하는 방법에 대한 지침은 전체 DEPLOYMENT.md 문서 가이드를 참조하십시오.