alza-mcp

alza-mcp-community

让你的 AI Agent 在 Alza.cz 上购物——中欧最大的电商平台。

非官方社区项目，非 Alza.cz a.s. 制作、认可或支持。

alza-mcp-community 是一个非官方的 Model Context Protocol 服务，通过基于浏览器的商品目录抓取以及逆向工程得出的移动端／网页 API，为 Claude（或任何兼容 MCP 的 Agent）提供访问 Alza 的接口：搜索商品、获取完整详情、查看评价、使用匿名／账户数据、管理购物车、选择配送／AlzaBox 自提、预览结账流程，以及仅凭明确的一次性确认令牌提交订单。

_{真实会话，仅使用商品目录工具集，无账户。重新录制说明：docs/demo-recording.md。静态版本：docs/demo.svg。}

询问：“帮我找一款 600 Kč 以下、专业级别的最佳轮毂清洁剂，并告诉我在布拉格哪里可以自提。” Agent 会调用 search_products → get_product → find_pickup_points，并给出包含真实价格和真实地址的答案。

重要

本项目是非官方项目，与 Alza.cz a.s. 无关联，未获其认可或赞助。它是供个人／研究使用的社区封装。部署或广泛分享前，请阅读免责声明。

---

快速安装

说明

已从 alza-mcp 更名。 应 Alza 的要求，项目现名为 alza-mcp-community，以明确表明它不是 Alza 的官方产品。如果你安装过旧软件包，请在 MCP 配置中将 alza-mcp 替换为 alza-mcp-community。你保存在 ~/.alza-mcp/ 中的登录信息仍然有效。

一键安装

这两个按钮安装的内容与下方手动配置相同：npx -y alza-mcp-community，无需环境变量或密钥。使用 npx／npm 安装时会运行 postinstall 步骤，下载 Playwright 的无头 Chromium（约 92 MB），并设置可选的 curl_cffi venv，因此首次安装需要一些时间，之后启动则只需几秒。.mcpb 安装包和使用 --ignore-scripts 的安装会跳过 postinstall：Chromium 会在首次调用浏览器功能时下载（约 30 秒），且不会创建 venv（请参阅安装方式与 curl_cffi venv）。对于 Claude Desktop，请从最新版本下载一键安装包 alza-mcp-community-<version>.mcpb 并打开，或使用下方的 JSON 配置。

Claude Code

claude mcp add alza --scope user -- npx -y alza-mcp-community

就这样。重启 Claude Code，输入 /mcp 进行确认，然后开始提问。安装过程会通过 postinstall 下载 Playwright 的无头 Chromium 浏览器（约 92 MB）；如果跳过了这一步，首次调用需要浏览器的工具时会下载（约 30 秒）。

Claude Desktop

将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "alza": {
      "command": "npx",
      "args": ["-y", "alza-mcp-community"]
    }
  }
}

重启应用。安装时同样会下载。

Cursor / Continue / 任意 MCP 客户端

配置格式相同——command: "npx"、args: ["-y", "alza-mcp-community"]。所有地方都使用标准 MCP 的 Stdio 传输。

---

可以问什么

测试期间记录的一次真实会话：

你： 帮我在 Alza 找一款约 500 Kč 的专业级轮毂清洁剂。我想要汽车美容级别的品牌。

Claude： （调用 search_products 搜索“čistič disků kol”，按评分排序，然后对排名靠前的商品调用 get_product）

当前目录中的前三款：

#	商品	品牌	容量	价格	★
1	Sonax Xtreme Full Effect	Sonax 🇩🇪	750 ml	559 Kč	4.8
2	Kenotek Wheel Cleaner Ultra	Kenotek 🇧🇪	1 L	455 Kč	4.8
3	Auto Finesse Reactive 1L	Auto Finesse 🇬🇧	1 L	599 Kč	4.4

推荐：Sonax Xtreme Full Effect 750 ml——这是汽车美容行业公认的推荐款。它能与铁粉反应（接触刹车粉尘颗粒时会变成紫色，方便观察清洁效果），Sonax 是德国维修厂的标准品牌，而且有现货。

这是 Agent 并行搜索两次、调用四个 MCP 工具并综合真实 Alza 数据的结果。没有虚构的商品编号。

---

功能介绍

共有 63 个领域工具（连同 list_toolsets、set_toolset 和 report_issue 共 66 个）。如果每次 tools/list 调用都列出所有工具，Agent 的上下文一开始就会塞满几十个工具，而它们可能在当前对话中根本用不到。因此，这些工具按工具集分组，默认仅启用两个工具集，提供 15 个领域工具，以及两个工具集控制工具和 report_issue：

工具集	默认启用？	涵盖内容
catalog	✅	搜索、商品详情、并排比较、评价、分类、自提点查询
auth	✅	OAuth 握手、账户状态、变更令牌签发器
basket_and_checkout	—	购物车、配送/自提选项、结账、下单与取消订单
account_management	—	个人资料、联系人、地址、注册、凭据/身份变更
orders_and_payments	—	订单历史、付款方式、售后付款、索赔、文档
reviews_and_subscriptions	—	评价、投诉、AlzaSubscription、附件、EAN 查询
watchdogs	—	Alza 原生的降价/到货提醒（列出、设置、删除）
chat	—	Alza 应用内聊天机器人
pc_builder	—	经过兼容性检查的 PC 配件清单：pc_build_check、pc_build_suggest
advanced_raw	—	mobile_read，无类型限制的备用入口

