SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentsvoila-sdk

voila-sdk

Personal Voila grocery automation: search products, check discounts, list delivery slots, read cart and order history and update cart quantities.

Open website

About this tool

Voila MCP is a set of automation tools built around Voila.ca personal grocery shopping, with the goal of opening shopping operations to coding agents while keeping them auditable and controllable.

  1. Purpose The project provides an SDK, MCP server, and CLI for Voila.ca shopping. Its core positioning is "safe personal shopping automation": enabling agents to query products, view deals, manage the cart, and read order history, but without touching checkout or order placement.

  2. Main capabilities The repository contains three publishable packages:

  • packages/voila-sdk: @firfi/voila-sdk, a TypeScript SDK for Voila sessions, search, categories, cart, order history, delivery slots, and checkout-readiness helpers.
  • packages/voila-mcp: @firfi/voila-mcp, a stdio MCP server that exposes small, auditable tools.
  • packages/voila-cli: @firfi/voila-cli, a user CLI that reuses the MCP operation registry. The root package is private, and publishable packages are located under packages/.

The tools provided by the MCP server include:

  • voila_check_session_health: reports active, guest, expired, or retryable session status.
  • voila_get_active_shopping_context: reads the current region, destination, fulfillment method, and cart context.
  • voila_get_slot_listings: lists delivery slots for the specified destination and region.
  • voila_reserve_slot: reserves a caller-selected slot only under an explicit confirmation flag.
  • voila_search_products: searches for products in the current session context.
  • voila_get_category_products: retrieves products by Voila category id.
  • voila_get_discounted_products: scans promotions and returns products with meaningful discounts.
  • voila_get_completed_orders: reads completed orders, with cursor-based pagination support.
  • voila_get_order_details: reads item-level details for a single completed order.
  • voila_get_completed_order_items: Aggregates previously ordered items across completed orders.
  • voila_get_cart: Reads active cart totals, restricted items, unavailable data, and pricing hints.
  • voila_add_cart_items: Increases quantity increments using Voila product UUIDs.
  • voila_remove_cart_items: Decreases quantity increments using Voila product UUIDs.

The server does not expose checkout or order placement tools. Cart changes use quantity increments and return server hints for restricted, unavailable, and price change situations.

III. How to Use Voila has no publicly documented third-party customer API, so the server uses the same same-origin JSON endpoints as the web app, with session-based authentication. Sessions must be captured interactively via the CLI; do not store Voila passwords in the MCP configuration. If the session is missing, expired, or guest-only, tool results will include authGuidance, which gives the exact CLI login command to run. The MCP server itself does not launch a browser. Logins performed while the server is running take effect on the next tool call, with no restart needed. When VOILA_AUTH_SESSION_PATH is explicitly set and guest mode is off, the MCP server also runs read-only authenticated session keepalive. Set VOILA_KEEPALIVE=0 to disable it; VOILA_KEEPALIVE_INTERVAL_SECONDS defaults to 86400 seconds and must be at least 3600. Keepalive never bootstraps a guest, and if the configured session snapshot disappears, it stops with a configuration error. Transport: stdio is the default for local MCP clients; HTTP can be used for registry checks and deployments behind a trusted gateway. Unless MCP_HTTP_PATH is set, the HTTP endpoint is /mcp. VOILA_GUEST=1 forces guest session behavior, suitable for secure introspection environments such as Glama. Do not expose HTTP with a real session file directly to the public internet; place authentication and access control in front of /mcp. The CLI default session path is ~/.config/voila/session.json. Browser login uses a persistent Playwright profile located at ~/.cache/voila/browser-profile unless --profile is provided; log in manually and close the browser window to save. Live endpoint smoke tests remain optional. Unless the test cleans up after itself and the caller explicitly requests it, do not run live cart change tests against a real account.

IV. Use Cases Suitable for scenarios where you want a coding agent or automation script to browse Voila.ca products, compare prices, view discounts, learn about delivery time slots, and manage cart contents in an auditable way, without manual item-by-item operations.

V. Limitations

  • Does not include checkout or order placement functionality; cart changes are limited to quantity increases and decreases.
  • Relies on non-public same-origin JSON endpoints, with session-based authentication, and sessions may expire.
  • Requires capturing the session yourself via the CLI; passwords cannot be stored in the MCP configuration.
  • HTTP mode requires additional front-end authentication and should not be exposed directly to the public internet.
  • Live cart change tests must be done with caution, only when explicitly requested and when cleanup is possible.

Related tools

Browse category