PrestaShop MCP Server

# PrestaShop MCP Server - Docker Usage Guide Complete guide for using the PrestaShop MCP server with Docker, inspired by best practices from the Magento GraphQL MCP implementation. ## 🚀 Quick Start ### Method 1: Wrapper Script (Recommended for IDEs) The easiest way to use the MCP server with Claude Desktop or Claude Code: ```bash ./run-docker-mcp.sh ``` **Features:** - ✅ Auto-builds Docker image if missing - ✅ Handles documentation mounting automatically - ✅ Proper STDIO transport for MCP clients - ✅ Shows configuration examples - ✅ No TTY issues ### Method 2: Docker Compose (For Remote Deployment) Start the server with HTTP transport: ```bash docker compose up -d ``` Access at: `http://localhost:8765/mcp` ### Method 3: Manual Docker Run ```bash docker run -i --rm prestashop-mcp:latest ``` --- ## 📋 IDE Integration ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "prestashop": { "command": "/Users/flo/fch/shopify/shopify-mcp-doc/prestashop-mcp/run-docker-mcp.sh" } } } ``` **Important:** Use absolute path to the wrapper script! ### Claude Code (Project-scoped) Create `.mcp.json` in your project: ```json { "mcpServers": { "prestashop": { "command": "./run-docker-mcp.sh" } } } ``` Then restart Claude Code. ### VS Code with HTTP Transport First start the server: ```bash docker compose up -d ``` Then configure VS Code MCP: ```json { "prestashop": { "type": "http", "url": "http://localhost:8765/mcp" } } ``` --- ## 🛠️ Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `PRESTASHOP_DOCS_PATH` | `/app/prestashop-docs` | Path to documentation | | `PRESTASHOP_DB_PATH` | `/app/database.db` | Path to SQLite database | | `PRESTASHOP_AUTO_FETCH` | `true` | Auto-clone docs if not found | | `PRESTASHOP_TRANSPORT` | `stdio` | Transport mode: `stdio`, `http`, or `sse` | | `PRESTASHOP_HOST` | `0.0.0.0` | Host for HTTP/SSE | | `PRESTASHOP_PORT` | `8765` | Port for HTTP/SSE | ### Using the Wrapper Script with Custom Configuration ```bash # Use local documentation export PRESTASHOP_DOCS_PATH=/path/to/prestashop-docs ./run-docker-mcp.sh # Cache the database for faster startup export PRESTASHOP_DB_PATH=~/.cache/prestashop-mcp/database.db ./run-docker-mcp.sh # Disable auto-fetch (requires mounted docs) export PRESTASHOP_AUTO_FETCH=false export PRESTASHOP_DOCS_PATH=/path/to/prestashop-docs ./run-docker-mcp.sh ``` --- ## 🔧 Transport Modes ### STDIO (Default) - Best for Local IDEs **Characteristics:** - ✅ No network exposure - ✅ Process isolation - ✅ Works with Claude Desktop/Code - ✅ No authentication needed - ⚠️ Local only **Usage:** ```bash ./run-docker-mcp.sh ``` **Important:** The wrapper script automatically uses `-i` (not `-it`) to avoid TTY issues with MCP clients. ### HTTP - Best for Remote Deployment **Characteristics:** - ✅ Remote access - ✅ Multiple clients - ✅ RESTful interface - ⚠️ Requires authentication in production - ⚠️ Network overhead **Usage:** ```bash docker compose up -d # Access at http://localhost:8765/mcp ``` **Security Note:** Do not expose to public internet without authentication! ### SSE (Server-Sent Events) - Best for Streaming **Characteristics:** - ✅ Real-time updates - ✅ Streaming responses - ✅ Lower latency than HTTP - ⚠️ Requires authentication in production **Usage:** ```bash docker run -p 8765:8765 \ -e PRESTASHOP_TRANSPORT=sse \ prestashop-mcp:latest ``` --- ## 💾 Database Caching The Docker image includes a pre-indexed database (~1095 documents). However, you can mount a persistent database cache for even faster startups: ### Via Wrapper Script ```bash export PRESTASHOP_DB_PATH=~/.cache/prestashop-mcp/database.db ./run-docker-mcp.sh ``` The wrapper script will: 1. Create the cache directory if it doesn't exist 2. Mount the database from the cache 3. Reuse it on subsequent runs ### Via Docker Compose Edit `docker-compose.yml`: ```yaml volumes: - ~/.cache/prestashop-mcp/database.db:/app/database.db ``` ### Manually ```bash mkdir -p ~/.cache/prestashop-mcp docker run -i --rm \ -v ~/.cache/prestashop-mcp/database.db:/app/database.db \ prestashop-mcp:latest ``` **Startup Times:** - Baked-in database: ~2-3 seconds - Cached database (mounted): ~1 second - Fresh indexing: ~30-60 seconds --- ## 📚 Documentation Mounting By default, the Docker image includes PrestaShop documentation cloned during the build. However, you can mount your own documentation: ### Why Mount Documentation? - ✅ Test with local changes - ✅ Use your own fork - ✅ Development workflow - ✅ Custom documentation ### Via Wrapper Script ```bash export PRESTASHOP_DOCS_PATH=/Users/flo/fch/shopify/shopify-mcp-doc/prestashop-docs ./run-docker-mcp.sh ``` ### Via Docker Compose ```yaml volumes: - /Users/flo/fch/shopify/shopify-mcp-doc/prestashop-docs:/data/prestashop-docs:ro environment: PRESTASHOP_DOCS_PATH: /data/prestashop-docs ``` ### Manually ```bash docker run -i --rm \ -v /path/to/prestashop-docs:/data/prestashop-docs:ro \ -e PRESTASHOP_DOCS_PATH=/data/prestashop-docs \ prestashop-mcp:latest ``` --- ## 🧪 Testing ### Test with Demo Script ```bash ./demo_queries.sh ``` ### Test STDIO Transport ```bash echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | ./run-docker-mcp.sh ``` ### Test HTTP Transport ```bash # Start server docker compose up -d # List tools curl -X POST http://localhost:8765/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' # Search docs curl -X POST http://localhost:8765/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_prestashop_docs","arguments":{"query":"Mac install"}}}' ``` ### Test from Python ```bash docker run --rm prestashop-mcp:latest python -c " from prestashop_mcp.search_v2 import search_documentation results = search_documentation('hooks', limit=3) for r in results: print(f'{r[\"title\"]}: {r[\"path\"]}') " ``` --- ## 🐛 Troubleshooting ### Issue: "Docker is not running" ```bash # Start Docker Desktop first open -a Docker # Wait for Docker to start, then retry ``` ### Issue: Wrapper script not found ```bash # Make it executable chmod +x run-docker-mcp.sh # Use absolute path in IDE config /Users/flo/fch/shopify/shopify-mcp-doc/prestashop-mcp/run-docker-mcp.sh ``` ### Issue: Image not found ```bash # Build the image docker build -f Dockerfile.mcp -t prestashop-mcp:latest . # Or let the wrapper script build it automatically ./run-docker-mcp.sh ``` ### Issue: MCP client can't connect (TTY error) **Cause:** Using `-t` flag with Docker run **Solution:** The wrapper script handles this automatically by using only `-i` flag. If running manually: ```bash # ❌ Wrong - includes TTY docker run -it prestashop-mcp:latest # ✅ Correct - STDIN only docker run -i prestashop-mcp:latest ``` ### Issue: Documentation not found **Check if auto-fetch is enabled:** ```bash # Default behavior - should auto-fetch ./run-docker-mcp.sh # Or explicitly enable export PRESTASHOP_AUTO_FETCH=true ./run-docker-mcp.sh ``` **Or mount documentation:** ```bash export PRESTASHOP_DOCS_PATH=/path/to/prestashop-docs ./run-docker-mcp.sh ``` ### Issue: Database indexing is slow **Solution:** Use database caching: ```bash export PRESTASHOP_DB_PATH=~/.cache/prestashop-mcp/database.db ./run-docker-mcp.sh ``` First run will index (slow), subsequent runs use cached database (fast). ### Issue: Port 8765 already in use (HTTP mode) **Edit docker-compose.yml:** ```yaml ports: - "9999:8765" # Use port 9999 on host instead ``` ### Viewing Logs ```bash # STDIO mode (wrapper script) # Logs appear in stderr (separate from STDIO communication) # HTTP mode (docker compose) docker logs prestashop-mcp-server docker logs -f prestashop-mcp-server # Follow logs ``` ### Verify Database ```bash docker run --rm prestashop-mcp:latest python -c " import sqlite3 conn = sqlite3.connect('/app/database.db') cursor = conn.cursor() cursor.execute('SELECT COUNT(*) FROM prestashop_docs') print(f'Documents: {cursor.fetchone()[0]}') conn.close() " ``` Should output: `Documents: 1095` --- ## 🔒 Security Best Practices ### Local Development (STDIO) - ✅ No network exposure - ✅ Process isolation via Docker - ✅ Read-only documentation mounts ### Remote Deployment (HTTP/SSE) - ⚠️ **DO NOT** expose to public internet without authentication - ✅ Use reverse proxy with authentication (nginx, Caddy) - ✅ Enable TLS/SSL for production - ✅ Restrict access with firewall rules **Example nginx config:** ```nginx location /prestashop-mcp { proxy_pass http://localhost:8765/mcp; auth_basic "PrestaShop MCP"; auth_basic_user_file /etc/nginx/.htpasswd; # Optional: IP whitelisting allow 192.168.1.0/24; deny all; } ``` --- ## 📊 Performance Comparison | Mode | Startup Time | Memory | Network | Use Case | |------|-------------|---------|---------|----------| | STDIO (wrapper) | ~2s | ~150MB | None | Local IDE integration | | HTTP | ~2s | ~150MB | Low | Remote deployment | | SSE | ~2s | ~150MB | Low | Streaming responses | | With mounted docs | +5-10s | ~150MB | - | Development/testing | | With cached DB | ~1s | ~150MB | - | Fastest startup | --- ## 🎯 Use Case Examples ### Case 1: Claude Desktop User ```bash # One-time setup chmod +x /Users/flo/fch/shopify/shopify-mcp-doc/prestashop-mcp/run-docker-mcp.sh # Add to Claude Desktop config (absolute path!) { "mcpServers": { "prestashop": { "command": "/Users/flo/fch/shopify/shopify-mcp-doc/prestashop-mcp/run-docker-mcp.sh" } } } # Restart Claude Desktop # Ask: "Search PrestaShop docs for module development" ``` ### Case 2: Development with Local Docs ```bash # Point to your local docs fork export PRESTASHOP_DOCS_PATH=/path/to/my/prestashop-docs-fork export PRESTASHOP_DB_PATH=~/.cache/prestashop-mcp/dev-database.db # Run with caching ./run-docker-mcp.sh ``` ### Case 3: Remote Team Server ```bash # Start HTTP server docker compose up -d # Team members configure their IDE: { "prestashop": { "type": "http", "url": "http://team-server.local:8765/mcp" } } ``` ### Case 4: CI/CD Integration ```bash # In your CI script docker run --rm prestashop-mcp:latest python -c " from prestashop_mcp.search_v2 import search_documentation results = search_documentation('deprecated API', doc_type='api') if results: print('Found deprecated APIs!') exit(1) " ``` --- ## 📖 Available MCP Tools Once connected, you can use these tools: ### Hook Tools - `search_prestashop_hooks(queries, hook_type?, origin?)` - Search hooks - `get_prestashop_hook(hook_name)` - Get specific hook - `list_prestashop_hooks(hook_type?, origin?)` - List all hooks ### Documentation Tools - `search_prestashop_docs(query, doc_type?, category?)` - Search all docs - `get_prestashop_doc(path)` - Get specific document - `list_prestashop_docs(doc_type?, category?)` - List documents - `get_prestashop_stats()` - Get statistics ### Parameters - **doc_type**: hook, guide, tutorial, api, reference, component, faq, general - **category**: basics, development, modules, themes, testing, etc. - **hook_type**: display, action - **origin**: core, module, theme --- ## 🤝 Contributing Found an issue? Have a suggestion? 1. Check existing issues 2. Review PRs for similar improvements 3. Follow the code style and patterns 4. Test your changes with the wrapper script --- ## 📄 License MIT License - See LICENSE file for details --- ## 🙏 Acknowledgments Docker integration inspired by: - [Magento GraphQL Docs MCP](https://github.com/florinel-chis/magento-graphql-docs-mcp) - PR #1 and #2 - Claude Code MCP best practices - FastMCP documentation --- **Need help?** Check the main [HOW_TO_QUERY_MCP.md](HOW_TO_QUERY_MCP.md) guide for more options.