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

   git clone <repository-url>
   cd mcp_demo
   

2. Install dependencies

   composer install
   

3. Environment setup

   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:

   php artisan migrate
   php artisan db:seed
   

6. Start the server

   php artisan serve
   

7. Access the application Open your browser and navigate to http://127.0.0.1:8000

Configuration

Database Configuration

SQLite (Default)

DB_CONNECTION=sqlite

MySQL (Alternative)

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:

CREATE DATABASE mcp_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

OpenAI Configuration

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

php artisan test

Code Style

./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.

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.