Prestashop MCP

🚀 PrestaShop MCP 服務器

這是一個專為 PrestaShop 文檔打造的服務器，它快速、可本地部署且支持離線使用。服務器對 1095 份以上的文檔進行了索引，涵蓋鉤子、指南、組件和 API 等內容，能為 Claude、Cursor 等 AI 助手及其他兼容 MCP 的工具，提供全面的 PrestaShop 開發文檔即時訪問服務。

🚀 快速開始

PrestaShop MCP 服務器是一個專門的 模型上下文協議 (MCP) 服務器，它能為 Claude、Cursor 等 AI 助手及其他兼容 MCP 的工具，提供全面的 PrestaShop 開發文檔即時訪問服務。

🎯 為何選擇此 MCP 服務器？

PrestaShop 是一個功能全面的電子商務平臺，擁有 647 個以上的鉤子、複雜的組件架構和大量的 API。此 MCP 服務器可讓你即時、離線訪問 1095 份以上的索引文檔：

• 647 個以上的 PrestaShop 鉤子：包含所有顯示和操作鉤子及其完整元數據。
• 模塊開發：提供創建和測試模塊的完整指南。
• 組件架構：涵蓋表單、網格、服務、CQRS 模式（119 個組件）。
• 主題開發：包括模板系統、Smarty/Twig 文檔。
• API 文檔：包含管理 API、Web 服務和域參考（96 個 API）。
• 指南與教程：涉及安裝、部署和貢獻指南。

與官方 PrestaShop 文檔對比

✨ 主要特性

• 🚀 極速響應：本地 SQLite FTS5 搜索（響應時間 <50ms）。
• 📚 全面覆蓋：涵蓋 1095 份以上的文檔，包括鉤子、指南、組件和 API。
• 🔌 離線優先：無需網絡請求，隨時隨地使用。
• 🐳 支持 Docker：通過智能包裝腳本輕鬆部署。
• 🎨 支持 IDE 集成：可與 Claude Desktop、Claude Code、VS Code、Cursor 等工具集成。
• 🔧 可定製：可添加自定義的 PrestaShop 文檔。
• 📖 豐富文檔：包含完整的語法、參數、示例和元數據。
• 🔍 智能搜索：支持按類型、類別和來源進行全文搜索。
• 🌐 多傳輸協議：支持 STDIO（本地）、HTTP 或 SSE（遠程部署）。

📦 安裝指南

選項 1：使用 Docker（最簡單 - 推薦）

git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp

# 使用包裝腳本（適用於 Claude Desktop/Code）
chmod +x run-docker-mcp.sh
./run-docker-mcp.sh

# 或者使用 Docker Compose（用於 HTTP/遠程部署）
docker compose up -d

包裝腳本會自動執行以下操作：

• 若 Docker 鏡像缺失，則自動構建。
• 處理文檔掛載或自動獲取。
• 為 MCP 客戶端配置 STDIO 傳輸。
• 避免 TTY 問題！

完整的 Docker 設置指南請參考 DOCKER_USAGE.md。

選項 2：使用 pip（Python 推薦）

pip install git+https://github.com/florinel-chis/prestashop-mcp.git

選項 3：從源代碼安裝

git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp
pip install -e .

📚 詳細文檔

文檔設置

MCP 服務器需要訪問 PrestaShop 官方文檔 倉庫以進行索引。

Docker 設置（自動）

Docker 會自動處理文檔：

• 首次運行時，會克隆 PrestaShop 文檔倉庫。
• 構建 Docker 鏡像時，會將文檔打包進去。
• 無需手動設置！

本地 Python 設置（手動）

對於本地安裝，需克隆文檔倉庫：

# 將 PrestaShop 文檔克隆到 prestashop-mcp 的同級目錄
cd /path/to/your/projects/
git clone https://github.com/PrestaShop/docs.git prestashop-docs

# 目錄結構應如下所示：
# /path/to/your/projects/
#   ├── prestashop-mcp/     (此倉庫)
#   └── prestashop-docs/    (PrestaShop 官方文檔)

# MCP 服務器會自動找到它

或者設置自定義位置：

# 設置環境變量
export PRESTASHOP_DOCS_PATH=/path/to/prestashop-docs

# 然後運行服務器
prestashop-mcp

文檔路徑優先級

服務器按以下順序查找文檔：

1. 環境變量：PRESTASHOP_DOCS_PATH（若已設置）。
2. 同級目錄：../prestashop-docs（相對於 MCP 服務器）。
3. 項目內部：./prestashop-docs（用於 Docker 構建）。

