Freento Mcp Server

Freento MCP for Magento 2 — 用户指南

使用 Model Context Protocol（MCP）将 Magento 2 商店连接到 Claude 和 ChatGPT 等 AI 助手。

目录

• 概述
• 要求
• 安装
• 配置
  • Claude Code
  • Claude Desktop
  • ChatGPT
• 可用工具
• 使用示例
• 筛选与运算符
• 聚合与分析
• 故障排除
• 安全性

概述

Freento MCP 是一个 Magento 2 扩展，实现了 Model Context Protocol——这是一项用于将 AI 助手连接到外部数据源的开放标准。借助此扩展，您可以：

• 使用自然语言查询订单、产品、客户和库存
• 即时生成销售报告和分析
• 监控系统健康状况（PHP、MySQL、缓存、搜索引擎版本）
• 审核管理员用户和安全设置

工作原理：

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AI Assistant   │  HTTP   │  Freento MCP    │         │   Magento 2 /   │
│  (Claude/GPT)   │ ◄─────► │  Server         │ ◄─────► │Server Resources │
└─────────────────┘ JSON-RPC└─────────────────┘         └─────────────────┘

MCP 服务充当 AI 助手与您的 Magento 安装之间的安全桥梁，可访问数据库、配置和其他 Magento 子系统等各类商店资源。

要求

• Magento 2.4.x（Open Source 或 Commerce）
• PHP 8.1 或更高版本
• 兼容 MCP 的 AI 客户端（Claude Code、Claude Desktop，或带 MCP 插件的 ChatGPT）

安装

通过 Composer（推荐）

composer require freento/module-mcp
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

手动安装

1. 下载模块并解压到 app/code/Freento/Mcp/
2. 启用模块：

php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

验证安装

php bin/magento module:status Freento_Mcp

预期输出：Module is enabled

配置

步骤 1：创建 ACL 角色

1. 在 Magento Admin 中，前往 System > Freento MCP > ACL Rules
2. 点击 Add New Role
3. 输入名称（例如“AI 助手”）
4. 选择该角色可访问的工具：
   • 销售工具（订单、报价、贷项通知单）
   • 目录工具（产品、库存）
   • 客户工具
   • 管理工具
   • 系统工具
5. 保存角色

步骤 2：创建 OAuth 客户端

1. 前往 System > Freento MCP > AI MCP Clients
2. 点击 Add New Client
3. 输入名称（例如“Claude Code”）
4. 选择在步骤 1 中创建的 ACL 角色
5. 保存客户端
6. 复制 Client ID 和 Client Secret

步骤 3：生成访问令牌

1. 打开您创建的 OAuth 客户端
2. 点击 Generate OTP——复制一次性密码（有效期为 24 小时）
3. 点击 Generate Token——在提示时输入 OTP
4. 复制生成的 Access Token

Claude Code

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

然后在 Claude Code 中重新连接 MCP：

/mcp

Claude Desktop

编辑您的 Claude Desktop 配置（Linux/Mac 上为 ~/.config/claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

重启 Claude Desktop 以应用更改。

ChatGPT 和其他 Web 客户端

对于支持 OAuth 2.0 的 Web AI 工具：

1. 注册您商店的 MCP 端点：https://your-store.com/freento_mcp/index/index
2. 输入步骤 2 中的 Client ID 和 Client Secret
3. 在提示授权时，输入从 OAuth 客户端页面生成的 OTP
4. 完成 OAuth 授权流程

可用工具

每个工具都支持灵活的筛选、排序和分页。结合 AI 后，这些功能几乎可以无限扩展——AI 可以执行多项查询、交叉引用数据、对结果进行分组和聚合，并提供智能分析。

AI 可以：

• 在一次对话中跨不同实体执行多项查询
• 使用运算符按任意字段筛选：eq、neq、in、like、gt、gte、lt、lte
• 对结果进行排序和分页
• 使用 sum、count、avg、min、max 进行聚合
• 按字段或时间段（天、月）分组
• 组合并分析来自多个来源的数据

销售工具

工具	描述
get_orders	查询订单，支持筛选、分页和聚合
get_order_items	获取订单行项目（订单中的产品）
get_quotes	查询购物车（进行中和已弃用）
get_quote_items	获取购物车行项目
get_creditmemos	查询贷项通知单

营销工具

工具	描述
get_cart_price_rules	查询购物车价格规则
get_coupons	查询优惠券

商品目录工具

工具	描述
get_products	查询产品，支持按属性筛选
get_categories	查询产品类别
get_product_prices	按客户组和网站获取产品价格
get_product_tier_prices	获取阶梯价格规则（基于数量的折扣）
get_tax_rules	获取税务规则和税率
get_stock_single_stock	获取库存水平

客户工具

工具	描述
get_customers	查询客户账户

管理工具

工具	描述
get_admins	列出管理员用户及其角色
get_locked_admins	查找被锁定的管理员账户（登录失败次数过多）

系统工具

工具	描述
get_system_versions	获取 Magento、PHP、MySQL、Redis、OpenSearch 版本
get_stores	获取商店层级结构（网站、商店组、商店视图）

使用示例

完成配置后，你可以用自然语言向 AI 助手提问：

订单与销售

"How many orders were placed last month?"
"Show me the 10 most recent orders"
"Find all orders over $500 that are still processing"
"What's the total revenue by payment method this year?"
"List orders for customer [email protected]"

产品与库存

"Show me out of stock products"
"Find products with SKU starting with 'ABC'"
"List products with less than 10 items in stock"
"Get all configurable products updated this week"

