leclerc-drive

mcp-leclerc-drive

首个适用于 E.Leclerc Drive 的开源 MCP 服务——让 Claude 原生搜索商品、管理购物车并准备采购订单，无需在网站上逐个点击。

🟢 v0.3——运行正常，且可通过 DataDome 防护。 所有八个工具均已在真实网站上完成端到端验证。请求在通过 CDP 驱动的真实 Chrome 中运行，因此可以通过 DataDome 的机器人防护（该防护会拦截无头客户端和 Cookie 重放）。你只需在打开的窗口中登录一次 Leclerc Drive；会话会持续保留。反向工程得出的 API 详见 docs/api-capture.md。

为什么要做

E.Leclerc Drive 没有公开 API。目前，自动化操作的唯一方式是浏览器自动化——速度慢（每件商品约需 3–5 秒）且脆弱（盲目点击）。本项目将底层操作封装为规范的 MCP 工具，让任何 MCP 客户端（Claude Desktop、Claude Code）都能直接操作。

工具

工具	描述
find_stores(query)	查找邮政编码或城市附近的门店 → 名称、ID、服务类型、距离、主机。
set_store(store_id)	选择并记住当前门店（自动解析正确的主机）。
get_store()	显示当前选中的门店。
search_product(query)	搜索商品目录 → 返回包含价格、每公斤价格、Nutri-Score、库存情况和 id 的商品。
add_to_cart(product_id, quantity?)	将商品加入购物车。
remove_from_cart(product_id)	从购物车中移除商品行。
update_quantity(product_id, quantity)	设置商品行的数量（设为 0 即可移除）。
get_cart()	查看完整购物车及总价。

状态

• 对 Leclerc Drive 端点进行反向工程（搜索／购物车／门店定位器——详见 docs/api-capture.md）
• 所有 8 个工具均已在真实门店完成端到端验证
• 支持在运行时选择门店并持久保存（find_stores / set_store）
• v0.3：通过真实 Chrome CDP 驱动抵御 DataDome 防护（成功应对会阻止 Cookie 重放的主动机器人挑战）✅
• 已发布至 npm + MCP registry
• 结账／预约配送时段

要求

• Node.js ≥ 22（使用内置的 WebSocket）
• 已安装 Google Chrome（服务通过 CDP 驱动 Chrome）

安装（开发版）

git clone https://github.com/skunkobi/mcp-leclerc-drive.git
cd mcp-leclerc-drive
npm install
npm run build

认证工作原理（通过 CDP 使用真实 Chrome）

Leclerc Drive 受到 DataDome 保护，会通过 HTTP 403 阻止非浏览器流量（无头客户端、重放 Cookie），一旦进入主动质询模式就会触发拦截。只有能执行质询的真实浏览器才能稳定通过。因此，服务会使用：

1. 首次请求时，服务会启动你安装的 Google Chrome，使用专用的持久化配置文件（~/.mcp-leclerc-drive/chrome）和调试端口——不添加自动化标记，因此 navigator.webdriver 会保持为 false。
2. Chrome 窗口会打开。在其中登录一次 Leclerc Drive。持久化配置文件会让你在重启后仍保持登录状态。
3. 每个请求都会通过 CDP 在该页面内部执行，因此会携带浏览器的 Cookie、TLS 指纹以及已通过的 DataDome 质询——从而顺利通过。

不会读取或存储 Cookie；也不会弹出 Keychain 提示。服务必须和 Chrome 运行在同一台机器上，而且确实会打开一个窗口（DataDome 可以检测无头模式——除非你了解风险，否则不要启用）。

环境变量	默认值	说明
LECLERC_STORE_ID	053701	默认商店 ID（运行时可由 set_store 覆盖）。
LECLERC_HOST	fd9-courses.leclercdrive.fr	默认后端主机（fdN 前缀因商店而异）。
LECLERC_CHROME_PATH	auto	Chrome 二进制文件的路径；如果不在默认位置，请设置此项。
LECLERC_CHROME_PROFILE_DIR	~/.mcp-leclerc-drive/chrome	Chrome 持久化配置文件目录。
LECLERC_CHROME_PORT	9222	CDP 远程调试端口。
LECLERC_HEADLESS	false	以无头模式运行 Chrome（⚠️ 可被 DataDome 检测到，不建议启用）。
LECLERC_MIN_INTERVAL_MS	1000	两次请求之间的最短延迟（用于规范请求行为）。
LECLERC_JITTER_MS	400	请求间额外增加的随机抖动延迟。
LECLERC_MAX_RETRIES	3	遇到暂时性 403/429 时，放弃前的重试次数。
LECLERC_BACKOFF_BASE_MS	1500	重试退避基准时间（每次尝试翻倍）。

