continentept-mcp 0.3.1 → 0.5.0

package/dist/mcp/contracts.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { MAX_REFERENCE_LENGTH, isProductReference, CartSchema, ProductDetailsSchema, FavoriteProductSchema, OrderSchema, ProductSchema, PurchaseFrequencySchema, ToolErrorSchema, CartMutationResultSchema, CartItemIdSchema, OrderIdSchema, BrowserStatusSchema, FavoritesStatusSchema } from '../domain/index.js';
+import { MAX_REFERENCE_LENGTH, isProductReference, CartSchema, ProductDetailsSchema, FavoriteProductSchema, OrderSchema, ProductSchema, PurchaseFrequencySchema, ToolErrorSchema, CartMutationResultSchema, CartItemIdSchema, OrderIdSchema, BrowserStatusSchema, FavoritesStatusSchema, UpdateStatusSchema } from '../domain/index.js';
 export const ProductReferenceInput = z.string().min(1).max(MAX_REFERENCE_LENGTH).regex(/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*(?:\.html)?$/)
     .refine(isProductReference, 'Expected a numeric productId or a product slug ending in it')
     .describe('productId from another tool, such as "00123". A product slug ending in that ID (for example "leite-00123") also works.');
@@ -42,7 +42,7 @@ export function outputSchema(data, extra = {}) {
         ]), ...extra });
 }
 const integer = z.number().int().nonnegative();