调用 list_toolsets 查看所有分组，并调用 set_toolset({id, enabled: true}) 启用工具集，然后再使用其中的工具——例如，添加商品到购物车前启用 basket_and_checkout。这是标准的 MCP 渐进式披露（RegisteredTool.enable()/.disable()，会触发常规的 tools/list_changed 通知）——没有移除任何功能，只是不会一次性全部显示。 报告问题。 无论启用了哪些工具集，report_issue 始终可用。当工具意外失败、返回明显错误的数据，或因 Alza 更改了某些内容而无法正常工作时，服务说明和错误消息本身都会提示 Agent 使用它。它会返回一份已脱敏的草稿（包含版本、Node、平台、店面、传输方式以及本会话近期的工具错误）、一条用于检查重复问题的 gh issue list 命令、一条可直接运行的 gh issue create --repo lukabudik/alza-mcp-community … 命令，以及一个预填内容的新建问题链接，供没有 shell 的 Agent 使用。服务本身不会提交任何内容：Agent 会先向你展示草稿，只有在你同意后，才会通过你的 GitHub 账号提交。凭据（包括 cookie 和 API 密钥）、电子邮件、电话号码、UUID、URL 查询参数值、账号 ID 和主目录路径都会自动脱敏；近期错误只保留路由和状态。无效参数和未知商品不会触发提示。

商品目录工具：

工具	用途
search_products	关键词搜索、价格／库存／屏幕尺寸筛选，以及有界的客户端排序（价格筛选和排序仅适用于排名靠前的约 72 个候选项；pageSize 是每页实际显示的商品卡片数；hasMore／nextPage 用于翻页；价格范围倒置或查询为空时会被拒绝）；品牌／属性筛选使用分类页面，并忽略 query
get_product	获取单个商品的完整详情——价格、库存情况、品牌、图片、URL
compare_products	并排比较 2–6 个商品——在一张对齐表格中列出价格、库存情况、评分和每一项规格；客户端支持时，可通过 MCP sampling 启用可选的 summarize: true 结论
get_product_reviews	通过评论 API 获取综合评分、评论数量和单条评论（作者、日期、评分、正文、优缺点），按最新顺序排列；评论列表可能比综合评论数量更长（看起来还包括其他店铺的评论）
recommend_alternatives	为商品推荐更便宜／评分更高／同品牌的替代品（Alza 自有替代品列表；同类别搜索作为后备方案）
find_pickup_points	按 5 位邮政编码查找最近的 AlzaBox 自提柜和 AlzaShop 展厅，按距离合并结果，并提供营业时间；无需购物车。邮政编码会通过公共的 OpenStreetMap Nominatim 服务（nominatim.openstreetmap.org）进行地理编码，因此规范化后的编码和国家／地区会发送给该第三方（不会发送给 Alza）；结果会缓存一周。此工具无法判断特定商品是否适合放入 AlzaBox；请使用 delivery_options
list_category_filters	获取分类品牌（brands[].valueId）和带有实时 ID／数量的属性分面——使用 producer_ids，或搭配 category_id 使用 filters（复选框分面使用 {param_id, value_id}；屏幕尺寸或刷新率等滑块范围使用 {param_id, min?, max?}）；不支持的 URL 筛选条件会返回错误（复选框值仅适用于 Alza 提供落地页的筛选项——HDMI 有对应页面，显示器面板类型和分辨率则没有）
get_deals	获取 alza.cz 和 alza.sk 上的折扣商品：当前可支付的价格（priceNow，包括促销码价格，例如 Alza dni 的“Kúpiť s kódom ALZADNI15”，并提供 promoCode／promoPercent）、标价和较早的划线价格、徽章（SUPER CENA、ZĽAVNENÉ -N %、CENOVÁ BOMBA、NOVINKA）、节省金额、月供、AlzaPlus+ 会员／非会员价格，以及根据观测到的价格计算出的折扣百分比。若优惠码价格不等于标价 × (1 − 百分比)，priceCheck 会对相应商品卡片进行标记。扫描店铺中的 category_id 或任意商品列表 url（例如 /monitory-23-a-24/alza-dni/18848792-e39.htm），并跟踪翻页链接，直到不再出现新商品（最多 5 页）；若未提供参数，则扫描热门分类。如果 Cloudflare 向无头浏览器发起验证，请设置 ALZA_CDP_URL 以使用自己的 Chrome
list_categories	获取顶级分类；提供 parent_id 时，则获取实际子分类——将返回的 ID 传入 search_products
autocomplete	通过纯 HTTP 获取搜索框建议（不渲染页面）：包含短语、分类、品牌和带有 ID／代码的商品——在调用 search_products 前，先细化不够准确的捷克语查询
product_by_ean	按条形码／EAN 查找目录商品（应用的相机条形码扫描 API，AT3；只读，无需账户；启用 reviews_and_subscriptions）

PC 装机工具（启用 pc_builder）：

工具	用途
pc_build_check	检查部件清单（Alza 代码）。检查插槽、RAM 代际／插槽数量、电源功率及余量、GPU 长度、散热器高度／冷排与机箱的适配性、外形规格和显示输出。返回价格、总价、库存情况，以及每条规则的判定结果和所用规格值
pc_build_suggest	根据 CZK 预算，从 Alza 的真实组件分类中推荐兼容配置（游戏／工作站／办公用途；固定的 fixed_parts；有界的详情获取）

账户和结账工具：