首次運行索引

首次運行時，服務器會：

1. 定位 PrestaShop 文檔倉庫。
2. 解析並索引 1095 份以上的 Markdown 文件。
3. 提取元數據（鉤子、組件、API、指南）。
4. 使用 Porter 詞幹提取算法構建 SQLite FTS5 搜索索引。
5. 將索引存儲在 ~/.mcp/prestashop-docs/database.db 中。

首次運行索引大約需要 30 - 60 秒，之後將使用緩存數據庫實現即時啟動。

強制重新索引：

# 本地安裝
python -m prestashop_mcp.ingest_v2 --force

# 或者刪除數據庫
rm ~/.mcp/prestashop-docs/database.db

💻 使用示例

在 Claude Desktop 中使用

標準安裝： 編輯 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "prestashop": {
      "command": "prestashop-mcp"
    }
  }
}

Docker 安裝（使用包裝腳本）：

{
  "mcpServers": {
    "prestashop": {
      "command": "/absolute/path/to/prestashop-mcp/run-docker-mcp.sh"
    }
  }
}

Docker 安裝（HTTP 傳輸）：

{
  "prestashop": {
    "type": "http",
    "url": "http://localhost:8765/mcp"
  }
}

（需要先運行 docker compose up -d）

在 VS Code 中使用

在項目根目錄創建 .mcp.json：

{
  "mcpServers": {
    "prestashop": {
      "type": "stdio",
      "command": "prestashop-mcp"
    }
  }
}

在 Claude Code 中使用

在項目根目錄創建 .mcp.json：

{
  "mcpServers": {
    "prestashop": {
      "command": "/absolute/path/to/run-docker-mcp.sh"
    }
  }
}

或者對於本地 Python 安裝：

{
  "mcpServers": {
    "prestashop": {
      "command": "python",
      "args": ["-m", "prestashop_mcp.server"]
    }
  }
}

在 Cursor 中使用

在 Cursor 的 MCP 配置中添加（設置 > 功能 > MCP 服務器）：

{
  "mcpServers": {
    "prestashop": {
      "command": "prestashop-mcp"
    }
  }
}

🛠️ 可用的 MCP 工具

配置完成後，你的 AI 助手可使用 7 種專業工具：

文檔工具

1. search_prestashop_docs(query, doc_type, category)

使用全文搜索功能搜索所有 PrestaShop 文檔。 參數：

• query：搜索詞。
• doc_type：按類型過濾，如鉤子、指南、教程、API、組件等。
• category：按類別過濾，如基礎、開發、模塊、主題等。 示例：

"搜索 PrestaShop 模塊開發文檔"
"查找 Mac 安裝指南"

2. get_prestashop_doc(path)

獲取特定文檔文件的完整內容。 示例：

"獲取 Mac 安裝指南"

3. list_prestashop_docs(doc_type, category)

列出可用的文檔文件，可選擇過濾條件。 示例：

"列出所有 PrestaShop 指南"
"顯示所有教程文檔"

4. get_prestashop_stats()

獲取索引文檔的統計信息。 示例：

"顯示 PrestaShop 文檔統計信息"

鉤子工具

5. search_prestashop_hooks(queries, hook_type, origin)

專門搜索 PrestaShop 鉤子。 示例：

"查找所有與產品相關的鉤子"

6. get_prestashop_hook(hook_name)

獲取特定鉤子的完整文檔。 示例：

"顯示 displayHeader 鉤子的文檔"

7. list_prestashop_hooks(hook_type, origin)

按類型和來源列出所有鉤子。 示例：

"列出所有顯示鉤子"

💬 示例查詢

你可以向 AI 助手提出以下問題： 安裝與設置：

• "如何在 Mac 上本地安裝 PrestaShop？"
• "PrestaShop 的系統要求是什麼？"
• "顯示 Docker 安裝指南"

模塊開發：

• "如何創建 PrestaShop 模塊？"
• "搜索模塊開發教程"
• "PrestaShop 模塊的結構是怎樣的？"

主題開發：

• "如何開發 PrestaShop 主題？"
• "顯示 Twig 模板文檔"
• "查找主題開發指南"

鉤子：

• "顯示 displayHeader 鉤子的文檔"
• "查找所有與產品相關的鉤子"
• "列出所有顯示鉤子"
• "actionProductAdd 鉤子的工作原理是什麼？"

組件與架構：