服务仍会对请求进行串行处理并拉开请求间隔（单队列，约 1 秒 + 随机抖动，失败后使用退避重试），以保持礼貌——即使现在由浏览器处理 DataDome，这也是良好的请求规范。

选择商店（无需设置环境变量）

最简单的方法：直接在对话中提出请求。无需设置环境变量。

> "trouve mon drive vers 44000"     → find_stores lists nearby drives
> "prends Rezé Atout Sud"           → set_store remembers it (correct host resolved)
> "cherche du lait"                  → runs on that store

set_store 会将你的选择保存到 ~/.mcp-leclerc-drive/config.json，因此在不同会话中都会保留；它还会为你解析正确的后端主机（fdN 前缀确实会因商店而异，例如 fd8、fd9、fd14……）。

⚠️ 一次只能使用一个 Drive。 Leclerc 会将你的会话绑定到单个 Drive。你通过 set_store 选择的商店必须是 Chrome 会话已登录的商店——通常这就是你自己的 Drive。如果切换到浏览器未登录的其他 Drive，就会返回“会话已过期”错误。

如果你更喜欢，也可以通过 LECLERC_STORE_ID / LECLERC_HOST 环境变量固定商店（例如用于无头部署）。若要手动查找：你的 Drive URL 类似于 https://fd9-courses.leclercdrive.fr/magasin-053701-053701-Your-Town/——6 位数字是商店 ID，fdN-courses.leclercdrive.fr 部分是主机名。

Claude Desktop / Claude Code（mcp 配置）

直接从 npm 安装——无需克隆：

# Claude Code
claude mcp add leclerc-drive -- npx -y mcp-leclerc-drive

或者在 Claude Desktop 配置中添加：

{
  "mcpServers": {
    "leclerc-drive": {
      "command": "npx",
      "args": ["-y", "mcp-leclerc-drive"]
    }
  }
}

无需设置环境变量——在对话中使用 find_stores / set_store 选择商店。首次使用时会打开 Chrome 窗口：登录一次 Leclerc Drive，即可开始使用。

开发

npm run dev        # tsc --watch
npm run typecheck  # type-check without emitting
npm run inspect    # run under the MCP Inspector

架构

src/
  index.ts          # MCP server: registers the 8 tools over stdio
  config.ts         # env-based config (store, host, Chrome/CDP, throttle)
  types.ts          # Product / CartItem / Cart
  store.ts          # active store selection + persistence (~/.mcp-leclerc-drive)
  browser.ts        # ChromeSession: drives real Chrome via CDP → beats DataDome
  leclerc/
    client.ts       # Leclerc Drive backend client (search + cart)
    locator.ts      # store finder: postal code / city → nearby drives
    throttle.ts     # request serialization + spacing + retry (hygiene)
docs/
  api-capture.md    # the reverse-engineered Leclerc Drive API

贡献

这是一个社区工具——非常欢迎大家贡献，无论是修复错误、支持你的商店，还是添加全新功能（结账、配送时段、已保存的清单等）。

请参阅 CONTRIBUTING.md，了解开发环境设置、如何使用自己的账户进行冒烟测试（npm run smoke），以及——对本项目最有用的内容——如何对新的 Leclerc Drive 端点进行逆向工程并将其接入。上方的状态清单中列出了适合新手处理的问题。

反馈与联系

非常欢迎反馈、错误报告和想法。

• **问题 / PR：**在仓库中提交问题。
• **电子邮件：**[email protected]

免责声明

这是非官方项目。与 E.Leclerc 无关，也未获其认可。请使用你自己的账户，并自行承担风险，同时遵守网站的服务条款。本项目旨在帮助你自动化处理个人杂货购物。

许可证

MIT