-export const SearchData = z.strictObject({ products: z.array(ProductSchema.safeExtend({ favorite: z.boolean(), similarity: z.number().min(0).max(1) })),
+export const SearchData = z.strictObject({ products: z.array(ProductSchema.safeExtend({ favorite: z.boolean() })),
     scanned: integer, returned: integer, favoritesLoaded: integer, completeness: z.enum(['complete', 'partial', 'unknown']),
     failures: z.array(ToolErrorSchema), nextCursor: z.string().nullable() });
 export const FavoritesData = z.strictObject({ favorites: z.array(FavoriteProductSchema), fetchedAt: z.iso.datetime({ offset: true }), completeness: z.enum(['complete', 'unknown']),
@@ -60,6 +60,6 @@ export const MutationOutput = outputSchema(ConfirmedMutationData);
 export const OrdersOutput = outputSchema(OrdersData);
 export const SingleOrderOutput = outputSchema(z.strictObject({ order: OrderSchema, unknownQuantityLines: integer }));
 export const FrequencyOutput = outputSchema(FrequencyData, { scan: FrequencyData.optional() });
-export const SessionStatusOutput = outputSchema(BrowserStatusSchema.extend({ favorites: FavoritesStatusSchema }));
+export const SessionStatusOutput = outputSchema(BrowserStatusSchema.extend({ favorites: FavoritesStatusSchema, update: UpdateStatusSchema }));
 export const GetProductInput = z.strictObject({ productId: ProductReferenceInput });
 export const ProductDetailsOutput = outputSchema(ProductDetailsSchema);

package/dist/mcp/guide.d.ts

@@ -1,5 +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 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). Each price says what it is for: per item, per piece, per kg or per l. A price per kg or per l is not the price of one pack; check packageText and secondaryPrice before comparing. Missing prices, quantities or completeness stay unknown; do not guess them.\n- If your client supports MCP prompts, the basket-planner prompt has the full workflow for planning a shopping list or basket.";
 export declare const basketPlannerPrompt: PromptHandler;

package/dist/mcp/guide.js

@@ -52,8 +52,8 @@ export const SERVER_INSTRUCTIONS = `Continente MCP shops at Continente.pt for on
 - 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.`;
+- Money is EUR in integer minorUnits (129 means €1.29). Each price says what it is for: per item, per piece, per kg or per l. A price per kg or per l is not the price of one pack; check packageText and secondaryPrice before comparing. Missing prices, quantities or completeness stay unknown; do not guess them.
+- If your client supports MCP prompts, the basket-planner prompt has the full workflow for planning a shopping list or basket.`;
 export const basketPlannerPrompt = {
     name: 'basket-planner',
     title: 'Plan a Continente basket',

package/dist/mcp/shopping.d.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolHandler } from './server.js';
 import type { SessionService } from '../ports.js';
+import type { UpdateStatus } from '../domain/index.js';
 import type { CatalogService, FavoritesService, SearchResult } from '../services/catalog.js';
 import type { CartService } from '../services/cart.js';
 import type { OrderService, PurchaseHistoryService, OrderListOptions } from '../services/orders.js';
@@ -12,10 +13,15 @@ export interface ShoppingServices {
     history: PurchaseHistoryService;
     session: SessionService;
 }
+/** What to do about a sign-in failure, depending on whether credentials are configured at all. */
+export declare function signInHelp(credentialsConfigured: boolean | null): string;
 export declare function formatProductSearchResults(products: SearchResult['page']['items']): string;
 export declare class ShoppingHandlers {
     private readonly services;
-    constructor(services: ShoppingServices);
+    private readonly update;
+    constructor(services: ShoppingServices, update: UpdateStatus);
+    /** An error result; sign-in failures before any cart write get guidance for fixing them. */
+    private failed;
     private recover;
     searchProducts(query: string, limit: number): Promise<CallToolResult>;
     getProduct(reference: string): Promise<CallToolResult>;
@@ -30,4 +36,4 @@ export declare class ShoppingHandlers {
     listFrequentlyBoughtProducts(orderLimit: number, limit: number): Promise<CallToolResult>;
     getSessionStatus(): Promise<CallToolResult>;
 }
-export declare function registerShoppingTools(services: ShoppingServices): ToolHandler[];
+export declare function registerShoppingTools(services: ShoppingServices, update?: UpdateStatus): ToolHandler[];

package/dist/mcp/shopping.js

@@ -1,7 +1,19 @@
 import { failure } from '../domain/index.js';
 import * as contracts from './contracts.js';
 import { withAuthenticationRecovery } from '../services/recovery.js';
-const NOT_LOGGED_IN = 'Sign-in required. Configure CONTINENTE_EMAIL and CONTINENTE_PASSWORD (see the configuration guide) or run `continentept-mcp login`.';
+const CONFIGURATION_GUIDE = 'https://github.com/andredelgado/continente-mcp/blob/main/docs/configuration.md';
+const PUBLIC_TOOLS = 'Searching and product details work without signing in.';
+/** What to do about a sign-in failure, depending on whether credentials are configured at all. */
+export function signInHelp(credentialsConfigured) {
+    if (credentialsConfigured === false) {
+        return 'Sign-in required: no Continente email and password are configured. In the Claude Desktop extension, enter them in the '
+            + `extension's settings; in other setups, set CONTINENTE_EMAIL and CONTINENTE_PASSWORD (see ${CONFIGURATION_GUIDE}). ${PUBLIC_TOOLS}`;
+    }
+    const cause = credentialsConfigured ? 'Continente did not accept the configured email and password, or asked for extra verification'
+        : 'Continente did not accept the sign-in, or no credentials are configured';
+    return `Sign-in failed: ${cause}. Check the credentials, or run \`continentept-mcp login --show-browser\` in a terminal `
+        + `to sign in and complete any verification (see ${CONFIGURATION_GUIDE}). ${PUBLIC_TOOLS}`;
+}
 const CHECKOUT_URL = 'https://www.continente.pt/checkout/carrinho/';
 // Text content mirrors the structured result for clients that only show text to the model,
 // so it always includes the identifiers needed for follow-up calls.
@@ -9,6 +21,8 @@ const euros = (money) => money === null ? 'price unavailable' : `€${(money.min
 const amount = (quantity) => `${Number(quantity.value.toPrecision(12))} ${quantity.unit}`;
 const observed = (quantity) => quantity.status === 'known' ? amount(quantity.quantity)
     : quantity.value === null ? 'quantity unknown' : `${quantity.value} (unit unknown)`;
+const PER = { item: '', piece: ' per piece', kg: '/kg', l: '/l' };
+const priced = (price) => price === null ? 'price unknown' : `${euros(price.amount)}${PER[price.per]}`;
 const quoted = (price) => price.amount === null ? 'price unavailable'
     : `${euros(price.amount)}${price.basis === 'unit' ? ' each' : price.basis === 'line' ? ' line total' : ''}`;
 const numbered = (lines) => lines.map((line, index) => `${index + 1}. ${line}`).join('\n');
@@ -17,17 +31,16 @@ function response(data, text, status = 'success') {
 }
 function errorResult(error, mutation) {
     const unknown = mutation?.outcome === 'unknown';
-    const publicError = { ...error, message: error.code === 'not_authenticated' && !unknown ? NOT_LOGGED_IN : error.message,
-        ...(unknown ? { retryable: false } : {}) };
+    const publicError = { ...error, ...(unknown ? { retryable: false } : {}) };
     const note = unknown ? '\nThe cart may have changed. Call get_cart before making another change; do not repeat this request automatically.'
         : mutation ? '\nThe cart was not changed.' : '';
     return { isError: true, content: [{ type: 'text', text: `Error (${publicError.code}): ${publicError.message}${note}` }],
         structuredContent: { result: { status: 'error', error: publicError, ...(mutation ? { mutation } : {}) } } };
 }
 export function formatProductSearchResults(products) {
-    return numbered(products.map(product => `${product.name}${product.favorite ? ' ⭐ favorite' : ''} — ${euros(product.price)}` +
-        `${product.unitPriceText ? ` (${product.unitPriceText})` : ''}${product.minimumText ? `, minimum ${product.minimumText}` : ''}` +
-        `\n   productId: ${product.productId}`));
+    return numbered(products.map(product => `${product.name}${product.favorite ? ' ⭐ favorite' : ''} — ${priced(product.price)}` +
+        `${product.secondaryPrice ? ` (${priced(product.secondaryPrice)})` : ''}${product.packageText ? `, pack ${product.packageText}` : ''}` +
+        `${product.minimumText ? `, minimum ${product.minimumText}` : ''}\n   productId: ${product.productId}`));
 }
 function formatSaleRules(rules) {
     const bounds = [rules.minimum && `minimum ${amount(rules.minimum)}`, rules.maximum && `maximum ${amount(rules.maximum)}`,
@@ -36,7 +49,7 @@ function formatSaleRules(rules) {
 }
 function formatProduct(product) {
     return [`${product.name}`, `productId: ${product.productId}`,
-        `Price: ${quoted(product.price)}${product.unitPriceText ? ` (${product.unitPriceText})` : ''}`,
+        `Price: ${priced(product.price)}${product.secondaryPrice ? ` (${priced(product.secondaryPrice)})` : ''}`,
         `Availability: ${product.availability}`,
         product.saleRules.status === 'available' ? `Sale rules: ${formatSaleRules(product.saleRules.rules)}`
             : `Sale rules unavailable: ${product.saleRules.error.message}`, `URL: ${product.url}`].join('\n');
@@ -69,8 +82,18 @@ function mutationText(value, operation) {
 }
 export class ShoppingHandlers {
     services;
-    constructor(services) {
+    update;
+    constructor(services, update) {
         this.services = services;
+        this.update = update;
+    }
+    /** An error result; sign-in failures before any cart write get guidance for fixing them. */
+    async failed(error, mutation) {
+        if (error.code !== 'not_authenticated' || mutation?.outcome === 'unknown')
+            return errorResult(error, mutation);
+        const status = await this.services.session.getStatus?.().catch(() => undefined);
+        const configured = status ? status.credentials.hasEmail === true && status.credentials.hasPassword === true : null;
+        return errorResult({ ...error, message: signInHelp(status?.credentials.hasEmail === null ? null : configured) }, mutation);
     }
     recover(operation) {
         return withAuthenticationRecovery(operation, () => this.services.session.refreshAuthentication());
@@ -78,37 +101,37 @@ export class ShoppingHandlers {
     async searchProducts(query, limit) {
         const result = await this.services.catalog.searchProducts(query, limit);
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const { page, scanned, favorites } = result.value;
         const partial = page.completeness === 'partial';
         const text = page.items.length
             ? `${page.items.length} of ${scanned} scanned products for "${query}":\n\n${formatProductSearchResults(page.items)}`
             : `No products found for "${query}".`;
         return response({ products: page.items, scanned, returned: page.items.length, favoritesLoaded: favorites.length, completeness: page.completeness,
-            failures: page.failures, nextCursor: page.nextCursor }, text + (partial ? '\n\nPartial results: some result pages could not be read.' : ''), partial ? 'partial' : page.items.length ? 'success' : 'empty');
+            failures: page.failures, nextCursor: page.nextCursor }, text + (partial ? `\n\nPartial results: ${page.failures.length} problem(s) reading results; see failures.` : ''), partial ? 'partial' : page.items.length ? 'success' : 'empty');
     }
     async getProduct(reference) {
         const result = await this.services.catalog.getProduct(reference);
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const product = result.value;
-        const partial = product.saleRules.status === 'unavailable' || product.price.amount === null || product.availability === 'unknown';
+        const partial = product.saleRules.status === 'unavailable' || product.price === null || product.availability === 'unknown';
         return response(product, formatProduct(product), partial ? 'partial' : 'success');
     }
     async listFavorites(refresh) {
         const result = await this.recover(() => refresh ? this.services.favorites.refreshFavorites() : this.services.favorites.listFavorites());
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const { favorites, source, freshness } = result.value;
         const header = `${favorites.length} favorites (${source === 'website' ? 'fetched from the website' : `cached ${result.value.fetchedAt}`}):`;
-        const list = numbered(favorites.map(item => `${item.name} — ${euros(item.price)}\n   productId: ${item.productId}`));
+        const list = numbered(favorites.map(item => `${item.name} — ${priced(item.price)}\n   productId: ${item.productId}`));
         return response(favoritesData(result.value), (favorites.length ? `${header}\n\n${list}` : 'No favorites saved.') +
             (freshness === 'stale' ? '\n\nThis snapshot is more than 24 hours old. Call list_favorites with refresh: true to update it.' : ''), favorites.length ? 'success' : 'empty');
     }
     async getCart() {
         const result = await this.recover(() => this.services.cart.getCart());
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const cart = result.value;
         if (!cart.items.length)
             return response(cart, 'The cart is empty.', 'empty');
@@ -117,13 +140,13 @@ export class ShoppingHandlers {
         return response(cart, `Cart (${cart.items.length} lines):\n\n${list}\n\nTotal: ${cart.total === null ? 'unavailable' : euros(cart.total)}` +
             `\nCheckout happens on the website: ${CHECKOUT_URL}`);
     }
-    mutation(result, operation) {
+    async mutation(result, operation) {
         if (!result.ok)
-            return errorResult(result.error, { outcome: 'not_applied' });
+            return this.failed(result.error, { outcome: 'not_applied' });
         const value = result.value;
         if (value.outcome === 'confirmed')
             return response(value, mutationText(value, operation));
-        return errorResult(value.error, value.outcome === 'unknown' ? { outcome: 'unknown', recovery: value.recovery } : { outcome: 'not_applied' });
+        return this.failed(value.error, value.outcome === 'unknown' ? { outcome: 'unknown', recovery: value.recovery } : { outcome: 'not_applied' });
     }
     async addCartItem(reference, quantity, cartItemId) {
         return this.mutation(await this.recover(() => this.services.cart.addCartItem(reference, quantity, cartItemId)), 'add');
@@ -137,7 +160,7 @@ export class ShoppingHandlers {
     async listOrders(limit, options) {
         const result = await this.recover(() => this.services.orders.listOrders(limit, options));
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const page = result.value;
         const partial = page.completeness === 'partial';
         const list = numbered(page.items.map(order => `${orderHeading(order)}\n${formatOrderLines(order)}`));
@@ -149,7 +172,7 @@ export class ShoppingHandlers {
     async getOrder(orderId) {
         const result = await this.recover(() => this.services.orders.getOrder(orderId));
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const order = result.value;
         const lines = order.lines.status === 'available' ? order.lines.items : [];
         const unknownQuantityLines = lines.filter(line => line.quantity.status === 'unknown').length;
@@ -159,7 +182,7 @@ export class ShoppingHandlers {
     async listFrequentlyBoughtProducts(orderLimit, limit) {
         const result = await this.recover(() => this.services.history.listFrequentlyBoughtProducts(orderLimit));
         if (!result.ok)
-            return errorResult(result.error);
+            return this.failed(result.error);
         const scan = result.value;
         if (!scan.succeeded && (scan.failed || scan.unscanned)) {
             const unavailable = errorResult(failure('order_details_unavailable', 'No order details could be read. See scan.failures.').error);
@@ -179,23 +202,25 @@ export class ShoppingHandlers {
         const favorites = await this.services.favorites.getCacheStatus();
         const credentials = status.credentials.hasEmail && status.credentials.hasPassword ? 'configured'
             : status.credentials.hasEmail === null ? 'unknown' : 'missing';
-        return response({ ...status, favorites }, `Browser: ${status.browser}. Credentials: ${credentials}. Saved cookies: ${status.savedCookies}. ` +
-            `Last observed login state: ${status.authentication.state}. Favorites snapshot: ${favorites.state}.`);
+        const update = this.update.available ? ` Update available: ${this.update.latestVersion} (running ${this.update.currentVersion}).` : '';
+        return response({ ...status, favorites, update: this.update }, `Browser: ${status.browser}. Credentials: ${credentials}. Saved cookies: ${status.savedCookies}. ` +
+            `Last observed login state: ${status.authentication.state}. Favorites snapshot: ${favorites.state}.${update}`);
     }
 }
 const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const ADD = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
 const UPDATE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
 const UNCERTAIN_WRITE = 'If the result has mutation.outcome "unknown", the cart may have changed: call get_cart before any further change and never repeat the request automatically.';
-export function registerShoppingTools(services) {
-    const handlers = new ShoppingHandlers(services);
+const NO_UPDATE_INFO = { currentVersion: null, latestVersion: null, available: false };
+export function registerShoppingTools(services, update = NO_UPDATE_INFO) {
+    const handlers = new ShoppingHandlers(services, update);
     function tool(name, title, description, inputSchema, outputSchema, annotations, execute, cartMutation = false) {
         return { definition: { name, title, description, annotations }, inputSchema, outputSchema, cartMutation,
             execute: raw => services.session.run(() => execute(raw)) };
     }
     return [
-        tool('search_products', 'Search products', 'Search the Continente.pt catalogue. No login needed. Results show price, unit price and productId; products in your saved favorites rank first. ' +
-            'Reads at most five result pages, so completeness may be "unknown" for broad queries.', contracts.SearchInput, contracts.SearchOutput, READ, args => handlers.searchProducts(args.query, args.limit)),
+        tool('search_products', 'Search products', 'Search the Continente.pt catalogue. No login needed. Results keep the website\'s relevance order, with products from your saved favorites first, and show ' +
+            'each price with what it is for (per item, piece, kg or litre), the pack size and productId. Reads at most five result pages, so completeness may be "unknown" for broad queries.', contracts.SearchInput, contracts.SearchOutput, READ, args => handlers.searchProducts(args.query, args.limit)),
         tool('get_product', 'Get product', 'Get one product by productId: price, availability and sale rules (sale unit, minimum, maximum and step). ' +
             'Check this before choosing a quantity for weighted or bulk products. No login needed.', contracts.GetProductInput, contracts.ProductDetailsOutput, READ, args => handlers.getProduct(args.productId)),
         tool('list_favorites', 'List favorites', 'List the products saved as favorites on the account. Uses a local snapshot that is refreshed automatically when missing; ' +

package/dist/parsers/catalog.d.ts

@@ -13,7 +13,13 @@ export declare function productReferenceFromUrl(href: string): Result<{
         code: string;
     }[] | undefined;
 }>;
-export declare function parseProductSearchPage(html: string): Result<Product[], ToolError>;
+export interface SearchPage {
+    products: Product[];
+    /** One entry per result that was skipped or kept with missing data. */
+    problems: ToolError[];
+}
+/** Parse one results page. A bad card is reported in `problems` instead of failing the page. */
+export declare function parseProductSearchPage(html: string): Result<SearchPage, ToolError>;
 export declare function parseFavoritesPageData(html: string): Result<{
     items: FavoriteProduct[];
     expectedIds: string[];
@@ -23,12 +29,14 @@ export declare function parseFavoritesContinuation(html: string): Result<string
 export declare function parseFavoritesPages(pages: string[]): Result<FavoriteProduct[], ToolError>;
 export declare function uniqueProducts<T extends FavoriteProduct>(products: T[]): T[];
 export interface RankedProduct extends Product {
-    /** The exact product is in the saved favorites. */
+    /** This exact product is in the saved favorites. */
     favorite: boolean;
-    /** Highest word overlap (0–1) between this name and a favorite's name. */
-    similarity: number;
 }
-/** Favorites first, then names most similar to a favorite; otherwise keep the site's order. */
+/**
+ * The website orders results by relevance to the query; keep that order and only move exact
+ * favorites to the front. Name similarity to favorites is not used: shared words such as a
+ * brand name would pull unrelated products above real matches.
+ */
 export declare function rankProductsByFavorites(products: Product[], favorites: FavoriteProduct[]): RankedProduct[];
 export declare function parseSearchPagination(html: string): Result<{
     url: string;

package/dist/parsers/catalog.js

@@ -1,5 +1,5 @@
 import { load } from 'cheerio';
-import { FavoriteProductSchema, ProductSchema, parseMoneyAmount, parseProductReference, parseValue } from '../domain/index.js';
+import { FavoriteProductSchema, ProductSchema, parsePriceTag, parseProductReference, parseValue } from '../domain/index.js';
 import { failure, success } from '../domain/index.js';
 export const STOREFRONT_ORIGIN = 'https://www.continente.pt';
 export function storefrontUrl(value) {
@@ -19,6 +19,7 @@ export function productReferenceFromUrl(href) {
     // Slugs can contain encoded punctuation that tool inputs do not accept; fall back to the numeric ID.
     return parsed.ok ? parsed : parseProductReference(slug?.match(/-(\d+)(?:-master)?$/)?.[1]);
 }
+const PRICE_IN_LABEL = /\d+[,.]\d+\s*€(?:\s*\/\s*[a-z]+)?/gi;
 const SEARCH_EMPTY = '.search-noresults-wrapper, .search-no-results, [data-search-empty]';
 const PRODUCT_LINK = 'a[href*="/produto/"]';
 /** Text after "=" in labels such as "Quant. Mínima = 600 gr (3 un)". */
@@ -26,35 +27,52 @@ function minimumLabel(label) {
     const [caption, ...rest] = label.split('=');
     return /m[ií]nim/i.test(caption ?? '') && rest.length ? text(rest.join('=')) || null : null;
 }
+/** Pack size from labels such as "emb. 940 gr" or "emb. 2 x 52 gr". */
+function packageLabel(label) {
+    return text(/^emb\.\s*(.+)$/i.exec(text(label))?.[1] ?? '') || null;
+}
+/** An unrecognised price is reported, not fatal: the product stays usable with an unknown price. */
+function priceOrNull(label) {
+    const parsed = parsePriceTag(label);
+    return parsed.ok ? { price: parsed.value, recognised: true } : { price: null, recognised: false };
+}
+/** Parse one results page. A bad card is reported in `problems` instead of failing the page. */
 export function parseProductSearchPage(html) {
     const $ = load(html);
     if ($(SEARCH_EMPTY).length)
-        return success([]);
+        return success({ products: [], problems: [] });
     const tiles = $($('.search-results-grid').length ? '.search-results-grid .ct-inner-tile-wrap' : '.ct-inner-tile-wrap').toArray();
     if (!tiles.length)
         return failure('invalid_data', 'The search results page was not recognised');
     const products = [];
-    for (const tile of tiles) {
+    const problems = [];
+    const problem = (message) => problems.push(failure('invalid_data', message).error);
+    tiles.forEach((tile, index) => {
         const card = $(tile);
+        const position = `Search result ${index + 1}`;
         const links = card.find(PRODUCT_LINK).toArray().map(link => ({ href: $(link).attr('href'), label: text($(link).text()) }));
         const href = links[0]?.href;
         const name = links.map(link => link.label).find(Boolean);
-        if (!href || !name)
-            return failure('invalid_data', 'A search result was not recognised');
-        const reference = productReferenceFromUrl(href);
-        if (!reference.ok)
-            return reference;
-        const price = parseMoneyAmount(text(card.find('.pwc-tile--price-primary').first().text()) || null);
-        if (!price.ok)
-            return price;
-        const product = parseValue(ProductSchema, { ...reference.value, name, price: price.value, url: storefrontUrl(href),
-            unitPriceText: text(card.find('.pwc-tile--price-secondary').first().text()) || null,
-            minimumText: minimumLabel(card.find('.pwc-tile--quantity').first().text()) }, 'product');
-        if (!product.ok)
-            return product;
-        products.push(product.value);
-    }
-    return success(uniqueProducts(products));
+        const reference = href ? productReferenceFromUrl(href) : null;
+        if (!href || !name || !reference?.ok) {
+            problem(`${position} was not recognised and was skipped.`);
+            return;
+        }
+        const main = priceOrNull(text(card.find('.pwc-tile--price-primary').first().text()));
+        const secondary = priceOrNull(text(card.find('.pwc-tile--price-secondary').first().text()));
+        if (!main.recognised)
+            problem(`${position} (product ${reference.value.productId}) has a price in an unrecognised format; its price is unknown.`);
+        const quantity = card.find('.pwc-tile--quantity').first().text();
+        const product = parseValue(ProductSchema, { ...reference.value, name, url: storefrontUrl(href), price: main.price,
+            secondaryPrice: secondary.price, packageText: packageLabel(quantity), minimumText: minimumLabel(quantity) }, 'product');
+        if (product.ok)
+            products.push(product.value);
+        else
+            problem(`${position} (product ${reference.value.productId}) was not recognised and was skipped.`);
+    });
+    if (!products.length && problems.length)
+        return failure('invalid_data', 'No search result on the page could be recognised');
+    return success({ products: uniqueProducts(products), problems });
 }
 export function parseFavoritesPageData(html) {
     const $ = load(html);
@@ -82,23 +100,19 @@ export function parseFavoritesPageData(html) {
         const anchor = card.find('a[href*="/produto/"]').filter((_, element) => text($(element).text()).length > 0).first();
         const label = text(anchor.text());
         const href = anchor.attr('href') ?? '';
-        const name = label.replace(/\d+[,.]\d+\s*€/g, '').trim();
+        const name = label.replace(PRICE_IN_LABEL, '').trim();
         if (!name) {
             error = failure('invalid_data', 'A favorite product was not recognised').error;
             return;
         }
         const ref = productReferenceFromUrl(href);
-        const rawPrice = text(card.find('.pwc-tile--price-primary').first().text()) || label.match(/(\d+[,.]\d+\s*€)/)?.[1];
-        const price = parseMoneyAmount(rawPrice);
+        const rawPrice = text(card.find('.pwc-tile--price-primary').first().text()) || label.match(PRICE_IN_LABEL)?.[0] || '';
         if (!ref.ok) {
             error = ref.error;
             return;
         }
-        if (!price.ok) {
-            error = price.error;
-            return;
-        }
-        const result = parseValue(FavoriteProductSchema, { ...ref.value, name, price: price.value, url: storefrontUrl(href) }, 'favorite');
+        // Favorites must be complete, but an unrecognised price only makes that price unknown.
+        const result = parseValue(FavoriteProductSchema, { ...ref.value, name, price: priceOrNull(rawPrice).price, url: storefrontUrl(href) }, 'favorite');
         if (result.ok)
             products.push(result.value);
         else
@@ -151,26 +165,15 @@ export function uniqueProducts(products) {
     return products.filter(product => { if (seen.has(product.productId))
         return false; seen.add(product.productId); return true; });
 }
-const words = (name) => new Set(name.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase()
-    .split(/[^a-z0-9]+/).filter(word => word.length > 1));
-function overlap(a, b) {
-    let shared = 0;
-    for (const word of a)
-        if (b.has(word))
-            shared++;
-    const union = a.size + b.size - shared;
-    return union ? shared / union : 0;
-}
-/** Favorites first, then names most similar to a favorite; otherwise keep the site's order. */
+/**
+ * The website orders results by relevance to the query; keep that order and only move exact
+ * favorites to the front. Name similarity to favorites is not used: shared words such as a
+ * brand name would pull unrelated products above real matches.
+ */
 export function rankProductsByFavorites(products, favorites) {
     const favoriteIds = new Set(favorites.map(product => product.productId));
-    const favoriteNames = favorites.map(product => words(product.name));
-    return products.map((product, position) => {
-        const name = words(product.name);
-        const similarity = Math.round(Math.max(0, ...favoriteNames.map(favorite => overlap(name, favorite))) * 100) / 100;
-        return { product: { ...product, favorite: favoriteIds.has(product.productId), similarity }, position };
-    }).sort((a, b) => Number(b.product.favorite) - Number(a.product.favorite) || b.product.similarity - a.product.similarity || a.position - b.position)
-        .map(entry => entry.product);
+    const ranked = products.map(product => ({ ...product, favorite: favoriteIds.has(product.productId) }));
+    return [...ranked.filter(product => product.favorite), ...ranked.filter(product => !product.favorite)];
 }
 export function parseSearchPagination(html) {
     const actions = load(html)('[data-url*="Search-UpdateGrid"]');

package/dist/parsers/product.js

@@ -1,5 +1,5 @@
 import { load } from 'cheerio';
-import { ProductDetailsSchema, parseMoneyAmount, parseProductReference, parseValue } from '../domain/index.js';
+import { ProductDetailsSchema, parsePriceTag, parseProductReference, parseValue } from '../domain/index.js';
 import { success, failure } from '../domain/index.js';
 import { parseSaleRules } from './cart.js';
 import { productReferenceFromUrl, storefrontUrl } from './catalog.js';
@@ -30,12 +30,14 @@ export function parseProductDetails(html, sourceUrl, expectedId) {
     });
     const offer = products.length === 1 ? record(products[0].offers) : null;
     const availability = typeof offer?.availability === 'string' ? offer.availability.replace(/^http:\/\//, 'https://') : '';
-    const priceText = $('.ct-pdp--prices .pwc-tile--price-primary').first().text().replace(/\s+/g, '').trim();
-    const amount = parseMoneyAmount(priceText);
+    const priceTag = (selector) => {
+        const parsed = parsePriceTag($(`.ct-pdp--prices ${selector}`).first().text());
+        return parsed.ok ? parsed.value : null;
+    };
     const product = {
         ...reference.value, name, url,
-        price: { amount: amount.ok ? amount.value : null, basis: rules.ok && rules.value.rules.saleUnit === 'un' && amount.ok && amount.value ? 'unit' : 'unknown' },
-        unitPriceText: $('.ct-pdp--prices .pwc-tile--price-secondary').first().text().replace(/\s+/g, ' ').trim() || null,
+        price: priceTag('.pwc-tile--price-primary'),
+        secondaryPrice: priceTag('.pwc-tile--price-secondary'),
         availability: availability === 'https://schema.org/InStock' ? 'available' : ['https://schema.org/OutOfStock', 'https://schema.org/Discontinued'].includes(availability) ? 'unavailable' : 'unknown',
         saleRules: rules.ok ? { status: 'available', rules: rules.value.rules } : { status: 'unavailable', error: rules.error },
     };

package/dist/runtime.d.ts

@@ -3,6 +3,7 @@ import type { Clock, Logger, FavoritesStore, CatalogGateway, FavoritesGateway, C
 import type { CookieStore } from './stores/files.js';
 import type { BrowserLauncher, StorefrontSession } from './session/browser.js';
 import type { ShoppingServices } from './mcp/shopping.js';
+import type { UpdateStatus } from './domain/index.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;
@@ -24,4 +25,5 @@ export declare function createShoppingServices(options?: RuntimeOptions): Shoppi
 export declare function createShoppingApplication(options: RuntimeOptions & {
     version: string;
     services?: ShoppingServices;
+    update?: UpdateStatus;
 }): import("./index.js").ContinenteMcpServer;

package/dist/runtime.js

@@ -10,6 +10,7 @@ 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';
+import { updateNotice } from './services/updates.js';
 export const systemClock = { now: () => new Date() };
 const chromiumInstaller = new ChromiumInstaller(async () => {
     // Skip per-percent progress lines; keep the start, finish and any errors.
@@ -43,7 +44,8 @@ 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,
+    const notice = options.update ? updateNotice(options.update) : null;
+    return createApplication({ version: options.version, tools: registerShoppingTools(services, options.update),
+        prompts: [basketPlannerPrompt], instructions: notice ? `${SERVER_INSTRUCTIONS}\n\n${notice}` : SERVER_INSTRUCTIONS,
         closeResources: () => services.session.shutdown?.() ?? services.session.run(() => services.session.closeBrowserSession()) });
 }

package/dist/services/catalog.d.ts

@@ -40,10 +40,16 @@ export declare class CatalogService {
             amount: {
                 currency: "EUR";
                 minorUnits: number;
-            } | null;
-            basis: "line" | "unit" | "unknown";
-        };
-        unitPriceText: string | null;
+            };
+            per: "item" | "kg" | "l" | "piece";
+        } | null;
+        secondaryPrice: {
+            amount: {
+                currency: "EUR";
+                minorUnits: number;
+            };
+            per: "item" | "kg" | "l" | "piece";
+        } | null;
         availability: "available" | "unavailable" | "unknown";
         saleRules: {
             status: "available";

package/dist/services/catalog.js

@@ -68,7 +68,7 @@ export class FavoritesService {
             return products;
         if (scope !== this.scope())
             return failure('cache_unavailable', 'Favorites account/session changed during refresh');
-        const cache = { schemaVersion: 1, accountScope: scope,
+        const cache = { schemaVersion: 2, accountScope: scope,
             fetchedAt: this.clock.now().toISOString(), favorites: products.value, completeness: 'complete' };
         const saved = await requestIO(() => this.store.save(cache));
         return saved.ok ? success(this.snapshot(cache, 'website')) : saved;
@@ -106,7 +106,8 @@ export class CatalogService {
                 failures.push(parsed.error);
                 break;
             }
-            products.push(...parsed.value);
+            products.push(...parsed.value.products);
+            failures.push(...parsed.value.problems);
         }
         const unique = uniqueProducts(products);
         const favorites = cache?.favorites ?? [];

package/dist/services/updates.d.ts

@@ -0,0 +1,21 @@
+import type { UpdateStatus } from '../domain/index.js';
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export declare const RELEASES_URL = "https://github.com/andredelgado/continente-mcp/releases/latest";
+export interface UpdateCheckOptions {
+    readonly currentVersion: string;
+    readonly packageName: string;
+    readonly dataDir: string;
+    readonly enabled?: boolean;
+    readonly now?: () => Date;
+    readonly timeoutMs?: number;
+    readonly fetchLatest?: (packageName: string, signal: AbortSignal) => Promise<string>;
+}
+/** True when `candidate` is a later stable release than `current`. Prereleases never count. */
+export declare function isNewerRelease(candidate: string, current: string): boolean;
+/**
+ * Look up the latest published version at most once a day. Never throws: when offline or
+ * disabled it reports no update, reusing the last known answer when there is one.
+ */
+export declare function checkForUpdate(options: UpdateCheckOptions): Promise<UpdateStatus>;
+/** A line for the assistant's instructions, or null when there is nothing to say. */
+export declare function updateNotice(status: UpdateStatus): string | null;