• "PrestaShop 中有哪些 UI 組件？"
• "顯示錶單類型文檔"
• "解釋 PrestaShop 中的 CQRS 模式"

API：

• "如何使用 PrestaShop 管理 API？"
• "顯示 Web 服務文檔"
• "查找 API 端點參考"

通用：

• "顯示 PrestaShop 文檔統計信息"
• "列出所有可用指南"
• "搜索部署文檔"

📊 文檔覆蓋範圍

總計：1095 份以上索引文檔

按文檔類型劃分

• 647 個鉤子：包含所有 PrestaShop 鉤子及其元數據。
  • 顯示鉤子（渲染內容）
  • 操作鉤子（觸發功能）
  • 核心、模塊和主題鉤子
  • 後臺和前臺位置
• 138 份通用文檔：指南、教程、貢獻文檔。
• 119 個組件：表單、網格、服務、UI 組件。
• 96 個 API 參考：管理 API、Web 服務、域參考。
• 64 份參考文檔：技術參考和規範。
• 12 份指南：安裝、部署、開發指南。
• 10 份常見問題解答：常見問題。
• 9 份教程：分步教程。

按類別劃分

• 697 份模塊文檔：模塊開發和鉤子。
• 208 份開發文檔：組件、架構、模式。
• 88 份 Web 服務文檔：API 和 Web 服務參考。
• 29 份主題文檔：主題開發和模板。
• 22 份貢獻文檔：參與 PrestaShop 開發的文檔。
• 17 份基礎文檔：安裝、系統要求、部署。
• 還有更多...

專業數據

• 386 個域參考：CQRS 命令和查詢。
• 119 個 UI 組件：表單類型、網格列等。

🔧 技術細節

運行測試

# 運行所有測試
pytest

# 運行特定測試
pytest tests/test_ingest.py

# 運行測試並統計覆蓋率
pytest --cov=prestashop_mcp

手動測試

# 索引文檔（使用新的綜合索引器）
python -m prestashop_mcp.ingest_v2

# 強制重新索引
python -m prestashop_mcp.ingest_v2 --force

# 檢查數據庫
sqlite3 ~/.mcp/prestashop-docs/database.db "SELECT COUNT(*) FROM prestashop_docs;"

# 按類型統計文檔數量
sqlite3 ~/.mcp/prestashop-docs/database.db "SELECT doc_type, COUNT(*) FROM prestashop_docs GROUP BY doc_type;"

工作原理

1. 索引過程：首次運行時，將 1095 份以上的文檔文件索引到 SQLite 中，並使用 FTS5 技術。涵蓋鉤子、指南、教程、API 文檔、組件等內容，自動進行分類和元數據提取，同時檢測 CQRS 域參考和 UI 組件。
2. 存儲方式：文檔存儲在 ~/.mcp/prestashop-docs/database.db 中。
3. 搜索功能：使用 SQLite FTS5 進行高效的全文搜索，並支持排名功能。採用 Porter 詞幹提取算法以提高搜索結果的準確性，同時支持按文檔類型、類別和其他元數據進行過濾。
4. 檢索方式：支持按路徑或名稱直接查找，實現即時訪問。
5. 多傳輸協議：支持 STDIO（本地）、HTTP 和 SSE（遠程）協議。

🤝 貢獻代碼

歡迎貢獻代碼！請閱讀 貢獻指南。

快速開始

# 分叉並克隆倉庫
git clone https://github.com/florinel-chis/prestashop-mcp.git
cd prestashop-mcp

# 創建虛擬環境
python -m venv venv
source venv/bin/activate  # 或者在 Windows 上使用 `venv\Scripts\activate`

# 安裝開發依賴
pip install -e ".[dev]"

# 運行測試
pytest

# 格式化代碼
black prestashop_mcp/

# 進行修改並提交 PR

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🙏 致謝

• 靈感來源於 Shopify Liquid MCP。
• Docker 集成借鑑了 Magento GraphQL Docs MCP 的最佳實踐，感謝 @cmuench。
• 基於 FastMCP 構建。
• 文檔來源於 PrestaShop Docs。
• MCP 協議由 Anthropic 提供。

🔗 相關項目

• Shopify Liquid MCP：用於 Shopify 主題開發。
• Magento GraphQL Docs MCP：用於 Magento 開發。
• FastMCP：MCP 服務器框架。
• Model Context Protocol：MCP 規範。

📞 支持

• 🐛 問題反饋
• 💬 討論交流

為 PrestaShop 開發社區精心打造 ❤️