SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI智能体voila-sdk

voila-sdk

Voila MCP 是一个面向个人 Voila.ca 杂货购物的自动化工具集，以模型上下文协议（MCP）服务器形式提供，让编码智能体可以安全地操作购物流程。它提供产品搜索、分类浏览、折扣扫描、配送时段查询、购物车增减以及已完成订单历史读取等功能，但刻意不暴露结账和下单工具，以保证安全性。项目以 npm 包形式发布，包含 @firfi/voila-mcp（stdio MCP 服务器）、@firfi/voila-sdk（TypeScript SDK，涵盖会话、搜索、分类、购物车、订单历史、配送时段和结账就绪辅助）和 @firfi/voila-cli（复用 MCP 操作注册表的用户命令行工具）。由于 Voila 未公开第三方客户 API，该工具使用与网页应用相同的同源 JSON 端点，采用基于会话的认证方式，需通过 CLI 交互式捕获会话，不应在 MCP 配置中存储密码。会话缺失、过期或仅访客时，工具结果会返回 authGuidance 指引登录命令。

访问官网

工具介绍

Voila MCP 是一套围绕 Voila.ca 个人杂货购物构建的自动化工具，目标是把购物操作开放给编码智能体（coding agents），同时保持可审计、可控制。

一、用途 该项目为 Voila.ca 购物提供 SDK、MCP 服务器和 CLI。其核心定位是“安全的个人购物自动化”：让智能体能够查询商品、查看优惠、管理购物车和读取历史订单，但不触达结账或下单环节。

二、主要能力 仓库包含三个可发布包：

  • packages/voila-sdk：@firfi/voila-sdk，是用于 Voila 会话、搜索、分类、购物车、订单历史、配送时段以及结账就绪辅助工具的 TypeScript SDK。
  • packages/voila-mcp：@firfi/voila-mcp，一个 stdio MCP 服务器，暴露小而可审计的工具。
  • packages/voila-cli：@firfi/voila-cli，一个复用 MCP 操作注册表的用户 CLI。 根包为私有，可发布包位于 packages/ 下。

MCP 服务器提供的工具包括：

  • voila_check_session_health：报告活动、访客、过期或可重试的会话状态。
  • voila_get_active_shopping_context：读取当前区域、目的地、配送方式和购物车上下文。
  • voila_get_slot_listings：列出指定目的地和区域的配送时段。
  • voila_reserve_slot：仅在明确确认标志下预留调用方选定的时段。
  • voila_search_products：在当前会话上下文中搜索产品。
  • voila_get_category_products：按 Voila 分类 id 获取产品。
  • voila_get_discounted_products：扫描促销并返回有意义的折扣产品。
  • voila_get_completed_orders：读取已完成订单，支持游标分页。
  • voila_get_order_details：读取单个已完成订单的商品级详情。
  • voila_get_completed_order_items：跨已完成订单聚合此前订购的商品。
  • voila_get_cart：读取活动购物车总计、受限商品、不可用数据和定价提示。
  • voila_add_cart_items：使用 Voila 产品 UUID 增加数量增量。
  • voila_remove_cart_items：使用 Voila 产品 UUID 减少数量增量。

服务器不暴露结账或下单工具。购物车变更使用数量增量，并针对受限、不可用和价格变动情况返回服务器提示。

三、使用方式 Voila 没有公开文档化的第三方客户 API，因此服务器使用与网页应用相同的同源 JSON 端点，认证基于会话。需通过 CLI 交互式捕获会话，不要在 MCP 配置中存储 Voila 密码。 如果会话缺失、过期或仅限访客，工具结果会包含 authGuidance，其中给出要运行的确切 CLI 登录命令。MCP 服务器自身不会启动浏览器。服务器运行期间进行的登录会在下一次工具调用时生效，无需重启。 当显式设置 VOILA_AUTH_SESSION_PATH 且关闭访客模式时，MCP 服务器还会运行只读的已认证会话保活。设置 VOILA_KEEPALIVE=0 可禁用它；VOILA_KEEPALIVE_INTERVAL_SECONDS 默认 86400 秒，且必须至少为 3600。保活从不引导访客，如果配置的会话快照消失，会以配置错误停止。 传输方式：stdio 是本地 MCP 客户端的默认方式；HTTP 可用于注册表检查以及部署在可信网关之后。除非设置 MCP_HTTP_PATH，否则 HTTP 端点为 /mcp。VOILA_GUEST=1 强制访客会话行为，适用于 Glama 等安全内省环境。不要将带真实会话文件的 HTTP 直接暴露到公网；应在 /mcp 前放置身份验证和访问控制。 CLI 默认会话路径为 ~/.config/voila/session.json。浏览器登录使用位于 ~/.cache/voila/browser-profile 的持久 Playwright 配置文件，除非提供 --profile；手动登录并关闭浏览器窗口以保存。 实时端点冒烟测试仍为可选。除非测试会自行清理且调用方明确要求，否则不要对真实账户运行实时购物车变更测试。

四、适用场景 适用于希望让编码智能体或自动化脚本以可审计方式浏览 Voila.ca 商品、比价、查看折扣、了解配送时段和管理购物车内容，而无需人工逐项操作的场景。

五、限制

  • 不包含结账和下单功能，购物车变更仅限于数量增减。
  • 依赖非公开的同源 JSON 端点，认证基于会话，会话可能过期。
  • 需要自行通过 CLI 捕获会话，不能把密码存入 MCP 配置。
  • HTTP 模式需要额外前置认证，不应直接公网暴露。
  • 实时购物车变更测试需谨慎，仅在被明确要求且能清理时进行。

同类工具

查看分类