Skip to content

ecomaibridge/core

BranchesTags

Repository files navigation

EcomAIBridge

Connect any ecommerce store to any AI — self-hosted, zero dependencies, privacy-first.

EcomAIBridge is an open-source PHP middleware that reads your existing ecommerce database and exposes it as AI-ready API endpoints. Drop it next to your store, point it at your database, and any AI system can instantly understand your products, categories, and inventory.

No plugins to install. No data leaving your server. No vendor lock-in.

License: AGPL-3.0 PHP 7.4+

Why EcomAIBridge?

Every ecommerce store needs AI capabilities — but existing solutions either lock you into a specific platform, send your data to someone else's cloud, or require complex plugin installations that break things.

EcomAIBridge takes a different approach:

  • Works with any platform — WooCommerce, OpenCart, PrestaShop, with more coming
  • Any AI provider — Claude, GPT, Gemini, DeepSeek, Groq, Mistral, OpenRouter, or any OpenAI-compatible API
  • Your data stays on your server — always. No cloud, no telemetry, no third-party data sharing
  • Zero dependencies — no Composer, no Node, no Docker. Just PHP 7.4+ and Apache
  • 5-minute setup — drop files, copy the config, done
  • Built-in chat widget — embed a working AI shopping assistant on any store immediately

Quick Start

  1. Download and extract to your web server:

    /var/www/html/ecomaibridge/   (Linux)
D:\wamp64\www\ecomaibridge\   (WAMP)

  2. Create writable directories:

    mkdir -p cache logs data
chmod 755 cache logs data

  3. Copy and edit the config file:

    cp config/config.example.php config/config.php

  4. Edit config/config.php with your database credentials, platform, and preferences. The file is fully documented with all available options.

  5. Verify the installation:

    http://yourstore.com/ecomaibridge/ai/status.json

    You should see {"success": true, "data": {"status": "ok", ...}}.

Embed the Chat Widget

Add this before </body> in your store's template:

<script src="https://yourstore.com/ecomaibridge/widget.js"></script>

That's it. Your customers now have an AI shopping assistant.

Supported Platforms

Platform Status Versions
WooCommerce Stable 5.x - 9.x
OpenCart Stable 3.x, 4.x
PrestaShop Stable 1.7, 8.x
Magento Planned Contribute!
BigCommerce Planned Contribute!

Adding a new platform? Implement ConnectorInterface — see CONTRIBUTING.md for a guide.

Supported AI Providers

Provider Type Default Model
Gemini OpenAI-compatible gemini-2.5-flash
Claude Anthropic native claude-sonnet-4
OpenAI Native gpt-4o-mini
DeepSeek OpenAI-compatible deepseek-chat
Groq OpenAI-compatible llama-3.1-8b-instant
Mistral OpenAI-compatible mistral-small-latest
OpenRouter OpenAI-compatible google/gemma-3-27b-it:free
GLM (ZhipuAI) OpenAI-compatible glm-4.5-flash
Any Custom base URL You choose

API Endpoints

All endpoints return JSON under the /ai/ prefix.

Method Endpoint Description
GET /.well-known/ai-bridge.json AI discovery manifest
GET /ai/status.json Health check and system status
GET /ai/products.json List products (supports ?search=, ?category=, ?limit=, ?mode=)
GET /ai/product/{id}.json Single product detail
GET /ai/products/batch.json?ids=1,2,3 Batch product lookup
GET /ai/categories.json Category tree
GET /ai/store.json Store metadata and capabilities
GET /ai/tools.json AI tool definitions (for function calling)
GET /ai/widget-config.json Chat widget configuration
POST /ai/chat AI chat endpoint (used by widget)
POST /ai/action Execute an action (requires API key)
POST /ai/cache/clear Clear cache (requires API key)

Response Modes

Products support three output modes via ?mode= to control token usage:

  • compact — id, title, price, availability (4 fields, minimal tokens)
  • summary — Adds SKU, URL, image, categories, sale prices
  • full — Complete product data including descriptions, dimensions, ratings, dates

MCP Support

EcomAIBridge includes a built-in Model Context Protocol (MCP) server, enabling AI tools like Claude Desktop to connect directly to your store's product catalog.

Architecture

ecomaibridge/
├── index.php               # Front controller
├── widget.js               # Embeddable chat widget
├── mcp-server.php          # MCP server for AI tool integration
├── config/
│   ├── config.php          # Your configuration (git-ignored)
│   └── config.example.php  # Template with all options documented
├── src/
│   ├── core/               # Bootstrap, Config, Router, constants
│   ├── connectors/         # Platform connectors (Woo, OpenCart, PrestaShop)
│   ├── transformers/       # Canonical AI schema normalization
│   ├── engine/             # Action engine + registry
│   ├── actions/            # Action implementations
│   ├── helpers/            # ConnectorFactory, FileCache, LLMClient, McpTools
│   └── exceptions/         # Custom exception classes
├── api/                    # Route handlers for each endpoint
├── tests/                  # Test suite (8 test suites)
├── cache/                  # File cache (git-ignored)
└── logs/                   # Log files (git-ignored)