工具	用途
auth_start	创建移动 API OAuth PKCE 授权 URL
auth_exchange	将返回的授权码兑换为移动 API 令牌
auth_discovery	从 identity.alza.cz 读取实时 OIDC 元数据
mobile_read	读取经 APK 确认的目录、导航、账户、订单历史、列表、分店、替代产品、购物篮、费用估算、网页付款后对话框、网页邮政编码（WCF GetZipCodes 对应接口）和聊天机器人导航功能
prepare_mutation	为一项固定且经源代码确认的变更操作创建一次性令牌，不发送请求；令牌与操作及确切的调用参数（payload）绑定，并在 5 分钟后过期
mutate_list	使用该令牌执行经验证、由 APK 确认的低风险变更操作（列表、优惠券、购物篮、国家/ISIC、礼品、监控、反馈、讨论）
account_status	检查是否已加载移动 API 访问令牌
cart	读取当前购物车和总金额
add_to_cart	通过 Alza 代码添加产品
delivery_options	从 APK getDeliveryPaymentGroups 端点读取配送和 AlzaBox/自提选项
select_pickup_point	虽然名称如此，但此工具会返回配送 → 付款关联信息（哪些付款方式适用于某种配送，以及每种方式对应的配送费）。它不会选择自提点：已于 2026-10-06 在已验证身份的购物车上重新测试。要选择 AlzaBox，请使用 web_pickup_places → web_place_order，并提供 parcel_shop_id。
checkout_preview	预览结账流程并返回一次性确认令牌
cancel_order	使用取消表单、原因和一次性 prepare_mutation 令牌取消订单中的一个部分
place_order	仅在提供预览令牌和必需的 API 载荷时，才执行移动 API 下单流程
web_pickup_places	读取实时网页自提点系列信息（AlzaBox/分店/全天候可用性、地点列表、地点详情），用于网页结账时选择配送方式（只读）
web_add_to_cart	将产品添加到实时网页 HATEOAS 购物篮（basket/v1/items，按访客标识），并返回提取出的购物篮 ID
web_cart	读取 web_add_to_cart 返回的购物篮 ID 对应的实时网页结账购物车状态和商品列表（只读）
chat_navigation	读取实时聊天机器人 HATEOAS 导航（chatbotapi.alza.cz，由服务端提供的聊天操作；只读）
chat_send	使用页面上下文开启/继续聊天机器人会话（会话级、按访客标识；返回 {configuration, showChat}）

用户管理、付款、订单和购买后工具：

工具	用途
profile	读取已认证的个人资料和通讯录（APK getUserData）
contacts	读取账户联系人列表
register	注册新的 Alza 账户（携带凭据的一次性令牌）
address_upsert	通过服务器提供的地址表单创建或编辑收货地址
address_delete	通过每个地址对应的操作删除收货地址
address_search	通过已验证的 getZipCodes 查询邮编／城市，或在个人资料提供 addressSearchAction 时使用该操作（只读）
payment_methods	列出 APK 配送付款组端点提供的付款方式
after_order_payments	列出订单部分的订单后付款选项
pay_after_order	执行订单后付款（APK AfterOrderRequestBody，一次性令牌）
web_place_order	通过实时验证的旧版 Web WCF 流程提交订单（SaveOrder2→3、113-gate 重试、CheckOrder4、SendOrder4；一次性令牌）——移动端 sendOrder3 返回 500 时可用的提交路径
web_pay_after_order	通过实时验证的 WCF CreateAfterPayment 执行 Web 订单后付款（一次性令牌）
order	根据数字型 user_id 和 order_id 读取用户订单（可选部分详情、里程碑、发票引用）
review_submit	通过服务器提供的评价表单提交商品评价
complaint_claims	根据 user_id 列出有效或已归档的保修申请（K1；只读）
subscription_overview	根据 user_id 读取账户订阅版块（导航中的 userSubscription 链接）（S1；响应格式尚未经过实时验证）
subscription_activate	激活 AlzaSubscription（一次性令牌）
subscription_update_installment	更改分期付款计划（一次性令牌）
upload_attachment	通过服务器提供的 multipart 操作上传图片附件（一次性令牌）
order_search	按关键词搜索账户订单（OR6；只读）
order_archive	读取账户的已归档订单（OR7；只读；“Skrýt zrušené”取消订单的显示／隐藏开关）
order_document	从服务器提供的 href 下载订单发票／文档（OR10；来源已验证为 Alza 主机系列；正文仅在 structuredContent 中返回）
gdpr_info	读取 GDPR 版块和导出对话框（A17；只读——显示数据导出将发送至何处）
claim_detail	从 detailAction 链接读取一项保修申请的详情（K2；只读；限定为保修申请路由）
change_password	更改账户密码（A14；一次性令牌；将用户从所有设备登出）
two_factor_set	启用／停用短信双重验证（A15；一次性令牌）
phone_change	更改联系电话号码（A16；一次性令牌）
email_change	更改联系邮箱（A16 同类操作；一次性令牌）
delete_account	删除账户（A18；一次性令牌；不可逆——仅限一次性账户）
watchdog_list	列出账户的 Alza 监控项：降价和补货提醒（B9a；只读；输出中不包含邮箱）
watchdog_set	为商品设置监控项（max_price 和／或 track_stock）。满足条件时，Alza 会向账户发送邮件（B9；一次性令牌）
watchdog_delete	根据 watchdog_id 或 commodity_id 删除监控项（B9b；一次性令牌）

高影响变更需要一次性确认令牌（移动端 place_order 使用 checkout_preview，其他受保护的变更使用 prepare_mutation）；完整路由清单、暴露决策和验证标签见 docs/mobile-endpoint-coverage.md。 OAuth 登录在 MCP 之外完成；auth_exchange 会交换返回的代码，服务会将访问令牌和刷新令牌保存在内存中，或从配置的令牌文件中加载。访问令牌过期（或距离其 JWT exp 不足 60 秒）时，会在下一次账户调用前刷新；并行调用会共用一次刷新。account_status 会报告 expiresAt/expired。如果令牌是从令牌文件加载的，刷新后的令牌会写回该文件（以原子方式写入，权限模式为 0600），因此重启时不会使用过期令牌；通过进程内 auth_exchange 获取的令牌则保留在内存中。

登录后出现“Při přihlášení došlo k chybě.”？ 通常登录已成功。Alza 会重定向到 alza://identity?code=…&state=…，桌面浏览器无法打开这个地址，因此页面会停滞，Alza 登录页面中的 40 秒计时器随后会显示该消息。登录前，打开 DevTools 并启用 Network → Preserve log。登录后，从重定向的 Location 标头中复制 alza://identity?code=… URL，或从有关无法启动 alza:// 的 Console 错误中复制该 URL。将完整 URL 作为 code 传给 auth_exchange。代码很快就会过期，因此请立即交换。注册和修改凭据工具确实会将密码或验证码作为参数接收，并由一次性确认令牌进行保护。账户、购物车和订单工具会发起 API 请求，并可在遇到验证时改用浏览器请求；它们不会自动填写结账表单。

