Czech DIY Retail MCP Server (czech-diy-mcp)

Model Context Protocol (MCP) server for Czech DIY retail discovery. The server uses live current retailer pages for BAUHAUS CZ, HORNBACH CZ, OBI CZ and Baumax CZ.

Release status

1.0.0 is the production release. Live product search/detail is implemented for all four retailers; BAUHAUS and OBI expose live store stock, HORNBACH exposes qualitative store offers where present, and Baumax store stock is explicitly NOT_SUPPORTED.

Česká dokumentace

czech-diy-mcp je read-only MCP server pro vyhledávání zboží v českých hobby marketech a stavebninách. Nabízí jednotné rozhraní pro BAUHAUS CZ, HORNBACH CZ, OBI CZ a Baumax CZ.

Server poskytuje:

• vyhledávání produktů, cen a kategorií;

• detail produktu včetně technických parametrů, EAN/GTIN a obrázků, pokud jsou dostupné;

• seznam prodejen;

• dostupnost produktu v konkrétní prodejně;

• porovnání cen mezi podporovanými prodejci.

Veřejné MCP nástroje jsou search_products, get_product, list_stores, get_stock a compare_price. Primární transport je Streamable HTTP na /mcp; kontrola dostupnosti aplikace je na /healthz.

Rychlé spuštění

uv sync --extra dev
uv run python -m czech_diy_mcp --transport http --port 8000

Poté je MCP server dostupný na http://localhost:8000/mcp a health endpoint na http://localhost:8000/healthz.

Docker

docker build -t czech-diy-mcp:1.0.0 .
docker run --rm -p 8000:8000 czech-diy-mcp:1.0.0

Důležitá pravidla dostupnosti

Pokud prodejce neposkytne spolehlivý údaj o skladovosti, server vrací UNKNOWN nebo NOT_SUPPORTED. Chybějící množství se nikdy nepřevádí na nulu a server nevymýšlí stav skladu. Skladová data jsou pouze okamžitý údaj a mohou se mezi jednotlivými požadavky změnit.

Server neprovádí objednávky, nepřidává zboží do košíku, nepřihlašuje zákazníky, nezpracovává platby a neřeší CAPTCHA ani jiné interaktivní výzvy.

Bezpečnost provozu

Server nepřijímá libovolné URL a používá pouze pevně definované domény prodejců. Přesto MCP endpoint nevystavujte přímo do veřejného internetu bez TLS, autentizace, rate limitu a firewallu. Podrobnosti jsou v Operations Manual a Security Policy.

Related MCP server: Shoptera Product Intelligence

1. Retailer Support Matrix

2. MCP Tools

The server exposes five normalized MCP tools:

1. search_products(query, retailer="all", max_price=None, max_results=20)

   • Search all live-enabled retailers in production.

2. get_product(retailer, product_id)

   • Retrieve full product details, GTIN/EAN, specifications, and manufacturer info.

3. list_stores(retailer, query=None)

   • List physical store locations matching an optional query string (city, postcode, name).

4. get_stock(retailer, product_id, store_id)

   • Query store-specific physical stock availability with maximum 60s cache TTL.

5. compare_price(query, retailers=None, max_results_per_retailer=10)

   • Compare prices across all four currently enabled retailer adapters; results include per-retailer errors and do not invent unavailable stock.

3. Installation & Local Development

Requirements

• Python 3.12+

Setup

uv sync --extra dev

4. Operational Commands & Testing

Run Tests with 100% Line & Branch Coverage

uv run pytest -m "not smoke and not container" --cov=czech_diy_mcp --cov-branch --cov-report=term-missing --cov-fail-under=100

Run Live Retailer Smoke Suite

pytest -m smoke

Code Formatting & Type Checking

uv run ruff check .
uv run ruff format --check .
uv run pyright

Mutation testing for critical parsing and comparison logic:

python scripts/run_mutation_audit.py

5. Running the MCP Server

Streamable HTTP (Default)

python -m czech_diy_mcp --transport http --port 8000

• MCP endpoint: POST /mcp

• Health check: GET /healthz

Stdio Transport

python -m czech_diy_mcp --transport stdio

6. Docker Deployment

Build Image

docker build -t czech-diy-mcp .

Run Container

docker run -d -p 8000:8000 --name czech-diy-mcp czech-diy-mcp

Docker Compose

docker compose up -d

7. Configuration

Environment variables (or .env file):

8. Architecture

                        MCP Client
                            │
                            ▼
                    ┌───────────────┐
                    │  MCP Server   │
                    │   server.py   │
                    └───────┬───────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ Service Layer │
                    │ catalog.py    │
                    └───────┬───────┘
                            │
          ┌─────────────────┼──────────────────┐
          │                 │                  │
          ▼                 ▼                  ▼
      BAUHAUS           HORNBACH              OBI
      Adapter            Adapter            Adapter

9. License

MIT License

10. Documentation

Additional release documentation is maintained in docs/:

• Architecture — application boundaries, adapters, data flow and normalized models.

• Operations Manual — deployment, health checks, configuration, logs and incident handling.

• Development and Testing — local workflow, fixtures, quality gates and live smoke tests.

• Release Checklist — reproducible release procedure and acceptance criteria.

11. Data and availability policy

The server is read-only. It never places orders, adds products to baskets, authenticates users, solves challenges or accepts arbitrary URLs.

Retailer data is request-time data and may change between calls. UNKNOWN means that the retailer did not provide a reliable signal; it is never converted to OUT_OF_STOCK, and an absent quantity is never converted to zero. fetched_at is returned with normalized records.

BAUHAUS is the primary production adapter. HORNBACH and OBI provide live catalogue/store integrations; their stock precision depends on the signal exposed by the Czech site. Baumax store stock is intentionally NOT_SUPPORTED where no reliable upstream signal exists.

12. Release limitations

• Retailer pages can rate-limit or challenge automated requests. Such responses are surfaced as structured errors.

• Stock is inherently volatile and is cached for at most the configured stock TTL (60 seconds by default).

• Exact quantity is returned only when the retailer explicitly exposes it.

• The in-memory cache is process-local and is not a shared distributed cache.

• DEK is reserved for a future adapter.