yandex-lavka-mcp 是一个非官方的 MCP（Model Context Protocol）服务器，用于让 AI 助手从 Yandex Lavka 订购杂货。它支持搜索商品、构建购物车并下真实订单，并在任何扣款发生前要求明确的人工确认。
【用途与定位】 该项目面向希望用 AI 助手操作自己 Yandex Lavka 账户完成购物的用户。它为非官方项目，Yandex Lavka 没有公开 API，因此项目直接对接 lavka.yandex.ru 使用的同一私有 Web API，并使用用户自己的 Yandex 会话 Cookie 进行认证。项目声明与 Yandex 无关联、未获其认可，使用可能违反 Yandex 服务条款，私有 API 也可能随时变更或被封禁。
【主要能力】
- 搜索 Yandex Lavka 商品目录；
- 构建购物车；
- 下单结算，采用两步确认流程保障资金安全；
- 支持多地点/多城市（目录、价格和购物车均按地点限定）；
- 支持通过 use_address 切换到已保存地址，或通过 set_delivery_address 设置任意城市的任意地址（借助 Lavka 自身的地址搜索进行地理编码）；
- 处理 3-D Secure：confirm_order 提交订单并扣款后轮询支付状态，若银行要求 3DS，会返回 wait_user_action 与 redirect_url，需打开该链接完成支付；
- 提供 cancel_order(order_id) 取消订单。
【资金安全机制】 下单是刻意的两步流程：checkout_preview 返回完整摘要且不产生任何扣款；confirm_order(confirmed_total) 除非刚运行过预览且传入的总额与预览完全一致，否则会拒绝执行。一旦更改购物车，预览即失效，必须重新预览。
【技术组成与安装使用】 技术栈为 Python 3.12+、FastMCP、httpx。仓库包含 client.py（异步 API 客户端，处理会话认证、CSRF、请求构建并裁剪超大响应）、endpoints.py（集中存放所有 API 路径，可从配置覆盖，无需改代码）、server.py（助手可见的 MCP 工具）。API 位于 https://lavka.yandex.ru/api/v1/providers/（下单为 /api/v1/orders/submit），请求需要首页 HTML 中的 CSRF 令牌以及 X-Lavka-Web- 请求头，客户端已处理。 使用步骤大致为：先在浏览器登录 Lavka，把会话 Cookie 放入 ~/.config/yandex-lavka-mcp/config.json（macOS 可从 Chrome 直接提取，任意系统可从 DevTools 复制 Cookie 请求头）；然后设置配送地点（复制 config.example.json 后编辑，或由助手通过 use_address / set_delivery_address 设置，未设置地点时目录不可用）；最后注册到助手（如 Claude Desktop 的 mcpServers）。默认使用 stdio，本地客户端适用；设置 YANDEX_LAVKA_MCP_TRANSPORT=streamable-http 可经 HTTP 暴露，以支持托管实例和 claude.ai 自定义连接器（手机/网页）。仓库包含预构建 Dockerfile，密钥在运行时注入，不烘焙进镜像。
【远程部署与认证】 公开端点会真实花钱，必须加以保护。claude.ai 的自定义连接器 UI 只支持 OAuth（不支持静态 bearer 或自定义请求头，后者仅适用于 Claude Code/Desktop）。该服务器是提供商无关的 OAuth 2.1 资源服务器，可对接任意 OpenID-Connect 提供商（Zitadel、Keycloak、Auth0、Google 等），依据该提供商的 JWKS 验证 JWT 访问令牌并通过 OAuth 受保护资源元数据发布。需安装 server 附加组件（pip install '.[server]'，Docker 镜像已含）并设置相应配置。除非配置 OAuth 或设置 YANDEX_LAVKA_MCP_ALLOW_INSECURE=1 自行前置认证，否则对外暴露的 HTTP 传输会拒绝启动。
【验证码与会话过期】 会话 Cookie 会过期，调用失败时需重新获取并更新 YANDEX_LAVKA_MCP_CONFIG_JSON 密钥；没有无头（headless）方式登录 Yandex。托管实例可能被 Yandex 以验证码回应，这取决于服务器 IP 而非会话本身；此时需通过该 IP 解决一次验证码，脚本会输出 spravka cookie，将其设为 YANDEX_LAVKA_MCP_SPRAVKA 密钥并重启，有效期约 30 天。
【限制与注意事项】 Lavka 每个账户在服务端只保留一个购物车，由乐观锁 cartVersion 保护。本服务器会串行化自身的购物车写入并在版本冲突时重试，因此同一会话内的并行工具调用是安全的。但不要同时从两处驱动同一 Yandex 账户（例如本服务器、第二个 MCP 会话以及 Lavka App），它们都写入同一个共享购物车，会出现其他写入者的商品混入。一次只使用一个客户端。Cookie 与地址仅保存在 ~/.config/yandex-lavka-mcp/config.json（权限 600，已 git 忽略），切勿提交。服务器不会添加支付方式或更改账户设置，下单始终需要明确确认的总额。项目采用 MIT 许可证，按“原样”提供，不提供任何担保。
