documentation Model Context Protocol (MCP)

ClicShopping · 2025-09-29T20:35:43Z

ClicShopping Version 4.08 and more :

MCP (Model Context Protocol) Documentation for ClicShopping

Overview

The ClicShopping MCP (Model Context Protocol) system allows for the integration of external Node.js or Python servers to extend the e-commerce application’s capabilities with advanced Artificial Intelligence functionalities. It provides a modular architecture for communication between ClicShopping and external services via standardized protocols.

What is MCP?

MCP is a communication protocol that enables applications to interact with language models and AI services in a standardized manner. In the context of ClicShopping, it facilitates:

Bidirectional communication between the e-commerce application and external AI servers
Integration of intelligent agents for task automation
Data access via secured REST APIs
Real-time monitoring and analytics of interactions

Importance in E-commerce

Advantages:

Intelligent automation: Automatic order management, product recommendations
24/7 customer support: Smart chatbots for customer assistance
Advanced analytics: Predictive analysis of sales and customer behavior
Personalization: AI-based personalized recommendations
Inventory optimization: Demand forecasting and automatic management

Disadvantages:

Implementation complexity: Requires advanced technical skills
Infrastructure costs: External servers and AI services
External dependency: Risk of third-party service outages
Security: Management of tokens and secure access

Examples of potential implementations:

🔗 Social Media Integrations

Instagram Shopping: Automatic product synchronization with Instagram posts
Facebook Marketplace: Automatic publication of new products
TikTok Shop: Integration with TikTok trends for recommendations
Pinterest: Automatic creation of pins for popular products

🏢 ERP Integrations

SAP: Synchronization of stocks, orders, and customers
Oracle NetSuite: Accounting integration and financial management
Microsoft Dynamics: Synchronization of customer and sales data
Odoo: Full CRM/ERP integration with inventory management

📈 Marketing Integrations

Mailchimp: Automatic customer segmentation and targeted campaigns
HubSpot: Lead scoring and customer journey automation
Google Analytics 4: Advanced tracking of conversions and behavior
Facebook Ads: Automatic optimization of advertising campaigns

💳 Payment Integrations

Stripe: Management of subscriptions and recurring payments
PayPal: Integration of payments and refunds
Klarna: Installment payments and credit scoring
Apple Pay/Google Pay: Optimized mobile payments

📦 Logistics Integrations

DHL/UPS/FedEx: Automatic shipping cost calculation and tracking
Amazon FBA: Amazon stock management and synchronization
Shopify Fulfillment: Optimization of distribution centers
ShipStation: Multi-carrier shipping automation

🎯 Analytics & BI Integrations

Tableau: Advanced sales dashboards
Power BI: Predictive analytics and automated reports
Google Data Studio: Marketing and performance reporting
Mixpanel: Advanced user event tracking

🤖 AI & Chatbot Integrations

OpenAI GPT: Smart chatbot for customer support
Dialogflow: Multilingual conversation management
Zendesk: Automation of support tickets
Intercom: Real-time chat with lead qualification

📱 Mobile Integrations

React Native: Native mobile application
Flutter: Cross-platform iOS/Android app
PWA: Progressive Web Application
Push Notifications: Personalized notifications

🔐 Security Integrations

Auth0: Advanced authentication and authorization
Okta: Identity and access management
Cloudflare: DDoS protection and CDN
Sentry: Real-time error monitoring

Examples of Integration Code

Example 1: Instagram Shopping Integration

// New MCP endpoint for Instagram
class InstagramIntegration extends \ClicShopping\OM\PagesAbstract
{
    public function syncProductsToInstagram(): void
    {
        $products = $this->getProductsForSync();
        
        foreach ($products as $product) {
            $instagramData = [
                'name' => $product['products_name'],
                'description' => $product['products_description'],
                'price' => $product['products_price'],
                'image_url' => $product['products_image'],
                'availability' => $product['products_quantity'] > 0 ? 'in stock' : 'out of stock'
            ];
            
            $this->postToInstagramAPI($instagramData);
        }
    }
}

Example 2: SAP ERP Integration

// Synchronization with SAP via MCP
class SAPIntegration extends \ClicShopping\OM\PagesAbstract
{
    public function syncOrdersToSAP(): void
    {
        $orders = $this->getPendingOrders();
        
        foreach ($orders as $order) {
            $sapData = [
                'order_number' => $order['orders_id'],
                'customer_code' => $order['customers_id'],
                'order_date' => $order['date_purchased'],
                'items' => $this->formatOrderItems($order['items'])
            ];
            
            $response = $this->sendToSAP($sapData);
            $this->updateOrderStatus($order['orders_id'], $response['status']);
        }
    }
}

Example 3: AI Chatbot with OpenAI

// Smart chatbot for customer support
class AIChatbot extends \ClicShopping\OM\PagesAbstract
{
    public function handleCustomerInquiry(string $message): array
    {
        $context = $this->getCustomerContext();
        
        $prompt = "As an e-commerce assistant, help this customer: " . $message;
        $prompt .= "\nCustomer context: " . json_encode($context);
        
        $response = $this->callOpenAI($prompt);
        
        // If necessary, create a support ticket
        if ($this->requiresHumanIntervention($response)) {
            $this->createSupportTicket($message, $context);
        }
        
        return [
            'response' => $response,
            'requires_human' => $this->requiresHumanIntervention($response),
            'suggested_products' => $this->extractProductSuggestions($response)
        ];
    }
}

