diff --git a/.agents/skills/marktguru/SKILL.md b/.agents/skills/marktguru/SKILL.md new file mode 100644 index 0000000..ce11287 --- /dev/null +++ b/.agents/skills/marktguru/SKILL.md @@ -0,0 +1,142 @@ +--- +name: marktguru +license: Apache-2.0 +description: Query weekly supermarket offers, flyer discounts, and price comparisons across German supermarkets (ALDI Süd, ALDI Nord, Lidl, EDEKA, REWE, Kaufland, PENNY, Netto, dm, ROSSMANN, etc.) via the Marktguru API and local MCP server. Use when the user asks to check supermarket discounts, find deals in brochures/prospekte, compare grocery prices for a postal code (PLZ), or create shopping lists from current promotions without needing fragile PDF OCR. +--- + +# Marktguru Supermarket Offers & MCP Server + +> Query live promotional flyers and circular offers from German supermarkets and drugstores without brittle PDF scraping or layout OCR. + +This skill is inspired by and expands upon the Home Assistant integration pattern (`thorschtn/ha-marktguru`), leveraging Marktguru's backend API (`api.marktguru.de`) to retrieve structured deal data for any German postal code. + +--- + +## Supported Supermarkets & Retailers + +Marktguru covers **over 450 retail chains** across Germany. The primary supported chains are: + +* **Discounter**: + * **ALDI SÜD** (`127153`) & **ALDI NORD** (`127139`) + * **Lidl** (`126679`) + * **PENNY** (`126765`) + * **Netto Marken-Discount** (`126735`) & **Netto (mit Hund)** (`126734`) + * **NORMA** (`126745`) +* **Supermärkte & Vollsortimenter**: + * **EDEKA** (`127093`) & **E center** (`126699`) + regionale Kaufleute (Simmel, Zurheide, etc.) + * **REWE** (`126802`) & **REWE Center** (`126804`) + * **nahkauf** (`137320`), **HIT** (`126598`), **tegut** (`126866`) +* **Großfläche / Hypermarket**: + * **Kaufland** (`126654`) + * **Globus** (`127177`) +* **Drogerien & Reform**: + * **dm-drogerie markt** (`127057`) + * **ROSSMANN** (`126811`) + * **Müller Drogeriemarkt** (`126720`) + +Full details and ID mappings are documented in [`references/supermarkets.md`](references/supermarkets.md). + +--- + +## Components + +The skill provides two primary components: + +1. **CLI & Python Client (`scripts/marktguru_client.py`)**: Zero external dependencies (uses standard library `urllib` and `json`). +2. **MCP Server (`scripts/marktguru_mcp.py`)**: Standard JSON-RPC 2.0 stdio server providing AI tools for search, comparison, and catalog retrieval. + +--- + +## 1. CLI Usage + +Run directly with standard `python3` (uses default postal code **`93059` Regensburg** if `--zip` is omitted): + +### A. Search for Deals +```bash +# Search for butter in Regensburg (93059 default) across Aldi, Lidl, and Edeka +python3 scripts/marktguru_client.py search "Butter" --supermarket "Aldi,Lidl,Edeka" + +# Search for coffee with raw JSON output +python3 scripts/marktguru_client.py search "Kaffee" --json +``` + +### B. Price Comparison (Sorted Ascending) +```bash +# Compare chocolate prices across all supermarkets in 93059 +python3 scripts/marktguru_client.py compare "Schokolade" + +# Compare beer prices between Lidl and Rewe in another postal code (e.g. 80331) +python3 scripts/marktguru_client.py compare "Bier" --zip 80331 --supermarket "Lidl,Rewe" +``` + +### C. List Supported Chains +```bash +python3 scripts/marktguru_client.py supermarkets +``` + +--- + +## 2. Model Context Protocol (MCP) Integration + +The MCP server exposes three tools to any MCP-compatible AI agent: + +* `search_supermarket_offers(query, zip_code="93059", supermarkets=None, limit=20)` +* `compare_supermarket_prices(query, zip_code="93059", supermarkets=None)` +* `list_supported_supermarkets()` + +### MCP Server Configuration (`mcp_config.json`) + +To enable the server in Antigravity or other MCP hosts: + +```json +{ + "mcpServers": { + "marktguru": { + "command": "python3", + "args": [ + "/Users/moritz/src/infrapuzzle/.agents/skills/marktguru/scripts/marktguru_mcp.py" + ] + } + } +} +``` + +--- + +## 3. Python Integration + +You can import the module directly in Python scripts or agent sidecars: + +```python +import sys +sys.path.append("/Users/moritz/src/infrapuzzle/.agents/skills/marktguru/scripts") +from marktguru_client import search_offers, compare_prices, DEFAULT_ZIP_CODE + +# Search deals (defaults to 93059) +results = search_offers("Kaffee", supermarkets=["Aldi", "Lidl"]) +for offer in results["offers"]: + print(f"[{offer['supermarket']}] {offer['product_name'] or offer['description']}: {offer['price']} €") + +# Compare prices +comparison = compare_prices("Milch") +cheapest = comparison["cheapest_offer"] +print(f"Cheapest milk: {cheapest['price']} € at {cheapest['supermarket']}") +``` + +--- + +## Data Extracted Per Offer + +Each item returned from the Marktguru API includes: +* `id`: Internal Marktguru offer ID. +* `supermarket`: Retailer name (e.g. "ALDI SÜD", "Lidl", "EDEKA"). +* `product_name`: Generic product name (e.g. "Butter", "Filterkaffee"). +* `brand`: Brand name (e.g. "Kerrygold", "Melitta", "Milka"). +* `description`: Promotional description / pack size (e.g. "je 250g Packung"). +* `price`: Promotional sale price in Euros (€). +* `old_price`: Regular price or crossed-out price (UVP). +* `discount_percent`: Calculated percentage savings (e.g. 28%). +* `reference_price`: Unit price (e.g. 5.16 € / kg). +* `loyalty_app_required`: Boolean flag indicating if a digital store app (Lidl Plus, Edeka App, Penny App) is required to receive the discount. +* `valid_from` & `valid_to`: Start and end dates of the promotion. +* `image_url`: High-resolution product image hosted on CDN. diff --git a/.agents/skills/marktguru/references/supermarkets.md b/.agents/skills/marktguru/references/supermarkets.md new file mode 100644 index 0000000..2f8a415 --- /dev/null +++ b/.agents/skills/marktguru/references/supermarkets.md @@ -0,0 +1,94 @@ +# Unterstützte Supermärkte & Händler (Marktguru) + +Über die Marktguru-Schnittstelle können Werbeprospekte, Wochenangebote und Rabattaktionen von über 450 Handelsketten und Einzelhändlern in Deutschland abgefragt werden. + +--- + +## 1. Discounter + +Discounter machen einen Großteil der wöchentlich wechselnden Prospektaktionen aus. Marktguru unterscheidet sauber zwischen den Ketten: + +| Kette | Marktguru ID | Typischer Aktionsrhythmus | App-Vorteile erfasst? | +| :--- | :--- | :--- | :--- | +| **ALDI SÜD** | `127153` | Mo. & Do. / Fr. & Sa. | Ja (ALDI App Angebote) | +| **ALDI NORD** | `127139` | Mo. & Do. / Fr. & Sa. | Ja | +| **Lidl** | `126679` | Mo.–Sa. / Do.–Sa. / Fr.–Sa. | Ja (`loyalty_app_required` für Lidl Plus) | +| **PENNY** | `126765` | Mo.–Sa. / Do.–Sa. | Ja (Penny App / Payback) | +| **Netto Marken-Discount** | `126735` | Mo.–Sa. / Do.–Sa. | Ja (Netto App / DeutschlandCard) | +| **Netto (mit Hund)** | `126734` | Mo.–Sa. (primär Ost-/Norddeutschland) | Ja | +| **NORMA** | `126745` | Mo. & Mi. / Fr. & Sa. | Ja | + +--- + +## 2. Vollsortimenter & Supermärkte + +Hier gibt es oft filialgenaue oder regionale Prospekte. Die API filtert automatisch anhand der übergebenen Postleitzahl (PLZ): + +| Kette | Marktguru ID | Besonderheiten | +| :--- | :--- | :--- | +| **EDEKA** | `127093` | Nationale & regionale Angebote; Marktguru aggregiert auch selbstständige Kaufleute (z.B. EDEKA Simmel, Zurheide, Niemerszein). | +| **E center** | `126699` | Großformatige EDEKA-Märkte mit erweitertem Non-Food- und Frischeangebot. | +| **REWE** | `126802` | Bundesweite Angebote sowie regionale Aktionen. | +| **REWE Center** | `126804` | Großflächenmärkte von REWE. | +| **nahkauf** | `137320` | Nachbarschaftsmärkte der REWE Group. | +| **HIT** | `126598` | Große Frische-Supermärkte (Dohle Handelsgruppe). | +| **tegut** | `126866` | Fokus auf Bio, Nachhaltigkeit und Regionales (Hessen, Bayern, Thüringen). | + +--- + +## 3. Großfläche & SB-Warenhäuser (Hypermarkets) + +| Kette | Marktguru ID | Besonderheiten | +| :--- | :--- | :--- | +| **Kaufland** | `126654` | Riesiges wöchentliches Prospektangebot (Lebensmittel + Non-Food, Kaufland Card). | +| **Globus** | `127177` | SB-Warenhäuser mit eigener Metzgerei und Bäckerei. | + +--- + +## 4. Drogeriemärkte + +Drogerieprospekte enthalten neben Pflege- und Haushaltsartikeln auch viele Bio-Lebensmittel, Snacks, Kaffee und Babynahrung: + +| Kette | Marktguru ID | Typische Angebote | +| :--- | :--- | :--- | +| **dm-drogerie markt** | `127057` | dmBio, Drogeriewaren, Tiernahrung. | +| **ROSSMANN** | `126811` | EnerBio, Kaffeeangebote, wöchentliche 10%-Coupons. | +| **Müller Drogeriemarkt** | `126720` | Drogerie, Parfümerie, Spielwaren, Naturshop. | +| **budni** | `126944` | Primär im Norden (Metropolregion Hamburg). | + +--- + +## 5. Getränkemärkte & Bio-Fachmärkte + +| Kette | Marktguru ID | Sortiment | +| :--- | :--- | :--- | +| **Netto Getränke-Discount** | `134009` | Bier, Mineralwasser, Softdrinks. | +| **Denns BioMarkt / Alnatura** | Diverse | Bio-Vollsortiment, Wochenaktionen. | + +--- + +## 6. Unterstützte Aliase im Client & MCP Server + +Wenn im Tool-Aufruf der Parameter `supermarkets` übergeben wird, werden folgende umgangssprachliche Bezeichnungen automatisch auf die korrekten Retailer-IDs gemappt: + +```json +{ + "aldi": [127153, 127139], // Findet automatisch ALDI SÜD und ALDI NORD + "aldi süd" / "aldi sued": [127153], + "aldi nord": [127139], + "lidl": [126679], + "edeka": [127093, 126699], // EDEKA und E center + "rewe": [126802, 126804], // REWE und REWE Center + "kaufland": [126654], + "penny": [126765], + "netto": [126735, 126734], // Netto Marken-Discount und Netto (mit Hund) + "norma": [126745], + "globus": [127177], + "dm": [127057], + "rossmann": [126811], + "müller" / "mueller": [126720], + "hit": [126598], + "tegut": [126866], + "nahkauf": [137320] +} +``` diff --git a/.agents/skills/marktguru/scripts/__pycache__/marktguru_client.cpython-312.pyc b/.agents/skills/marktguru/scripts/__pycache__/marktguru_client.cpython-312.pyc new file mode 100644 index 0000000..9b3f97c Binary files /dev/null and b/.agents/skills/marktguru/scripts/__pycache__/marktguru_client.cpython-312.pyc differ diff --git a/.agents/skills/marktguru/scripts/__pycache__/marktguru_mcp.cpython-312.pyc b/.agents/skills/marktguru/scripts/__pycache__/marktguru_mcp.cpython-312.pyc new file mode 100644 index 0000000..12e1f25 Binary files /dev/null and b/.agents/skills/marktguru/scripts/__pycache__/marktguru_mcp.cpython-312.pyc differ diff --git a/.agents/skills/marktguru/scripts/marktguru_client.py b/.agents/skills/marktguru/scripts/marktguru_client.py new file mode 100755 index 0000000..135c5c3 --- /dev/null +++ b/.agents/skills/marktguru/scripts/marktguru_client.py @@ -0,0 +1,577 @@ +#!/usr/bin/env python3 +""" +Marktguru API Client (Production Grade) +Fetches promotional offers and discounts from German supermarkets via the Marktguru API. + +Key Design Principles: +- Zero external dependencies (uses standard library only: urllib, json, os, time, datetime). +- Resilient: Retries with exponential backoff on transient errors. +- Low Maintenance: Configurable keys and postal codes via environment variables. +- Fail-Safe: Caching with stale fallback if upstream API is temporarily unreachable. +- Defensive: Robust parsing protecting against upstream schema shifts and malformed payloads. +""" + +import os +import sys +import time +import json +import logging +import hashlib +import tempfile +import urllib.request +import urllib.parse +import urllib.error +from datetime import datetime, timezone +from typing import List, Dict, Any, Optional, Set, Tuple + +# Logger writing to stderr to keep stdout pure for JSON / CLI +logger = logging.getLogger("marktguru_client") +if not logger.handlers: + handler = logging.StreamHandler(sys.stderr) + handler.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")) + logger.addHandler(handler) + logger.setLevel(logging.INFO) + +API_BASE = "https://api.marktguru.de/api/v1" + +# Environment variable overrides for zero-code configuration changes +DEFAULT_ZIP_CODE = os.environ.get("MARKTGURU_ZIP_CODE", "93059") +CLIENT_KEY = os.environ.get("MARKTGURU_CLIENT_KEY", "WU/RH+PMGDi+gkZer3WbMelt6zcYHSTytNB7VpTia90=") +API_KEY = os.environ.get("MARKTGURU_API_KEY", "8Kk+pmbf7TgJ9nVj2cXeA7P5zBGv8iuutVVMRfOfvNE=") +CACHE_TTL = int(os.environ.get("MARKTGURU_CACHE_TTL", "1800")) # 30 minutes +CACHE_ENABLED = os.environ.get("MARKTGURU_CACHE_ENABLED", "true").lower() in ("true", "1", "yes") + +HEADERS = { + "x-clientkey": CLIENT_KEY, + "x-apikey": API_KEY, + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)", + "Accept": "application/json", +} + +# Major supermarket chains and their Marktguru retailer IDs +MAJOR_RETAILERS: Dict[str, Dict[str, Any]] = { + "ALDI SÜD": {"id": 127153, "type": "Discounter", "major": True}, + "ALDI NORD": {"id": 127139, "type": "Discounter", "major": True}, + "Lidl": {"id": 126679, "type": "Discounter", "major": True}, + "EDEKA": {"id": 127093, "type": "Supermarkt", "major": True}, + "E center": {"id": 126699, "type": "Supermarkt", "major": True}, + "REWE": {"id": 126802, "type": "Supermarkt", "major": True}, + "REWE Center": {"id": 126804, "type": "Supermarkt", "major": True}, + "Kaufland": {"id": 126654, "type": "Großfläche/Hypermarkt", "major": True}, + "PENNY": {"id": 126765, "type": "Discounter", "major": True}, + "Netto Marken-Discount": {"id": 126735, "type": "Discounter", "major": True}, + "Netto (mit Hund)": {"id": 126734, "type": "Discounter", "major": False}, + "NORMA": {"id": 126745, "type": "Discounter", "major": True}, + "Globus": {"id": 127177, "type": "Großfläche/Hypermarkt", "major": True}, + "HIT": {"id": 126598, "type": "Supermarkt", "major": False}, + "tegut": {"id": 126866, "type": "Supermarkt", "major": False}, + "nahkauf": {"id": 137320, "type": "Supermarkt", "major": False}, + "dm-drogerie markt": {"id": 127057, "type": "Drogerie", "major": True}, + "ROSSMANN": {"id": 126811, "type": "Drogerie", "major": True}, + "Müller Drogeriemarkt": {"id": 126720, "type": "Drogerie", "major": True}, +} + +# Aliases mapping user query strings to Marktguru retailer IDs +RETAILER_ALIASES: Dict[str, List[int]] = { + "aldi": [127153, 127139], + "aldi süd": [127153], + "aldi sued": [127153], + "aldi nord": [127139], + "lidl": [126679], + "edeka": [127093, 126699], + "e center": [126699], + "ecenter": [126699], + "rewe": [126802, 126804], + "kaufland": [126654], + "penny": [126765], + "netto": [126735, 126734], + "norma": [126745], + "globus": [127177], + "hit": [126598], + "tegut": [126866], + "nahkauf": [137320], + "dm": [127057], + "rossmann": [126811], + "müller": [126720], + "mueller": [126720], +} + + +def _get_cache_dir() -> str: + """Returns directory path for local cached responses.""" + cache_dir = os.path.join(tempfile.gettempdir(), "marktguru_cache") + try: + os.makedirs(cache_dir, exist_ok=True) + except Exception: + pass + return cache_dir + + +def _read_cache(cache_key: str, max_age_seconds: int = CACHE_TTL) -> Tuple[Optional[Dict[str, Any]], bool]: + """ + Reads cache file. Returns (data, is_fresh). + If cache is expired, returns (data, False) so caller can use it as emergency fallback. + """ + if not CACHE_ENABLED: + return None, False + + cache_file = os.path.join(_get_cache_dir(), f"{cache_key}.json") + if not os.path.isfile(cache_file): + return None, False + + try: + with open(cache_file, "r", encoding="utf-8") as f: + payload = json.load(f) + cached_time = payload.get("_cached_at", 0) + age = time.time() - cached_time + data = payload.get("data") + is_fresh = age < max_age_seconds + return data, is_fresh + except Exception as e: + logger.debug(f"Failed to read cache {cache_key}: {e}") + return None, False + + +def _write_cache(cache_key: str, data: Dict[str, Any]) -> None: + """Writes data to cache file atomically.""" + if not CACHE_ENABLED: + return + + cache_file = os.path.join(_get_cache_dir(), f"{cache_key}.json") + temp_file = f"{cache_file}.tmp.{os.getpid()}" + try: + payload = { + "_cached_at": time.time(), + "data": data, + } + with open(temp_file, "w", encoding="utf-8") as f: + json.dump(payload, f, ensure_ascii=False) + os.replace(temp_file, cache_file) + except Exception as e: + logger.debug(f"Failed to write cache {cache_key}: {e}") + if os.path.exists(temp_file): + try: + os.remove(temp_file) + except Exception: + pass + + +def resolve_supermarket_ids(supermarkets: Optional[List[str]]) -> Optional[str]: + """Resolves human supermarket names/aliases to comma-separated Marktguru retailer IDs.""" + if not supermarkets: + return None + + # Handle string passed instead of list (e.g. "Aldi, Lidl") + if isinstance(supermarkets, str): + supermarkets = [s.strip() for s in supermarkets.split(",") if s.strip()] + + resolved_ids: Set[int] = set() + for name in supermarkets: + if not isinstance(name, str): + continue + cleaned = name.strip().lower() + if not cleaned: + continue + + if cleaned in RETAILER_ALIASES: + resolved_ids.update(RETAILER_ALIASES[cleaned]) + elif cleaned.isdigit(): + resolved_ids.add(int(cleaned)) + else: + found = False + for r_name, r_info in MAJOR_RETAILERS.items(): + if cleaned in r_name.lower(): + resolved_ids.add(r_info["id"]) + found = True + if not found: + logger.warning(f"Unknown supermarket name '{name}' skipped.") + + return ",".join(str(i) for i in sorted(resolved_ids)) if resolved_ids else None + + +def format_iso_date(iso_str: Optional[str]) -> str: + """Formats an ISO-8601 date string to human-readable DD.MM.YYYY format.""" + if not iso_str or not isinstance(iso_str, str): + return "-" + try: + dt = datetime.fromisoformat(iso_str.replace("Z", "+00:00")) + return dt.strftime("%d.%m.%Y") + except Exception: + return iso_str[:10] if len(iso_str) >= 10 else iso_str + + +def parse_offer(raw: Any, zip_code: str) -> Optional[Dict[str, Any]]: + """ + Defensively parses and standardizes an offer payload from Marktguru. + Protects against null fields, malformed dates, and missing keys. + """ + if not isinstance(raw, dict): + return None + + try: + offer_id = raw.get("id") + price = raw.get("price") + if isinstance(price, (int, float)): + price = round(float(price), 2) + else: + price = None + + old_price = raw.get("oldPrice") + if isinstance(old_price, (int, float)): + old_price = round(float(old_price), 2) + else: + old_price = None + + ref_price = raw.get("referencePrice") + if isinstance(ref_price, (int, float)): + ref_price = round(float(ref_price), 2) + else: + ref_price = None + + discount_pct = None + if old_price and price and old_price > price: + discount_pct = round(((old_price - price) / old_price) * 100) + + # Validity dates + validity = raw.get("validityDates") + valid_from_raw = None + valid_to_raw = None + is_valid_now = True + days_remaining = None + + if isinstance(validity, list) and len(validity) > 0 and isinstance(validity[0], dict): + valid_from_raw = validity[0].get("from") + valid_to_raw = validity[0].get("to") + + try: + now = datetime.now(timezone.utc) + if valid_to_raw and isinstance(valid_to_raw, str): + dt_to = datetime.fromisoformat(valid_to_raw.replace("Z", "+00:00")) + diff = (dt_to - now).days + days_remaining = max(0, diff) + if dt_to < now: + is_valid_now = False + + if valid_from_raw and isinstance(valid_from_raw, str): + dt_from = datetime.fromisoformat(valid_from_raw.replace("Z", "+00:00")) + if dt_from > now: + is_valid_now = False + except Exception: + pass + + # Supermarket / advertiser extraction + supermarket = "Unbekannt" + supermarket_id = None + advertisers = raw.get("advertisers") + if isinstance(advertisers, list) and len(advertisers) > 0 and isinstance(advertisers[0], dict): + supermarket = advertisers[0].get("name") or "Unbekannt" + supermarket_id = advertisers[0].get("id") + + # High resolution CDN image + image_url = None + if offer_id: + image_url = f"https://mg2de.b-cdn.net/api/v1/offers/{offer_id}/images/default/0/medium.webp" + + # Unit & volume + unit_info = raw.get("unit") + unit_name = None + if isinstance(unit_info, dict): + unit_name = unit_info.get("shortName") or unit_info.get("name") + + product_info = raw.get("product") + product_name = None + if isinstance(product_info, dict): + product_name = product_info.get("name") + + brand_info = raw.get("brand") + brand_name = None + if isinstance(brand_info, dict): + brand_name = brand_info.get("name") + + return { + "id": offer_id, + "supermarket": supermarket, + "supermarket_id": supermarket_id, + "product_name": product_name, + "brand": brand_name, + "description": raw.get("description"), + "price": price, + "old_price": old_price, + "reference_price": ref_price, + "discount_percent": discount_pct, + "unit": unit_name, + "volume": raw.get("volume"), + "loyalty_app_required": bool(raw.get("requiresLoyalityMembership", False)), + "is_valid_now": is_valid_now, + "days_remaining": days_remaining, + "valid_from": format_iso_date(valid_from_raw), + "valid_to": format_iso_date(valid_to_raw), + "image_url": image_url, + "zip_code": str(zip_code), + } + except Exception as e: + logger.debug(f"Error parsing single offer {raw.get('id') if isinstance(raw, dict) else raw}: {e}") + return None + + +def _fetch_with_retry(url: str, max_retries: int = 2) -> Dict[str, Any]: + """ + Executes HTTP request with exponential backoff on transient errors (5xx / network blips). + """ + last_err: Optional[Exception] = None + + for attempt in range(max_retries + 1): + req = urllib.request.Request(url, headers=HEADERS) + try: + with urllib.request.urlopen(req, timeout=10) as resp: + raw_bytes = resp.read() + return json.loads(raw_bytes.decode("utf-8")) + except urllib.error.HTTPError as e: + last_err = e + # Retry only on transient server errors (500, 502, 503, 504) or rate limits (429) + if e.code in (429, 500, 502, 503, 504) and attempt < max_retries: + backoff = 0.5 * (2 ** attempt) + logger.warning(f"Marktguru HTTP {e.code}. Retrying in {backoff:.1f}s (attempt {attempt+1}/{max_retries})...") + time.sleep(backoff) + continue + raise + except (urllib.error.URLError, TimeoutError, OSError) as e: + last_err = e + if attempt < max_retries: + backoff = 0.5 * (2 ** attempt) + logger.warning(f"Connection issue ({e}). Retrying in {backoff:.1f}s...") + time.sleep(backoff) + continue + raise + + raise last_err or RuntimeError("Max retries exceeded") + + +def search_offers( + query: str, + zip_code: str = DEFAULT_ZIP_CODE, + supermarkets: Optional[List[str]] = None, + limit: int = 24, + offset: int = 0, + force_refresh: bool = False, +) -> Dict[str, Any]: + """ + Searches current supermarket offers in Germany via the Marktguru API. + + Args: + query: Search term (e.g. 'Butter', 'Kaffee', 'Bier', 'Milch') + zip_code: German postal code (default: '93059' Regensburg) + supermarkets: List of supermarket names or aliases (e.g. ['Aldi', 'Lidl', 'Edeka']) + limit: Max number of items to return (default: 24, max: 50) + offset: Result pagination offset + force_refresh: If True, bypasses local TTL cache + """ + cleaned_query = (query or "").strip() + cleaned_zip = str(zip_code or DEFAULT_ZIP_CODE).strip() + limit = max(1, min(int(limit), 50)) + offset = max(0, int(offset)) + + retailer_ids = resolve_supermarket_ids(supermarkets) + + # Compute deterministic cache key + cache_raw = f"{cleaned_query.lower()}:{cleaned_zip}:{retailer_ids or ''}:{limit}:{offset}" + cache_key = hashlib.sha256(cache_raw.encode("utf-8")).hexdigest()[:16] + + if not force_refresh: + cached_data, is_fresh = _read_cache(cache_key) + if is_fresh and cached_data: + return cached_data + + params: Dict[str, Any] = { + "as": "web", + "limit": limit, + "offset": offset, + "q": cleaned_query, + "zipCode": cleaned_zip, + } + if retailer_ids: + params["retailers"] = retailer_ids + + url = f"{API_BASE}/offers/search?{urllib.parse.urlencode(params)}" + + try: + data = _fetch_with_retry(url) + except Exception as e: + logger.error(f"Marktguru API query failed: {e}") + # Emergency fail-safe: Check if stale cache is available + cached_data, _ = _read_cache(cache_key, max_age_seconds=86400 * 7) + if cached_data: + logger.warning("Serving stale cached data due to API failure.") + cached_data["warning"] = "Stale cache returned due to temporary upstream API issue." + return cached_data + + return { + "error": f"API request failed: {str(e)}", + "query": cleaned_query, + "zip_code": cleaned_zip, + "total_results": 0, + "returned_count": 0, + "offers": [], + "available_retailers": [], + } + + raw_results = data.get("results") or [] + parsed_offers: List[Dict[str, Any]] = [] + for item in raw_results: + parsed = parse_offer(item, cleaned_zip) + if parsed is not None: + parsed_offers.append(parsed) + + filters = data.get("filters") or {} + raw_retailers = filters.get("retailers") or [] + available_retailers = [ + {"name": r.get("name"), "id": r.get("id"), "count": r.get("resultsCount")} + for r in raw_retailers if isinstance(r, dict) and r.get("name") + ] + + result = { + "query": cleaned_query, + "zip_code": cleaned_zip, + "total_results": data.get("totalResults", len(parsed_offers)), + "returned_count": len(parsed_offers), + "available_retailers": available_retailers, + "offers": parsed_offers, + } + + _write_cache(cache_key, result) + return result + + +def compare_prices( + query: str, + zip_code: str = DEFAULT_ZIP_CODE, + supermarkets: Optional[List[str]] = None, + force_refresh: bool = False, +) -> Dict[str, Any]: + """ + Compares prices for a given product query across supermarkets, sorted from cheapest to most expensive. + """ + data = search_offers(query, zip_code=zip_code, supermarkets=supermarkets, limit=50, force_refresh=force_refresh) + offers = data.get("offers", []) + + # Filter out items without price and sort ascending + priced_offers = [o for o in offers if o.get("price") is not None] + priced_offers.sort(key=lambda x: x["price"]) + + return { + "query": query, + "zip_code": str(zip_code), + "total_compared": len(priced_offers), + "cheapest_offer": priced_offers[0] if priced_offers else None, + "all_offers_sorted": priced_offers, + } + + +def list_supported_supermarkets() -> Dict[str, Any]: + """Returns a structured catalog of all major supermarket chains supported by Marktguru.""" + categories: Dict[str, List[Dict[str, Any]]] = { + "Discounter": [], + "Supermarkt": [], + "Großfläche / Hypermarkt": [], + "Drogerie": [], + } + + for name, info in MAJOR_RETAILERS.items(): + cat = info.get("type", "Sonstige") + if cat not in categories: + categories[cat] = [] + categories[cat].append({ + "name": name, + "id": info["id"], + "major": info.get("major", False) + }) + + return { + "default_zip_code": DEFAULT_ZIP_CODE, + "cache_ttl_seconds": CACHE_TTL, + "supported_chains_count": len(MAJOR_RETAILERS), + "categories": categories, + "supported_aliases": list(RETAILER_ALIASES.keys()), + } + + +def main(): + import argparse + parser = argparse.ArgumentParser(description="Query German supermarket flyers/discounts via Marktguru") + subparsers = parser.add_subparsers(dest="command", required=True) + + # Search + search_p = subparsers.add_parser("search", help="Search offers for a product") + search_p.add_argument("query", help="Product to search (e.g. Butter, Kaffee)") + search_p.add_argument("--zip", default=DEFAULT_ZIP_CODE, help=f"Postal code (default: {DEFAULT_ZIP_CODE})") + search_p.add_argument("--supermarket", help="Comma-separated supermarkets (e.g. 'Aldi,Lidl,Edeka')") + search_p.add_argument("--limit", type=int, default=15, help="Max results (default 15)") + search_p.add_argument("--refresh", action="store_true", help="Bypass local cache") + search_p.add_argument("--json", action="store_true", help="Output raw JSON") + + # Compare + comp_p = subparsers.add_parser("compare", help="Compare prices across supermarkets") + comp_p.add_argument("query", help="Product to compare") + comp_p.add_argument("--zip", default=DEFAULT_ZIP_CODE, help=f"Postal code (default: {DEFAULT_ZIP_CODE})") + comp_p.add_argument("--supermarket", help="Comma-separated supermarkets") + comp_p.add_argument("--refresh", action="store_true", help="Bypass local cache") + comp_p.add_argument("--json", action="store_true", help="Output raw JSON") + + # Supermarkets + subparsers.add_parser("supermarkets", help="List all supported supermarkets and chains") + + args = parser.parse_args() + + if args.command == "supermarkets": + data = list_supported_supermarkets() + print(json.dumps(data, indent=2, ensure_ascii=False)) + return + + sm_list = [s.strip() for s in args.supermarket.split(",")] if getattr(args, "supermarket", None) else None + + if args.command == "search": + result = search_offers( + args.query, + zip_code=args.zip, + supermarkets=sm_list, + limit=args.limit, + force_refresh=args.refresh + ) + if args.json: + print(json.dumps(result, indent=2, ensure_ascii=False)) + else: + if "error" in result and not result.get("offers"): + print(f"❌ Fehler: {result['error']}") + return + + print(f"\n🔍 Angebote für '{args.query}' in PLZ {args.zip} (Gefunden: {result['total_results']}):\n") + for o in result["offers"]: + disc_str = f" (-{o['discount_percent']}%)" if o.get("discount_percent") else "" + loyalty_str = " 📱 [App Coupon]" if o.get("loyalty_app_required") else "" + timing_str = f"noch {o['days_remaining']} Tage" if o.get("days_remaining") is not None else f"bis {o['valid_to']}" + print(f" • [{o['supermarket']}] {o['description'] or o['product_name'] or 'Angebot'}") + print(f" Preis: {o['price']:.2f} €{disc_str}{loyalty_str} | Gültig: {timing_str}") + if o.get("reference_price"): + print(f" Grundpreis: {o['reference_price']:.2f} € / {o.get('unit') or 'Einheit'}") + print() + + elif args.command == "compare": + result = compare_prices( + args.query, + zip_code=args.zip, + supermarkets=sm_list, + force_refresh=args.refresh + ) + if args.json: + print(json.dumps(result, indent=2, ensure_ascii=False)) + else: + print(f"\n🏷️ Preisvergleich für '{args.query}' in PLZ {args.zip}:\n") + for idx, o in enumerate(result["all_offers_sorted"], 1): + disc_str = f" (UVP {o['old_price']:.2f}€)" if o.get("old_price") else "" + loyalty_str = " [App erforderlich]" if o.get("loyalty_app_required") else "" + print(f" {idx:2d}. {o['price']:.2f} € - [{o['supermarket']}] {o['description'] or o['product_name']}{disc_str}{loyalty_str}") + print() + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/marktguru/scripts/marktguru_mcp.py b/.agents/skills/marktguru/scripts/marktguru_mcp.py new file mode 100755 index 0000000..c07072b --- /dev/null +++ b/.agents/skills/marktguru/scripts/marktguru_mcp.py @@ -0,0 +1,319 @@ +#!/usr/bin/env python3 +""" +Marktguru MCP (Model Context Protocol) Server (Production Grade) +Exposes German supermarket flyers, discounts, and price comparison tools over standard JSON-RPC 2.0 stdio. + +Key Design Principles: +- Zero external dependencies: Uses standard library only. +- Strict Protocol Compliance: Conforms to MCP (2024-11-05) and JSON-RPC 2.0 specifications. +- Defensive Argument Coercion: Tolerates string/number variations commonly output by LLMs. +- Graceful Signal Handling: Clean exit on SIGINT, SIGTERM, and EOF. +- Stream Isolation: All logs and diagnostics route to stderr, ensuring stdout is 100% clean JSON-RPC. +""" + +import sys +import json +import signal +import logging +from typing import Dict, Any, List, Optional + +# Import business logic from hardened client script +from marktguru_client import ( + search_offers, + compare_prices, + list_supported_supermarkets, + DEFAULT_ZIP_CODE, + MAJOR_RETAILERS, + RETAILER_ALIASES, +) + +# Configure logging strictly to stderr +logging.basicConfig( + stream=sys.stderr, + level=logging.INFO, + format="%(asctime)s [%(levelname)s] %(name)s: %(message)s" +) +logger = logging.getLogger("marktguru-mcp") + +PROTOCOL_VERSION = "2024-11-05" +SERVER_NAME = "marktguru-mcp-server" +SERVER_VERSION = "1.1.0" + +TOOLS = [ + { + "name": "search_supermarket_offers", + "description": ( + "Search current weekly supermarket offers and promotional discounts in Germany via the Marktguru API. " + "Supports filtering by postal code (PLZ) and specific supermarket chains (e.g. Aldi Süd, Aldi Nord, Lidl, Edeka, Rewe, Kaufland, Penny, Netto)." + ), + "inputSchema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "The product or keyword to search for (e.g. 'Butter', 'Kaffee', 'Bier', 'Milch', 'Nutella', 'Schokolade')." + }, + "zip_code": { + "type": "string", + "description": f"5-digit German postal code (PLZ). Defaults to '{DEFAULT_ZIP_CODE}' (Regensburg)." + }, + "supermarkets": { + "type": "array", + "items": {"type": "string"}, + "description": "Optional list of supermarket names to filter by (e.g. ['Aldi', 'Lidl', 'Edeka', 'Rewe', 'Kaufland', 'Penny', 'Netto', 'dm', 'Rossmann']). If omitted, all available retailers are included." + }, + "limit": { + "type": "integer", + "description": "Maximum number of offers to return (default: 20, max: 50)." + } + }, + "required": ["query"] + } + }, + { + "name": "compare_supermarket_prices", + "description": ( + "Compare current prices for a product across German supermarkets in a given postal code. " + "Returns results sorted from lowest to highest price, highlighting the cheapest deal, regular prices (UVP), and required loyalty app memberships." + ), + "inputSchema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "The product or grocery item to compare (e.g. 'Kaffee', 'Butter', 'Bier', 'Olivenöl')." + }, + "zip_code": { + "type": "string", + "description": f"5-digit German postal code (PLZ). Defaults to '{DEFAULT_ZIP_CODE}' (Regensburg)." + }, + "supermarkets": { + "type": "array", + "items": {"type": "string"}, + "description": "Optional list of supermarket names to compare (e.g. ['Aldi', 'Lidl', 'Edeka', 'Rewe'])." + } + }, + "required": ["query"] + } + }, + { + "name": "list_supported_supermarkets", + "description": ( + "List all supermarket, discounter, hypermarket, and drugstore chains supported by the Marktguru service in Germany, " + "including their categories (Discounter, Supermarkt, Großfläche, Drogerie) and accepted name aliases." + ), + "inputSchema": { + "type": "object", + "properties": {} + } + } +] + + +def _sanitize_supermarkets(sm_input: Any) -> Optional[List[str]]: + """Coerces various LLM input formats (list, comma-string, single string) into a clean list.""" + if not sm_input: + return None + if isinstance(sm_input, list): + return [str(s).strip() for s in sm_input if str(s).strip()] + if isinstance(sm_input, str): + return [s.strip() for s in sm_input.split(",") if s.strip()] + return None + + +def handle_initialize(req_id: Any, params: Dict[str, Any]) -> Dict[str, Any]: + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "protocolVersion": PROTOCOL_VERSION, + "capabilities": { + "tools": { + "listChanged": False + } + }, + "serverInfo": { + "name": SERVER_NAME, + "version": SERVER_VERSION + } + } + } + + +def handle_tools_list(req_id: Any) -> Dict[str, Any]: + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "tools": TOOLS + } + } + + +def handle_tools_call(req_id: Any, params: Dict[str, Any]) -> Dict[str, Any]: + tool_name = params.get("name") + args = params.get("arguments", {}) + + logger.info(f"Tool call requested: {tool_name} with args={args}") + + try: + if tool_name == "search_supermarket_offers": + query = str(args.get("query") or "").strip() + if not query: + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "content": [{"type": "text", "text": "Error: 'query' argument is required and cannot be empty."}], + "isError": True + } + } + + zip_code = str(args.get("zip_code") or DEFAULT_ZIP_CODE).strip() + supermarkets = _sanitize_supermarkets(args.get("supermarkets")) + try: + limit = int(args.get("limit") or 20) + except (ValueError, TypeError): + limit = 20 + + data = search_offers(query, zip_code=zip_code, supermarkets=supermarkets, limit=limit) + text_result = json.dumps(data, indent=2, ensure_ascii=False) + + elif tool_name == "compare_supermarket_prices": + query = str(args.get("query") or "").strip() + if not query: + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "content": [{"type": "text", "text": "Error: 'query' argument is required and cannot be empty."}], + "isError": True + } + } + + zip_code = str(args.get("zip_code") or DEFAULT_ZIP_CODE).strip() + supermarkets = _sanitize_supermarkets(args.get("supermarkets")) + + data = compare_prices(query, zip_code=zip_code, supermarkets=supermarkets) + text_result = json.dumps(data, indent=2, ensure_ascii=False) + + elif tool_name == "list_supported_supermarkets": + data = list_supported_supermarkets() + text_result = json.dumps(data, indent=2, ensure_ascii=False) + + else: + return { + "jsonrpc": "2.0", + "id": req_id, + "error": { + "code": -32601, + "message": f"Method or tool '{tool_name}' not found." + } + } + + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "content": [ + { + "type": "text", + "text": text_result + } + ], + "isError": False + } + } + + except Exception as e: + logger.exception(f"Exception during tool execution '{tool_name}': {e}") + return { + "jsonrpc": "2.0", + "id": req_id, + "result": { + "content": [ + { + "type": "text", + "text": f"Tool execution failed: {type(e).__name__}: {str(e)}" + } + ], + "isError": True + } + } + + +def process_message(line: str) -> Optional[Dict[str, Any]]: + if not line.strip(): + return None + + try: + msg = json.loads(line) + except json.JSONDecodeError as e: + logger.error(f"Malformed JSON-RPC received: {e}") + return { + "jsonrpc": "2.0", + "id": None, + "error": {"code": -32700, "message": f"Parse error: {str(e)}"} + } + + method = msg.get("method") + req_id = msg.get("id") + params = msg.get("params", {}) + + # Notifications do not return a response + if req_id is None: + if method == "notifications/initialized": + logger.info("Client acknowledged initialized notification.") + elif method == "notifications/cancelled": + logger.info(f"Client cancelled operation: {params}") + return None + + # Standard Requests + if method == "initialize": + return handle_initialize(req_id, params) + elif method == "tools/list": + return handle_tools_list(req_id) + elif method == "tools/call": + return handle_tools_call(req_id, params) + elif method == "ping": + return {"jsonrpc": "2.0", "id": req_id, "result": {}} + else: + return { + "jsonrpc": "2.0", + "id": req_id, + "error": { + "code": -32601, + "message": f"Method '{method}' is not supported." + } + } + + +def _sig_handler(sig, frame): + logger.info(f"Received termination signal {sig}. Exiting gracefully.") + sys.exit(0) + + +def main(): + signal.signal(signal.SIGINT, _sig_handler) + signal.signal(signal.SIGTERM, _sig_handler) + + logger.info(f"Starting {SERVER_NAME} v{SERVER_VERSION} (stdio mode)...") + + try: + for raw_line in sys.stdin: + response = process_message(raw_line) + if response is not None: + output = json.dumps(response, ensure_ascii=False) + "\n" + sys.stdout.write(output) + sys.stdout.flush() + except (KeyboardInterrupt, BrokenPipeError): + pass + except Exception as e: + logger.exception(f"Fatal error in stdio loop: {e}") + sys.exit(1) + + logger.info("Marktguru MCP server shutdown complete.") + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/marktguru/tests/test_marktguru.py b/.agents/skills/marktguru/tests/test_marktguru.py new file mode 100644 index 0000000..0833201 --- /dev/null +++ b/.agents/skills/marktguru/tests/test_marktguru.py @@ -0,0 +1,180 @@ +#!/usr/bin/env python3 +""" +Unit tests for the Marktguru skill & MCP Server. +Runs completely offline using standard library unittest. +""" + +import sys +import os +import json +import unittest +from datetime import datetime, timezone, timedelta + +# Add scripts directory to path +SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "scripts")) +if SCRIPTS_DIR not in sys.path: + sys.path.insert(0, SCRIPTS_DIR) + +from marktguru_client import ( + resolve_supermarket_ids, + format_iso_date, + parse_offer, + list_supported_supermarkets, + DEFAULT_ZIP_CODE, + _read_cache, + _write_cache, + _get_cache_dir, +) +from marktguru_mcp import process_message, SERVER_NAME, PROTOCOL_VERSION + + +class TestMarktguruClient(unittest.TestCase): + def test_default_zip_code(self): + self.assertEqual(DEFAULT_ZIP_CODE, "93059") + + def test_resolve_supermarket_ids_aliases(self): + # Aldi maps to Aldi Nord and Aldi Süd + aldi_ids = resolve_supermarket_ids(["aldi"]) + self.assertIn("127153", aldi_ids) + self.assertIn("127139", aldi_ids) + + # Edeka maps to Edeka and E center + edeka_ids = resolve_supermarket_ids(["edeka"]) + self.assertIn("127093", edeka_ids) + self.assertIn("126699", edeka_ids) + + # Lidl + lidl_ids = resolve_supermarket_ids(["lidl"]) + self.assertEqual(lidl_ids, "126679") + + # Comma-separated string support + combined = resolve_supermarket_ids("Lidl, Kaufland") + self.assertIn("126679", combined) + self.assertIn("126654", combined) + + # Unknown supermarket is ignored gracefully + unknown = resolve_supermarket_ids(["NonExistentMarket123"]) + self.assertIsNone(unknown) + + def test_format_iso_date(self): + self.assertEqual(format_iso_date("2026-10-15T12:00:00Z"), "15.10.2026") + self.assertEqual(format_iso_date(None), "-") + self.assertEqual(format_iso_date(""), "-") + self.assertEqual(format_iso_date("invalid-date-format"), "invalid-da") + + def test_parse_offer_defensive(self): + # 1. Complete payload + now = datetime.now(timezone.utc) + from_date = (now - timedelta(days=1)).isoformat() + to_date = (now + timedelta(days=4)).isoformat() + + raw_complete = { + "id": 99999, + "price": 1.49, + "oldPrice": 2.29, + "referencePrice": 5.96, + "requiresLoyalityMembership": True, + "description": "250g Packung", + "product": {"name": "Süßrahmbutter"}, + "brand": {"name": "Landliebe"}, + "advertisers": [{"name": "EDEKA", "id": "retailers/127093"}], + "unit": {"shortName": "kg"}, + "volume": 0.25, + "validityDates": [{"from": from_date, "to": to_date}] + } + + parsed = parse_offer(raw_complete, "93059") + self.assertIsNotNone(parsed) + self.assertEqual(parsed["id"], 99999) + self.assertEqual(parsed["supermarket"], "EDEKA") + self.assertEqual(parsed["price"], 1.49) + self.assertEqual(parsed["old_price"], 2.29) + self.assertEqual(parsed["discount_percent"], 35) # (2.29 - 1.49) / 2.29 = 34.9% -> 35% + self.assertTrue(parsed["loyalty_app_required"]) + self.assertTrue(parsed["is_valid_now"]) + self.assertGreaterEqual(parsed["days_remaining"], 3) + self.assertIn("https://mg2de.b-cdn.net/api/v1/offers/99999", parsed["image_url"]) + + # 2. Minimal / empty payload + raw_empty = {} + parsed_min = parse_offer(raw_empty, "93059") + self.assertIsNotNone(parsed_min) + self.assertEqual(parsed_min["supermarket"], "Unbekannt") + self.assertIsNone(parsed_min["price"]) + self.assertIsNone(parsed_min["discount_percent"]) + + # 3. Invalid types (not a dict) + self.assertIsNone(parse_offer("not a dict", "93059")) + self.assertIsNone(parse_offer(None, "93059")) + + def test_cache_mechanism(self): + test_key = "test_unit_key_123" + test_data = {"hello": "world", "timestamp": 12345} + + _write_cache(test_key, test_data) + data, is_fresh = _read_cache(test_key, max_age_seconds=60) + self.assertTrue(is_fresh) + self.assertEqual(data, test_data) + + # Stale cache test + data_stale, is_fresh_stale = _read_cache(test_key, max_age_seconds=-1) + self.assertFalse(is_fresh_stale) + self.assertEqual(data_stale, test_data) # still returned as fallback! + + def test_list_supported_supermarkets(self): + catalog = list_supported_supermarkets() + self.assertEqual(catalog["default_zip_code"], "93059") + self.assertIn("Discounter", catalog["categories"]) + self.assertIn("Supermarkt", catalog["categories"]) + self.assertIn("aldi", catalog["supported_aliases"]) + self.assertIn("edeka", catalog["supported_aliases"]) + + +class TestMarktguruMCP(unittest.TestCase): + def test_mcp_initialize(self): + req = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}) + resp = process_message(req) + self.assertEqual(resp["id"], 1) + self.assertEqual(resp["result"]["protocolVersion"], PROTOCOL_VERSION) + self.assertEqual(resp["result"]["serverInfo"]["name"], SERVER_NAME) + + def test_mcp_tools_list(self): + req = json.dumps({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}) + resp = process_message(req) + tools = [t["name"] for t in resp["result"]["tools"]] + self.assertIn("search_supermarket_offers", tools) + self.assertIn("compare_supermarket_prices", tools) + self.assertIn("list_supported_supermarkets", tools) + + def test_mcp_tools_call_supermarket_catalog(self): + req = json.dumps({ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": {"name": "list_supported_supermarkets", "arguments": {}} + }) + resp = process_message(req) + self.assertFalse(resp["result"]["isError"]) + content_text = resp["result"]["content"][0]["text"] + data = json.loads(content_text) + self.assertEqual(data["default_zip_code"], "93059") + + def test_mcp_tools_call_missing_query(self): + req = json.dumps({ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": {"name": "search_supermarket_offers", "arguments": {"query": ""}} + }) + resp = process_message(req) + self.assertTrue(resp["result"]["isError"]) + self.assertIn("required", resp["result"]["content"][0]["text"]) + + def test_mcp_notification_silence(self): + req = json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + resp = process_message(req) + self.assertIsNone(resp) # Notifications must not produce responses + + +if __name__ == "__main__": + unittest.main()