continentept-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,7 +6,19 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- Server instructions: assistants receive the cart rules (exact totals, one change at a time, check the cart after an uncertain change) as soon as they connect.
+- A `basket-planner` prompt with the full shopping workflow, with an optional request to plan for. No skill install is needed.
+- Documentation for supplying credentials from 1Password with `op run`.
+
+### Changed
+
+- The `basket-planner` skill links to the online tool reference, so it also works when uploaded on its own.
+
+## [0.1.0] - 2026-10-15
 
 ### Added
 
@@ -16,5 +28,6 @@ All notable changes to this project are documented here. The format follows
 - Automatic sign-in from environment variables or a private credentials file, and a `login` command.
 - The `basket-planner` skill for planning a shopping list and updating the basket.
 
-[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/andredelgado/continente-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/andredelgado/continente-mcp/releases/tag/v0.1.0

package/README.md

@@ -23,8 +23,9 @@ on the website.
   of retrying.
 - **Your account**: favorites, order history and a ranking of the products you buy most.
 - **Runs locally** over stdio. Credentials and cookies stay on your machine.
-- **Bundled skill** ([`basket-planner`](skills/basket-planner/SKILL.md)) that teaches an
-  assistant to plan a shopping list and update the basket.
+- **Built-in guidance.** The server tells the assistant the cart rules as soon as it
+  connects, and offers a `basket-planner` prompt with the full shopping workflow. Nothing
+  extra to install; the same guide also ships as a [skill](skills/basket-planner/SKILL.md).
 
 ## Requirements
 
@@ -50,6 +51,9 @@ printf 'CONTINENTE_EMAIL=you@example.com\nCONTINENTE_PASSWORD=your-password\n' >
 chmod 600 ~/.continentept-mcp/credentials.env
 ```
 
+Using 1Password? Skip the file and pass secret references through `op run` instead; see
+[Using 1Password](docs/configuration.md#using-1password).
+
 Optionally check that login works:
 
 ```sh
@@ -108,6 +112,18 @@ In that case the result has `mutation.outcome: "unknown"` and asks the client to
 `get_cart` before doing anything else. The server never retries such a change on its own,
 and clients should not either: repeating an `add_cart_item` could add the item twice.
 
+### Guidance for the assistant
+
+When a client connects, the server sends short instructions with these cart rules, so the
+assistant follows them without any setup. For planning a shopping list, pick the
+**basket-planner** prompt from your client's prompt or attachment menu, optionally with a
+request such as "weekly basket for two".
+
+The same guide is available as a skill in
+[`skills/basket-planner`](skills/basket-planner/SKILL.md). Clients that support skills, such
+as Claude Desktop (Settings → Capabilities → Skills) or Claude Code (`~/.claude/skills/`),
+then apply it automatically whenever you ask about groceries.
+
 ## Command line
 
 ```text

package/dist/application.d.ts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/mcp/guide.d.ts

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

package/dist/mcp/guide.js

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

package/dist/mcp/server.d.ts

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

package/dist/mcp/server.js

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

package/dist/runtime.js

@@ -8,6 +8,7 @@ import { CatalogService, FavoritesService } from './services/catalog.js';
 import { CartService } from './services/cart.js';
 import { OrderService, PurchaseHistoryService } from './services/orders.js';
 import { registerShoppingTools } from './mcp/shopping.js';
+import { SERVER_INSTRUCTIONS, basketPlannerPrompt } from './mcp/guide.js';
 export const systemClock = { now: () => new Date() };
 export const launchBrowser = async (options) => (await import('playwright')).chromium.launch(options);
 /** Build the shopping services. Nothing is read or launched until this is called. */
@@ -34,5 +35,6 @@ export function createShoppingServices(options = {}) {
 export function createShoppingApplication(options) {
     const services = options.services ?? createShoppingServices(options);
     return createApplication({ version: options.version, tools: registerShoppingTools(services),
+        prompts: [basketPlannerPrompt], instructions: SERVER_INSTRUCTIONS,
         closeResources: () => services.session.shutdown?.() ?? services.session.run(() => services.session.closeBrowserSession()) });
 }

package/docs/configuration.md

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

package/docs/tools.md

@@ -1,7 +1,8 @@
 # Tool reference
 
-Continente MCP exposes 11 tools. Every tool has a strict input schema (unknown fields are
-rejected), an output schema, a title and the four MCP behaviour annotations.
+Continente MCP exposes 11 tools, server instructions and one prompt. Every tool has a strict
+input schema (unknown fields are rejected), an output schema, a title and the four MCP
+behaviour annotations.
 
 | Tool | Login | Changes the cart | Inputs |
 | --- | --- | --- | --- |
@@ -199,6 +200,17 @@ credentials, cookies or file paths.
 
 Invalid arguments and unknown tools are JSON-RPC errors (`-32602`), not tool results.
 
+## Instructions and prompt
+
+The server sends **instructions** when a client connects: the quantity, cart-change and
+uncertain-outcome rules described above, in a few lines. Clients such as Claude include them
+in the assistant's context automatically.
+
+It also offers one **prompt**, `basket-planner` ("Plan a Continente basket"). It returns the
+full shopping workflow as a user message. Its optional `request` argument, such as
+`weekly basket for two`, is appended to the workflow. The text is the same as the
+[`basket-planner` skill](../skills/basket-planner/SKILL.md).
+
 ## Limits and lifecycle
 
 - Calls run one at a time. Each call has a 45-second budget, including time spent waiting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continentept-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Continente.pt: search products, check sale rules, read favorites and orders, and make verified cart changes.",
   "keywords": [
     "mcp",

package/skills/basket-planner/SKILL.md

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