エージェント型リテールMCPシステム

Firebase Firestoreデータベースに安全に接続されたModel Context Protocol (MCP) サーバーを実装し、Streamlitチャットインターフェースで制御、OpenAIの gpt-4o を活用するフルスタック人工知能アプリケーションです。

システムアーキテクチャ

このプロジェクトは、疎結合なマイクロサービスパターンを使用して構築されています。

1. MCPバックエンドサーバー (src/server.py): 小売特化型ツール ['check_inventory', 'calculate_elasticity', 'get_demand_forecast'] を公開する fastmcp Pythonサーバー。Google Cloud Firestoreに直接接続します。

2. AI Streamlitフロントエンド (src/client.py): 永続的な Server-Sent Events (SSE) を使用してバックエンドサーバーと通信する非同期Web 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のアプリケーションデフォルト認証情報をネイティブに使用しようとします)。

インストール

このプロジェクトでは、超高速なPythonパッケージ依存関係マネージャーである 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

アプリケーションの実行

Webインターフェースとツールサーバーは分離されたローカルネットワークループ上で通信するため、2つの別々のターミナルタブで両方のプロセスを並行して実行する必要があります。

1. バックエンドツールサーバーの起動

これにより、HTTP Server Sent Eventsを介してすべてのツール実行リクエストをネイティブに処理するASGI Uvicornアプリがポート8000で立ち上がります。

uv run python src/server.py

2. Streamlitクライアントの起動

新しいターミナルウィンドウで、Streamlit会話エージェントを起動します：

uv run streamlit run src/client.py 

Webブラウザのタブが自動的に http://localhost:8501 で開きます。これで、「製品P1002の在庫レベルは？」や「P1100の価格弾力性予測を分析して」といった質問ができるようになります。

クラウドデプロイメント (Google Cloud Run)

AIエージェントとバックエンドインフラストラクチャを恒久的にクラウドへ移行したい場合、Google Cloud Runでのサーバーレスデプロイメント用に特別に設計された高度なDockerfileを設定済みです。

両方のコンテナをWebにプッシュする手順については、完全な DEPLOYMENT.md ドキュメントガイドを参照してください。