continentept-mcp 0.4.0 → 0.6.0

package/dist/mcp/contracts.d.ts

@@ -205,14 +205,45 @@ export declare const SearchData: z.ZodObject<{
         productSlug: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ProductSlug", "out">>;
         name: z.ZodString;
         price: z.ZodNullable<z.ZodObject<{
-            currency: z.ZodLiteral<"EUR">;
-            minorUnits: z.ZodNumber;
+            amount: z.ZodObject<{
+                currency: z.ZodLiteral<"EUR">;
+                minorUnits: z.ZodNumber;
+            }, z.core.$strict>;
+            per: z.ZodEnum<{
+                item: "item";
+                kg: "kg";
+                l: "l";
+                piece: "piece";
+            }>;
         }, z.core.$strict>>;
         url: z.ZodURL;
-        unitPriceText: z.ZodNullable<z.ZodString>;
+        secondaryPrice: z.ZodNullable<z.ZodObject<{
+            amount: z.ZodObject<{
+                currency: z.ZodLiteral<"EUR">;
+                minorUnits: z.ZodNumber;
+            }, z.core.$strict>;
+            per: z.ZodEnum<{
+                item: "item";
+                kg: "kg";
+                l: "l";
+                piece: "piece";
+            }>;
+        }, z.core.$strict>>;
+        packageText: z.ZodNullable<z.ZodString>;
+        recommendedPrice: z.ZodNullable<z.ZodObject<{
+            amount: z.ZodObject<{
+                currency: z.ZodLiteral<"EUR">;
+                minorUnits: z.ZodNumber;
+            }, z.core.$strict>;
+            per: z.ZodEnum<{
+                item: "item";
+                kg: "kg";
+                l: "l";
+                piece: "piece";
+            }>;
+        }, z.core.$strict>>;
         minimumText: z.ZodNullable<z.ZodString>;
         favorite: z.ZodBoolean;
-        similarity: z.ZodNumber;
     }, z.core.$strict>>;
     scanned: z.ZodNumber;
     returned: z.ZodNumber;
@@ -256,8 +287,16 @@ export declare const FavoritesData: z.ZodObject<{
         productSlug: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ProductSlug", "out">>;
         name: z.ZodString;
         price: z.ZodNullable<z.ZodObject<{
-            currency: z.ZodLiteral<"EUR">;
-            minorUnits: z.ZodNumber;
+            amount: z.ZodObject<{
+                currency: z.ZodLiteral<"EUR">;
+                minorUnits: z.ZodNumber;
+            }, z.core.$strict>;
+            per: z.ZodEnum<{
+                item: "item";
+                kg: "kg";
+                l: "l";
+                piece: "piece";
+            }>;
         }, z.core.$strict>>;
         url: z.ZodURL;
     }, z.core.$strict>>;
@@ -498,14 +537,45 @@ export declare const SearchOutput: z.ZodObject<{
                 productSlug: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ProductSlug", "out">>;
                 name: z.ZodString;
                 price: z.ZodNullable<z.ZodObject<{
-                    currency: z.ZodLiteral<"EUR">;
-                    minorUnits: z.ZodNumber;
+                    amount: z.ZodObject<{
+                        currency: z.ZodLiteral<"EUR">;
+                        minorUnits: z.ZodNumber;
+                    }, z.core.$strict>;
+                    per: z.ZodEnum<{
+                        item: "item";
+                        kg: "kg";
+                        l: "l";
+                        piece: "piece";
+                    }>;
                 }, z.core.$strict>>;
                 url: z.ZodURL;
-                unitPriceText: z.ZodNullable<z.ZodString>;
+                secondaryPrice: z.ZodNullable<z.ZodObject<{
+                    amount: z.ZodObject<{
+                        currency: z.ZodLiteral<"EUR">;
+                        minorUnits: z.ZodNumber;
+                    }, z.core.$strict>;
+                    per: z.ZodEnum<{
+                        item: "item";
+                        kg: "kg";
+                        l: "l";
+                        piece: "piece";
+                    }>;
+                }, z.core.$strict>>;
+                packageText: z.ZodNullable<z.ZodString>;
+                recommendedPrice: z.ZodNullable<z.ZodObject<{
+                    amount: z.ZodObject<{
+                        currency: z.ZodLiteral<"EUR">;
+                        minorUnits: z.ZodNumber;
+                    }, z.core.$strict>;
+                    per: z.ZodEnum<{
+                        item: "item";
+                        kg: "kg";
+                        l: "l";
+                        piece: "piece";
+                    }>;
+                }, z.core.$strict>>;
                 minimumText: z.ZodNullable<z.ZodString>;
                 favorite: z.ZodBoolean;
-                similarity: z.ZodNumber;
             }, z.core.$strict>>;
             scanned: z.ZodNumber;
             returned: z.ZodNumber;