客户

"How many customers registered this month?"
"Find customer with email [email protected]"
"List customers in the Wholesale group"

系统与管理

"What PHP version is running?"
"Show me all admin users"
"Are there any locked admin accounts?"
"What search engine is configured?"

分析与报告

"Revenue by month for the last 12 months"
"Top 10 customers by total order value"
"Average order value by payment method"
"Order count by status"

高级 AI 驱动分析

真正的强大之处在于将数据与 AI 推理相结合。提出复杂的业务问题，获取可执行的洞察：

客户洞察：

"Analyze my top 10 customers from the last 6 months. Who are they,
what do they buy, and how can I increase sales?"

AI 将检索数据并提供如下分析：

Mike Johnson — 总计 $4,250，8 笔订单 客户画像：职业鼓手，每隔 5-6 周购买镲片和鼓棒

建议：为鼓棒设置自动补货，提供新到镲片的抢先选购机会，并考虑推出“鼓手忠诚度”折扣等级。

客户流失预防：

"Find customers who were active but haven't ordered in 90 days.
What patterns do you see and how can I win them back?"

库存优化：

"Analyze sales velocity vs current stock levels.
What should I reorder and what's at risk of becoming dead stock?"

收入机会：

"What patterns exist in high-value orders? How can I get more customers
to spend at that level?"

弃置购物车分析：

"Look at abandoned carts from this week. What are people leaving behind
and what might be causing it?"

这能将商店数据转化为战略性商业情报，提供通常需要花费数小时处理电子表格或聘请专职分析师才能获得的洞察。

筛选与运算符

所有列表工具都支持通过 filters 参数进行强大的筛选。

筛选结构

{
  "filters": {
    "field_name": { "operator": "value" }
  }
}

可用运算符

运算符	描述	示例
eq	等于	{"status": {"eq": "processing"}}
neq	不等于	{"status": {"neq": "canceled"}}
in	在列表中	{"status": {"in": ["processing", "complete"]}}
nin	不在列表中	{"status": {"nin": ["canceled", "closed"]}}
like	SQL LIKE 模式	{"email": {"like": "%@gmail.com"}}
nlike	SQL NOT LIKE	{"sku": {"nlike": "TEST%"}}
gt	大于	{"grand_total": {"gt": 100}}
gte	大于或等于	{"qty": {"gte": 10}}
lt	小于	{"created_at": {"lt": "2024-01-01"}}
lte	小于或等于	{"price": {"lte": 50}}

组合筛选条件

多个筛选条件将通过 AND 逻辑组合：

{
  "filters": {
    "status": {"in": ["processing", "pending"]},
    "grand_total": {"gte": 100},
    "created_at": {"gte": "2024-01-01"}
  }
}

日期筛选

使用 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS 格式：

{
  "filters": {
    "created_at": {"gte": "2024-01-01", "lt": "2024-02-01"}
  }
}

聚合与分析

get_orders 工具支持用于分析的聚合功能：

参数

参数	值	描述
function	count, sum, avg, min, max	聚合函数
field	grand_total, total_qty_ordered, total_item_count	要聚合的字段
group_by	status, month, day, customer_email, store_id, payment_method	分组方式

示例

订单总数：

{"function": "count"}

按月统计收入：

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "month"
}

按付款方式统计平均订单金额：

{
  "function": "avg",
  "field": "grand_total",
  "group_by": "payment_method"
}

消费金额最高的前 10 位客户：

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "customer_email",
  "filters": {
    "status": {"nin": ["canceled", "closed"]}
  },
  "limit": 10
}

故障排除

工具未显示在 AI 助手中

1. 确认模块已启用：

   php bin/magento module:status Freento_Mcp
   

2. 刷新 Magento 缓存：

   php bin/magento cache:flush
   

3. 在 AI 客户端中重新连接 MCP（例如，在 Claude Code 中输入 /mcp）

“身份验证失败”错误

• 确认访问令牌正确
• 检查 Magento Admin 中的 OAuth Client 是否已启用
• 如果令牌已过期，请重新生成

“访问被拒绝”错误

ACL Role 缺少所需权限。请在 System > Freento MCP > ACL Rules 中编辑 ACL Role，并授予必要工具的访问权限。

连接超时

• 确认可以从互联网访问 Magento 商店
• 检查防火墙规则是否允许传入连接
• 对于本地开发，请使用 ngrok 等隧道服务

手动测试端点

curl -X POST https://your-store.com/freento_mcp/index/index \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

安全

最佳实践

1. 使用 HTTPS — 在生产环境中始终使用 HTTPS 加密 API 通信

2. 最小权限 — 通过 ACL Roles 仅授予用例所需的工具权限

3. 分离客户端 — 为不同用户或用途创建独立的 OAuth Clients

4. 定期审计 — 定期检查活跃客户端，并停用不再使用的客户端

5. 令牌轮换 — 定期重新生成访问令牌

6. 匿名模式 — 在 Stores > Configuration > Freento MCP > Privacy 中启用匿名模式，以在 MCP 工具响应中隐藏 PII 字段（电子邮件、姓名）。由于通过 MCP 连接的 AI 助手属于第三方服务，建议启用此模式，避免客户个人数据被传输到外部，除非明确需要传输这些数据。

令牌安全

• 切勿将令牌提交到版本控制系统
• 使用环境变量或安全的机密管理方案
• 定期轮换令牌
• 如果令牌遭到泄露，请立即撤销

支持

联系：https://freento.com/contact

许可证

MIT 许可证 — 详情请参阅 LICENSE。