La Belle Vie — Grocery MCP server

An MCP server (plus an optional thin lbv CLI) that lets an AI agent do the groceries on labellevie.com — search the catalog, fill the basket, reorder past shops, check delivery coverage and slots, and assemble a ready-to-pay summary. It is built on the private JSON API the website itself uses (backend: Deleev). This repo is a blueprint for a remote MCP server for La Belle Vie: deploy your own copy on Vercel (this repository is not a hosted public MCP). Swap the src/lbv/* client layer to bring another service to your agent. Lineage and freeze tags live in HISTORY.md.

Payment is never automated. Every flow stops at a ready-to-pay basket and hands you a summary plus the labellevie.com/panier link. There is deliberately no tool that places or pays for an order, and no card data is ever handled. You review and pay yourself on the site.

How it works

Claude connector ──MCP (OAuth via Descope, email OTP)──┐
                                                        ├─▶ Vercel: MCP server  (/mcp)
lbv CLI / agent ──MCP (static bearer LBV_API_TOKEN)─────┘        mcp-handler + withMcpAuth
                                                                 tool handlers ─▶ src/lbv/* core
                                                                          │
                                                    per-caller connection in Vercel KV:
                                                    AES-encrypted LBV login + cookie jar
                                                    (connected once via /connect/<code>)
                                                                          ▼
                                                    labellevie.com  +  search.deleev.com

Both the agent and the CLI speak MCP to the same deployed server. Your La Belle Vie login is not a server env var: each caller connects their own account once through a one-time browser link (connect_account). The server verifies the login against labellevie.com, then stores the session cookie jar plus the credentials encrypted with AES-256-GCM (LBV_CRED_KEY) in Vercel KV so it can transparently re-login when the cookie expires. The client-facing La Belle Vie logic is written once in src/lbv/* and both surfaces are thin.

Related MCP server: mcp-leclerc-drive

Tools

connect = needs a connected account (see Connect your account).

How the agent should shop

Keyword search alone can conflate meanings — search_products("banane") returns fresh bananas and banana-flavored candy. When a query is ambiguous (or you want to explore an aisle you don't know the French keywords for), call browse_categories first: no arguments lists the store's top-level aisles, parentId drills into one, query finds a category by name. Then pass the category id as categoryId to search_products to keep only products in that category (or any of its subcategories). The search gateway paginates before this filter, so a filtered page reports filteredCount/scannedCount and can legitimately come back empty — try the next page or a broader category.

Recurring purchases. Three sources feed a basket of things the user buys regularly: list_usual_products (the site's most-ordered products), list_recent_orders → get_order_products (what a past order contained, with today's price and availability) and list_favorites (the user's own lists). Each returns product ids to pass to add_to_cart; reorder takes a whole past order in one call, and add_to_favorites / remove_from_favorites curate the lists for next time. Products flagged available: false have been withdrawn or are out of stock — skip them or search for a replacement.

Connect your account

Tools marked connect act on your La Belle Vie account. Instead of a shared login in server env vars, each caller connects their own account once:

1. Ask the agent to run connect_account (CLI: lbv connect). It returns a link like https://<server>/connect/<code> — valid 10 minutes, single use, bound to your verified (OAuth or static-token) identity.

2. Open the link and enter your labellevie.com email + password on that page. The credentials go from your browser to this server to labellevie.com — never through the chat or the model.

3. On success the server keeps the authenticated cookie jar plus your credentials encrypted with AES-256-GCM (LBV_CRED_KEY) in KV, so it can silently re-login when the session cookie expires. The connection lives 90 days past its last use (rolling), i.e. effectively until you disconnect.

connection_status shows what is connected; disconnect_account deletes the stored credentials and session. A wrong password can be retried up to 5 times per link; an expired or used link shows a clear page telling you to ask the agent for a fresh one. Static-bearer (CLI) callers share one connection; each OAuth user gets their own isolated connection.

Use it from an agent

This repo is a template. Point every client at your deployment (https://<your-app>.vercel.app/mcp), not at someone else's.

Two independent auth paths hit the same /mcp endpoint: OAuth (Descope, for Claude Desktop/claude.ai connectors) and a static bearer token (for the CLI and any MCP client that supports headers).

Claude Desktop / claude.ai (OAuth custom connector):

1. Deploy this repo (see Deploy (Vercel)).

2. Settings → Connectors → Add custom connector → URL https://<your-app>.vercel.app/mcp.

3. Click Connect — a Descope sign-in opens. Enter the allow-listed email and the one-time code it receives.

4. Approve the consent screen; the tools appear.

Sign-in is by email one-time code and access is restricted server-side to a single allow-listed address (LBV_ALLOWED_EMAIL): any other account — even one that completes the Descope flow — is rejected with a 401. Self-registration is blocked in Descope besides.

Claude Code:

claude mcp add --transport http labellevie https://<your-app>.vercel.app/mcp \
  --header "Authorization: Bearer $LBV_API_TOKEN"

Generic MCP JSON config:

{
  "mcpServers": {
    "labellevie": {
      "type": "http",
      "url": "https://<your-app>.vercel.app/mcp",
      "headers": { "Authorization": "Bearer <LBV_API_TOKEN>" }
    }
  }
}

Use it from the CLI

The lbv CLI is a thin MCP client — it holds no secrets beyond the bearer token and talks to the same server.

npm run build:cli          # produces dist/cli.js (the `lbv` bin)

export LBV_MCP_URL="https://<your-app>.vercel.app/mcp"
export LBV_API_TOKEN="…"

lbv search "banane bio" --perPage 5
lbv categories                     # top-level aisles
lbv categories 74                  # subcategories of category 74
lbv categories --find fromage      # find categories by name
lbv search banane --category 74    # keyword search filtered to a category
lbv add 49135 2
lbv cart
lbv slots 75011
lbv connect                   # one-time browser link to connect your LBV account
lbv status                    # which account is connected
lbv orders                    # recent orders: id, date, product count
lbv order 123456              # products of one past order, with availability
lbv usuals                    # most-ordered products
lbv reorder 123456            # add a whole past order into the basket
lbv favorites                 # favorites lists + their products
lbv favorite 49135 --list "Courses de la semaine"   # add to a list (created if missing)
lbv unfavorite 49135          # remove from every favorites list
lbv checkout 75011            # ready-to-pay summary; never pays
lbv disconnect                # delete the stored credentials + session
lbv <command> --json         # print the structured JSON result instead of text
lbv --help

Local development

Requires Node 24+ (engines.node: ">=24") — the same version CI and the Vercel runtime use. The stack is Next 16 (App Router), mcp-handler v2, MCP SDK v2 and zod 4.

npm install
npm run dev                  # Next.js dev server → http://localhost:3000/mcp

# Inspect the tools interactively:
npx @modelcontextprotocol/inspector      # point it at http://localhost:3000/mcp + your bearer

# Or drive it with the CLI against local dev:
LBV_MCP_URL=http://localhost:3000/mcp LBV_API_TOKEN=dev-token lbv search "lait"

Without KV, connect_account links are stored in gitignored .lbv-dev-store.json so the /mcp and /connect routes share state. Production must use Vercel KV / Upstash.

Health check (no auth): GET /api/health reports liveness and whether the bearer token / OAuth / KV / LBV_CRED_KEY are configured, plus connectReady (KV and key present — the account-connect flow will work). It never returns secrets.

Environment variables

Server variables go in the Vercel project; LBV_EMAIL/LBV_PASSWORD live only in your local .env.local (gitignored) for verify-auth / integration tests:

See .env.example.

Verify auth

To confirm the login handshake works with your credentials (the same handshake the /connect page uses), locally:

# put LBV_EMAIL / LBV_PASSWORD in .env.local first
npm run verify-auth

This performs the real login + an authenticated GET /api/fullprofile. Your password is read locally and sent only to labellevie.com — never printed or committed.

Testing

npm run lint                 # ESLint (flat config)
npm run typecheck            # tsc --noEmit
npm test                     # unit + contract tests (mocked, no secrets, no network)
npm run test:integration     # opt-in live tests — needs LBV_LIVE=1 + LBV_EMAIL/LBV_PASSWORD
npm run capture-fixtures     # re-capture the orders/favorites responses into a temp dir (local creds)

• Unit (tests/unit): request builders + response parsers grounded in captured API fixtures, the CSRF login handshake + auto re-login, and the session store.

• Contract (tests/contract): starts the MCP server in-process and asserts the exact tool set, each tool's input schema, and — as a guardrail regression — that no payment/order-placing tool is exposed.

• Integration (tests/integration): read-only / self-reverting live calls (search, coverage, slots, an add→view→remove cart round-trip that restores the basket, the orders pages, and a favorites round-trip on a throwaway __lbv_mcp_test_* list that is deleted afterwards). Never touches payment. Skipped unless LBV_LIVE=1.

• Fixtures (tests/fixtures): npm run capture-fixtures logs in with the local LBV_EMAIL/LBV_PASSWORD, performs read-only requests and writes the raw responses to a temp directory — never into the repo. Before copying a capture in, strip everything personal (name, email, address, phone, user id) and replace real order/list ids with synthetic ones; product data is public catalogue content and stays.

CI/CD & branches

• main = published template tip, dev = integration. Flow: feature branch → PR → dev → PR → main.

• .github/workflows/ci.yml (push/PR to dev & main): install → lint → typecheck → test → build, on Node 24. Fully mocked, no secrets — this is the merge gate.

• .github/workflows/integration.yml (manual, via Run workflow): runs the live tests with the repo secrets LBV_EMAIL / LBV_PASSWORD, also on Node 24. Kept off the PR path so a flaky external API never blocks a merge. Community clones only need this if they add their own secrets.

Lineage: HISTORY.md. Frozen snapshot: git checkout freeze-2026-08-11.

Deploy (Vercel)

This is your MCP. Import this repository as a new Vercel project — do not attach it to someone else's existing deployment.

git clone https://github.com/McCANNParis/MCPServerLaBelleVie.git
cd MCPServerLaBelleVie

1. Fork or clone McCANNParis/MCPServerLaBelleVie.

2. In Vercel: Add New… → Project → import that GitHub repo (production branch main).

3. Marketplace: add a KV / Upstash Redis store so KV_REST_API_URL and KV_REST_API_TOKEN are injected.

4. Set LBV_API_TOKEN and LBV_CRED_KEY (openssl rand -hex 32 for each). Optional OAuth: DESCOPE_PROJECT_ID plus LBV_ALLOWED_EMAIL (and/or LBV_ALLOWED_SUBJECT). Do not set LBV_EMAIL / LBV_PASSWORD on Vercel — each user connects through connect_account.

5. Deploy. Env changes apply only to new deployments — redeploy after changing them.

6. From each MCP client, run connect_account once and complete the browser login.

7. Point Claude / the CLI at https://<your-app>.vercel.app/mcp.

Vercel picks the function runtime from engines.node in package.json (Node 24) — no runtime setting to configure in the dashboard.

Add LBV_EMAIL / LBV_PASSWORD as GitHub Actions secrets only if you want the optional live integration workflow.

Notes & limitations

• This automates your own account through the app's private, undocumented API. Keep it to personal use and gently rate-limited. Undocumented endpoints can change without notice; /api/health helps flag breakage early.

• Payment is out of scope by design — the tool stops at a ready basket and you complete payment.

• Favorites are the site's own "listes favoris": the tools read and edit the same lists you see on labellevie.com. add_to_favorites creates "Mes favoris" when the account has no list yet, and asks for listId/listName when it has several. Lists themselves are never deleted by a tool.

• The orders pages (/commande-rapide/…) are server-rendered HTML, parsed with a few patterns behind a page-marker check: if La Belle Vie changes that markup, list_recent_orders / list_usual_products fail with an explicit "site may have changed" error rather than an empty list.

License

MIT