Prestashop MCP Analytics

PrestaShop MCP分析

MCP服务器，用于通过LLM接口进行只读PrestaShop销售分析。

 ](https://nodejs.org/) 

🎯 特性

• 📊 产品销售统计 -按产品列出的详细销售明细
• 🔍 按名称搜索产品 -使用自然语言搜索查找产品（v1.3中的新功能）
• 🏆 畅销产品 -按数量或收入分列的畅销书
• 📅 灵活的日期范围 -查询任何期间（最多2年）
• 🎨 多种输出格式 -JSON用于API，Markdown用于人类
• 🔒 安全且只读 -无写操作，基于环境的身份验证
• ⚡ 高效分页 -通过自动分页处理大型数据集
• 🎯 订单状态筛选 -按订单状态筛选以获得准确报告

📋 先决条件

• Node.js 18+
• PrestaShop 1.7.x或8.x，启用Web服务
• API密钥 具有读取权限 orders, order_details, products

🚀 安装

1.从npm安装

npm install @dfr_contact/prestashop-mcp-analytics

或者克隆并安装以进行开发：

git clone 
cd prestashop-mcp-analytics
npm install

2.配置环境

cp .env.example .env
# Edit .env with your PrestaShop credentials

所需变量：

PRESTASHOP_BASE_URL=https://your-prestashop-store.com
PRESTASHOP_WS_KEY=YOUR_32_CHARACTER_WEBSERVICE_KEY

3.建造

npm run build

4.跑步

npm start

🔧 PrestaShop设置

1. 首选 高级参数>Web服务
2. 启用Web服务
3. 创建新的API密钥：

- 点击“添加新的Web服务密钥” - 生成一个32个字符的密钥 - 启用密钥（状态：是） - 授予 获取 权限： - orders - order_details - products - 保存

🛠️ 用法

使用克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "prestashop-analytics": {
      "command": "npx",
      "args": ["-y", "@dfr_contact/prestashop-mcp-analytics"],
      "env": {
        "PRESTASHOP_BASE_URL": "https://your-store.com",
        "PRESTASHOP_WS_KEY": "your_32_character_key_here"
      }
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "prestashop-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@dfr_contact/prestashop-mcp-analytics/dist/index.js"],
      "env": {
        "PRESTASHOP_BASE_URL": "https://your-store.com",
        "PRESTASHOP_WS_KEY": "your_32_character_key_here"
      }
    }
  }
}

查询示例

获取产品销售统计数据（按ID或名称）：

"How many units of product ID 42 were sold in September 2024?"
"Show me revenue for product #15 this quarter"
"What are the sales for 'DJI O4 Air Unit' last month?"
"Get stats for 'Condensateur Panasonic' this week"

获取顶级产品：

"What are my top 5 products this month?"
"Show me top 10 products by revenue in Q4 2024"

🔍 按名称搜索产品（v1.3中的新功能）

现在，您可以使用产品名称而不是ID搜索产品：

直接产品名称：

{
  "product_name": "DJI O4 Air Unit",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31"
}

部分匹配（不区分大小写）：

{
  "product_name": "motor",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31"
}

特征：

• ✅ 不区分大小写 部分匹配
• ✅ 多语言 支持（所有语言的搜索）
• ✅ 快速性能 （500个产品约200-350ms）
• ✅ 智能操控:

- 0结果→ 有用的错误消息 - 1结果→ 自动选择 - 多重返回值→ 可供选择的交互式列表

对话示例：

User: "Show me sales for Condensateur Panasonic last week"
Assistant: Found 2 products:
  1. Condensateur Panasonic Low ESR 680uF 35V (ID: 2557)
  2. Condensateur Panasonic Low ESR 1000uF 35V (ID: 3249)

Please specify which product you want by using the product_id.

🎯 订单状态过滤（v1.1中的新功能）

这两个工具都支持按PrestaShop订单状态进行过滤，以实现精确的报告：

匹配PrestaShop后台统计信息：

{
  "product_id": 42,
  "date_from": "2025-01-01",
  "date_to": "2025-01-31",
  "order_states": [4, 5]
}

常见的PrestaShop状态：

• 1 -等待支票付款
• 2 -已接受付款
• 3 -处理中
• 4 -已发货
• 5 -已交付
• 6 -已取消
• 7 -已退款
• 8 -付款错误

推荐过滤器：

• 后台对等: [4, 5] （仅发货+交付）
• 所有有效订单: [2, 3, 4, 5] （通过交付接受付款）
• 所有州：省略参数（默认行为）

💡 提示： PrestaShop后台通常从统计数据中排除处理（3）和退款（7）状态。使用 order_states: [4, 5] 完全匹配。

🧪 发展

命令

npm run build          # Compile TypeScript
npm run dev            # Watch mode with auto-rebuild
npm test               # Run tests
npm run test:watch     # Tests in watch mode
npm run test:coverage  # Generate coverage report
npm run lint           # Check code quality
npm run lint:fix       # Auto-fix linting issues
npm run format         # Check code formatting
npm run format:fix     # Auto-format code

项目结构

src/
├── index.ts                    # Entry point + MCP server setup
├── config.ts                   # Configuration & environment
├── types.ts                    # TypeScript interfaces
├── constants.ts                # Global constants
├── schemas/                    # Zod validation schemas
│   ├── common.schema.ts
│   ├── product-sales-stats.schema.ts
│   └── top-products.schema.ts
├── services/                   # Business logic
│   ├── prestashop-api.service.ts
│   └── orders.service.ts
├── formatters/                 # Output formatting
│   ├── json.formatter.ts
│   └── markdown.formatter.ts
├── tools/                      # MCP tool handlers
│   ├── get-product-sales-stats.tool.ts
│   └── get-top-products.tool.ts
└── utils/                      # Utilities
    ├── date.utils.ts
    ├── error.utils.ts
    ├── validation.utils.ts
    └── truncation.utils.ts

📚 文档

• CLAUDE.md -完整的项目架构和规范
• 实施_计划.md -日常实施指南

🔒 安全

• ✅ 只读操作（GET请求）
• ✅ 基于环境的身份验证
• ✅ 使用Zod进行严格的输入验证
• ✅ 请求超时（30秒）
• ✅ 响应大小限制（25000个字符）
• ✅ 日志中没有秘密

⚠️ 局限性

• 日期范围： 每次查询最多730天（2年）
• 产品限制： 每项请求1-100件产品
• 响应大小： 截断为25000个字符
• 订单： 每次查询最多处理1000个订单
• 操作： 只读，不支持写

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📝 许可证

MIT许可证-请参阅 许可证 详细信息文件

🆘 支持

对于问题和疑问：

• 检查 CLAUDE.md 故障排除部分
• 在GitHub上打开一个问题

🎉 致谢

内置：

• 模型上下文协议SDK
• 萨德 用于验证
• 阿西奥斯 对于HTTP请求