French Grocery

Name: French Grocery
Author: maxime-desmarchelier

本地服务

github.com商业与营销03 天前更新

代码仓库访问官网

关于 French Grocery

French Grocery 是供 Agent 操作法国 E.Leclerc Drive 和 Super U 在线杂货服务的本地 MCP 服务。它可搜索商品、管理购物车并比较价格和配送条件，但不会下单；预约时段和付款由用户在零售商网站完成。

主要功能

01搜索商品及促销信息
02查看配料、过敏原和产地
03添加、调整或移除购物车商品
04读取订单最低金额和可用时段
05比较不同零售商的购物车
06选择门店（E.Leclerc Drive）

适用场景

01为一份食谱搜索并整理所需商品
02比较 E.Leclerc Drive 与 Super U 的购物车总价
03核对商品成分、过敏原及配送时段

MCP 相关

这是通过 stdio 在本地运行的 MCP 服务，向 Agent 提供 E.Leclerc Drive 和 Super U 的商品、购物车、门店及订单条件工具。它不会提交订单，预订时段和付款仍由用户在网站上完成。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "maxime-desmarchelier-fr-grocery": {
      "command": "npx",
      "args": [
        "-y",
        "fr-grocery-mcp"
      ],
      "env": {
        "FR_GROCERY_CONFIG": "<FR_GROCERY_CONFIG>",
        "FR_GROCERY_CHROME_PORT": "<FR_GROCERY_CHROME_PORT>",
        "FR_GROCERY_STATE_DIR": "<FR_GROCERY_STATE_DIR>"
      }
    }
  }
}

启动命令npx -y fr-grocery-mcp

需要配置的环境变量

FR_GROCERY_CONFIGPath to the optional JSON configuration file. Without it, only Super U is enabled.

FR_GROCERY_CHROME_PORTChrome DevTools Protocol port; overrides the configuration file.

FR_GROCERY_STATE_DIRDirectory for retailer state such as the selected Leclerc store.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmfr-grocery-mcp0.1.1stdio

工具

收录的工具列表 · 更新于 3 天前

参数	类型	必填	说明
check	boolean	否	查询每个网站（只读）

详细介绍

fr-grocery-mcp

一个 MCP 服务，为 Agent 提供访问法国零售商在线杂货服务（“drive”）的领域级权限：目前支持 E.Leclerc Drive 和 Super U（coursesu.com），其他零售商可通过新增适配器接入。搜索商品、查看成分、管理购物车、查看时段和最低订单金额、比较购物车。仅此而已。

推理工作（食谱、食材、人数对应的用量、商品选择、价格与促销取舍）由 Agent 完成。例如：

购买制作 4 人份意式肉酱面和四种奶酪披萨所需的食材，选择 Leclerc 和 Super U 中最便宜的商店。

Agent 会整理清单，在每家零售商处搜索各项食材、填充购物车，然后进行比较。 绝不会下单：预约时段和付款由用户在网站上完成。

警告

本项目与 E.Leclerc、Système U 或任何零售商均无关联，未获其认可或支持。它会以人工操作的速度，使用你自己的已登录浏览器会话，仅供个人使用。零售商网站可能会随时变更，其使用条款同样适用：使用风险自负。

工具

每个零售商工具都接受 store（leclerc、superu：根据配置生成的枚举）。

工具	效果	注释
`list_stores(check=false)`	已接入的零售商及其功能；启用 `check` 时，返回各会话的状态和当前活动门店	只读
`search_products(store, query, limit=20)`	商品：`id`、标签、`price_eur`、`unit_price`（€/kg、€/l、€/piece）、`available`、类型化的 `promotions`、`best_offer`（净成本，包含组合优惠和会员优惠）	只读
`get_product(store, product_id)`	商品页面：`ingredients`（过敏原以大写字母标示；原始商品为 `null`）、申报的 `allergens`、`origin`	只读
`get_cart(store)`	商品行（`product_id`、`name`、`quantity`、`line_total_eur`、`unit_price`）和 `total_eur`	只读
`get_order_conditions(store?)`	门店、已预订时段、购物车关联的时段、带日期的后续时段（ISO `start`）、最低要求；省略 `store` 表示所有零售商	只读
`add_to_cart(store, product_id, quantity=1)`	在已有数量上增加
`set_quantity(store, product_id, quantity)`	设置数量（0 = 移除）	幂等
`remove_from_cart(store, product_id)`	移除商品	破坏性操作、幂等
`find_stores(store, query)`	查找邮政编码或城镇附近的门店（如果零售商支持）	只读
`set_store(store, store_id)`	选择并记住当前活动门店	幂等
`compare_carts(mode="drive")`	各零售商的购物车：总额、商品行、最低金额和差额、后续时段；按价格从低到高排序	只读

