内容
# Wegmans-MCP
一款让 AI 助手与 Wegmans 连锁超市互动的 MCP（模型上下文协议）服务器。搜索产品、查找商店位置、管理购物车、查看购买记录 — 所有操作都可以通过自然语言完成。
## 功能
该服务器连接到 Wegmans 的 Algolia 搜索 API 和商业后端，提供了 12 种工具：
| 工具 | 是否需要认证 | 描述 |
| --- | --- | --- |
| `search_products` | 否 | 完整的产品搜索，包含价格、货架位置、图片和评分 |
| `get_product_details` | 否 | 通过 ID 进行详细的产品查询 |
| `browse_category` | 否 | 按部门（农产品、熟食、烘焙食品等）浏览 |
| `find_stores` | 否 | 通过城市、州或邮政编码查找商店编号 |
| `get_my_items` | 否 | 您最常购买的商品，按购买频率排名 |
| `add_to_cart` | 是 | 将商品添加到您的真实 Wegmans 购物车 |
| `get_cart` | 是 | 查看当前购物车内容 |
| `refresh_my_items` | 否 | 从浏览器捕获（旧版）更新购买记录 |
| `sync_purchase_history` | 是 | 从收据、订单和排名中获取完整的购买记录 |
| `get_purchase_patterns` | 否* | 分析您购买每种商品的频率和再次购买的时间 |
| `get_shopping_suggestions` | 否* | 智能购物清单 — 您可能需要的商品，按紧急程度排序 |
| `get_product_history` | 否* | 特定商品的完整购买时间线 |
* 读取由 `sync_purchase_history` 同步的本地数据。
未经身份验证的工具可以直接使用 — 无需账户。购物车和同步操作需要您的 Wegmans 凭证。
## 设置
```bash
git clone https://github.com/BrianVia/wegmans-mcp.git
cd wegmans-mcp
npm install
npm run build
```
### 添加到 Claude Code
```json
{
"mcpServers": {
"wegmans": {
"command": "node",
"args": ["/path/to/wegmans-mcp/dist/index.js"],
"env": {
"WEGMANS_STORE": "133"
}
}
}
}
```
### 添加到 Claude 桌面版
```json
{
"mcpServers": {
"wegmans": {
"command": "node",
"args": ["/path/to/wegmans-mcp/dist/index.js"],
"env": {
"WEGMANS_STORE": "133",
"WEGMANS_EMAIL": "your-email@example.com",
"WEGMANS_PASSWORD": "your-password",
"WEGMANS_CUSTOMER_ID": "your-customer-uuid"
}
}
}
}
```
## 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `WEGMANS_STORE` | 否 | 您的商店编号（默认为 `133`）。使用 `find_stores` 查找您的商店编号。 |
| `WEGMANS_EMAIL` | 用于购物车操作 | 您的 wegmans.com 账户邮箱 |
| `WEGMANS_PASSWORD` | 用于购物车操作 | 您的 wegmans.com 账户密码 |
| `WEGMANS_CUSTOMER_ID` | 用于购物车操作 | 您的 Wegmans 客户 UUID（参见 [查找您的客户 ID](#finding-your-customer-id)） |
## 查找您的商店编号
每个 Wegmans 商店都有一个用于定价、库存和货架位置的数字商店 ID。
**常见商店：**
| 商店 | 编号 |
| --- | --- |
| Chantilly, VA（14361 Newbrook Dr.） | `133` |
| Reston, VA（11950 Hopper St.） | `146` |
使用 `find_stores` 工具查找其他商店，或：
```
> find_stores("Reston")
Reston, VA — 商店 #146 — 11950 Hopper St., Reston, VA 20191
> find_stores("VA")
Dulles #7, Fairfax #16, Chantilly #133, Reston #146, Tysons #115, ...
```
商店编号决定了可用的商品、价格和返回的货架位置。商店的库存不同，因此这很重要。
## 查找您的客户 ID
您的客户 ID 是 Wegmans 分配给您的账户的 UUID。要查找它：
1. 登录 [wegmans.com](https://www.wegmans.com)
2. 打开开发者工具（F12）→ 网络选项卡
3. 搜索任何发送到 `algolia.net` 的请求
4. 在请求体中查找 `userToken` — 那是您的客户 ID
它看起来像：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`（一个 UUID）
## 使用示例
### 搜索产品
搜索返回产品名称、店内和配送价格、货架位置、图片、评分、过敏信息等。
```
> search_products("lactose free 2% milk")
1. fairlife 2% Reduced Fat Ultra-Filtered Milk, Lactose Free — $5.49（货架：乳制品）
2. Lactaid Milk, Reduced Fat, 2% Milkfat — $5.99（货架：乳制品）
3. Wegmans 2% Reduced Fat Lactose Free Milk — $3.79（货架：乳制品）
4. Organic Valley Milk, Lactose Free, Reduced Fat, 2% — $6.29（货架：乳制品）
```
```
> search_products("bananas", { max_results: 2 })
1. Bananas, Sold by the Each — $0.19 ($0.49/lb.) — 货架：农产品
2. Organic Bananas, Bunch — $1.38 ($0.69/lb.) — 货架：农产品
```
### 将商品添加到购物车
`add_to_cart` 工具接受产品 ID（来自搜索结果）和数量。它查找完整产品详情，与 Wegmans 进行身份验证，并将其添加到您的真实购物车中。
```
> add_to_cart("92685", 5)
Added to cart: 5x Bananas, Sold by the Each ($0.19 each)
> add_to_cart("116893", 1)
Added to cart: 1x Lactaid Milk, Reduced Fat, 2% Milkfat ($5.99 each)
```
商品累计 — 每次添加操作都会读取现有的购物车并合并新商品，因此您不会丢失已有的商品。
### 查看您最常购买的商品
`get_my_items` 工具返回您的购买记录，按频率排名。这对于创建每周购物清单或让 AI 建议您可能需要的商品非常有用。
```
> get_my_items({ limit: 10 })
您的前 10 个最常购买商品（共 546 个）：
1. Wegmans Grade AA Large Eggs, 18 Count — $2.49（货架：乳制品）
2. Lactaid Milk, Reduced Fat, 2% Milkfat — $5.99（货架：乳制品）
3. Bananas, Sold by the Each — $0.19（货架：农产品）
4. Large Fresh Limes — $0.50（货架：农产品）
5. Strawberries — $2.99（货架：农产品）
6. Wegmans Organic Lemonade — $3.49（货架：18A）
7. Wegmans Cherry Tomatoes on the Vine, Flavor Bombs — $5.79（货架：农产品）
8. Wegmans Pancake Mix — $2.29（货架：11B）
9. Lemons — $0.69（货架：农产品）
10. MadeGood Mornings Soft Baked Blueberry Flavor Oat Bars — $4.49（货架：04B）
```
### 批量添加您的常购商品
AI 助手可以将 `get_my_items` 与 `add_to_cart` 结合使用，快速创建您的每周购物车：
```
"添加我的前 10 个常购商品"
OK — Wegmans Grade AA Large Eggs, 18 Count （购物车中有 10 件商品）
OK — Lactaid Milk, Reduced Fat, 2% Milkfat （购物车中有 10 件商品）
OK — Bananas, Sold by the Each （购物车中有 10 件商品）
OK — Large Fresh Limes （购物车中有 10 件商品）
OK — Strawberries （购物车中有 10 件商品）
...
```
### 购买智能 - “我本周需要什么？”
真正的强大功能：同步您的完整购买记录，然后让 AI 计算出您需要什么。
**步骤 1：同步您的记录**（获取 63+ 收据和 71+ 订单来自 Wegmans）
```
> sync_purchase_history
购买记录同步：
- 63 张店内收据（862 个商品明细）
- 71 个在线订单（1238 个商品明细）
- 2100 个总购买事件
- 818 个跟踪的独特商品
```
**步骤 2：查看您的购买模式**
```
> get_purchase_patterns({ product_name: "milk" })
1. [~] Milk, Reduced Fat, 2% Milkfat （乳制品）
53 次购买 | 每 ~7 天 | 上次：1 天前 | 即将到期：6 天
> get_purchase_patterns({ urgency: "overdue" })
1. [!!] Clementines, Bagged （农产品）— 68 天前，通常每 26 天（逾期 42 天）
2. [!!] Whipped Cream Cheese Spread （乳制品）— 63 天前，通常每 24 天（逾期 39 天）
...
```
**步骤 3：获取智能购物清单**
```
> get_shopping_suggestions({ lookahead_days: 7 })
1. [!!] Clementines, Bagged （农产品）[ID: 44091]
上次购买 68 天前，您通常每 26 天购买一次（逾期 42 天）
2. [!!] Cream Cheese Icing Cinnamon Rolls （乳制品）[ID: 139106]
上次购买 38 天前，您通常每 24 天购买一次（逾期 15 天）
3. [!] Bananas, Sold by the Each （农产品）[ID: 92685]
上次购买 5 天前，您通常每 8 天购买一次（3 天后到期）
```
**步骤 4：深入了解特定产品**
```
> get_product_history({ product_id: "116893" })
## Milk, Reduced Fat, 2% Milkfat （ID: 116893）
您大约每 7 天购买一次该商品（基于 53 次购买）。上次购买于 1 天前。
摘要：53 次购买 | 总花费：$351.49 | 平均每次购买：$6.63
| 日期 | 数量 | 价格 | 来源 | 商店 |
|------------|-----|--------|---------|-------|
| 2026-04-04 | 2 | $13.78 | 订单 | - |
| 2026-03-26 | 1 | $6.89 | 订单 | - |
| 2026-03-21 | 1 | $6.89 | 订单 | - |
| ... | | | | |
```
**终极组合**：询问 AI 助手“将我本周需要的所有商品添加到购物车” — 它会调用 `get_shopping_suggestions` 然后为每个商品调用 `add_to_cart`。
### 遗留：从浏览器刷新我的商品
`refresh_my_items` 工具仍然适用于更新基于 Algolia 的频率排名。对于具有时间戳和模式的完整购买记录，请改用 `sync_purchase_history`。
## 架构
```
src/
index.ts # MCP 服务器 — 工具定义和处理程序
algolia.ts # Algolia 产品搜索客户端
auth.ts # Azure AD B2C OAuth 身份验证（PKCE 流）
cart.ts # 购物车操作（添加到购物车，获取购物车，产品查找）
stores.ts # 商店定位器（从 wegmans.com/api/stores 获取）
receipts.ts # 店内收据获取器（63+ 收据，包含商品详情）
orders.ts # 在线订单获取器（71+ 订单，包含商品明细）
my-items-api.ts # Wegmans 我的商品 API（排名列表，包含 lastPurchasedDate）
purchase-history.ts # 统一数据层 — 合并所有来源，本地持久化
patterns.ts # 纯分析 — 间隔，预测，购物建议
my-items.ts # 查询 Algolia 以获取评分的产品列表
refresh-my-items.ts # 解析和保存购买记录数据
data/
purchase-history.json # 统一购买时间线（gitignored）
my-items.json # 基于 Algolia 的旧频率缓存（gitignored）
docs/
api-reference.md # 文档化的 Wegmans API 端点
```
### 工作原理
**产品搜索** 直接使用 Wegmans 的 Algolia 索引，使用他们的公共搜索 API 密钥。不需要身份验证。每个产品都有特定于商店的定价、货架位置和可用性 — 因此 `WEGMANS_STORE` 设置很重要。
**购物车操作** 使用 `api.digitaldevelopment.wegmans.cloud` 处的 Wegmans 商业 API。身份验证通过 Azure AD B2C 使用 PKCE OAuth 流进行 — 服务器处理完整的登录流程（GET 授权页面 → POST 凭证 → GET 授权码 → 交换令牌）并缓存访问令牌，直到令牌过期。
**购买智能** 同步三个 API 来源：
- `/commerce/receipts` — 63+ 张店内收据，包含商品级详情（商品、数量、价格、时间戳、商店）
- `/commerce/order/orders/{id}` — 71+ 个在线订单，包含商品明细
- `/commerce/my-items` — 排名商品列表，包含 `lastPurchasedDate`
这些被合并成 `data/purchase-history.json` 中的统一时间线。`patterns.ts` 模块使用中位数（对异常值稳健）计算每个产品的购买间隔，分类紧急程度，并生成购物建议。您停止购买的商品在 3 次购买间隔或 90 天后会自动过滤掉。
### 商店感知数据
所有产品数据都是特定于商店的。同一个产品在不同商店可能有不同的价格、货架位置和可用性：
- **商店 133（Chantilly, VA）**：香蕉 0.49 美元/磅，货架：农产品
- **商店 146（Reston, VA）**：相同产品，可能有不同的货架位置
`WEGMANS_STORE` 环境变量（或每个工具的 `store_number` 参数）控制您看到的商店数据。
## API 详情
参见 [docs/api-reference.md](docs/api-reference.md)，了解此服务器使用的 Wegmans API 的完整文档，包括：
- Algolia 产品搜索（公开，无身份验证）
- 商店定位器 API（公开，无身份验证）
- 购物车管理 API（已身份验证）
- Azure AD B2C 身份验证流程
### 速率限制
来自 Wegmans 的响应头：
- 产品搜索（Algolia）：每周期 50,000 次调用
- 购物车 API：每周期 5,000 次调用
## 限制
- **无优惠券管理** — Algolia 数据包括数字优惠券 ID，收据显示折扣金额，但剪贴/应用优惠券尚未实现。
- **每个购物车的配送类型单一** — 购物车 API 将每个购物车绑定到一种配送类型（店内取货、取货或配送）。
- **模式准确性取决于数据** — 购买次数少于 3 次的产品不会获得间隔预测。购买 3 次后，如果 3 倍的通常间隔或 90 天后未再次购买商品，则会过滤掉。
- **同步是显式的** — 您必须调用 `sync_purchase_history` 以获取新鲜数据。没有后台轮询。
## 先前的工作
该项目得到了 [wegmans-shopping](https://github.com/nathannorman-toast/wegmans-shopping) 项目的启发，该项目使用 Playwright 通过 Algolia 拦截来抓取产品数据。MCP 服务器采用不同的方法 — 直接命中 Algolia 进行搜索，并使用商业 API 进行购物车操作。
## 许可证
ISC
