# README

This is an MCP server for decathlon.nl. The Netherlands website uses a different format than the rest of Decathlon (including IN) so this is a separate MCP server to deal with that.

## Setup

You can set this up in claude code or your favourite mcp client in stdio mode with uv (recommended).

For Claude Code:

```bash
claude mcp add decathlon -- uv run --project /path/to/decathlon-mcp decathlon-mcp
```

Or add it to your `~/.claude.json` / client config directly:

```json
{
  "mcpServers": {
    "decathlon": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/decathlon-mcp", "decathlon-mcp"]
    }
  }
}
```

## Manual Setup

Requires Python >= 3.13 and [uv](https://docs.astral.sh/uv/).

```bash
git clone <repo-url>
cd decathlon-mcp
uv sync
uv run decathlon-mcp
```

This runs the server over stdio. Point any MCP client that supports stdio transport at the `decathlon-mcp` command.

## Details

This MCP server implements four different tools:

- `search_suggestions(query)` — autocomplete suggestions for a search term, including matching categories and popular queries.

- `search_products(query, page)` — product search. Returns a normalized summary per product: Decathlon ids (`id`, `model_id`, `sku_id`), title, brand, URL, image, price (with original price when discounted), online availability, sizes, rating and review count. Use `sku_id` with `get_product_details` and `model_id` with `get_reviews`.

- `get_product_details(sku_ids[])` — full details for one or more SKUs (batched): description, colors, size, weight, current price vs original price, seller, fulfillment options (store pickup / delivery / shipping), per-store stock availability, categories and sports.

- `get_reviews(model_id, page, per_page)` — customer reviews with aggregate stats (average rating, satisfaction %, star distribution) plus individual reviews with verified-purchase flags and sub-ratings per attribute (ease of use, value for money, etc.).

A typical agent flow is: `search_products` to find candidates → `get_product_details` to compare price/stock/sizes across variants → `get_reviews` to judge quality.

### Implementation notes

The site soft-blocks bursts of requests (~1–2 min cooldown during which pages come back without product data), so requests are spaced at least 3 seconds apart and `search_products` retries with backoff when a response is missing data.

Product search uses the Next.js RSC protocol (`RSC: 1` header on `/search`) since there is no public JSON search endpoint; its flight-data format is internal to Next.js and may need parser updates if Decathlon upgrades their stack. The product-details and reviews endpoints are plain JSON and more stable.

### Disclaimer

This is not an official project. Currently limited to read-only access for obvious reasons.