每次更改后都会重新读取购物车，并返回 confirmed：如果网站保留了目标数量，则为 true。结果为类型化数据（outputSchema + structuredContent），服务器还会向 Agent 发送描述操作流程的 instructions。每种商品最多 50 件，以避免单位错误。

错误（isError、error 字段）：ValidationError（修正调用）、NotSupportedError（零售商不支持此操作）、SessionExpiredError（在 Chrome 中重新登录）、SiteBlockedError（反机器人拦截：停止操作）、TransientError（自动重试，然后报告）。

商品标签、促销文本和搜索词均保留法语，与网站上的内容一致。

各零售商的功能

功能	E.Leclerc Drive	Super U
搜索、购物车、促销	是（即时、多件优惠、Ticket）	是（即时、多件优惠、Carte U）
商品页面	配料、过敏原、产地	配料、产地
从 Agent 选择门店	`find_stores` / `set_store`	否：在网站上选择
最低订单金额	未登录时不显示	是
时段	下一个时段、购物车日期	下一个时段、已预约时段

要求

Node ≥ 26（原生运行 TypeScript：无需构建步骤）。使用 mise：mise install --locked 会安装 mise.lock 中记录的版本。
启动时带有 --remote-debugging-port=9222 参数并已登录相关网站的 Chrome（mise run chrome 会在 ~/.fr-grocery-mcp/chrome 中启动专用配置文件）。程序会按域名查找或打开每个网站对应的标签页。

请求通过浏览器会话逐一发送，并在请求之间留出间隔：服务会重放网站在点击操作时执行的行为（参见 docs/retailers/）。不会绕过任何保护机制：遇到反机器人拦截时，服务会停止，不会重试。

配置

FR_GROCERY_CONFIG 指向一个 JSON 文件。如果未提供文件，则只会接入 Super U。

{
  "chrome": { "port": 9222, "timeoutMs": 30000 },
  "stores": [
    {
      "retailer": "leclerc",
      "store": {
        "storeId": "123456",
        "retrievalPointId": "123456",
        "host": "fd7-courses.leclercdrive.fr",
        "name": "My Leclerc Drive"
      }
    },
    { "retailer": "superu", "minIntervalMs": 300 }
  ]
}

零售商的顺序即为优先级顺序。minIntervalMs 用于设置请求之间的间隔（默认值：Leclerc 为 1000 ms，Super U 为 300 ms）。Leclerc 门店的相关值可通过 find_stores / set_store 获取：通过 set_store 选定的门店会保存在 $FR_GROCERY_STATE_DIR/leclerc-store.json 中（默认目录为 ~/.fr-grocery-mcp），并优先于配置文件中的设置。FR_GROCERY_CHROME_PORT 可覆盖文件中的端口。Super U 门店需在 coursesu.com 上选择。

使用方法

该服务以 fr-grocery-mcp npm 包的形式发布，并在本地通过 stdio 运行。Claude Code（.mcp.json）：

{
  "mcpServers": {
    "fr-grocery-mcp": {
      "command": "npx",
      "args": ["-y", "fr-grocery-mcp@latest"],
      "env": { "FR_GROCERY_CONFIG": "/path/to/fr-grocery-mcp.json" }
    }
  }
}

为确保设置可复现，请指定精确版本（例如 [email protected]），而不是 @latest。同一软件包也列于官方 MCP Registry 中，标识符为 io.github.maxime-desmarchelier/fr-grocery-mcp。每个版本都会发布到 npm、GitHub Releases 和 MCP Registry；参见 docs/releasing.md。

从源码检出目录运行时，改用 "command": "node" 和 "args": ["/path/to/fr-grocery-mcp/src/main.ts"]。手动检查：npm run inspect（MCP Inspector）。

开发

npm ci
npm run check                      # typecheck + lint + tests with coverage thresholds
mise run lint                      # the git hook's ruleset on the whole repository (what CI runs)
npm test                           # unit, adapter contract, integration (no access to the sites)
npm run doctor                     # real sites, read-only: session, search, product page, cart per retailer
npm run test:live                  # real sites: changes then removes an item that is not in the cart
LIVE_STORES=leclerc npm run test:live
npm run fixtures -- leclerc        # captures a retailer's reference pages again
npm run format                     # Biome

架构和技术选择：docs/architecture.md。添加零售商：docs/adding-a-retailer.md。发布： docs/releasing.md。