@@ -598,8 +668,16 @@ export declare const FavoritesOutput: z.ZodObject<{
                 productSlug: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ProductSlug", "out">>;
                 name: z.ZodString;
                 price: z.ZodNullable<z.ZodObject<{
-                    currency: z.ZodLiteral<"EUR">;
-                    minorUnits: z.ZodNumber;
+                    amount: z.ZodObject<{
+                        currency: z.ZodLiteral<"EUR">;
+                        minorUnits: z.ZodNumber;
+                    }, z.core.$strict>;
+                    per: z.ZodEnum<{
+                        item: "item";
+                        kg: "kg";
+                        l: "l";
+                        piece: "piece";
+                    }>;
                 }, z.core.$strict>>;
                 url: z.ZodURL;
             }, z.core.$strict>>;
@@ -677,6 +755,10 @@ export declare const CartOutput: z.ZodObject<{
                 productId: z.core.$ZodBranded<z.ZodString, "ProductId", "out">;
                 cartItemId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "CartItemId", "out">>;
                 name: z.ZodString;
+                kind: z.ZodEnum<{
+                    bag: "bag";
+                    product: "product";
+                }>;
                 quantity: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     status: z.ZodLiteral<"known">;
                     quantity: z.ZodObject<{
@@ -700,22 +782,49 @@ export declare const CartOutput: z.ZodObject<{
                         unsupported_unit: "unsupported_unit";
                     }>>;
                 }, z.core.$strict>], "status">;