结账路径： web_place_order 会提交由 add_to_cart 填充的购物车，此前需要调用 delivery_options，并可进行任何针对购物车的 web_pickup_places 查询。web_add_to_cart → web_cart HATEOAS 购物篮是独立的。记录的实时测试中，移动端 place_order 路径被服务端 HTTP 500 错误阻断；旧版 WCF 路径已通过实时验证。带日期的证据请参阅已知限制。

移动端 API 环境变量：

环境变量	用途
ALZA_API_BASE_URL	移动端 API 基础 URL，默认为 https://www.alza.cz
ALZA_VISITOR_ID	可选的匿名访客 UUID；否则每个进程会生成一个
ALZA_OAUTH_CLIENT_ID	auth_start、auth_exchange 和令牌刷新使用的 OAuth 客户端 ID，默认为 alza_Android。仅在同时更改 ALZA_OAUTH_CLIENT_SECRET 时修改
ALZA_OAUTH_REDIRECT_URI	OAuth 重定向 URI，默认为 alza://identity
ALZA_COUNTRY / ALZA_CULTURE	在 OAuth 授权 URL 中发送的 countryCode / culture，默认值为 ALZA_BASE_URL 对应商城的值（alza.cz 为 CZ / cs-CZ，alza.sk 为 SK / sk-SK）
ALZA_OAUTH_AUTHORITY	OAuth 授权机构，默认为 https://identity.alza.cz
ALZA_OAUTH_CLIENT_SECRET	alza_Android OAuth 客户端为机密客户端——令牌请求需要其嵌入 APK 的密钥（默认使用经源代码验证的值；设为 "" 可为公共客户端省略该密钥）。供 auth_exchange 和令牌刷新使用
ALZA_CLIENT_SECRET	PKCE 交换脚本使用的相同密钥（scripts/e2e-order-payment.browser.mjs exchange、scripts/alza-auth-exchange.mjs）
ALZA_TOKEN_FILE	由 scripts/alza-auth-login* / scripts/alza_auth_login.py 写入的 JSON 令牌存储文件（默认为 ~/.alza-mcp/tokens.json；设为 none 可禁用自动加载）。服务刷新从该文件加载的令牌后，会以原子方式将其重写（权限模式为 0600）；设为 none 时不会读取或写入该文件

此外：

• 📦 资源 — alza://product/{code} 让 Agent 可以通过 URI 读取商品。
• 💬 提示词 — /find-product 是一款引导式购物助手。
• 🌍 多语言地区 — 商品目录地区配置通过 ALZA_BASE_URL 支持 alza.cz、.sk、.hu、.at、.de、.co.uk。API 调用（自动补全、单条评价、替代商品、导航、聊天机器人、账户读取）会发送该店铺的 country 和 Accept-Language；webapi.alza.cz 和 chatbotapi.alza.cz 为所有店铺提供服务，并根据 country 选择店铺（已于 2026-10-12 对 alza.sk 进行实时验证）。账户／结账验证仅适用于 CZ；账户写入操作（2FA、电话、电子邮件、账户删除、监控器、购物篮解锁）仍会发送 country=CZ。

---

配置

全部为可选项——alza-mcp-community 开箱即用。

环境变量	默认值	用途
ALZA_BASE_URL	https://www.alza.cz	切换地区：https://www.alza.cz、.sk、.hu、.at、.de、.co.uk
ALZA_CDP_URL	未设置	通过 CDP 连接到已运行的 Chrome，而不是启动受管理的 Chromium。复用现有浏览器会话；另行设置 ALZA_MCP_SKIP_INSTALL=1 可跳过安装时的下载。使用 --remote-debugging-port=9222 启动 Chrome，并设置 ALZA_CDP_URL=http://localhost:9222。
ALZA_TOOLSETS	未设置	除默认的 catalog + auth 外，启动时要启用的工具集，以逗号分隔（basket_and_checkout,orders_and_payments），或设为 all。适用于不会在 set_toolset 后重新加载工具列表的 MCP 客户端（它们会忽略 notifications/tools/list_changed），以便从第一次 tools/list 开始就能看到购物篮、订单和账户工具。ID：参见 list_toolsets；未知 ID 会导致服务在启动时停止。
ALZA_HEADLESS	true	设为 false 可显示用于抓取和 API 回退的浏览器；OAuth／MFA／支付交互仍由用户控制
ALZA_IDLE_TTL_MS	180000	没有工具调用时，经过这么多毫秒后关闭无头 Chromium。在内存受限的机器上可调低此值；如果短时间内频繁调用且不想承受重新启动的延迟，可调高此值（或设为极大值以停用）。
ALZA_PROXY_URL	未设置	通过 HTTP(S) 或 SOCKS5 代理转发 Alza 流量（http://user:pass@host:port、socks5://host:port），例如当此机器的 IP 遇到 Cloudflare 验证（数据中心和 CI IP 会遇到）时使用住宅代理。受管理的 Chromium 和 curl_cffi sidecar 均会使用此代理。设置后，账户栈不会再回退到不经过代理的普通 fetch（只会回退到受管理的浏览器）；禁用 sidecar（ALZA_CF_TRANSPORT=0）时，OAuth、AppAction 和文档请求会被拒绝，而不会直接发送，因此代理故障会被报告，而非绕过。无效值会导致服务在启动时以单行错误停止。不会经过代理的项目：ALZA_CDP_URL 浏览器和多部分上传（upload_attachment），sidecar 无法处理此类上传。
ALZA_DEBUG	false	输出详细的 stderr 日志（等同于 ALZA_LOG_LEVEL=debug）
ALZA_LOG_LEVEL	info	stderr 日志的最低级别：debug、info、warn 或 error
ALZA_CF_TRANSPORT	已启用	设为 0 可禁用 Chrome 指纹 curl_cffi sidecar（此时账户栈会使用普通 fetch 和浏览器）
ALZA_CF_PYTHON	自动	安装了 curl_cffi 的 Python 解释器。默认搜索顺序：此变量、软件包中的 .venv-cf（Windows 上为 bin/python 或 Scripts\python.exe），然后是 python3（Windows 上为 python／py）