Example 4: Predictive Analytics

// Sales prediction with AI
class PredictiveAnalytics extends \ClicShopping\OM\PagesAbstract
{
    public function predictSales(): array
    {
        $historicalData = $this->getSalesHistory();
        $externalFactors = $this->getExternalData(); // Weather, events, etc.
        
        $prediction = $this->runMLModel([
            'historical_sales' => $historicalData,
            'seasonality' => $this->getSeasonalityFactors(),
            'external_factors' => $externalFactors,
            'inventory_levels' => $this->getCurrentInventory()
        ]);
        
        return [
            'predicted_sales' => $prediction['sales'],
            'recommended_stock' => $prediction['stock_recommendations'],
            'confidence_score' => $prediction['confidence'],
            'risk_factors' => $prediction['risks']
        ];
    }
}

Concrete Use Cases

🛒 B2C E-commerce

Personalized recommendations: “Customers who bought this product also viewed…”
24/7 chat support: Automatic assistance with escalation to a human
Intelligent inventory management: Stock-out prediction
Dynamic pricing: Automatic price adjustment based on competition

🏢 B2B E-commerce

Personalized catalog: Prices and products according to the customer
Large order management: ERP integration for high volumes
Automated reporting: Dashboards for resellers
Discount management: Automatic calculation based on commercial agreements

🎯 Marketplace

Multi-vendor synchronization: Centralized stock management
Fraud detection: Automatic detection of suspicious transactions
Fee optimization: Automatic commission calculation
Dispute management: Automation of resolution processes

📱 Mobile Commerce

Smart push notifications: Personalized notifications
Geolocation: Location-based offers
Mobile payments: Apple Pay/Google Pay integration
Image recognition: Product search by photo

Measurable Business Benefits

📈 Sales Performance

+25% conversion thanks to personalized recommendations
-40% shopping cart abandonment with the smart chat
+30% average cart value via cross-sell suggestions
-60% order processing time with automation

💰 Cost Optimization

-50% support costs with chat automation
-30% logistics costs with inventory optimization
-25% marketing costs with precise targeting
-70% human errors with process automation

🎯 Customer Experience

+90% customer satisfaction with 24/7 support
-80% response time to customer inquiries
+45% loyalty thanks to personalization
+60% problem resolution rate on first interaction

MCP Architecture

General Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   ClicShopping  │◄──►│    MCP Server   │◄──►│    AI Services  │
│   (PHP Core)    │    │  (Node.js/Python)│    │   (OpenAI, etc.)│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Database    │    │   Monitoring    │    │    Analytics    │
│                 │    │     & Logs      │    │    & Reports    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

ClicShopping MCP Architecture

The ClicShopping MCP system is organized into several components:

1. Core Classes

MCPConnector: Connection and protocol management
McpMonitor: Performance oversight and monitoring
McpService: Core services for MCP operations
McpDecisionAgent: Intelligent agent for automation

2. API Endpoints

/mcp&customersProducts: Products API
/mcp&ragBI: RAG (Retrieval-Augmented Generation) Interface for admins - the rag must ve activated
You are free to create other EndPoints (see example above)

3. Admin Configuration

Administration interface for configuring MCP servers
Token, port, SSL management
Real-time monitoring

What is Not Provided with the APP

The Chat

The chat interface is not included in the ClicShopping application. To implement it:

Chat construction and connection:

Create a chat interface (HTML/CSS/JavaScript)
Connect to the MCP server via WebSocket or HTTP

Use the available API endpoints:

// Example of chat connection
const chatEndpoint = 'http://your-domain/index.php?mcp&customersProducts';

// Sending a message
fetch(chatEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    message: 'Looking for products',
    context: {
      user_type: 'client',
      session_id: 'unique_session_id'
    }
  })
});

The Node.js/Python MCP Server

The external MCP server is not provided with the application. To build it:

Node.js MCP Server Example:

// Example of a Node.js MCP server
const express = require('express');
const app = express();

app.post('/mcp/products', async (req, res) => {
  // Logic for processing product requests
  const response = await processProductRequest(req.body);
  res.json(response);
});

app.listen(3000, () => {
  console.log('MCP server started on port 3000');
});

Server Connection:

Configuration in the ClicShopping admin: Host, Port, SSL, Token
API Usage: Access via the /Shop/json routes

Configuration and Usage

Configuration in the Administration

MCP configuration is done directly in the ClicShopping administration interface:

Available parameters:

Server Host: Address of the MCP server (default: localhost)
Server Port: Port of the MCP server (default: 3000)
SSL: Secure protocol activation
Token: Authentication token for security
Status: MCP module activation/deactivation

Alert configuration:

Latency thresholds: Maximum response time
Availability thresholds: Maximum downtime
Notifications: Email alert configuration

Access API - Shop Routes

