UK Supermarkets

supermarkets-uk-mcp

用于在英国 9 家超市中搜索和比较杂货价格的 MCP 服务。它提供商品搜索、价格比较、类别浏览，以及（仅限 Tesco）订单历史和购物篮管理。每家超市都通过通用接口实现为可插拔的数据源，服务会并发向各门店发送请求并汇总结果。

入门

要求

• Go 1.27.3+（用于从源代码构建）

• Chrome、Chromium 或 Microsoft Edge — Tesco、Asda 和 Waitrose 需要使用它进行无头浏览器渲染，登录任何超市也需要使用它。Sainsbury's、Ocado、Morrisons 和 Shopify 门店无需浏览器即可使用。

  在 Linux 上，请避免使用 snap 打包的 Chromium（Ubuntu 默认的 chromium 软件包）。当它作为某些父进程的子进程启动时（观察到的情况是在 Claude Desktop 的 Electron 进程树下运行），已知会无限期挂起——无论是优雅关闭 CDP 标签页，还是强制终止后由操作系统回收进程，都会如此。在上述环境下，这个问题每次都能复现，而使用相同代码搭配非 snap 版 Chrome/Chromium 时从未出现。请改为安装 Google Chrome 或非 snap 版 Chromium，并在未自动检测到时将 CHROME_EXEC_PATH 指向该浏览器。

安装

预构建的二进制文件可从 Releases 获取。

从源代码安装：

go install github.com/jbeshir/mcp-servers/supermarkets-uk/cmd/supermarkets-uk-mcp@latest

或者从仓库根目录构建：

make build

此外还提供了一个基于 chromedp/headless-shell 的 Dockerfile，可开箱即用地支持基于浏览器的门店：

docker build -t supermarkets-uk-mcp ./supermarkets-uk

配置

开始使用无需设置环境变量——所有超市无需登录即可使用。

变量	必需	描述
CHROME_EXEC_PATH	否	要启动的 Chrome/Chromium 二进制文件路径。留空则使用自动检测。关于 Linux 上 snap 打包版 Chromium 的说明，请参阅上文。

请参阅下文的登录，了解启用交互式登录所需的其他变量。

Claude Desktop

{
  "mcpServers": {
    "supermarkets-uk": {
      "command": "/path/to/supermarkets-uk-mcp"
    }
  }
}

Claude Code

claude mcp add supermarkets-uk /path/to/supermarkets-uk-mcp

工具

工具	描述
list_supermarkets	列出所有受支持的超市及其 ID 和状态
search_products	在一家或多家超市中搜索商品
compare_prices	比较各家超市中某件商品的价格
get_product_details	获取详细的商品信息（价格、描述、成分、营养信息）
browse_categories	浏览某家超市的商品类别
get_order_history	获取过往订单历史（仅限 Tesco，需登录）
get_basket	获取当前购物篮内容（仅限 Tesco，需登录）
add_to_basket	将商品加入购物篮或更新其数量（仅限 Tesco，需登录）
remove_from_basket	从购物篮中移除商品（仅限 Tesco，需登录）

支持的超市

超市	ID	数据源	需要浏览器
Tesco	tesco	HTML（无头浏览器）	是
Sainsbury's	sainsburys	JSON API	否
Ocado	ocado	服务端渲染的 HTML（OSP）	否
Morrisons	morrisons	服务端渲染的 HTML（OSP）	否
Asda	asda	Algolia API（搜索）+ HTML（详情）	是
Waitrose	waitrose	HTML（无头浏览器）	是
HiYoU	hiyou	Shopify 预测搜索 API	否
Tuk Tuk Mart	tuktukmart	Shopify 预测搜索 API	否
Morueats	morueats	Shopify 预测搜索 API	否

商品信息覆盖范围

并非所有超市提供的详细信息都相同：

字段	Tesco	Sainsbury's	Ocado	Morrisons	Asda	Waitrose	Shopify 商店
名称 / 价格 / URL	是	是	是	是	是	是	是
单位价格	是	是	是	是	是	是	--
促销信息	是	是	是	是	是	是	--
描述	是	是	是	是	是	是	是
配料	是	是	是	是	是	是	--
营养信息	是	是	是	是	是	是	--
饮食信息	--	--	--	--	是	--	--
重量	--	--	--	是	是	是	是

登录

登录是可选的，可启用个性化结果（例如本地库存、配送情况）、订单历史记录和购物篮管理。登录需要在本地运行服务，并确保有可用的浏览器。

要启用登录，请为要登录的每家超市设置 <SUPERMARKET>_LOGIN=true。首次使用时，会打开一个可见的浏览器窗口，供你手动完成登录。会话 Cookie 会缓存到磁盘，并在重启后重复使用。如果 Cookie 过期，服务会清除它们并自动触发重新登录。

所有超市的登录都需要 Chrome、Chromium 或 Edge，包括其他操作不需要浏览器的超市。超市会话往往会频繁过期，因此请做好定期重新登录的准备。