安装路径与 curl_cffi 虚拟环境

Chrome 指纹旁路程序需要一个安装了 curl_cffi 的 Python 虚拟环境（固定版本范围为 >=0.16,<0.17，这是经过测试的范围）。各安装路径的操作如下：

安装路径	Chromium headless-shell	curl_cffi 虚拟环境
npx -y alza-mcp-community / npm i alza-mcp-community（Linux、macOS、WSL、MSYS bash）	由 postinstall 下载	如果存在 bash 和 python3（带有 venv），则由 postinstall 创建；如果创建失败，会删除部分创建的虚拟环境
ALZA_MCP_SKIP_INSTALL=1 或 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1	跳过（需要时在运行时下载）	仍会创建
ALZA_MCP_SKIP_VENV=1	下载	跳过
--ignore-scripts 或 .mcpb 包	需要时在运行时下载	不会创建。对于 --ignore-scripts，在软件包目录中运行 npx -y alza-mcp-community --setup-cf（跨平台，无需 bash）或 bash scripts/ensure-cf-venv.sh；对于 .mcpb 包，运行一次 --setup-cf，并将 ALZA_CF_PYTHON 指向任意安装了 curl_cffi 的解释器
本仓库的检出目录（npm ci）	跳过	跳过；请自行运行 npm run setup:cf 和 npx playwright install chromium --only-shell

没有虚拟环境时，服务仍可运行：账号栈会回退到普通 fetch 和浏览器，而 Cloudflare 更常对浏览器发起挑战。Windows：解释器查找也会尝试 .venv-cf\Scripts\python.exe、python 和 py，且 bash 脚本无法在普通 Windows 上运行。请改用 npx -y alza-mcp-community --setup-cf：该命令用 Node 实现，会查找 py -3/python/python3，在软件包目录中运行 python -m venv .venv-cf，安装 curl_cffi>=0.16,<0.17，验证导入，打印成功或失败信息，并以 0/1 退出。它可重复运行；如果 pip 失败，会删除创建到一半的虚拟环境；遵循 ALZA_MCP_SKIP_VENV=1；且不会自动运行（服务绝不会在运行时安装软件包；旁路程序不可用时只会记录一行提示，建议运行该命令）。虚拟环境会创建在运行该命令的软件包副本中（对于 npx，即其缓存目录；获取新版本或清除 npm 缓存时，该目录会被替换，因此届时需要重新运行 --setup-cf），所以 .mcpb 包不会使用它，因为 .mcpb 包有自己的目录：运行命令后，请在该包的环境中将 ALZA_CF_PYTHON 设置为命令打印的解释器（或任意安装了 curl_cffi 的解释器）。Windows 路径（Scripts\python.exe、py -3）仅通过模拟进程进行了单元测试，在真实 Windows 机器上的状态为 unresolved（未进行实机测试）。

---

通过 HTTP 运行（Streamable HTTP）

默认使用 stdio，上面的安装代码片段也是如此。若要改为通过 MCP Streamable HTTP 提供同一服务，例如供只接受 URL 的客户端使用：

npx -y alza-mcp-community --http --port 3000          # or: ALZA_TRANSPORT=http ALZA_HTTP_PORT=3000 npx -y alza-mcp-community
# → MCP endpoint http://127.0.0.1:3000/mcp, health check http://127.0.0.1:3000/healthz

claude mcp add --transport http alza http://127.0.0.1:3000/mcp

通过 HTTP 运行时，服务的限制比通过 stdio 运行时更严格，因为多个客户端都可能访问网络端点：

• 默认情况下仅启用目录。 只有只读、匿名的工具集可用：catalog（已启用）和 pc_builder（使用 set_toolset 启用）。其他所有工具集（auth、basket/checkout、account、orders/payments、reviews/subscriptions、chat、advanced_raw）均处于锁定状态：list_toolsets 会显示锁定原因，而 set_toolset 会拒绝启用它们。这些工具会登录真实的 Alza 账户并执行操作（订单、付款、凭据），因此共享端点不得意外提供这些工具。设置 ALZA_HTTP_ENABLE_ACCOUNT=1 即可解锁。
• 每个 MCP 会话使用一个独立服务。 每个 Mcp-Session-Id 都有自己的服务实例，包括独立的工具集状态、OAuth 令牌和一次性确认令牌。启用 ALZA_HTTP_ENABLE_ACCOUNT=1 后，每个会话还会拥有独立的浏览器上下文和 Chrome 指纹辅助进程，因为两者都会保存 Alza Cookie。会话在闲置 30 分钟后过期。
• 不使用令牌文件。 ALZA_TOKEN_FILE（~/.alza-mcp/tokens.json）保存一个人的登录信息，因此 HTTP 模式不会加载它。每个会话都通过 auth_start → auth_exchange 登录。对于单用户本地主机设置，可以设置 ALZA_HTTP_ALLOW_TOKEN_FILE=1（同时设置 ALZA_HTTP_ENABLE_ACCOUNT=1）；此时每个会话都会以该账户登录，因此切勿在共享主机上这样做。所有会话都从同一个刷新令牌开始。Alza 可能会在刷新时轮换该令牌（2026-09-10 的报告提到了这一点；2026-10-07 的一次运行中，同一个刷新令牌连续返回了六次，因此应将轮换视为可能发生，而非必然发生）；如果发生轮换，最先刷新的会话会使其他会话持有的副本失效（它们随后需要执行 auth_start → auth_exchange）。每个会话都会将刷新后的令牌写回令牌文件，因此重启时会读取最新令牌；此模式下请保持仅有一个活动会话。
• 默认仅绑定本地主机。 服务绑定到 127.0.0.1，并拒绝 Host 或 Origin 不是环回名称的请求（防止 DNS 重绑定）。没有内置身份验证或 TLS。如果绑定到其他地址（--host 0.0.0.0），请将服务置于同时提供这两项功能的反向代理之后，并设置 ALZA_HTTP_ALLOWED_HOSTS。

