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 开发社区精心打造 ❤️