continentept-mcp 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -6,7 +6,26 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.3.0] - 2026-10-15
+
+### Added
+
+- One-click Claude Desktop extension (`continentept-mcp.mcpb`) attached to every release. It asks for your email and password at install time.
+- Chromium downloads automatically the first time it is needed; `install-browser` is now optional. While it downloads, tools return a retryable `browser_unavailable` error explaining the wait.
+
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- Server instructions: assistants receive the cart rules (exact totals, one change at a time, check the cart after an uncertain change) as soon as they connect.
+- A `basket-planner` prompt with the full shopping workflow, with an optional request to plan for. No skill install is needed.
+- Documentation for supplying credentials from 1Password with `op run`.
+
+### Changed
+
+- The `basket-planner` skill links to the online tool reference, so it also works when uploaded on its own.
+
+## [0.1.0] - 2026-10-15
 
 ### Added
 
@@ -16,5 +35,7 @@ All notable changes to this project are documented here. The format follows
 - Automatic sign-in from environment variables or a private credentials file, and a `login` command.
 - The `basket-planner` skill for planning a shopping list and updating the basket.
 
-[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/andredelgado/continente-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/andredelgado/continente-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/andredelgado/continente-mcp/releases/tag/v0.1.0

package/README.md

@@ -23,25 +23,33 @@ on the website.
   of retrying.
 - **Your account**: favorites, order history and a ranking of the products you buy most.
 - **Runs locally** over stdio. Credentials and cookies stay on your machine.
-- **Bundled skill** ([`basket-planner`](skills/basket-planner/SKILL.md)) that teaches an
-  assistant to plan a shopping list and update the basket.
+- **Built-in guidance.** The server tells the assistant the cart rules as soon as it
+  connects, and offers a `basket-planner` prompt with the full shopping workflow. Nothing
+  extra to install; the same guide also ships as a [skill](skills/basket-planner/SKILL.md).
 
 ## Requirements
 
-- Node.js 22 or newer
 - A Continente.pt account for account features (search and product details work without one)
+- Claude Desktop on macOS or Windows for the one-click install, or Node.js 22 or newer for
+  any other MCP client
 
-## Quick start
+The server drives the website with Chromium, which it downloads automatically the first time
+it needs it (about 150 MB, once).
 
-**1. Install the browser** the server uses to talk to the website (one-time download):
+## Install in Claude Desktop (one click)
 
-```sh
-npx -y continentept-mcp install-browser
-```
+1. Download [**continentept-mcp.mcpb**](https://github.com/andredelgado/continente-mcp/releases/latest/download/continentept-mcp.mcpb)
+   from the latest release.
+2. Open it. Claude Desktop shows an install dialog; click **Install**.
+3. Enter your Continente email and password when asked. Claude Desktop keeps the password
+   in its secure settings storage.
 
-On Linux, append `--with-deps` to also install the required system libraries.
+That's it. The extension updates when you install a newer `.mcpb`. To use 1Password instead
+of storing the password in Claude Desktop, use the manual setup below.
 
-**2. Save your credentials** in `~/.continentept-mcp/credentials.env` (see
+## Manual setup (any MCP client)
+
+**1. Save your credentials** in `~/.continentept-mcp/credentials.env` (see
 [configuration](docs/configuration.md) for other options):
 
 ```sh
@@ -50,13 +58,16 @@ printf 'CONTINENTE_EMAIL=you@example.com\nCONTINENTE_PASSWORD=your-password\n' >
 chmod 600 ~/.continentept-mcp/credentials.env
 ```
 
+Using 1Password? Skip the file and pass secret references through `op run` instead; see
+[Using 1Password](docs/configuration.md#using-1password).
+
 Optionally check that login works:
 
 ```sh
 npx -y continentept-mcp login
 ```
 
-**3. Add the server to your MCP client.**
+**2. Add the server to your MCP client.**
 
 Claude Code:
 
@@ -80,6 +91,10 @@ Claude Desktop, Cursor and other clients (`claude_desktop_config.json`, `mcp.jso
 To keep the credentials file elsewhere, add
 `"env": { "CONTINENTE_CREDENTIALS_FILE": "/absolute/path/to/credentials.env" }`.
 
+Chromium downloads itself on first use. To fetch it ahead of time, run
+`npx -y continentept-mcp install-browser` (on Linux, add `--with-deps` for the system
+libraries it needs).
+
 Then ask your assistant something like *"Add semi-skimmed milk and a dozen eggs to my
 Continente cart"* or *"What do I usually buy? Build me a list for this week."*
 
@@ -108,12 +123,24 @@ In that case the result has `mutation.outcome: "unknown"` and asks the client to
 `get_cart` before doing anything else. The server never retries such a change on its own,
 and clients should not either: repeating an `add_cart_item` could add the item twice.
 
+### Guidance for the assistant
+
+When a client connects, the server sends short instructions with these cart rules, so the
+assistant follows them without any setup. For planning a shopping list, pick the
+**basket-planner** prompt from your client's prompt or attachment menu, optionally with a
+request such as "weekly basket for two".
+
+The same guide is available as a skill in
+[`skills/basket-planner`](skills/basket-planner/SKILL.md). Clients that support skills, such
+as Claude Desktop (Settings → Capabilities → Skills) or Claude Code (`~/.claude/skills/`),
+then apply it automatically whenever you ask about groceries.
+
 ## Command line
 
 ```text
 continentept-mcp                    Start the MCP server on stdio
 continentept-mcp login              Sign in and save the session (--show-browser to watch)
-continentept-mcp install-browser    Download Chromium (extra arguments go to Playwright)
+continentept-mcp install-browser    Download Chromium now instead of on first use (extra arguments go to Playwright)
 continentept-mcp --version
 ```
 

package/dist/application.d.ts

@@ -1,8 +1,10 @@
 import { ContinenteMcpServer } from './mcp/server.js';
-import type { ToolHandler } from './mcp/server.js';
+import type { PromptHandler, ToolHandler } from './mcp/server.js';
 export interface ApplicationOptions {
     readonly version: string;
     readonly tools?: readonly ToolHandler[];
+    readonly prompts?: readonly PromptHandler[];
+    readonly instructions?: string;
     readonly closeResources?: () => Promise<void>;
     readonly requestTimeoutMs?: number;
 }

package/dist/cli.js

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createShoppingApplication } from './runtime.js';
 import { runAutoLogin } from './auto-login.js';
 import { isMainModule } from './main-module.js';
+import { runChromiumInstall } from './session/chromium.js';
 const USAGE = `Usage: continentept-mcp [command]
 
 Commands:
@@ -57,11 +55,6 @@ export async function connectStdioApplication(application) {
         throw error;
     }
 }
-function installBrowser(extra) {
-    const playwright = dirname(createRequire(import.meta.url).resolve('playwright/package.json'));
-    const result = spawnSync(process.execPath, [join(playwright, 'cli.js'), 'install', 'chromium', ...extra], { stdio: 'inherit' });
-    return result.status ?? 1;
-}
 export async function main(args) {
     const [command, ...rest] = args;
     switch (command) {
@@ -78,7 +71,7 @@ export async function main(args) {
                 return 1;
             }
         case 'install-browser':
-            return installBrowser(rest);
+            return runChromiumInstall(rest);
         case '-v':
         case '--version':
             console.log(packageVersion());

package/dist/clients/policy.d.ts

@@ -7,7 +7,7 @@ export interface HttpResponse {
 }
 /** Only known authentication evidence triggers recovery; arbitrary upstream failures do not. */
 export declare function responseStatus(response: HttpResponse | null, finalUrl: string): import("../domain/result.js").Result<undefined, {
-    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
     message: string;
     retryable: boolean;
     issues?: {
@@ -16,7 +16,7 @@ export declare function responseStatus(response: HttpResponse | null, finalUrl:
     }[] | undefined;
 }>;
 export declare function authenticatedPayload(input: unknown): import("../domain/result.js").Result<unknown, {
-    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
     message: string;
     retryable: boolean;
     issues?: {

package/dist/clients/storefront.js

@@ -1,4 +1,5 @@
 import { requestIO, requestTimeout, checkRequest, RequestStopped, reportProgress } from '../session/request.js';
+import { BrowserUnavailable } from '../session/chromium.js';
 import { failure, success } from '../domain/index.js';
 import { parseProductSearchPage, parseSearchPagination, parseFavoritesPageData, STOREFRONT_ORIGIN, storefrontUrl } from '../parsers/catalog.js';
 import { responseStatus, authenticatedPayload } from './policy.js';
@@ -6,6 +7,12 @@ import { orderHistoryUrl } from '../parsers/orders.js';
 import { field } from '../parsers/records.js';
 export const CART_SUMMARY_URL = `${STOREFRONT_ORIGIN}/on/demandware.store/Sites-continente-Site/default/Cart-MiniCartShow`;
 const ORDER_DETAIL_PATHS = ['/conta/detalhe-encomenda/', '/detalhe-encomenda'];
+/** Map an error from starting or using the browser; cancellation keeps propagating. */
+function browserFailure(error) {
+    if (error instanceof RequestStopped)
+        throw error;
+    return error instanceof BrowserUnavailable ? { ok: false, error: error.toolError } : failure('upstream_unavailable');
+}
 const productPath = (reference) => `/produto/${reference.endsWith('.html') ? reference : `${reference}.html`}`;
 export class StorefrontClient {
     session;
@@ -30,9 +37,7 @@ export class StorefrontClient {
             return success(lease);
         }
         catch (error) {
-            if (error instanceof RequestStopped)
-                throw error;
-            return failure('upstream_unavailable');
+            return browserFailure(error);
         }
     }
     async html(path, marker = 'main, [role="main"], .product-line, a[href*="/produto/"]') {
@@ -125,7 +130,7 @@ async function readContinuation(site, url) {
         return status.ok ? success(await site.io(lease, () => response.text())) : status;
     }
     catch (error) {
-        return failure(error instanceof RequestStopped ? error.code : 'upstream_unavailable');
+        return error instanceof RequestStopped ? failure(error.code) : browserFailure(error);
     }
 }
 export class FavoritesClient {
@@ -196,9 +201,7 @@ export class CartClient {
             return authenticatedPayload(data);
         }
         catch (error) {
-            if (error instanceof RequestStopped)
-                throw error;
-            return failure('upstream_unavailable');
+            return browserFailure(error);
         }
     }
     async fetchProductForm(reference) {
@@ -264,9 +267,7 @@ export class CartClient {
             });
         }
         catch (error) {
-            if (error instanceof RequestStopped)
-                throw error;
-            return failure('upstream_unavailable');
+            return browserFailure(error);
         }
     }
 }
@@ -288,9 +289,7 @@ export class OrdersClient {
             return success(await this.site.io(response.value, () => page.content()));
         }
         catch (error) {
-            if (error instanceof RequestStopped)
-                throw error;
-            return failure('upstream_unavailable');
+            return browserFailure(error);
         }
     }
     async fetchOrderLines(url) {

package/dist/domain/errors.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export declare const ToolErrorCodeSchema: z.ZodEnum<{
+    browser_unavailable: "browser_unavailable";
     cache_unavailable: "cache_unavailable";
     cancelled: "cancelled";
     cart_change_rejected: "cart_change_rejected";
@@ -18,6 +19,7 @@ export declare const ToolErrorCodeSchema: z.ZodEnum<{
 }>;
 export declare const ToolErrorSchema: z.ZodObject<{
     code: z.ZodEnum<{
+        browser_unavailable: "browser_unavailable";
         cache_unavailable: "cache_unavailable";
         cancelled: "cancelled";
         cart_change_rejected: "cart_change_rejected";

package/dist/domain/errors.js

@@ -4,7 +4,7 @@ export const ToolErrorCodeSchema = z.enum([
     'not_found', 'sale_rules_unknown', 'quantity_below_minimum',
     'cart_change_rejected', 'cart_change_unconfirmed', 'cache_unavailable',
     'order_details_unavailable',
-    'cancelled', 'deadline_exceeded', 'server_closed', 'queue_full',
+    'cancelled', 'deadline_exceeded', 'server_closed', 'queue_full', 'browser_unavailable',
 ]);
 export const ToolErrorSchema = z.strictObject({
     code: ToolErrorCodeSchema,

package/dist/domain/models.d.ts

@@ -176,6 +176,7 @@ export declare const OrderSchema: z.ZodObject<{
         status: z.ZodLiteral<"unavailable">;
         error: z.ZodObject<{
             code: z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -317,6 +318,7 @@ export declare const ProductDetailsSchema: z.ZodObject<{
         status: z.ZodLiteral<"unavailable">;
         error: z.ZodObject<{
             code: z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";

package/dist/domain/outcomes.d.ts

@@ -42,6 +42,7 @@ export declare const CartMutationResultSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     outcome: z.ZodLiteral<"not_applied">;
     error: z.ZodObject<{
         code: z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";
@@ -80,6 +81,7 @@ export declare const CartMutationResultSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     outcome: z.ZodLiteral<"unknown">;
     error: z.ZodObject<{
         code: z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";
@@ -119,6 +121,7 @@ export declare function pageResultSchema<T extends z.ZodType>(item: T): z.ZodObj
     }>;
     failures: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { createApplication } from './application.js';
 export type { ApplicationOptions } from './application.js';
 export { ContinenteMcpServer } from './mcp/server.js';
-export type { McpServerOptions, ToolHandler } from './mcp/server.js';
+export type { McpServerOptions, PromptHandler, ToolHandler } from './mcp/server.js';
+export { BASKET_PLANNER_GUIDE, SERVER_INSTRUCTIONS, basketPlannerPrompt } from './mcp/guide.js';
 export * from './domain/index.js';
 export { createShoppingApplication, createShoppingServices } from './runtime.js';
 export type { RuntimeOptions } from './runtime.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createApplication } from './application.js';
 export { ContinenteMcpServer } from './mcp/server.js';
+export { BASKET_PLANNER_GUIDE, SERVER_INSTRUCTIONS, basketPlannerPrompt } from './mcp/guide.js';
 export * from './domain/index.js';
 export { createShoppingApplication, createShoppingServices } from './runtime.js';

package/dist/mcp/contracts.d.ts

@@ -44,6 +44,7 @@ export declare const PublicErrorSchema: z.ZodObject<{
         code: z.ZodString;
     }, z.core.$strict>>>;
     code: z.ZodUnion<readonly [z.ZodEnum<{
+        browser_unavailable: "browser_unavailable";
         cache_unavailable: "cache_unavailable";
         cancelled: "cancelled";
         cart_change_rejected: "cart_change_rejected";
@@ -74,6 +75,7 @@ export declare const ErrorResultSchema: z.ZodObject<{
             code: z.ZodString;
         }, z.core.$strict>>>;
         code: z.ZodUnion<readonly [z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";
@@ -115,6 +117,7 @@ export declare const ExecutionErrorSchema: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -164,6 +167,7 @@ export declare function outputSchema<T extends z.ZodType>(data: T, extra?: z.Zod
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -220,6 +224,7 @@ export declare const SearchData: z.ZodObject<{
     }>;
     failures: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";
@@ -314,6 +319,7 @@ export declare const OrdersData: z.ZodObject<{
             status: z.ZodLiteral<"unavailable">;
             error: z.ZodObject<{
                 code: z.ZodEnum<{
+                    browser_unavailable: "browser_unavailable";
                     cache_unavailable: "cache_unavailable";
                     cancelled: "cancelled";
                     cart_change_rejected: "cart_change_rejected";
@@ -348,6 +354,7 @@ export declare const OrdersData: z.ZodObject<{
     }>;
     failures: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<{
+            browser_unavailable: "browser_unavailable";
             cache_unavailable: "cache_unavailable";
             cancelled: "cancelled";
             cart_change_rejected: "cart_change_rejected";
@@ -384,6 +391,7 @@ export declare const OrdersData: z.ZodObject<{
         orderNumber: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "OrderNumber", "out">>;
         error: z.ZodObject<{
             code: z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -445,6 +453,7 @@ export declare const FrequencyData: z.ZodObject<{
         orderNumber: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "OrderNumber", "out">>;
         error: z.ZodObject<{
             code: z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -508,6 +517,7 @@ export declare const SearchOutput: z.ZodObject<{
             }>;
             failures: z.ZodArray<z.ZodObject<{
                 code: z.ZodEnum<{
+                    browser_unavailable: "browser_unavailable";
                     cache_unavailable: "cache_unavailable";
                     cancelled: "cancelled";
                     cart_change_rejected: "cart_change_rejected";
@@ -543,6 +553,7 @@ export declare const SearchOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -621,6 +632,7 @@ export declare const FavoritesOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -715,6 +727,7 @@ export declare const CartOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -792,6 +805,7 @@ export declare const MutationOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -869,6 +883,7 @@ export declare const OrdersOutput: z.ZodObject<{
                     status: z.ZodLiteral<"unavailable">;
                     error: z.ZodObject<{
                         code: z.ZodEnum<{
+                            browser_unavailable: "browser_unavailable";
                             cache_unavailable: "cache_unavailable";
                             cancelled: "cancelled";
                             cart_change_rejected: "cart_change_rejected";
@@ -903,6 +918,7 @@ export declare const OrdersOutput: z.ZodObject<{
             }>;
             failures: z.ZodArray<z.ZodObject<{
                 code: z.ZodEnum<{
+                    browser_unavailable: "browser_unavailable";
                     cache_unavailable: "cache_unavailable";
                     cancelled: "cancelled";
                     cart_change_rejected: "cart_change_rejected";
@@ -939,6 +955,7 @@ export declare const OrdersOutput: z.ZodObject<{
                 orderNumber: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "OrderNumber", "out">>;
                 error: z.ZodObject<{
                     code: z.ZodEnum<{
+                        browser_unavailable: "browser_unavailable";
                         cache_unavailable: "cache_unavailable";
                         cancelled: "cancelled";
                         cart_change_rejected: "cart_change_rejected";
@@ -974,6 +991,7 @@ export declare const OrdersOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -1051,6 +1069,7 @@ export declare const SingleOrderOutput: z.ZodObject<{
                     status: z.ZodLiteral<"unavailable">;
                     error: z.ZodObject<{
                         code: z.ZodEnum<{
+                            browser_unavailable: "browser_unavailable";
                             cache_unavailable: "cache_unavailable";
                             cancelled: "cancelled";
                             cart_change_rejected: "cart_change_rejected";
@@ -1090,6 +1109,7 @@ export declare const SingleOrderOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -1164,6 +1184,7 @@ export declare const FrequencyOutput: z.ZodObject<{
                 orderNumber: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "OrderNumber", "out">>;
                 error: z.ZodObject<{
                     code: z.ZodEnum<{
+                        browser_unavailable: "browser_unavailable";
                         cache_unavailable: "cache_unavailable";
                         cancelled: "cancelled";
                         cart_change_rejected: "cart_change_rejected";
@@ -1205,6 +1226,7 @@ export declare const FrequencyOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -1290,6 +1312,7 @@ export declare const SessionStatusOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";
@@ -1406,6 +1429,7 @@ export declare const ProductDetailsOutput: z.ZodObject<{
                 status: z.ZodLiteral<"unavailable">;
                 error: z.ZodObject<{
                     code: z.ZodEnum<{
+                        browser_unavailable: "browser_unavailable";
                         cache_unavailable: "cache_unavailable";
                         cancelled: "cancelled";
                         cart_change_rejected: "cart_change_rejected";
@@ -1441,6 +1465,7 @@ export declare const ProductDetailsOutput: z.ZodObject<{
                 code: z.ZodString;
             }, z.core.$strict>>>;
             code: z.ZodUnion<readonly [z.ZodEnum<{
+                browser_unavailable: "browser_unavailable";
                 cache_unavailable: "cache_unavailable";
                 cancelled: "cancelled";
                 cart_change_rejected: "cart_change_rejected";

package/dist/mcp/guide.d.ts

@@ -0,0 +1,5 @@
+import type { PromptHandler } from './server.js';
+export declare const BASKET_PLANNER_GUIDE = "# Basket planner\n\nTurn the user's shopping intent into a product list or a verified basket using the **continentept-mcp** tools. A request for a plan authorizes research only; a request to add, remove or set items authorizes those basket changes. Keep the user's existing choices and constraints. Ask only about choices that change the result, such as an unspecified substitute or whether a quantity means \"more\" or \"in total\".\n\n## Choose products and quantities\n\n1. Use `search_products` with `query` (and `limit` when useful). Treat results as candidates: match size, brand, dietary constraints and intended use before choosing. Keep `productId` as a string, including leading zeros.\n2. Use `get_product` when price, availability or sale rules matter. Quantities are in the returned sale unit. Respect minimum, maximum and step; never assume a weighted product is sold by the kilogram and never silently round a requested amount.\n3. Before changing the basket, read `get_cart` for current quantities and line identities. If several lines share a product ID, use the intended line's `cartItemId`, or ask the user which line they mean.\n4. Show unresolved choices. Missing prices, availability, quantities or sale rules stay unknown. Money is EUR in integer `minorUnits` (129 means \u20AC1.29). Keep product prices, basket totals and estimated list costs distinct.\n\nSearches read a bounded number of result pages; respect `completeness` and `failures` and do not claim a search was exhaustive.\n\n## Change the basket\n\n- `set_cart_item_quantity({ productId, quantity, cartItemId? })` makes the basket hold exactly `quantity`, adding the product if needed. Zero removes it. Prefer this whenever the user states a desired total; repeating it is safe.\n- `add_cart_item({ productId, quantity, cartItemId? })` adds `quantity` on top of what is already there (default one sale unit). Use it only for \"add more\".\n- `remove_cart_item({ productId, cartItemId? })` removes a line. An already absent item is confirmed without a write.\n\nIf the basket holds two units, \"add two more\" is `add_cart_item` with 2, while \"I need two\" is `set_cart_item_quantity` with 2 (which changes nothing). Process a list one item at a time and read each result before continuing. There is no batch, checkout or payment tool; checkout happens on the website.\n\n## Read outcomes before reporting success\n\nRead `structuredContent.result` rather than inferring success from prose.\n\n- `status: success`, `empty` or `partial` carries `data`. Report partial-result warnings and unavailable data.\n- A confirmed change has `data.outcome: \"confirmed\"` and `confirmedQuantity`, the quantity now in the basket. Report that observed quantity.\n- `status: error` carries `error`. For basket changes also read `mutation`: `not_applied` means nothing was submitted or the change was rejected; fix the reported cause before trying again.\n- `mutation.outcome: \"unknown\"` means the change may have happened. Stop dependent basket changes, call `get_cart`, and compare with the state before the change. Never repeat the original request just because the response was lost. If the basket state cannot settle the intent, explain the uncertainty and ask the user.\n\nA timeout, cancellation or lost connection during a change is not evidence that the basket stayed the same. Apply the same reconciliation when no structured result arrives.\n\n## Use account context when it helps\n\nFor \"my usual items\", `list_favorites` and `list_frequently_bought_products` can inform a proposed list. Past purchases are evidence, not permission to buy them again.\n\n`list_favorites` returns a local snapshot with `source` and `freshness`; pass `refresh: true` when the user wants the current website list or the snapshot is stale. An empty list is a valid result, and a failed refresh does not mean favorites disappeared.\n\n`list_orders` supports `limit`, `includeLines`, `detailLimit` and `cursor` (the returned `nextCursor`). Use the internal `orderId` with `get_order`, not the displayed order number. `list_frequently_bought_products` has separate `orderLimit` and `limit`; its scan counts and failures show how representative the ranking is. Never add quantities expressed in different units.\n\n`get_session_status` reports local state only; it does not verify that the login still works. Do not include credentials or account details in summaries.\n\nFinish with the chosen or changed items, confirmed quantities and units, and any unresolved choices or failures. Keep planned items separate from changes the server confirmed.\n\nFor exact schemas and limits, see the [tool reference](https://github.com/andredelgado/continente-mcp/blob/main/docs/tools.md).";
+/** Sent to every client on connect; the essential rules for working with the cart safely. */
+export declare const SERVER_INSTRUCTIONS = "Continente MCP shops at Continente.pt for one account. Checkout and payment always happen on the website.\n\n- Quantities are in the product's sale unit. Call get_product before choosing a quantity for weighted or bulk products, and respect its minimum, maximum and step.\n- set_cart_item_quantity sets an exact total (adding the product if needed; 0 removes it). add_cart_item adds on top of what is already there. When the user says how many they need, use set_cart_item_quantity.\n- Change the cart one item at a time and read structuredContent.result before reporting success. confirmedQuantity is what the cart now holds.\n- If a cart change returns mutation.outcome \"unknown\", the cart may have changed. Call get_cart and decide from its contents. Never repeat the change automatically.\n- Money is EUR in integer minorUnits (129 means \u20AC1.29). Missing prices, quantities or completeness stay unknown; do not guess them.\n- For planning a shopping list or basket, use the basket-planner prompt for the full workflow.";
+export declare const basketPlannerPrompt: PromptHandler;

package/dist/mcp/guide.js

@@ -0,0 +1,67 @@
+// The basket-planner guide, served as the `basket-planner` prompt. Keep it identical to the body of
+// skills/basket-planner/SKILL.md; a test fails when they differ.
+export const BASKET_PLANNER_GUIDE = `# Basket planner
+
+Turn the user's shopping intent into a product list or a verified basket using the **continentept-mcp** tools. A request for a plan authorizes research only; a request to add, remove or set items authorizes those basket changes. Keep the user's existing choices and constraints. Ask only about choices that change the result, such as an unspecified substitute or whether a quantity means "more" or "in total".
+
+## Choose products and quantities
+
+1. Use \`search_products\` with \`query\` (and \`limit\` when useful). Treat results as candidates: match size, brand, dietary constraints and intended use before choosing. Keep \`productId\` as a string, including leading zeros.
+2. Use \`get_product\` when price, availability or sale rules matter. Quantities are in the returned sale unit. Respect minimum, maximum and step; never assume a weighted product is sold by the kilogram and never silently round a requested amount.
+3. Before changing the basket, read \`get_cart\` for current quantities and line identities. If several lines share a product ID, use the intended line's \`cartItemId\`, or ask the user which line they mean.
+4. Show unresolved choices. Missing prices, availability, quantities or sale rules stay unknown. Money is EUR in integer \`minorUnits\` (129 means €1.29). Keep product prices, basket totals and estimated list costs distinct.
+
+Searches read a bounded number of result pages; respect \`completeness\` and \`failures\` and do not claim a search was exhaustive.
+
+## Change the basket
+
+- \`set_cart_item_quantity({ productId, quantity, cartItemId? })\` makes the basket hold exactly \`quantity\`, adding the product if needed. Zero removes it. Prefer this whenever the user states a desired total; repeating it is safe.
+- \`add_cart_item({ productId, quantity, cartItemId? })\` adds \`quantity\` on top of what is already there (default one sale unit). Use it only for "add more".
+- \`remove_cart_item({ productId, cartItemId? })\` removes a line. An already absent item is confirmed without a write.
+
+If the basket holds two units, "add two more" is \`add_cart_item\` with 2, while "I need two" is \`set_cart_item_quantity\` with 2 (which changes nothing). Process a list one item at a time and read each result before continuing. There is no batch, checkout or payment tool; checkout happens on the website.
+
+## Read outcomes before reporting success
+
+Read \`structuredContent.result\` rather than inferring success from prose.
+
+- \`status: success\`, \`empty\` or \`partial\` carries \`data\`. Report partial-result warnings and unavailable data.
+- A confirmed change has \`data.outcome: "confirmed"\` and \`confirmedQuantity\`, the quantity now in the basket. Report that observed quantity.
+- \`status: error\` carries \`error\`. For basket changes also read \`mutation\`: \`not_applied\` means nothing was submitted or the change was rejected; fix the reported cause before trying again.
+- \`mutation.outcome: "unknown"\` means the change may have happened. Stop dependent basket changes, call \`get_cart\`, and compare with the state before the change. Never repeat the original request just because the response was lost. If the basket state cannot settle the intent, explain the uncertainty and ask the user.
+
+A timeout, cancellation or lost connection during a change is not evidence that the basket stayed the same. Apply the same reconciliation when no structured result arrives.
+
+## Use account context when it helps
+
+For "my usual items", \`list_favorites\` and \`list_frequently_bought_products\` can inform a proposed list. Past purchases are evidence, not permission to buy them again.
+
+\`list_favorites\` returns a local snapshot with \`source\` and \`freshness\`; pass \`refresh: true\` when the user wants the current website list or the snapshot is stale. An empty list is a valid result, and a failed refresh does not mean favorites disappeared.
+
+\`list_orders\` supports \`limit\`, \`includeLines\`, \`detailLimit\` and \`cursor\` (the returned \`nextCursor\`). Use the internal \`orderId\` with \`get_order\`, not the displayed order number. \`list_frequently_bought_products\` has separate \`orderLimit\` and \`limit\`; its scan counts and failures show how representative the ranking is. Never add quantities expressed in different units.
+
+\`get_session_status\` reports local state only; it does not verify that the login still works. Do not include credentials or account details in summaries.
+
+Finish with the chosen or changed items, confirmed quantities and units, and any unresolved choices or failures. Keep planned items separate from changes the server confirmed.
+
+For exact schemas and limits, see the [tool reference](https://github.com/andredelgado/continente-mcp/blob/main/docs/tools.md).`;
+/** Sent to every client on connect; the essential rules for working with the cart safely. */
+export const SERVER_INSTRUCTIONS = `Continente MCP shops at Continente.pt for one account. Checkout and payment always happen on the website.
+
+- Quantities are in the product's sale unit. Call get_product before choosing a quantity for weighted or bulk products, and respect its minimum, maximum and step.
+- set_cart_item_quantity sets an exact total (adding the product if needed; 0 removes it). add_cart_item adds on top of what is already there. When the user says how many they need, use set_cart_item_quantity.
+- Change the cart one item at a time and read structuredContent.result before reporting success. confirmedQuantity is what the cart now holds.
+- If a cart change returns mutation.outcome "unknown", the cart may have changed. Call get_cart and decide from its contents. Never repeat the change automatically.
+- Money is EUR in integer minorUnits (129 means €1.29). Missing prices, quantities or completeness stay unknown; do not guess them.
+- For planning a shopping list or basket, use the basket-planner prompt for the full workflow.`;
+export const basketPlannerPrompt = {
+    name: 'basket-planner',
+    title: 'Plan a Continente basket',
+    description: 'Workflow for choosing products, checking sale quantities and changing the cart safely.',
+    arguments: { request: 'What to plan or buy, for example "weekly basket for two" or "add milk and eggs".' },
+    render: ({ request }) => ({
+        description: 'Continente basket planning workflow',
+        messages: [{ role: 'user', content: { type: 'text',
+                    text: request?.trim() ? `${BASKET_PLANNER_GUIDE}\n\n## Request\n\n${request.trim()}` : BASKET_PLANNER_GUIDE } }],
+    }),
+};

package/dist/mcp/server.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult, GetPromptResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { z } from 'zod';
 import type { RequestOptions } from '../session/request.js';
@@ -14,9 +14,20 @@ export interface ToolHandler {
     readonly cartMutation?: boolean;
     execute(input: unknown): Promise<CallToolResult>;
 }
+/** A prompt template. Every argument is an optional string, as MCP prompt arguments are strings. */
+export interface PromptHandler {
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly arguments?: Readonly<Record<string, string>>;
+    render(args: Readonly<Record<string, string | undefined>>): GetPromptResult;
+}
 export interface McpServerOptions {
     readonly version: string;
     readonly tools: readonly ToolHandler[];
+    readonly prompts?: readonly PromptHandler[];
+    /** Usage guidance sent to clients when they connect. */
+    readonly instructions?: string;
     readonly closeResources?: () => Promise<void>;
     readonly requestTimeoutMs?: number;
 }
@@ -27,6 +38,7 @@ export declare class ContinenteMcpServer {
     private cleanup;
     private readonly shutdown;
     constructor(options: McpServerOptions);
+    private registerPrompts;
     private registerTools;
     dispatchToolCall(name: string, input?: unknown, options?: RequestOptions): Promise<CallToolResult>;
     private execute;

package/dist/mcp/server.js

@@ -11,7 +11,7 @@ export class ContinenteMcpServer {
     shutdown = new AbortController();
     constructor(options) {
         this.options = options;
-        this.server = new McpServer({ name: 'continentept-mcp', version: options.version }, { capabilities: { tools: {} } });
+        this.server = new McpServer({ name: 'continentept-mcp', version: options.version }, { capabilities: { tools: {} }, ...(options.instructions ? { instructions: options.instructions } : {}) });
         for (const handler of options.tools) {
             if (this.handlers.has(handler.definition.name))
                 throw new Error(`Duplicate tool: ${handler.definition.name}`);
@@ -19,6 +19,15 @@ export class ContinenteMcpServer {
         }
         this.server.server.onclose = () => { this.shutdown.abort(new RequestStopped('server_closed')); void this.closeResources().catch(() => { }); };
         this.registerTools();
+        this.registerPrompts();
+    }
+    registerPrompts() {
+        for (const prompt of this.options.prompts ?? []) {
+            const argsSchema = Object.fromEntries(Object.entries(prompt.arguments ?? {})
+                .map(([name, description]) => [name, z.string().optional().describe(description)]));
+            this.server.registerPrompt(prompt.name, { ...(prompt.title ? { title: prompt.title } : {}),
+                ...(prompt.description ? { description: prompt.description } : {}), argsSchema }, args => prompt.render(args));
+        }
     }
     registerTools() {
         if (!this.handlers.size)

package/dist/parsers/cart.d.ts

@@ -21,7 +21,7 @@ export declare function parseProductForm(input: unknown, expectedId: ProductId):
     csrf: string;
     sale: SaleMetadata;
 }, {
-    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
     message: string;
     retryable: boolean;
     issues?: {
@@ -37,7 +37,7 @@ export declare function parseCartControls(html: string, productId: ProductId, ca
     measureOptions: string;
     gtmIndex: string;
 }, {
-    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
     message: string;
     retryable: boolean;
     issues?: {

package/dist/parsers/catalog.d.ts

@@ -5,7 +5,7 @@ export declare function productReferenceFromUrl(href: string): Result<{
     productId: string & import("zod").$brand<"ProductId">;
     productSlug: (string & import("zod").$brand<"ProductSlug">) | null;
 }, {
-    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
     message: string;
     retryable: boolean;
     issues?: {

package/dist/runtime.d.ts

@@ -4,6 +4,7 @@ import type { CookieStore } from './stores/files.js';
 import type { BrowserLauncher, StorefrontSession } from './session/browser.js';
 import type { ShoppingServices } from './mcp/shopping.js';
 export declare const systemClock: Clock;
+/** Launch Playwright's Chromium, downloading it first if this machine does not have it yet. */
 export declare const launchBrowser: BrowserLauncher;
 export interface RuntimeOptions {
     env?: Environment;

package/dist/runtime.js

@@ -2,14 +2,24 @@ import { createApplication } from './application.js';
 import { favoritesScope, loadSettings } from './config.js';
 import { FileCookieStore, FileFavoritesStore } from './stores/files.js';
 import { BrowserSession } from './session/browser.js';
+import { ChromiumInstaller, runChromiumInstall } from './session/chromium.js';
 import { AuthenticationClient } from './clients/authentication.js';
 import { StorefrontClient, CatalogClient, FavoritesClient, CartClient, OrdersClient } from './clients/storefront.js';
 import { CatalogService, FavoritesService } from './services/catalog.js';
 import { CartService } from './services/cart.js';
 import { OrderService, PurchaseHistoryService } from './services/orders.js';
 import { registerShoppingTools } from './mcp/shopping.js';
+import { SERVER_INSTRUCTIONS, basketPlannerPrompt } from './mcp/guide.js';
 export const systemClock = { now: () => new Date() };
-export const launchBrowser = async (options) => (await import('playwright')).chromium.launch(options);
+const chromiumInstaller = new ChromiumInstaller(async () => {
+    // Skip per-percent progress lines; keep the start, finish and any errors.
+    const code = await runChromiumInstall([], line => { if (!line.includes('%'))
+        console.error(`[chromium] ${line}`); });
+    if (code !== 0)
+        throw new Error(`Chromium download exited with code ${code}`);
+}, message => console.error(message));
+/** Launch Playwright's Chromium, downloading it first if this machine does not have it yet. */
+export const launchBrowser = chromiumInstaller.launcher(async (options) => (await import('playwright')).chromium.launch(options));
 /** Build the shopping services. Nothing is read or launched until this is called. */
 export function createShoppingServices(options = {}) {
     const settings = loadSettings(options.env ?? process.env);
@@ -34,5 +44,6 @@ export function createShoppingServices(options = {}) {
 export function createShoppingApplication(options) {
     const services = options.services ?? createShoppingServices(options);
     return createApplication({ version: options.version, tools: registerShoppingTools(services),
+        prompts: [basketPlannerPrompt], instructions: SERVER_INSTRUCTIONS,
         closeResources: () => services.session.shutdown?.() ?? services.session.run(() => services.session.closeBrowserSession()) });
 }

package/dist/services/catalog.d.ts

@@ -67,7 +67,7 @@ export declare class CatalogService {
         } | {
             status: "unavailable";
             error: {
-                code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+                code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
                 message: string;
                 retryable: boolean;
                 issues?: {
@@ -77,7 +77,7 @@ export declare class CatalogService {
             };
         };
     }, {
-        code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+        code: "browser_unavailable" | "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
         message: string;
         retryable: boolean;
         issues?: {

package/dist/session/chromium.d.ts

@@ -0,0 +1,25 @@
+import type { ToolError } from '../domain/index.js';
+import type { Logger } from '../ports.js';
+import type { BrowserLauncher } from './browser.js';
+/** The browser cannot be used yet; carries the message to show instead of a generic failure. */
+export declare class BrowserUnavailable extends Error {
+    readonly toolError: ToolError;
+    constructor(toolError: ToolError);
+}
+export declare const isMissingBrowserError: (error: unknown) => boolean;
+/** Run Playwright's installer for Chromium. With `onOutput`, its output is captured instead of inherited. */
+export declare function runChromiumInstall(extraArgs?: readonly string[], onOutput?: (line: string) => void): Promise<number>;
+/**
+ * Downloads Chromium the first time a launch finds it missing. Concurrent requests share one
+ * download, and a request that would run past its budget gets a "try again shortly" error.
+ */
+export declare class ChromiumInstaller {
+    private readonly install;
+    private readonly logger;
+    private readonly maxWaitMs;
+    private pending;
+    constructor(install: () => Promise<void>, logger: Logger, maxWaitMs?: number);
+    private start;
+    private waitForInstall;
+    launcher(launch: BrowserLauncher): BrowserLauncher;
+}

package/dist/session/chromium.js

@@ -0,0 +1,74 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { requestTimeout } from './request.js';
+/** The browser cannot be used yet; carries the message to show instead of a generic failure. */
+export class BrowserUnavailable extends Error {
+    toolError;
+    constructor(toolError) {
+        super(toolError.message);
+        this.toolError = toolError;
+        this.name = 'BrowserUnavailable';
+    }
+}
+const unavailable = (message) => new BrowserUnavailable({ code: 'browser_unavailable', message, retryable: true });
+export const isMissingBrowserError = (error) => error instanceof Error && /Executable doesn't exist/i.test(error.message);
+/** Run Playwright's installer for Chromium. With `onOutput`, its output is captured instead of inherited. */
+export function runChromiumInstall(extraArgs = [], onOutput) {
+    const cli = join(dirname(createRequire(import.meta.url).resolve('playwright/package.json')), 'cli.js');
+    const child = spawn(process.execPath, [cli, 'install', 'chromium', ...extraArgs], { stdio: onOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+    if (onOutput) {
+        const forward = (chunk) => chunk.toString().split(/\r?\n|\r/).map(line => line.trim()).filter(Boolean).forEach(onOutput);
+        child.stdout?.on('data', forward);
+        child.stderr?.on('data', forward);
+    }
+    return new Promise(resolve => { child.on('error', () => resolve(1)); child.on('close', code => resolve(code ?? 1)); });
+}
+/**
+ * Downloads Chromium the first time a launch finds it missing. Concurrent requests share one
+ * download, and a request that would run past its budget gets a "try again shortly" error.
+ */
+export class ChromiumInstaller {
+    install;
+    logger;
+    maxWaitMs;
+    pending;
+    constructor(install, logger, maxWaitMs = 25000) {
+        this.install = install;
+        this.logger = logger;
+        this.maxWaitMs = maxWaitMs;
+    }
+    start() {
+        this.pending ??= this.install().then(() => this.logger('Chromium is ready.'), error => { this.pending = undefined; throw error; });
+        return this.pending;
+    }
+    async waitForInstall() {
+        const pending = this.start();
+        // Leave time to launch the browser and do the actual work within the same request.
+        const budget = Math.max(0, requestTimeout(this.maxWaitMs + 10000) - 10000);
+        let timer;
+        const outcome = await Promise.race([pending.then(() => 'ready', () => 'failed'),
+            new Promise(resolve => { timer = setTimeout(() => resolve('waiting'), budget); })]);
+        clearTimeout(timer);
+        if (outcome === 'failed')
+            throw unavailable('Chromium could not be downloaded. Check the internet connection, or run `continentept-mcp install-browser`.');
+        if (outcome === 'waiting')
+            throw unavailable('Chromium is being downloaded for first use (about 150 MB). Try again in a minute.');
+    }
+    launcher(launch) {
+        return async (options) => {
+            if (this.pending)
+                await this.waitForInstall();
+            try {
+                return await launch(options);
+            }
+            catch (error) {
+                if (!isMissingBrowserError(error))
+                    throw error;
+                this.logger('Chromium is not installed; downloading it now. This happens once.');
+                await this.waitForInstall();
+                return launch(options);
+            }
+        };
+    }
+}

package/docs/configuration.md

@@ -1,7 +1,9 @@
 # Configuration
 
 Settings come from environment variables and an optional private credentials file. They are
-read when the server starts.
+read when the server starts. The Claude Desktop extension asks for your email and password
+when you install it and passes them to the server for you; the rest of this page is for
+manual setups.
 
 ## Variables
 
@@ -40,6 +42,49 @@ chmod 600 ~/.continentept-mcp/credentials.env
 
 On Windows, limit the folder's permissions to your user account.
 
+## Using 1Password
+
+With the [1Password CLI](https://developer.1password.com/docs/cli/get-started/), the
+credentials never need to be written to a file. Put secret references in the MCP client
+configuration and start the server through `op run`, which swaps them for the real values:
+
+```json
+{
+  "mcpServers": {
+    "continente": {
+      "command": "op",
+      "args": ["run", "--no-masking", "--", "npx", "-y", "continentept-mcp"],
+      "env": {
+        "CONTINENTE_EMAIL": "op://Personal/Continente/username",
+        "CONTINENTE_PASSWORD": "op://Personal/Continente/password"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```sh
+claude mcp add continente \
+  -e CONTINENTE_EMAIL=op://Personal/Continente/username \
+  -e CONTINENTE_PASSWORD=op://Personal/Continente/password \
+  -- op run --no-masking -- npx -y continentept-mcp
+```
+
+- Replace `Personal/Continente` with your vault and item. In 1Password, right-click a field
+  and choose **Copy Secret Reference** to get the exact reference.
+- Turn on **Settings → Developer → Integrate with 1Password CLI** in the 1Password app so
+  `op` unlocks with Touch ID or your system password. You are asked when the client starts
+  the server.
+- Keep `--no-masking`. Without it, `op run` filters the server's output, which carries the MCP
+  protocol.
+- The same works for the login command:
+  `CONTINENTE_EMAIL=op://… CONTINENTE_PASSWORD=op://… op run -- npx -y continentept-mcp login`.
+
+Only the credentials come from 1Password. The website session the server saves after signing
+in still lives in the data directory, as described below.
+
 ## Sign-in and saved session
 
 Account tools reuse the saved session. When the website reports that it has expired, the

package/docs/tools.md

@@ -1,7 +1,8 @@
 # Tool reference
 
-Continente MCP exposes 11 tools. Every tool has a strict input schema (unknown fields are
-rejected), an output schema, a title and the four MCP behaviour annotations.
+Continente MCP exposes 11 tools, server instructions and one prompt. Every tool has a strict
+input schema (unknown fields are rejected), an output schema, a title and the four MCP
+behaviour annotations.
 
 | Tool | Login | Changes the cart | Inputs |
 | --- | --- | --- | --- |
@@ -194,11 +195,23 @@ credentials, cookies or file paths.
 | `cart_change_rejected` | The website rejected the cart change. |
 | `cart_change_unconfirmed` | The cart change could not be confirmed. |
 | `cache_unavailable` | The local favorites snapshot could not be read or written. |
+| `browser_unavailable` | Chromium is still downloading for first use, or the download failed. Retryable. |
 | `cancelled`, `deadline_exceeded`, `server_closed`, `queue_full` | The request stopped before completing. |
 | `internal_error`, `invalid_result` | Unexpected server failure. Details are not exposed. |
 
 Invalid arguments and unknown tools are JSON-RPC errors (`-32602`), not tool results.
 
+## Instructions and prompt
+
+The server sends **instructions** when a client connects: the quantity, cart-change and
+uncertain-outcome rules described above, in a few lines. Clients such as Claude include them
+in the assistant's context automatically.
+
+It also offers one **prompt**, `basket-planner` ("Plan a Continente basket"). It returns the
+full shopping workflow as a user message. Its optional `request` argument, such as
+`weekly basket for two`, is appended to the workflow. The text is the same as the
+[`basket-planner` skill](../skills/basket-planner/SKILL.md).
+
 ## Limits and lifecycle
 
 - Calls run one at a time. Each call has a 45-second budget, including time spent waiting.

package/docs/troubleshooting.md

@@ -5,7 +5,8 @@ without contacting the website.
 
 | Symptom | What to do |
 | --- | --- |
-| `Executable doesn't exist` or the browser fails to start | Run `npx -y continentept-mcp install-browser`. On Linux, add `--with-deps` to install system libraries. |
+| `browser_unavailable`: Chromium is being downloaded | The first use downloads Chromium (about 150 MB). Wait a minute and try again. |
+| `browser_unavailable`: Chromium could not be downloaded | Check the internet connection, then run `npx -y continentept-mcp install-browser` to see the download output. On Linux, add `--with-deps` to install system libraries. |
 | `not_authenticated` | Check that `get_session_status` reports credentials as configured, then run `continentept-mcp login` to test them. See [configuration](configuration.md). |
 | Sign-in keeps failing | Run `continentept-mcp login --show-browser` to watch the browser and complete any extra verification the website asks for. |
 | Status shows `authentication: unknown` | Nothing has been observed since the server started or since the saved session changed. Any account tool will establish it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continentept-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for Continente.pt: search products, check sale rules, read favorites and orders, and make verified cart changes.",
   "keywords": [
     "mcp",
@@ -62,7 +62,8 @@
     "test": "node build/tools/run-tests.js",
     "test:browser": "npm run build && tsc -p tsconfig.tests.json && node build/tools/run-tests.js --browser",
     "test:package": "npm run build:tools && node build/tools/package-smoke.js",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "build:bundle": "npm run build && node build/tools/build-bundle.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
@@ -71,6 +72,7 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2",
     "@types/node": "^22.18.0",
     "typescript": "^7.0.2"
   }

package/skills/basket-planner/SKILL.md

@@ -47,4 +47,4 @@ For "my usual items", `list_favorites` and `list_frequently_bought_products` can
 
 Finish with the chosen or changed items, confirmed quantities and units, and any unresolved choices or failures. Keep planned items separate from changes the server confirmed.
 
-For exact schemas and limits, see the [tool reference](../../docs/tools.md).
+For exact schemas and limits, see the [tool reference](https://github.com/andredelgado/continente-mcp/blob/main/docs/tools.md).