环境变量 / 标志	默认值	用途
--http、ALZA_TRANSPORT=http	stdio	通过 Streamable HTTP 提供服务
--help、--version（-h、-v）		打印用法或版本信息，然后退出
--port N、ALZA_HTTP_PORT（或 PORT）	3000	监听端口（0 会选择可用端口）
--host H、ALZA_HTTP_HOST	127.0.0.1	绑定地址
ALZA_HTTP_ALLOWED_HOSTS	绑定到环回地址时为环回名称，否则不进行检查	以逗号分隔的主机名列表，允许出现在 Host/Origin 中
ALZA_HTTP_ENABLE_ACCOUNT	off	解锁身份验证/账户/结账/订单/付款工具集（每个会话单独登录）
ALZA_HTTP_ALLOW_TOKEN_FILE	off	也将 ALZA_TOKEN_FILE 加载到每个会话中（仅限单用户；需要 ALZA_HTTP_ENABLE_ACCOUNT）
ALZA_HTTP_MAX_SESSIONS	50	并发会话上限（超过时返回 HTTP 503）
ALZA_HTTP_SESSION_IDLE_MS	1800000	会话在没有请求达到此时长后关闭（持有开放 GET/SSE 流的会话不会关闭）
ALZA_HTTP_REQUEST_TIMEOUT_MS	30000	客户端发送完整请求的时限（请求头的时限减半）；超时后返回 HTTP 408。响应（包括工具调用和 GET/SSE 流）不受限制
ALZA_HTTP_MAX_CONNECTIONS	256	开放 TCP 连接上限（SSE 流也计入）；超过上限的连接会被丢弃
目前尚不支持托管。 托管端点（Vercel mcp-handler、Fly、Railway 等）是后续计划。主要障碍是 Cloudflare，而非传输方式：Alza 受 Cloudflare Bot Management 保护，headless 浏览器和 curl_cffi sidecar 都能从住宅 IP 通过验证（已实时验证），但从数据中心 IP 访问时更容易受到质询。托管实例可能需要住宅代理（ALZA_PROXY_URL）或浏览器即服务（例如通过 ALZA_CDP_URL 使用 Browserbase）。每日 canary 的 GitHub 托管运行展示了这一点：它们会遇到 Cloudflare 的交互式质询。托管环境还需要具备以下条件：镜像中包含 Chromium 和带有 curl_cffi 的 Python；有足够的内存，为每个账户会话运行一个浏览器；使用粘性路由（会话保存在单个进程的内存中）；并在端点前进行身份验证。在任何多用户托管环境中，都应锁定账户工具集。

---

Pi Agent 集成

在 pi 的全局 MCP 配置（~/.pi/agent/mcp.json）中注册本地构建版本：

{
  "alza": {
    "command": "node",
    "args": ["/absolute/path/to/alza-mcp-community/dist/index.js"]
  }
}

运行 /reload（或运行 mcp connect alza——网关会重新启动 stdio 进程，因此无需运行 /reload，新构建的 dist/ 就会生效）。网关会在 alza_ 前缀下公开工具（领域工具以及 list_toolsets/set_toolset/report_issue；在调用 set_toolset 之前，仅启用 catalog 和 auth 工具集），例如 alza_search_products、alza_get_product、alza_cart 等。身份验证信息会从 ~/.alza-mcp/tokens.json 自动加载。已在两种模式下验证：(a) 通过网关在会话中使用——搜索/筛选/详情、通过身份验证后添加到购物车、无效优惠券往返请求 → 服务端 err:1 信封（docs/live-evidence/pi-integration-2026-09-10.md）；以及 (b) headless 模式（一次性提示词 pi -p），此时 Agent 会发现 alza_* 工具，使用正确的参数调用 search_products，并报告正确的、库存充足的最低价商品（docs/live-evidence/headless-pi-2026-09-12.json）；2026-09-13 的重新运行又增加了三个 headless 场景——按价格升序排序的商品目录搜索、经过身份验证的账户操作流程（account_status + cart），以及一次性变更令牌流程（prepare_mutation）——所有记录均见 docs/live-evidence/headless-pi-2026-09-13.json。

---

工作原理

Alza 没有面向消费者的公开 API。本项目对 Android 应用的 REST 接口进行逆向工程（从 APK 中还原路由名称和 DTO），并研究网站自身的结账流程。这两者都不是受支持或有文档说明的接口，因此随时可能变更或失效，恕不另行通知。

Cloudflare Bot Management。 Alza 使用了这项服务，普通 HTTP 客户端会收到 HTTP 403。此服务通过两种方式绕过它：使用无头 Chromium（抓取目录），以及使用 Chrome 指纹 HTTP 辅助进程（scripts/cf-transport.py，通过 curl_cffi 模拟 Chrome 的 TLS/HTTP2 指纹）调用账户/结账 API。这属于规避机器人防护措施，Alza 的使用条款可能禁止此行为。辅助进程及其设置脚本随 npm 软件包一同发布，postinstall 会尝试设置其 curl_cffi venv。它仍为可选项：如果没有 Python 或 curl_cffi，账户栈（包括 OAuth 登录）会退回到普通 fetch；对于同源 API 调用，则会使用浏览器。只有在辅助进程尚未发送请求时，才会通过其他方式重新发送会修改数据的请求（POST/PUT/PATCH/DELETE）；如果辅助进程发送请求后发生故障（超时、连接错误），工具会报告结果未知，而不会再次发送订单、付款或账户变更请求。使用前请参阅免责声明和 SECURITY.md。

