内容
🛒 超市 MCP 服务器
> **MCP** 服务器，用于搜索产品、比较价格和在智利超市中创建最佳购物清单，支持 Claude、ChatGPT 或其他 MCP 客户端。
[](https://www.npmjs.com/package/mcp-supermercados-cl)
重点是 **深入到您已购物的供应链** — 俱乐部价格、按 RUT 的优惠、常购商品、购物车 — 同时与诸如容量次要的比较。涵盖该国五大连锁店。
100% 本地化：流量来自 **您的** 机器，以人性化的节奏，并且您的凭证从未触及中央服务器。
---
## 目录
- [是否部署在 Vercel/AWS 上？](#-是否部署在-vercelaws-上)
- [安装](#-安装)
- [各大超市的覆盖范围](#-各大超市的覆盖范围)
- [可用的工具](#-可用的工具)
- [会话的工作原理](#-会话的工作原理-无服务器凭证)
- [开发和测试](#-开发和测试)
- [架构](#-架构)
- [如何贡献](#-如何贡献)
- [法律声明](#-法律声明)
- [许可证](#-许可证)
---
## 🚫 是否部署在 Vercel/AWS 上？ 不
**此 MCP 没有生产环境 URL，不部署在任何服务器上。** 这是故意的，也是其功能的原因：
- 使用 **stdio**（本地）传输，而不是 HTTP。它在您的机器上运行，与您的 MCP 客户端（Claude Desktop、Claude Code、Cursor、ChatGPT Desktop）一起。
- Unimarc、Tottus 和 Lider **阻止来自数据中心的流量**（反机器人）。云部署 **无法** 用于这些连锁店：它们需要您的住宅 IP。
- 合作伙伴价格、您的常购商品和购物车存在于 **您的登录浏览器** 中。凭证不应触及中央服务器 — 这也避免了最大的法律风险（一个刮取他人帐户的服务）。
像这样的 MCP 的“生产”方式是 **本地安装**（通过 `npx` 或克隆存储库）并将其连接到您的客户端。就像大多数 MCP 服务器一样。
---
## 📦 安装
需要 **Node.js ≥ 20**。发布于 npm：[`mcp-supermercados-cl`](https://www.npmjs.com/package/mcp-supermercados-cl)。
**选项 1 — 通过 `npx`（推荐）。** 您不需要安装任何东西；您的 MCP 客户端会在运行时执行它。在 **Claude Desktop** / **Claude Code**（`claude_desktop_config.json` 或 `.mcp.json`）中：
```json
{
"mcpServers": {
"supermercados": {
"command": "npx",
"args": ["-y", "mcp-supermercados-cl"]
}
}
}
```
**选项 2 — 从代码（用于开发或贡献）：**
```bash
git clone https://github.com/NLACE-COM/mcp-supermercados-cl.git
cd mcp-supermercados-cl
npm install
npm run build
```
并将您的客户端指向本地构建：
```json
{
"mcp {
"supermercados": {
"command": "node",
"args": ["/绝对路径/到/仓库/dist/index.js"]
}
}
}
```
适用于快速开发：
```bash
npm run dev # 通过 tsx 进行 stdio 服务器
npm run inspector # 打开 MCP Inspector
```
---
## 🏬 各大超市的覆盖范围
| 连锁店 | 平台 | 搜索 | 合作伙伴价格 | 详情 | 会话 / 购物车 |
| ---------------- | ------------------------- | :--: | :-----------: | :---: | :-------------------------: |
| **Jumbo** | Cencosud（Constructor.io） | ✅ | ✅ Prime | ✅ | ✅ 常购商品、列表、购物车 |
| **Santa Isabel** | Cencosud（Constructor.io） | ✅ | ✅ | ✅ | Cencosud 购物车¹ |
|imarc** | VTEX（自定义 BFF） | ✅ | ✅ Unimarc 俱乐部 | — | — |
| **Tottus** | Falabella（ SSR） | ✅ | — | — | — |
| **Lider** | Walmart Glass（SSR） | ✅ | —² | — | — |
¹ Santa Isabel 的购物车重用了与 Jumbo 相同的 Cencosud BFF；通过 santaisabel.cl 上的会话激活。
² Lider 没有像 Jumbo 的 Prime 那样公开双重合作伙伴价格；其折扣是直接折扣（“Lider 价格”）+ 捆绑销售。
> ⚠️ Unimarc、Tottus 和 **住宅 IP**（您的机器）；数据中心阻止。从数据中心阻止 MCP 在本地运行，因此在您的设备上运行。
所有结果均 **丰富**：名称、品牌、图片、当前价格、正常价格、合作伙伴**标准化单位价格**（按千克/升比较格式）和 **捆绑销售**（“2 x $2,000”，“购买 8 件， $X”）。
---
## 🧰 可
**核心 - 使用您的会话创建最佳列表： 工具 | 功能 |
| | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build_list` | 将自然语言列表转换为具体产品。优先考虑常购商品、最佳单位价格和优惠。标志 `onlyOffers` / `onlyInStock` 和 `maxBudget`（调整为更便宜的替代品以适应）。包括格式化 |
| `suggest_swaps` | 按单位价格计算的便捷替代品。带有 `preferNatural`：类似价格的替代品，成分更少。 `get_frequent_purchases` | 商品，带有合作伙伴价格（需要会话）。 |
| `get_saved_lists` |保存的列表（需要会话）。 |
| `add_to_cart` / `get_cart` | 将列表放入 Jumbo 的购物车中；总计、节省和省。 目录阅读：**
| 工具 |
| ---------------- ----------------------------------------------------------------------------------------------------------- |
|_products` | 在任何连中搜索。过滤器 `maxPrice`/`min/`inStockOnly`，排序 `sortBy`（价格 / 单位价格）。 |
| `get_product` | 通过 URL/slug 获取合作伙伴价格、EAN、**成分营养标签。 |
| `get_offers | Jumbo 当前优惠；`primeOnly`过滤器。 |
| `find_opportunities 按 `discountPct` 排序的最大折扣，有库存。`excludeIds` 突出您没有的商品。 |
**比较和诊断：**
| 工具 | 功能 |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `compare_stores` | 在多个连锁店中比较列表总价；标记最便宜的并警告格式不同的情况。 |
| `discover_branch` | 通过读取，获取您的分支（branchId），无需手动输入。 |
| `adapter_status` | 当前哪些连锁店响应，延迟时间是多少。 |
### 💬 有指导的提示
为了避免猜测您需要什么，服务器提供了模板，您的 MCP 客户端会将其显示为建议： **`armar_lista`** （带有可选预算）、**`conectar_sesion`** 、 **`comparar_carro **`ofertas_frecuentes`** 。服务器 `instructions`，以便模型在首次引导您（哪家连锁店、何时请求如何读取错误）。
错误是 **：每个错误都有一个 `action`，包含下一步的具体操作（重新登录、重试、使用住宅 IP...），而不是技术消息。
---
## 🔐 会话的工作原理（无服务器凭证）
合作伙伴价格、常购商品和存在于登录后。在 Jumbo 中，令牌存在于浏览器的 `localStorage` 中，因此 **服务器从未看到凭证**：客户端（与您的登录浏览器一起）从 DOM 中提取执行身份验证调用，而 MCP 只规范结果 [`src/adapters/session.ts`](src/adapters/session.ts) 和 [`docs/captura-cencosud-2026-07-06.md`](docs/captura-cencosud-2026-07-06.md)。
### 那么代码中出现的 API 密钥呢？
您将在适配器中看到像 `key_JopvNXKS61kwGkBeJumbo）或 `be-reg-groceries-catalog-wdhhq5a2fkenSanta Isabel）这样的密钥。**它们的。** 它们是 Constructor.io 和 Cencosud/Unimarc 目录 BFF 的 **公共前端密钥**：它们嵌入在 jumbo.cl 和 santaisabel.cl 的 JavaScript 中，在任何访问者的 DevTools 中都可见。它们仅标识客户端的搜索索引 — **不授予任何帐户访问权限或写入权限**。如果没有它们，搜索器将无响应。
**确实** 敏感的数据（会话令牌、合作伙伴价格、购物车）存在于您的登录浏览器中，**从未** 存在于此存储库中。自动扫描器可能会公共密钥标记为“暴露令牌”；这是假阳性。
---
## 和测试
```bash
npm test # 使用真实的 fixtures 进行合约测试（无网络）— 132 tests
npm run test:live # 实时测试网站（选择加入，LIVE=npm run typecheck # tsc --
npm run lint # ESLint
npm # Prettier (--write); format 进行验证
```
合约测试使用存储在 [`tests/fixtures/`](xtures) 中的真实响应记录。实时测试需要网络，对于 Unimarc/Tottus/Lider，需要住宅 IP。当连锁店更改其格式时，请重新录制一个 fixture，并记录日期。
每个推送和 PR 都在 CI（GitHub Actions，Node 20 和 22）上运行 `lint + typecheck + build + test`。每周一次的实时烟雾测试会在问题中发出警报，如果连锁店更改其格式。要贡献，请查看 [CONTRIBUTING.md](ING.md)。
### 会话流程：手动或会话的工具（`get_cart`_frequent_purchases`、`get_saved、`add_to_cart`）返回一个 `browserSnippet`：一个 **单个调用** 的 fetch 操作在已经登录的站点选项卡中。您传递 JSON 对象，工具会对其进行规范化 — 服务器从未看到您的令牌。
要自动化它（无需复制/粘贴），有一个可选的 Playwright 桥（`src/adapters/playwrightBridge.ts`），它重用您已经登录的 Chrome 配置文件。Playwright **不** 随软件包一起提供；如果您需要，请单独安装：
``` install playwright
npx playwright install chromium## 🏗 架构
- **，一个适配器每个连锁店**/adapters/`). 标准化模式与 zod/core/types.ts`): 分离 **普通价格和合作伙伴价格**，标准化单位价格为规范基数。
- **按主机类型以人性化节奏进行 HTTP 请求**：API 端点（Constructor.io 和 Cencosud/Unimarc/Santa Isabel 的 BFF）约为 350 毫秒；使用 SSR 抓取的站点（Tottus、Lider、`www.*` 的 PDP）保持在 ~1 秒。带有回退的重试，现实的用户代理（`src/http/client.ts`）。缓存 TTL 15 分钟。可按环境调整：`SUPERMERCADOS_MIN_DELAY_MS`、`SUP_FAST_DELAY_MS`、`SUPERMERCADOS_TIMEOUT_MS`、`SUPERMERCADOS_MAX_RETRIES`。
- **实时反馈**：`build_list` 和 `compare_stores` 在客户端支持时发出 MCP通知 (`notifications/progress`)，以避免列表中保持沉默。`compare_stores限制每个连锁店 25 秒，并结果而不是阻塞其他链。
- **隔离适配器**：一个站点更改一个适配器，而不是整个适配器。
- 文档位于 [`docs/`](docs) 和 [`docs/quitectura.md/PLAN-arquitectura.md)```
src/
├── index.ts # MCP 入口（stdio）
├── server.ts #注册
├── core/ # 类型、注册表、规范化、listBuilder、比较...
/ # cencosud（Jumbo Isabel）、unimarc、tottus、lider tools/ 每个文件一个 MCP 工具
└── # 带有重试的
```
---
🤝 如何贡献贡献！该项目社区一起成长。请参阅 [CONTRIBUT](CONTRIBUT)。
高影响力的
- Unimarc、Tottus 和 Lider 的购物车/会话（每个都有自己的登录）。
- Unimarc/Tottus/Lider（`get_product`）。
- 新的连锁店或药店。
- 保持 fixtures 与连锁店更改其 API 时保持同步连锁其格式时npm run test:live` 会检测到## ⚖️ 法律声明
**个人** 工具，开源，无中央后端。每个用户从自己的 IP 地址以人性化的节奏操作自己的帐户，不会重新分发数据。在使用之前，请查看每个连锁店的条款和条件。**不隶属于** Cencosud、SMU、Falabella 或 Walmart。提到的其各自所有者所有。请自行承担使用风险。
---
## 📄 许可证](LICENSE)cp-superm-cl 贡献