-                price: z.ZodObject<{
-                    amount: z.ZodNullable<z.ZodObject<{
+                price: z.ZodNullable<z.ZodObject<{
+                    amount: z.ZodObject<{
                         currency: z.ZodLiteral<"EUR">;
                         minorUnits: z.ZodNumber;
-                    }, z.core.$strict>>;
-                    basis: z.ZodEnum<{
-                        line: "line";
-                        unit: "unit";
-                        unknown: "unknown";
+                    }, z.core.$strict>;
+                    per: z.ZodEnum<{
+                        item: "item";
+                        kg: "kg";
+                        l: "l";
+                        piece: "piece";
                     }>;
-                }, z.core.$strict>;
-            }, z.core.$strict>>;
-            total: z.ZodNullable<z.ZodObject<{
-                currency: z.ZodLiteral<"EUR">;
-                minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                lineTotal: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
             }, z.core.$strict>>;
+            totals: z.ZodObject<{
+                products: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                bags: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                deposit: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                delivery: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                discounts: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+                grandTotal: z.ZodNullable<z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
         }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         status: z.ZodLiteral<"error">;
@@ -1364,18 +1473,42 @@ export declare const ProductDetailsOutput: z.ZodObject<{
             productSlug: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ProductSlug", "out">>;
             name: z.ZodString;
             url: z.ZodURL;
-            price: z.ZodObject<{
-                amount: z.ZodNullable<z.ZodObject<{
+            price: z.ZodNullable<z.ZodObject<{
+                amount: z.ZodObject<{
                     currency: z.ZodLiteral<"EUR">;
                     minorUnits: z.ZodNumber;
-                }, z.core.$strict>>;
-                basis: z.ZodEnum<{
-                    line: "line";
-                    unit: "unit";
-                    unknown: "unknown";
+                }, z.core.$strict>;
+                per: z.ZodEnum<{
+                    item: "item";
+                    kg: "kg";
+                    l: "l";
+                    piece: "piece";
                 }>;
-            }, z.core.$strict>;
-            unitPriceText: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+            secondaryPrice: z.ZodNullable<z.ZodObject<{
+                amount: z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>;
+                per: z.ZodEnum<{
+                    item: "item";
+                    kg: "kg";
+                    l: "l";
+                    piece: "piece";
+                }>;
+            }, z.core.$strict>>;
+            recommendedPrice: z.ZodNullable<z.ZodObject<{
+                amount: z.ZodObject<{
+                    currency: z.ZodLiteral<"EUR">;
+                    minorUnits: z.ZodNumber;
+                }, z.core.$strict>;
+                per: z.ZodEnum<{
+                    item: "item";
+                    kg: "kg";
+                    l: "l";
+                    piece: "piece";
+                }>;
+            }, z.core.$strict>>;
             availability: z.ZodEnum<{
                 available: "available";
                 unavailable: "unavailable";

package/dist/mcp/contracts.js

@@ -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']),

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).";
+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. The amount to pay is `get_cart`'s `totals.grandTotal`, which includes the bags the website adds.\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

@@ -9,7 +9,7 @@ Turn the user's shopping intent into a product list or a verified basket using t
 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.
+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. The amount to pay is \`get_cart\`'s \`totals.grandTotal\`, which includes the bags the website adds.
 
 Searches read a bounded number of result pages; respect \`completeness\` and \`failures\` and do not claim a search was exhaustive.
 
@@ -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

@@ -13,11 +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;
     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>;

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,25 +21,25 @@ 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 quoted = (price) => price.amount === null ? 'price unavailable'
-    : `${euros(price.amount)}${price.basis === 'unit' ? ' each' : price.basis === 'line' ? ' line total' : ''}`;
+const PER = { item: '', piece: ' per piece', kg: '/kg', l: '/l' };
+const priced = (price) => price === null ? 'price unknown' : `${euros(price.amount)}${PER[price.per]}`;
 const numbered = (lines) => lines.map((line, index) => `${index + 1}. ${line}`).join('\n');
 function response(data, text, status = 'success') {
     return { structuredContent: { result: { status, data } }, content: [{ type: 'text', text }] };
 }
 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.recommendedPrice ? `, PVPR ${priced(product.recommendedPrice)}` : ''}` +
+        `${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 +48,8 @@ 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)})` : ''}` +
+            `${product.recommendedPrice ? `, PVPR ${priced(product.recommendedPrice)}` : ''}`,
         `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');
@@ -74,58 +87,72 @@ export class ShoppingHandlers {
         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());
     }
     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');
-        const list = numbered(cart.items.map(item => `${item.name} — ${observed(item.quantity)} × ${quoted(item.price)}` +
+        const list = numbered(cart.items.map(item => `${item.name}${item.kind === 'bag' ? ' (bag)' : ''} — ${observed(item.quantity)} × ${priced(item.price)}` +
+            `${item.lineTotal ? `, line ${euros(item.lineTotal)}` : ''}` +
             `\n   productId: ${item.productId}${item.cartItemId ? `, cartItemId: ${item.cartItemId}` : ''}`));
-        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}`);
+        const { totals } = cart;
+        const optional = [['Deposit', totals.deposit], ['Delivery', totals.delivery], ['Discounts', totals.discounts]]
+            .filter(([, value]) => value !== null && value.minorUnits > 0).map(([label, value]) => `${label}: ${euros(value)}`);
+        const summary = [`Products: ${totals.products === null ? 'unavailable' : euros(totals.products)}`,
+            ...(totals.bags !== null && totals.bags.minorUnits > 0 ? [`Bags: ${euros(totals.bags)}`] : []), ...optional,
+            `Total to pay: ${totals.grandTotal === null ? 'unavailable' : euros(totals.grandTotal)}`].join('\n');
+        return response(cart, `Cart (${cart.items.length} lines):\n\n${list}\n\n${summary}\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');
@@ -139,7 +166,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)}`));
@@ -151,7 +178,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;
@@ -161,7 +188,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);
@@ -198,13 +225,15 @@ export function registerShoppingTools(services, update = NO_UPDATE_INFO) {
             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; ' +
             'snapshots older than 24 hours are marked stale. Pass refresh: true to fetch the current list from the website.', contracts.FavoritesInput, contracts.FavoritesOutput, READ, args => handlers.listFavorites(args.refresh)),
-        tool('get_cart', 'Get cart', 'Read the shopping cart: each line with productId, cartItemId, quantity and price, plus the total. ' +
+        tool('get_cart', 'Get cart', 'Read the shopping cart: each line with productId, cartItemId, kind (product or bag), quantity, unit price (per item or per kg) ' +
+            'and lineTotal, plus the totals ' +
+            '(products, bags, deposit, delivery, discounts and grandTotal, the amount to pay). ' +
             'Use it to check current quantities before changing them and to verify any uncertain change.', contracts.EmptyInput, contracts.CartOutput, READ, () => handlers.getCart()),
         tool('add_cart_item', 'Add to cart', 'Add an amount of a product to the cart, on top of any quantity already there. quantity is in the product sale unit (default 1). ' +
             `Use set_cart_item_quantity instead when the user wants a specific total. ${UNCERTAIN_WRITE}`, contracts.AddCartItemInput, contracts.MutationOutput, ADD, args => handlers.addCartItem(args.productId, args.quantity, args.cartItemId), true),