链接归因。 目录工具返回的商品、类别和推荐链接（search_products、get_product、compare_products、recommend_alternatives、get_deals、autocomplete、list_categories、pc_build_*、watchdog_list 和 alza://product/{code} 资源）会附带 utm_source=alza-mcp-community&utm_medium=mcp，这是应 Alza 的要求添加的，以便 Alza 了解经由此服务访问的流量。这些参数只会添加到向你展示的 Alza 商城链接中。此服务自身向 Alza 发出的请求、登录、付款、API、PDF 和图片 URL，以及账户和结账工具的原始响应，都不会添加标记。不会添加其他数据。

未提供通用的任意路由工具。覆盖范围如下：

• 不包含：管理登录路由、遥测/审计路由、设备令牌和匿名活动路由、外部付款跳转（Klarna、Google Pay），以及快捷下单付款相关路由族（在覆盖矩阵中标记为 blocked）。
• 包含，但需要一次性令牌：下单和取消订单、账户注册，以及凭据/身份变更（密码、2FA、电话、电子邮件、删除账户——delete_account 不可撤销）。
• 仅当服务器驱动的操作 URL 是在已确认的响应中返回时，才会通过经过来源验证的 AppActionExecutor 执行（GET/POST、路径允许列表、每种工具对应的路由族和方法、凭据/付款/订单及 GET 写入路由的拒绝列表、敏感字段阻止列表、一次性确认令牌）；此类 URL 不会作为任意 MCP URL 接受。

完整的 12 个路由族清单（含方法、DTO、前置条件、副作用、暴露情况和验证状态）维护在 docs/mobile-endpoint-coverage.md 中。

旧版目录兼容性仍使用原始页面适配器：

• 搜索会访问 /search.htm?exps=... 并抓取 .browsingitem 卡片。
• 商品详情来自页面 JSON-LD。
• 评价使用 JSON-LD 汇总评分。
• 自提点数据由分店数据和地理编码组成。
• 仍启用每进程缓存。

图片、字体和分析请求会在路由层级被拦截。目录页面仍会加载脚本，排序后的搜索可能会获取多个结果页。典型延迟：搜索约 2 秒，商品详情在缓存预热后约 5 秒。

┌────────────────────────────────────────────┐
│ stdio transport (npx alza-mcp-community)             │
├────────────────────────────────────────────┤
│ MCP tools / resources / prompts            │
│  grouped into toolsets (toolsets.ts)       │
├────────────────────────────────────────────┤
│ Domain: catalog · reviews · pickup ·       │
│         mobile-account (cart/checkout/…)   │
├────────────────────────────────────────────┤
│ Infra:                                     │
│  • browser (Playwright, CDP)               │
│  • impersonate-transport (curl_cffi        │
│    Chrome-fingerprint sidecar)             │
│  • mobile-api (APK-derived REST client)    │
│  • jsonld (schema.org parser)              │
│  • cache (LRU + TTL)                       │
│  • locale (multi-country)                  │
└────────────────────────────────────────────┘

有关更深入的架构说明——包括为什么我们不提供 HTTP/okhttp 方案——请参阅 ARCHITECTURE.md。

---

开发

git clone https://github.com/lukabudik/alza-mcp-community.git
cd alza-mcp-community
npm install                 # dev checkout: postinstall is skipped on purpose
npm run setup:cf            # optional curl_cffi venv (needs bash + python3)
npx playwright install chromium --only-shell   # browser for live runs
npm test                    # unit tests, no network
npm run typecheck
npm run build               # → dist/
npm run eval                # agent-driven MCP eval harness (6 scenarios) → docs/live-evidence/
npm run validate:api        # hits real Alza — runs every tool end-to-end
npm run pentest:app-action  # Node AppAction transport comparison
npm run live:endpoint-matrix # bounded read-only APK route matrix; requires ALZA_API_BASE_URL
npm run live:user-journeys   # catalog, delivery/cart, and anonymous-account journeys
npm run auth:login:py        # PKCE login step 1 (prints browser URL + pending-login.json)
npm run auth:exchange        # PKCE login step 2 (Node, needs a CF-friendly egress)
node scripts/e2e-order-payment.browser.mjs exchange "<pasted alza://identity redirect>"
                             # step 2 via Playwright (works even when Cloudflare challenges plain HTTP)
npm run live:e2e             # real order + after-order payment through the MCP tools
                             # (browser-backed transport; use ALZA_HEADLESS=false to watch it)
npm run live:e2e:node        # same journey over plain HTTP (in-memory MCP client); needs a
                             # non-challenged egress or a fresh ~/.alza-mcp/tokens.json
STOP_BEFORE_ORDER=1 npm run live:e2e   # dry run: stop right before order submission
ALLOW_ANON=1 STOP_BEFORE_ORDER=1 npm run live:e2e
                             # anonymous dry run; ALLOW_ANON alone does not prevent ordering
node dist/index.js          # run the server (waits for stdio MCP messages)
node dist/index.js --http   # or serve MCP Streamable HTTP on http://127.0.0.1:3000/mcp

延伸阅读：

• ARCHITECTURE.md — 说明代码为何采用当前结构（CF、Playwright、hydration 策略）
• ROADMAP.md — 后续计划
• CONTRIBUTING.md — 仓库布局以及如何添加工具

---

路线图

main 已涵盖目录、筛选、购物车、结账、下单／取消订单和账户管理（参见功能以及 docs/gap-analysis.md 中的已知限制）。接下来：

• PC builder 后续工作（#15；pc_builder 工具集已发布）以及托管式 HTTP 端点（#16 的后续工作；本地 --http 模式已发布）

优先级见 ROADMAP.md；所有事项都记录在 issues 中——good first issue 是入门的好起点。

---

常见问题

为什么要下载 92 MB 的 Chromium？

Alza 的机器人防护可能会拦截普通 HTTP 请求。目录使用无头 Chromium 渲染产品页面；账户组件也可以使用可选的 Chrome 指纹侧车服务，并在需要时回退到由浏览器支持的请求。Chromium 会由 postinstall 钩子安装，或在首次启动时按需安装。参见工作原理。