Design Principles

  • No plugins — Reads directly from the store database via PDO. Your store code is never touched.
  • Config-driven — All behavior controlled via config.php. No code changes needed.
  • Connector pattern — Each platform gets a connector that speaks its database schema. Add a new platform by implementing one interface.
  • Transformer pattern — Raw platform data is normalized into a canonical AI-optimized schema with multiple verbosity modes.
  • Action engine — 11-step validation pipeline for operations (auth, format, load, mode, permissions, validate, execute, transform, log, respond).
  • Zero external dependencies — No Composer, no npm. Pure PHP with built-in extensions. Runs on any shared host.

How It Works

┌─────────────┐     ┌──────────────────────────────────┐     ┌─────────────┐
│              │     │         EcomAIBridge                 │     │              │
│  Your Store  │     │                                      │     │  AI System   │
│  Database    │────>│  Connector → Transformer → API      │────>│  (Claude,    │
│  (MySQL/     │     │                                      │     │   GPT, etc)  │
│  MariaDB)    │     │  Reads only. Never writes.           │     │              │
└─────────────┘     └──────────────────────────────────┘     └─────────────┘
                                     │
                                     v
                              ┌──────────────┐
                              │  Chat Widget  │
                              │  (widget.js)  │
                              └──────────────┘
  1. Connector reads raw product data from your ecommerce database
  2. Transformer converts it to a canonical, AI-optimized format
  3. API serves it as clean JSON endpoints
  4. AI systems consume the endpoints (via REST, MCP, or the built-in chat widget)
  5. Your data never leaves your server — the AI provider only sees the specific products relevant to each query

Configuration

All configuration lives in config/config.php. See config/config.example.php for the complete reference with every option documented.

Key sections:

  • Platform — which ecommerce system
  • Database — connection credentials
  • Security — API key, CORS, allowed IPs
  • Chat — AI provider, API key, model, rate limits
  • Widget — theme color, position, welcome message
  • Cache — TTL settings per endpoint

Running Tests

php tests/run.php              # Run all suites
php tests/run.php config       # Run a specific suite
php tests/run.php connector
php tests/run.php transformer
php tests/run.php cache
php tests/run.php action
php tests/run.php integration
php tests/run.php security
php tests/run.php performance

Note: The config and cache suites run without a database. All other suites (connector, transformer, action, integration, security, performance) require a valid config/config.php with a real database connection.

Security

  • API key authentication via X-API-Key header (constant-time comparison)
  • SQL injection prevention via PDO prepared statements exclusively
  • Path traversal protection in .htaccess
  • Protected directories: config/, src/, logs/, tests/
  • Security headers: X-Content-Type-Options, X-Frame-Options, Content-Security-Policy
  • Rate limiting: per-IP per-minute + daily caps (configurable)
  • Read-only database access by design — EcomAIBridge never writes to your store

Requirements

  • PHP 7.4+ (tested up to 8.4)
  • Apache with mod_rewrite enabled
  • MySQL / MariaDB
  • A supported ecommerce platform with database access

That's it. No Composer. No Node. No Redis. No Docker.

Contributing

We welcome contributions! The most impactful way to help is adding a new platform connector.

See CONTRIBUTING.md for guidelines.

Roadmap

Platform Connectors

  • Magento connector
  • BigCommerce connector
  • Zen Cart connector
  • osCommerce connector

API-Based Connectors (hosted platforms)

  • Shopify connector (REST/GraphQL API)
  • WooCommerce REST API connector (remote stores)
  • Ecwid connector

Features

  • Multi-language support (auto-detect store locale)
  • OpenAPI / Swagger spec generation

Infrastructure

  • Redis cache driver
  • Nginx configuration support
  • Docker deployment option

Commercial Add-ons

EcomAIBridge is fully functional as a standalone open-source project. No features are artificially limited.

For stores that need more, commercial add-ons are available:

  • Native WooCommerce Plugin — admin dashboard, one-click install, visual configuration, AI tuning and more
  • Native OpenCart Plugin — dedicated versions for 3.x and 4.x with admin dashboard, visual configuration, AI tuning and more
  • Standalone PRO Features — admin UI, analytics dashboard, AI tuning and more

Learn more at ecomaibridge.com

License

This repository contains the Core Edition of EcomAIBridge, licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You may use, study, modify, and self-host the Core Edition under the terms of AGPL-3.0.

If you distribute a modified version, distribute a derivative work, or offer a modified version to users over a network, you must comply with AGPL-3.0, including making the corresponding source code available under AGPL-3.0.

If you want to use EcomAIBridge Core inside a proprietary product, commercial plugin, closed-source integration, or closed hosted offering, contact us for a separate commercial license.

See LICENSING.md for full details on the Core vs. Commercial editions.

Links

Built with care by a solo developer who believed every store deserves AI. If EcomAIBridge helps you, a star on GitHub means the world.

About

Open-source middleware connecting any ecommerce store to any AI

Resources

Readme

License

AGPL-3.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 — Initial Public Release Latest
May 1, 2026

Packages

 
 
 

Contributors

Languages