continentept-mcp 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,19 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-15
+
+### Added
+
+- Listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.andredelgado/continente-mcp`, with both the npm package and the Claude Desktop extension. Every release updates the listing.
+
+## [0.3.0] - 2026-10-15
+
+### Added
+
+- One-click Claude Desktop extension (`continente-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
@@ -28,6 +41,8 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/andredelgado/continente-mcp/compare/v0.3.0...v0.3.1
+[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

@@ -29,20 +29,29 @@ on the website.
 
 ## 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 [**continente-mcp.mcpb**](https://github.com/andredelgado/continente-mcp/releases/latest/download/continente-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`. The server is also listed
+in the [MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.andredelgado/continente-mcp`, so clients that browse the registry can find it. 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
@@ -60,7 +69,7 @@ Optionally check that login works:
 npx -y continentept-mcp login
 ```
 
-**3. Add the server to your MCP client.**
+**2. Add the server to your MCP client.**
 
 Claude Code:
 
@@ -84,6 +93,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."*
 
@@ -129,7 +142,7 @@ then apply it automatically whenever you ask about groceries.
 ```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/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/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/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,6 +2,7 @@ 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';
@@ -10,7 +11,15 @@ 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);

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
 

package/docs/tools.md

@@ -195,6 +195,7 @@ 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. |
 

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,7 @@
 {
   "name": "continentept-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
+  "mcpName": "io.github.andredelgado/continente-mcp",
   "description": "MCP server for Continente.pt: search products, check sale rules, read favorites and orders, and make verified cart changes.",
   "keywords": [
     "mcp",
@@ -62,7 +63,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 +73,7 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2",
     "@types/node": "^22.18.0",
     "typescript": "^7.0.2"
   }