登录和下单如何受到保护？

1. OAuth 登录不会将 Alza 密码作为 MCP 工具参数传递——登录在用户的浏览器中完成（OAuth PKCE），MCP 只会交换返回的代码。必须将凭据作为参数传递的工具（register、change_password、phone_change、email_change）需要明确的一次性令牌，且只能在用户直接指示时调用。
2. checkout_preview 会在检查购物车和配送选项后创建一次性确认令牌；place_order 会拒绝任意令牌。
3. web_place_order（目前可用的提交路径——移动端 place_order 会在服务器端返回 HTTP 500）以及其他所有高影响操作（cancel_order、pay_after_order、delete_account 等）都需要来自 prepare_mutation 的一次性令牌。令牌只能使用一次，会绑定到单项操作和作为 payload 传入的确切参数，并在 5 分钟后过期。MFA 和 3-D Secure 仍由用户在浏览器中操作。
4. 这些工具会创建、更改和取消真实订单与账户。令牌用于防止 Agent 意外调用，并不能代替用户确认操作——让你的 Agent 显示订单摘要并先征求确认。

可以避免下载 Chromium 吗？

可以。将 ALZA_CDP_URL 设置为现有 Chrome 的调试端口：

# launch Chrome with debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222
# tell alza-mcp-community to attach
ALZA_MCP_SKIP_INSTALL=1 ALZA_CDP_URL=http://localhost:9222 npx alza-mcp-community

MCP 将使用你的 Chrome——无需单独下载、冷启动更快，而且会继承你已有的 Alza Cookie。

Alza 会要求下架吗？

有可能，你应该做好这种准备。该项目没有商业意图，会缓存内容以尽量减少流量，并通过 issues 提供下架联系渠道——如果 Alza 要求移除，我们会照办。但它确实能绕过 Alza 的机器人防护（参见工作原理），因此按 Alza 的标准来看，它并不是一种礼貌的抓取方式，而且 Alza 的使用条款可能禁止此类行为。请将其用于个人自动化，而非大规模使用。

这与 rohlik-mcp 有何不同？

tomaspavlin/rohlik-mcp 是本项目的灵感来源。区别如下：

• Rohlik 不受 Cloudflare 挑战保护 → rohlik-mcp 使用普通 HTTP。由于 Alza 受此保护，我们只能使用真正的浏览器。
• Alza 的商品目录大得多（数百万个 SKU，而非一份杂货清单）。
• 我们覆盖完整的购买流程（购物车、结账、下单和取消订单），并提供账户管理，而不只是读取商品目录；我们还将工具分组为工具集，因此默认只启用商品目录和身份验证工具集。
• 除工具外，我们还提供 MCP 资源和提示词。

---

免责声明

alza-mcp-community 与 Alza.cz a.s. 无关联，也未获其认可或赞助。“Alza”“Alza.cz”和“AlzaBox”是其各自所有者的商标。

本软件的功能。 这是一个通过逆向工程实现的客户端。其移动 API 路由和数据结构是从 Alza Android 应用中还原的；其商品目录工具则通过无头浏览器抓取 alza.cz 页面。为了访问 Alza 的服务端，本软件会绕过 Cloudflare Bot Management（无头 Chromium 加上 Chrome 指纹 HTTP 辅助程序）。Android 应用的 OAuth 客户端凭据嵌入在公开 APK 中，并被用作令牌交换的默认凭据。

法律事项。 以上均非已发布或受支持的接口，且 Alza 的使用条款可能禁止自动访问、绕过机器人防护和逆向工程。您能否以及如何使用本软件，取决于您所在的司法管辖区以及您与 Alza 之间的协议。对此，您须自行承担全部责任。本内容不构成法律建议，维护者也不声明使用本软件合法或获得许可。

本软件会操作真实账户并花费真实资金。 结账、订单、付款、注册和账户删除工具会对 Alza 的真实账户执行操作。提交的订单真实有效且具有约束力；取消订单不保证成功。一次性令牌可防止 Agent 意外调用，但不能代替您亲自确认每项操作。仅使用您能接受损失的账户和订单进行测试，切勿使用您不愿将凭据暴露给 Agent 上下文的账户。

不提供担保。 本软件按“原样”提供，遵循 MIT 许可证。维护者不保证其可用性、准确性或对任何用途的适用性，也不对因使用本软件而导致的订单、扣款、账户锁定或封禁承担责任。上游接口可能随时更改，因此任何工具都可能停止工作。请勿将本软件用于商业决策。

安全问题——请参阅 SECURITY.md。Alza 员工或权利持有人如有疑虑，请提交 issue 或联系维护者——我们会尽快回复，并配合合理的移除请求。

---

许可证

MIT。请参阅 LICENSE。

贡献者

Luka Budík 创建者、维护者

Samuel Seidel 维护者

@jankryh 修复 OAuth 登录

特别感谢 Samuel Seidel，他是项目首位外部贡献者，如今也是共同维护者。他构建了账户、购物车、结账和订单工具、工具集、类型化输出架构、分类筛选功能以及经过实时验证的测试框架。这些贡献共同将项目从一个包含 5 个工具的商品目录浏览器，发展成了完整的购物 Agent（#1、#5）。

也感谢 @jankryh，他查明了 OAuth 登录无法通过 npm 包正常使用的原因，并修复了这个问题（#29、#30）。

欢迎参与贡献，详见 CONTRIBUTING.md 和未解决的问题。

致谢

• tomaspavlin/rohlik-mcp — 直接的灵感来源；我们借鉴了它的布局模式。
• topmonks/hlidac-shopu — Alza 爬虫方案参考（HTTP + 代理）。
• microsoft/playwright-mcp — 官方 Playwright MCP，证明了由浏览器驱动的 MCP 是许多网站的恰当抽象方式。
• Model Context Protocol 和 TypeScript SDK。