README.md•13.7 kB
# PrestaShop MCP Server
> 🚀 **Fast, local, offline-first MCP server** for PrestaShop documentation with **1,095+ indexed documents** including hooks, guides, components, and APIs.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
[](https://www.docker.com/)
A specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides instant access to comprehensive PrestaShop development documentation for AI assistants like Claude, Cursor, and other MCP-compatible tools.
## 🎯 Why This MCP Server?
PrestaShop is a comprehensive e-commerce platform with 647+ hooks, complex component architecture, and extensive APIs. This MCP server provides instant, offline access to **1,095+ indexed documents**:
- **647+ PrestaShop Hooks** - All display and action hooks with complete metadata
- **Module Development** - Complete guides for creating and testing modules
- **Component Architecture** - Forms, Grids, Services, CQRS patterns (119 components)
- **Theme Development** - Template system, Smarty/Twig documentation
- **API Documentation** - Admin API, webservice, and domain references (96 APIs)
- **Guides & Tutorials** - Installation, deployment, contribution guides
### vs. Official PrestaShop Documentation
| Feature | Official Docs Website | This (PrestaShop MCP) |
|---------|----------------------|----------------------|
| **Access** | Online only | **Local + Offline** |
| **Speed** | Network-dependent | **Instant (<50ms)** |
| **Search** | Web search | **SQLite FTS5 full-text** |
| **AI Integration** | Manual lookup | **Direct MCP integration** |
| **Customization** | Fixed | **Add your own docs** |
## ✨ Features
- 🚀 **Lightning Fast** - Local SQLite FTS5 search (<50ms response time)
- 📚 **Comprehensive Coverage** - 1,095+ documents: hooks, guides, components, APIs
- 🔌 **Offline First** - No network requests, works anywhere
- 🐳 **Docker Ready** - Easy deployment with intelligent wrapper script
- 🎨 **IDE Integration** - Works with Claude Desktop, Claude Code, VS Code, Cursor
- 🔧 **Customizable** - Add your own project-specific PrestaShop docs
- 📖 **Rich Documentation** - Full syntax, parameters, examples, and metadata
- 🔍 **Smart Search** - Full-text search with type, category, and origin filtering
- 🌐 **Multiple Transports** - STDIO (local), HTTP, or SSE (remote deployment)
## 📦 Installation
### Option 1: Using Docker (Easiest - Recommended)
```bash
git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp
# Using the wrapper script (best for Claude Desktop/Code)
chmod +x run-docker-mcp.sh
./run-docker-mcp.sh
# Or using Docker Compose (for HTTP/remote deployment)
docker compose up -d
```
The wrapper script automatically:
- Builds the Docker image if missing
- Handles documentation mounting or auto-fetching
- Configures STDIO transport for MCP clients
- No TTY issues!
See [DOCKER_USAGE.md](./DOCKER_USAGE.md) for complete Docker setup guide.
### Option 2: Using pip (Recommended for Python)
```bash
pip install git+https://github.com/florinel-chis/prestashop-mcp.git
```
### Option 3: From Source
```bash
git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp
pip install -e .
```
## 📚 Documentation Setup
The MCP server requires access to the [PrestaShop official documentation](https://github.com/PrestaShop/docs) repository for indexing.
### Docker Setup (Automatic)
**Docker automatically handles documentation:**
- On first run, it clones the PrestaShop docs repository
- Documentation is baked into the Docker image during build
- No manual setup needed!
### Local Python Setup (Manual)
**For local installations, clone the documentation repository:**
```bash
# Clone PrestaShop docs as a sibling directory to prestashop-mcp
cd /path/to/your/projects/
git clone https://github.com/PrestaShop/docs.git prestashop-docs
# Directory structure should look like:
# /path/to/your/projects/
# ├── prestashop-mcp/ (this repository)
# └── prestashop-docs/ (PrestaShop official docs)
# The MCP server will automatically find it
```
**Or set a custom location:**
```bash
# Set environment variable
export PRESTASHOP_DOCS_PATH=/path/to/prestashop-docs
# Then run the server
prestashop-mcp
```
### Documentation Path Priority
The server looks for documentation in this order:
1. **Environment variable**: `PRESTASHOP_DOCS_PATH` (if set)
2. **Sibling directory**: `../prestashop-docs` (relative to MCP server)
3. **Inside project**: `./prestashop-docs` (for Docker builds)
### First Run Indexing
**On first run, the server will:**
1. Locate the PrestaShop documentation repository
2. Parse and index 1,095+ markdown files
3. Extract metadata (hooks, components, APIs, guides)
4. Build SQLite FTS5 search index with Porter stemming
5. Store in `~/.mcp/prestashop-docs/database.db`
**Indexing takes ~30-60 seconds** on first run, then uses the cached database for instant startup.
**Force reindexing:**
```bash
# Local installation
python -m prestashop_mcp.ingest_v2 --force
# Or delete the database
rm ~/.mcp/prestashop-docs/database.db
```
## 🎮 Usage
### With Claude Desktop
**Standard Installation:**
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"prestashop": {
"command": "prestashop-mcp"
}
}
}
```
**Docker Installation (using wrapper script):**
```json
{
"mcpServers": {
"prestashop": {
"command": "/absolute/path/to/prestashop-mcp/run-docker-mcp.sh"
}
}
}
```
**Docker Installation (HTTP transport):**
```json
{
"prestashop": {
"type": "http",
"url": "http://localhost:8765/mcp"
}
}
```
(Requires running `docker compose up -d` first)
### With VS Code
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"prestashop": {
"type": "stdio",
"command": "prestashop-mcp"
}
}
}
```
### With Claude Code
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"prestashop": {
"command": "/absolute/path/to/run-docker-mcp.sh"
}
}
}
```
Or for local Python installation:
```json
{
"mcpServers": {
"prestashop": {
"command": "python",
"args": ["-m", "prestashop_mcp.server"]
}
}
}
```
### With Cursor
Add to Cursor's MCP configuration (Settings > Features > MCP Servers):
```json
{
"mcpServers": {
"prestashop": {
"command": "prestashop-mcp"
}
}
}
```
## 🛠️ Available MCP Tools
Once configured, your AI assistant has access to 7 specialized tools:
### Documentation Tools
#### 1. `search_prestashop_docs(query, doc_type, category)`
Search ALL PrestaShop documentation using full-text search.
**Parameters:**
- `query` - Search terms
- `doc_type` - Filter by: hook, guide, tutorial, api, component, etc.
- `category` - Filter by: basics, development, modules, themes, etc.
**Example:**
```
"Search PrestaShop docs for module development"
"Find installation guides for Mac"
```
#### 2. `get_prestashop_doc(path)`
Get the full content of a specific documentation file.
**Example:**
```
"Get the Mac installation guide"
```
#### 3. `list_prestashop_docs(doc_type, category)`
List available documentation files with optional filters.
**Example:**
```
"List all PrestaShop guides"
"Show me all tutorial documents"
```
#### 4. `get_prestashop_stats()`
Get statistics about the indexed documentation.
**Example:**
```
"Show me PrestaShop documentation statistics"
```
### Hook Tools
#### 5. `search_prestashop_hooks(queries, hook_type, origin)`
Search PrestaShop hooks specifically.
**Example:**
```
"Find all hooks related to products"
```
#### 6. `get_prestashop_hook(hook_name)`
Get complete documentation for a specific hook.
**Example:**
```
"Show me the displayHeader hook"
```
#### 7. `list_prestashop_hooks(hook_type, origin)`
List all hooks organized by type and origin.
**Example:**
```
"List all display hooks"
```
## 💬 Example Queries
Try asking your AI assistant:
**Installation & Setup:**
- "How do I install PrestaShop locally on Mac?"
- "What are the system requirements for PrestaShop?"
- "Show me the Docker installation guide"
**Module Development:**
- "How do I create a PrestaShop module?"
- "Search for module development tutorials"
- "What's the module structure in PrestaShop?"
**Theme Development:**
- "How do I develop a PrestaShop theme?"
- "Show me Twig template documentation"
- "Find theme development guides"
**Hooks:**
- "Show me documentation for the displayHeader hook"
- "Find all hooks related to products"
- "List all display hooks"
- "How does the actionProductAdd hook work?"
**Components & Architecture:**
- "What UI components are available in PrestaShop?"
- "Show me form types documentation"
- "Explain the CQRS pattern in PrestaShop"
**APIs:**
- "How do I use the PrestaShop Admin API?"
- "Show me webservice documentation"
- "Find API endpoint references"
**General:**
- "Show me PrestaShop documentation statistics"
- "List all available guides"
- "Search for deployment documentation"
## 📊 Documentation Coverage
**Total: 1,095+ Indexed Documents**
### By Document Type
- **647 Hooks** - All PrestaShop hooks with metadata
- Display hooks (render content)
- Action hooks (trigger functionality)
- Core, Module, and Theme hooks
- Back office and Front office locations
- **138 General Docs** - Guides, tutorials, contribution docs
- **119 Components** - Forms, Grids, Services, UI components
- **96 API References** - Admin API, webservice, domain references
- **64 References** - Technical references and specifications
- **12 Guides** - Installation, deployment, development guides
- **10 FAQs** - Frequently asked questions
- **9 Tutorials** - Step-by-step tutorials
### By Category
- **697 Module docs** - Module development and hooks
- **208 Development docs** - Components, architecture, patterns
- **88 Webservice docs** - API and webservice references
- **29 Theme docs** - Theme development and templates
- **22 Contribution docs** - Contributing to PrestaShop
- **17 Basics** - Installation, system requirements, deployment
- And more...
### Specialized Data
- **386 Domain References** - CQRS commands and queries
- **119 UI Components** - Form types, grid columns, etc.
## 🔧 Development
### Running Tests
```bash
# Run all tests
pytest
# Run specific test
pytest tests/test_ingest.py
# Run with coverage
pytest --cov=prestashop_mcp
```
### Manual Testing
```bash
# Index documentation (uses new comprehensive indexer)
python -m prestashop_mcp.ingest_v2
# Force reindex
python -m prestashop_mcp.ingest_v2 --force
# Check database
sqlite3 ~/.mcp/prestashop-docs/database.db "SELECT COUNT(*) FROM prestashop_docs;"
# Get statistics by type
sqlite3 ~/.mcp/prestashop-docs/database.db "SELECT doc_type, COUNT(*) FROM prestashop_docs GROUP BY doc_type;"
```
## 📖 How It Works
1. **Indexing**: On first run, indexes 1,095+ documentation files into SQLite with FTS5
- Hooks, guides, tutorials, API docs, components, and more
- Automatic categorization and metadata extraction
- CQRS domain references and UI component detection
2. **Storage**: Documentation stored in `~/.mcp/prestashop-docs/database.db`
3. **Search**: Uses SQLite FTS5 for efficient full-text search with ranking
- Porter stemming for better search results
- Filter by document type, category, and other metadata
4. **Retrieval**: Direct lookups by path or name for instant access
5. **Multi-Transport**: Supports STDIO (local), HTTP, and SSE (remote) protocols
## 🤝 Contributing
Contributions welcome! Please read our [Contributing Guide](./CONTRIBUTING.md).
### Quick Start
```bash
# Fork and clone
git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install for development
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black prestashop_mcp/
# Make changes and submit PR
```
## 📜 License
MIT License - see [LICENSE](./LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by [Shopify Liquid MCP](https://github.com/florinel-chis/shopify-liquid-mcp)
- Docker integration based on best practices from [Magento GraphQL Docs MCP](https://github.com/florinel-chis/magento-graphql-docs-mcp), thank you [@cmuench](https://github.com/cmuench)
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Documentation from [PrestaShop Docs](https://github.com/PrestaShop/docs)
- MCP Protocol by [Anthropic](https://www.anthropic.com/)
## 🔗 Related Projects
- [Shopify Liquid MCP](https://github.com/florinel-chis/shopify-liquid-mcp) - For Shopify theme development
- [Magento GraphQL Docs MCP](https://github.com/florinel-chis/magento-graphql-docs-mcp) - For Magento development
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
## 📞 Support
- 🐛 [Issues](https://github.com/florinel-chis/prestashop-mcp/issues)
- 💬 [Discussions](https://github.com/florinel-chis/prestashop-mcp/discussions)
---
**Made with ❤️ for the PrestaShop development community**