WooCommerce Gemini AI Support Agent

A premium, production-ready WooCommerce customer support agent powered by Google Gemini API (RAG + MCP) built entirely in pure PHP as a WordPress plugin.

This plugin runs directly within the WordPress runtime environment and communicates with local resources via HTTP loopbacks without requiring any external Node.js servers, external databases, or complex daemon scripts.

🏗️ Architecture Overview

The plugin utilizes a unified Retrieval-Augmented Generation (RAG) and Model Context Protocol (MCP) architecture to drive conversation logic:

                  ┌────────────────────────┐
                  │     Shop Frontend      │
                  │  (Glassmorphic Chat)   │
                  └───────────┬────────────┘
                              │ REST AJAX Request
                  ┌───────────▼────────────┐
                  │    Plugin API Route    │
                  └───────────┬────────────┘
                              │ Core Agent Loop
                  ┌───────────▼────────────┐
                  │   PHP Agent Engine     ├──────────┐
                  └─────┬──────────────┬───┘          │
                        │              │              │
       Semantic policy  │              │ JSON-RPC     │ REST
            similarity  │              │ Loopback     │ HTTPS
  ┌─────────────────────▼─┐      ┌─────▼────────┐  ┌──▼────────────┐
  │     RAG Engine        │      │ Local MCP    │  │ Google Gemini │
  │ (gemini-embedding-2)  │      │ Client       │  │ (3.5-flash)   │
  └───────────────────────┘      └──────┬───────┘  └───────────────┘
                                        │
                                 ┌──────▼───────┐
                                 │ WooCommerce  │
                                 │ DB (Abilities│
                                 └──────────────┘

1. Agent Engine (includes/class-agent.php): Drives the conversational tool-calling loop using the gemini-3.5-flash-lite model. It statefully tracks history, skips welcome headers for Gemini formatting compliance, and recursively cleans up complex nested parameter schemas (including oneOf, anyOf, allOf, not) to strip out unsupported additionalProperties constraints.
2. RAG Engine (includes/class-rag.php): Configures and semantic-searches store policy options. Vectors are computed during saves using gemini-embedding-2 and compared locally using a pure PHP cosine similarity calculator.
3. Abilities Integration (includes/class-abilities.php): Exposes custom database actions as standard WordPress Abilities, which are automatically translated to MCP tools by the adapter plugin.
4. Stateful MCP Client (includes/class-mcp-client.php): Automates session negotiation (initialize JSON-RPC handshake) and injects required session tokens (Mcp-Session-Id and Mcp-Protocol-Version). It resolves Apache's HTTP authorization-header stripping restriction by supplying a custom local token matching the site's private NONCE_KEY hash.

✨ Features

• 💬 Glassmorphic Floating Chat Widget: Modern CSS styling with automatic light/dark mode syncing (OS-based or user-controlled).
• 🔊 Sound notifications: Built-in sound tone synthesis using the HTML5 Web Audio API (no raw file assets required).
• 🛡️ Verification and Security: Order lookup queries require matching billing emails to prevent information leaks.
• 🔄 Hybrid RAG + MCP Tools: The Check Return Eligibility tool retrieves live order completion timestamps via MCP and dynamically evaluates them against policy return windows fetched via RAG.
• 📇 Plug-and-play local authentication: Zero-configuration hook bypasses standard HTTP authorization checks.

🛠️ Installation

Prerequisites

• WordPress >= 6.9
• WooCommerce >= 8.0
• MCP Adapter plugin activated (WordPress package for Abilities-to-MCP bridge)

Step 1: Install the Plugin

Upload the plugin folder woocommerce-gemini-support to your wp-content/plugins/ directory:

cd wp-content/plugins/
git clone https://github.com/ajaychandani003/woocommerce-gemini-support.git

Step 2: Activate

1. Navigate to your WordPress Admin Dashboard -> Plugins -> Installed Plugins.
2. Locate WooCommerce Gemini Support and click Activate.

⚙️ Configuration

1. Navigate to Settings -> Gemini AI Support in your WordPress dashboard.
2. Configure the connection fields:
   • Gemini API Key: Your API key from Google AI Studio.
   • WP Admin Username: Your site's admin username (used as a backend fallback).
   • WP Application Password: An application password generated from Users -> Profile (used as a backend fallback).
3. Fill in the Store Policies (RAG Knowledge Base) fields:
   • Return Policy: E.g., "At AJAY AI Customers can request a return within 30 days of delivery. Products must be unused, in original condition, and include original packaging."
   • Refund Policy: E.g., "Approved refunds are processed back to the original payment method within 5-10 business days."
   • Shipping Policy: E.g., "Orders are processed within 1-3 business days. Delivery takes 3-7 business days."
4. Click Save Changes. The plugin will automatically call Google Gemini to index your policies and build the RAG database.

💬 Verification & Testing

Visit your storefront where you'll find the support chat widget in the bottom right corner. Test the following interactions:

1. RAG Policy check: "What is your return policy?" (retrieves and summarizes vector matches).
2. MCP Order Lookup: "Where is my order #63?" (asks for verification email, checks WooCommerce, and returns status).
3. Hybrid RAG + MCP calculation: "Can I return order #63?" (authenticates email, pulls the order completion date, gets the policy return window via RAG, checks eligibility, and provides details).

📜 License

Distributed under the GPL-2.0-or-later License. See LICENSE or plugin headers for details.