French Grocery

fr-grocery-mcp

エージェントに、フランスの小売業者が提供するオンライン食料品サービス（ドライブ）へのドメインレベルのアクセスを提供するMCP サーバーです。現在は E.Leclerc Drive と Super U（coursesu.com）に対応しており、新しいアダプターを追加すれば他のサービスにも対応できます。商品の検索、原材料の確認、カートの管理、受け取り枠と最低注文金額の確認、カートの比較ができます。それ以外の機能はありません。

推論（レシピ、材料、人数に応じた分量、商品の選択、価格と割引の比較）はエージェントが担います。たとえば、次のように指示できます。

4人分のスパゲッティ・ボロネーゼと4種のチーズのピザを作るのに必要なものを、LeclercとSuper Uのうち最も安い方で注文してください。

エージェントはリストを作成し、各小売業者でそれぞれの材料を検索してカートに追加し、最後に比較します。 注文が確定されることはありません。受け取り枠の予約と支払いは、ユーザーがサイト上で行います。

警告

このプロジェクトは、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、€/個）、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）で、サーバーはフローを説明する instructions をエージェントに送信します。数量の誤りを防ぐため、商品ごとに上限を 50 個に設定しています。

エラー（isError、error フィールド）：ValidationError（呼び出しを修正してください）、NotSupportedError（小売業者が対応していません）、SessionExpiredError（Chrome で再度ログインしてください）、SiteBlockedError（ボット対策によるブロックです。停止してください）、TransientError（自動で再試行し、その後に報告されます）。

商品ラベル、プロモーションのテキスト、検索語は、サイト上の表記どおりフランス語のままです。

小売業者ごとの機能

機能	E.Leclerc Drive	Super U
検索、カート、プロモーション	はい（即時割引、まとめ買い、Ticket）	はい（即時割引、まとめ買い、Carte U）
商品ページ	原材料、アレルゲン、原産地	原材料、原産地
エージェントからの店舗選択	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 に 専用プロファイルを起動します）。ドメインに基づいて、サイトごとにタブを1つ見つけるか、新しく開きます。

リクエストはブラウザーセッションを通じて、一度に1件ずつ、間隔を空けて送信されます。サーバーはサイト上でクリックしたときの動作を再現します（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" }
    }
  }
}

再現可能なセットアップにするには、@latest ではなく、正確なバージョン（例：[email protected]）を指定してください。同じ パッケージは、公式 MCP Registry（https://registry.modelcontextprotocol.io/）に 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 を参照してください。

貢献

Issue とプルリクエストを歓迎します。セットアップ、コードのルール、プルリクエスト前に npm run check で確認すべき内容については、 CONTRIBUTING.md を参照してください。main は保護されており、CI が成功している必要があります。

セキュリティ

脆弱性は公開 Issue ではなく、リポジトリの Security タブから非公開で報告してください。SECURITY.md を参照してください。

ライセンス

MIT。E.Leclerc Drive アダプターは mcp-leclerc-drive（MIT）で得られた知見を活用しています。NOTICE を参照してください。