Implement Colruyt Xtra MCP Server

[ddvlamin]

Background & Motivation

The goal is to build a Model Context Protocol (MCP) server for the Colruyt Xtra app. This will enable an AI assistant to fetch most bought items, search for products, and add items to their shopping list. A key feature is the ability to read recipes from local markdown files, parse ingredients, and add them to the list, resolving ambiguities by cross-referencing with the user's purchase history.

Scope & Impact

• Authentication: The MCP server will accept authentication arguments (e.g., username/password or tokens) upon startup/installation so that all subsequent tools can act on behalf of the user.
• Core MCP Tools:
  • get_most_bought_products: Fetch the user's most bought products.
  • search_products: Search the Colruyt catalog for products by name/keyword.
  • add_items_to_list: Add specified products to the user's Colruyt shopping list.
• AI Skills/Logic:
  • add_recipe_ingredients: Parse markdown files from recipes/, extract ingredients, and add them to the list. It will use a two-step matching process: searching the catalog first, and if the match isn't clear, cross-referencing with the user's most-bought list to resolve ambiguity.

Proposed Solution

1. Authentication: Implement a login flow in Python that uses the provided startup arguments to authenticate with Colruyt and obtain the x-cg-apikey and session cookies (clpbff_session). This ensures the AI can use the tools seamlessly. If necessary, we will discover the specific login API endpoints using network inspection during development.
2. Server Framework: Initialize a Python-based MCP server using the mcp SDK, configured to accept the necessary arguments.
3. API Client Integration: Implement HTTP clients (using httpx) for the most-bought-products, search, and add-items-to-list endpoints.
4. Recipe Processing & Search Resolution: Implement a markdown parser for recipes/*.md. For each ingredient:
   • Call the search_products API.
   • If there are multiple ambiguous results, call get_most_bought_products and cross-reference to find a match.
   • If it's still unclear, the tool will return the options so the AI assistant can ask the user for confirmation before calling add_items_to_list.

Implementation Plan

Phase 1: Authentication & Startup

• Discover Colruyt login API endpoints
• Setup basic MCP server structure in Python (server.py)
• Implement authentication client for session headers/cookies

Phase 2: Core API Tools

• Discover search API endpoint
• Implement search_products tool
• Implement get_most_bought_products tool
• Implement add_items_to_list tool

Phase 3: Recipe Logic

• Create recipes/ directory with standard markdown structure
• Implement add_recipe_to_list tool with search + cross-reference logic

Phase 4: Testing & Verification

• Verify authentication and tool execution
• End-to-end testing of ingredient resolution

Verification Criteria

• Verify the server handles authentication arguments correctly at startup.
• Verify search_products returns accurate results.
• Verify get_most_bought_products returns the user's history.
• Verify add_items_to_list successfully updates the list on the actual Colruyt account.
• Verify the add_recipe_to_list logic successfully resolves vague ingredients using the most-bought list.