变量	描述
TESCO_LOGIN	启用 Tesco 登录
SAINSBURYS_LOGIN	启用 Sainsbury's 登录
OCADO_LOGIN	启用 Ocado 登录
MORRISONS_LOGIN	启用 Morrisons 登录
ASDA_LOGIN	启用 Asda 登录
WAITROSE_LOGIN	启用 Waitrose 登录
SUPERMARKET_COOKIE_DIR	覆盖 Cookie 存储目录（默认：操作系统配置目录）

启用登录的示例：

{
  "mcpServers": {
    "supermarkets-uk": {
      "command": "/path/to/supermarkets-uk-mcp",
      "env": {
        "TESCO_LOGIN": "true",
        "WAITROSE_LOGIN": "true",
        "SUPERMARKET_COOKIE_DIR": "/home/you/.supermarket-cookies"
      }
    }
  }
}

核心概念

• Datasource — 用于单家超市的可插拔适配器。每个数据源都会实现通用的 ProductSource 接口（搜索、商品详情、分类浏览），并根据超市的要求使用相应的传输方式：JSON API、服务端渲染的 HTML 抓取，或无头 Chrome 渲染。
• AuthProductSource — 对 ProductSource 的扩展，支持注入和验证会话 Cookie。九家超市中有六家实现了此接口，可启用个性化结果等登录功能。三家基于 Shopify 的商店仅实现普通的 ProductSource，不支持身份验证。
• 客户端协调器 — client.Client 类型将全部九个数据源连接起来。它负责管理搜索的并发扇出、通过检测会话过期实现延迟身份验证，以及按主机进行速率限制。
• 身份验证解析器 — 为每家超市提供的封装器，用于处理延迟登录。首次使用启用了登录的超市时，它会打开一个可见的浏览器窗口，供用户手动完成登录。会话 Cookie 会持久化到磁盘并重复使用。如果请求返回 ErrSessionExpired，解析器会清除 Cookie 并触发重新登录。
• 共享浏览器 — 所有基于浏览器的数据源共用一个无头 Chrome 实例（通过 chromedp）。每个请求都会在共享浏览器上下文中打开一个新标签页，以便 Cookie 在不同页面导航间保持有效。
• OSP（Ocado Smart Platform） — Ocado 和 Morrisons 共用一种服务端渲染的 HTML 结构。单个 osp 包通过商店专属配置参数实现对两者的支持。

架构

graph TD
    MCP["MCP Client<br/>(Claude Desktop, etc.)"]
    SRV["MCP Server<br/>9 tools"]
    ORCH["Client Orchestrator<br/>concurrent fan-out + auth"]

    MCP -->|"stdio JSON-RPC"| SRV
    SRV --> ORCH

    subgraph "Datasource Adapters"
        direction LR
        BROWSER["Browser-based<br/>Tesco, Asda, Waitrose"]
        HTML["HTML scraping<br/>Ocado, Morrisons"]
        API["JSON API<br/>Sainsburys"]
        SHOPIFY["Shopify API<br/>HiYoU, TukTukMart, Morueats"]
    end

    ORCH --> BROWSER
    ORCH --> HTML
    ORCH --> API
    ORCH --> SHOPIFY

    CHROME["Headless Chrome"]
    BROWSER --> CHROME

外部依赖

graph LR
    SM["supermarkets-uk-mcp"]

    SM -->|"Headless Chrome"| TESCO["tesco.com"]
    SM -->|"Headless Chrome"| ASDA_BR["asda.com"]
    SM -->|"Headless Chrome"| WAITROSE["waitrose.com"]
    SM -->|"HTTP + HTML parsing"| OCADO["ocado.com"]
    SM -->|"HTTP + HTML parsing"| MORR["groceries.morrisons.com"]
    SM -->|"JSON API"| SAINS["sainsburys.co.uk"]
    SM -->|"Shopify predictive search API"| SHOPIFY["hiyou.co / tuktukmart.co.uk / morueats.co.uk"]

数据流

使用多个超市调用 search_products 时，会向所有目标商店并发发出请求。单个商店的失败会记录在各自的结果中，而不会导致整个请求失败。

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Orch as Orchestrator
    participant Auth as Auth Resolver
    participant DS as Datasource Adapters
    participant Ext as Supermarket Sites

    Client->>Server: search_products(query, stores)
    Server->>Orch: SearchAll(query, stores)

    par One goroutine per store
        Orch->>Auth: ensureAuth(tesco)
        Note over Auth: Lazy login on first use
        Auth-->>Orch: ready
        Orch->>DS: Tesco.SearchProducts
        DS->>Ext: Headless Chrome
        Ext-->>DS: Rendered HTML
    and
        Orch->>DS: Sainsburys.SearchProducts
        DS->>Ext: JSON API
        Ext-->>DS: JSON response
    and
        Orch->>DS: Ocado.SearchProducts
        DS->>Ext: HTTP GET
        Ext-->>DS: Server-rendered HTML
    end

    DS-->>Orch: Parsed products (per store)
    Orch-->>Server: Combined results
    Server-->>Client: Formatted tool response

如果已登录请求因 ErrSessionExpired 失败，身份验证解析器会清除缓存的 Cookie，打开浏览器窗口以便重新登录，并透明地重试请求。