MCP E-commerce Demo

# MCP Demo Project A Laravel-based Model Context Protocol (MCP) demonstration project featuring an e-commerce order management system with AI-powered chat functionality using OpenAI. ## Features - **Order Management**: Display and manage customer orders with pagination - **Product Catalog**: Browse supermarket products (sodas, chips, ice cream, etc.) - **AI Chat Interface**: Query order and product data using natural language in Traditional Chinese - **Database Integration**: SQLite database with seeded sample data - **Modern UI**: Responsive design using Tailwind CSS ## Project Structure ### Models - **Product**: Represents supermarket items with name, price, description, stock, and category - **Order**: Customer orders with transaction ID, customer name, amount, status, and product relationships ### Database Schema #### Products Table - `id` - Primary key - `name` - Product name (Traditional Chinese) - `description` - Product description - `price` - Product price (HKD) - `stock_quantity` - Available stock - `category` - Product category (飲料, 零食, 雪糕) - `created_at`, `updated_at` - Timestamps #### Orders Table - `id` - Primary key - `transaction_id` - Unique transaction identifier (TXN######) - `name` - Customer name (Traditional Chinese) - `amount` - Order total amount - `status` - Order status (pending, processing, completed, cancelled, refunded) - `product_id` - Foreign key to products table - `quantity` - Quantity ordered - `created_at`, `updated_at` - Timestamps ### Sample Data - **10 Products**: Supermarket items including: - 可口可樂 (Coca-Cola) - 樂事薯片 (Lay's Chips) - 哈根達斯雪糕 (Häagen-Dazs Ice Cream) - 百事可樂 (Pepsi) - And more... - **500 Orders**: Randomly generated orders with: - Unique transaction IDs - Chinese customer names - Random products and quantities - Various order statuses - Realistic timestamps ## AI Chat Functionality The AI chat interface uses OpenAI's GPT-3.5-turbo model to answer queries about orders and products. The system: 1. **Processes natural language queries** in Traditional Chinese 2. **Searches relevant data** based on keywords and patterns 3. **Provides context** to the AI model with retrieved data 4. **Returns intelligent responses** about orders and products ### Example Queries - "顯示所有已完成的訂單" (Show all completed orders) - "TXN000001 的訂單詳情" (Details for order TXN000001) - "陳大明的所有訂單" (All orders for customer 陳大明) - "有什麼飲料產品？" (What beverage products are available?) ## Installation & Setup ### Prerequisites - PHP 8.1+ - Composer - Node.js & npm (optional, for asset compilation) ### Installation Steps 1. **Clone the repository** ```bash git clone <repository-url> cd mcp_demo ``` 2. **Install dependencies** ```bash composer install ``` 3. **Environment setup** ```bash cp .env.example .env php artisan key:generate ``` 4. **Configure OpenAI API** Add your OpenAI API key to `.env`: ``` OPENAI_API_KEY=your_openai_api_key_here ``` 5. **Database setup** The project is configured to use SQLite by default: ```bash php artisan migrate php artisan db:seed ``` 6. **Start the server** ```bash php artisan serve ``` 7. **Access the application** Open your browser and navigate to `http://127.0.0.1:8000` ## Configuration ### Database Configuration **SQLite (Default)** ```env DB_CONNECTION=sqlite ``` **MySQL (Alternative)** ```env DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=mcp_demo DB_USERNAME=root DB_PASSWORD=your_password ``` For MySQL, create the database first: ```sql CREATE DATABASE mcp_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` ### OpenAI Configuration ```env OPENAI_API_KEY=your_openai_api_key_here ``` ## Usage ### Main Dashboard - View paginated list of orders with details - Browse product catalog - Use AI chat to query data ### AI Chat Interface The chat interface supports various query types: - Order lookup by transaction ID - Customer order history - Product searches - Status-based filtering - General inquiries about the data ### API Endpoints - `GET /` - Main dashboard - `POST /chat` - AI chat endpoint ## Technical Implementation ### MCP Integration The project demonstrates MCP concepts by: 1. **Data Retrieval**: Structured database queries based on AI prompts 2. **Context Building**: Formatting retrieved data for AI consumption 3. **Response Generation**: Using OpenAI to generate intelligent responses 4. **User Interface**: Real-time chat interface for natural language queries ### Technologies Used - **Backend**: Laravel 12, PHP 8.1+ - **Database**: SQLite/MySQL - **AI**: OpenAI GPT-3.5-turbo - **Frontend**: Blade templates, Tailwind CSS, jQuery - **HTTP Client**: OpenAI PHP Client ## Development ### Adding New Features 1. Create new models/controllers as needed 2. Update database migrations and seeders 3. Extend the chat functionality in `ChatController` 4. Add new UI components to the dashboard ### Testing ```bash php artisan test ``` ### Code Style ```bash ./vendor/bin/pint ``` ## Troubleshooting ### Database Issues - Ensure SQLite is enabled in PHP - For MySQL, check connection credentials - Run `php artisan config:clear` after configuration changes ### OpenAI Issues - Verify API key is correct - Check API quota and usage limits - Ensure internet connectivity ### Performance - Consider adding database indexes for large datasets - Implement caching for frequently accessed data - Use Laravel queues for heavy AI operations ## License This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request ## Support For issues or questions, please create an issue in the repository or contact the development team.