The MCP API is accessible via the /Shop/json routes of ClicShopping:

1. CustomersProducts.php

This class serves as the main entry point for the MCP products API. It manages:

Main features:

Product list: GET ?mcp&customersProducts&action=products
Product detail: GET ?mcp&customersProducts&action=product&id={ID}
Search: GET ?mcp&customersProducts&action=search&query={TERM}
Statistics: GET ?mcp&customersProducts&action=stats
Categories: GET ?mcp&customersProducts&action=categories
Recommendations: GET ?mcp&customersProducts&action=recommendations
Customer chat: POST ?mcp&customersProducts (with JSON body)

Example usage:

# Product list
curl "http://localhost/clicshopping_test/index.php?mcp&customersProducts&action=products&limit=5"

# Product search
curl "http://localhost/clicshopping_test/index.php?mcp&customersProducts&action=search&query=washcloth"

# Customer chat (POST)
curl -X POST "http://localhost/clicshopping_test/index.php?mcp&customersProducts" \
  -H "Content-Type: application/json" \
  -d '{"message": "I am looking for cleaning products", "context": {"user_type": "client"}}'

2. RagBI.php

RAG (Retrieval-Augmented Generation) interface identical to ClicShopping’s internal chat but accessible via MCP:
To use it, you must activate the Agent RAG-BI inside the administration.

Features:

Semantic queries: Smart search in the database
Analytical queries: Analysis of sales and performance data
OpenAI Integration: Use of language models for responses
Translation cache: Performance optimization

Example usage:

# RAG BI Query
curl -X POST "http://localhost/clicshopping_test/index.php?mcp&ragBI" \
  -H "Content-Type: application/json" \
  -d '{"message": "Give me a table of the evolution of turnover by month for the year 2025"}'

3. customerOrders.php

Customer order management API:

Features:

Order list: GET ?mcp&customerOrders&action=list_orders&customer_id={ID}
Order detail: GET ?mcp&customerOrders&action=read_order&order_id={ID}
Cancellation: POST ?mcp&customerOrders&action=cancel_order
Messages: POST ?mcp&customerOrders&action=send_message
History: GET ?mcp&customerOrders&action=history&order_id={ID}

Examples of Future Implementation

Agentic Approach

The MCP system supports the implementation of intelligent agents for:

Recommendation Agent:

// Example of a Recommendation Agent
class RecommendationAgent {
  public function analyzeCustomerBehavior($customerId) {
    // Analyze customer behavior
    // Generate personalized recommendations
  }
}

Stock Management Agent:

// Example of a Stock Management Agent
class StockAgent {
  public function predictDemand($productId) {
    // Demand prediction
    // Optimization of stock levels
  }
}

Customer Support Agent:

// Example of a Support Agent
class SupportAgent {
  public function handleCustomerInquiry($message) {
    // Process customer inquiries
    // Automatic escalation if necessary
  }
}

Monitoring and CronJobs

Monitoring System

The MCP system includes complete monitoring:

Monitored metrics:

Response time: Latency of MCP requests
Availability: Uptime of the MCP server
Errors: Error rate and error types
Security: Intrusion attempts and unauthorized access

Automatic alerts:

Performance thresholds: Alerts if response time > threshold
Service outages: Notifications in case of unavailability
Suspicious activities: Detection of attacks or abuse

CronJob Configuration

The MCP system uses scheduled tasks for:

1. Health Monitoring (every 5 minutes)

// CronJob: McpHealthCron
// Checks the health of the MCP server
// Stores alerts in the database
// Cleans up old alerts (>30 days)

2. Decision Agent (every 5 minutes)

// CronJob: mcp_agent
// Executes the intelligent decision agent
// Processes automated tasks
// Updates recommendations

CronJob Configuration:

# Add to crontab
*/5 * * * * /usr/bin/php /path/to/clicshopping/index.php?cronId={CRON_ID}

Security

Authentication and Authorization

Access Tokens:

Secure generation: Unique tokens per session
Automatic expiration: Token rotation
Validation: Verification on every request

Endpoint protection:

Configured CORS: Controlled access by origin
Parameter validation: Input sanitization
Production mode: Access restrictions in production

Security Best Practices

Use HTTPS in production
Configure strong tokens and renew them regularly
Limit access by IP if necessary
Monitor logs to detect suspicious activities
Regularly update dependencies

Troubleshooting

Common Problems

1. Connection to the MCP server fails

Check the configuration (host, port, SSL)
Verify that the MCP server is started
Check error logs

2. Authentication errors

Verify the token validity
Check permission configuration
Check security logs

3. Degraded performance

Check monitoring metrics
Optimize database queries
Increase resource limits

Logs and Debugging

Log files:

MCP Logs: Available in the database and admin interface (export) for various traceability
PHP Error Logs: Standard PHP configuration
Monitoring Logs: mcp_alerts database

Support and Resources

Additional Documentation

DeepWiki/ClicShopping: Detailed architecture : https://deepwiki.com/ClicShopping/ClicShopping
GitHub Issues: Technical support and bugs : https://github.com/ClicShopping/ClicShopping/issues
ClicShopping Forum: Community and assistance

Sign In