# Beezy

> Beezy is a shopping area where you can discover products from local shops.

This is an area domain: it lists products and shops from multiple local shops in one shopping area. If you run in a browser, use the WebMCP tools below to search products, shops, brands and categories - they are the preferred way to query the site. Always link back to real pages using the urls returned by the tools.

## WebMCP tools (preferred way to search)

This site registers WebMCP tools in the browser via `document.modelContext.registerTool()` (W3C WebMCP spec, Chrome 146+ experimental). If you run in a browser that supports WebMCP, **use these tools as your primary way to search the site** - they query the live product API and return real page URLs you can link back to. Do not guess or invent URLs; always use the urls returned by the tools.

- search_products: Search products (variations) available on beezy. Returns product ids, titles and page urls. Optionally scope by brand, category or a local area (bounding box or point). Use short keywords; for broad questions search on price and location without a category.
- find_product_stock: Find which shops near a point sell a product, with price in euros, availability (in_stock, call_for_stock, out_of_stock) and a stock_note to quote to the customer (stock is as reported by the shop, never present it as a guaranteed count), distance, phone, open_now and today_hours, and a link to the shop product page. Identify the product by product_id (from search_products) or ean.
- search_locations: Search shops (locations) on beezy. Returns shop ids, titles, addresses and page urls. Optionally scope by city, brand or a local area (bounding box or point).
- search_brands: Search brands on beezy. Returns brand ids, titles and page urls. Optionally scope to a single shop.
- search_categories: Search product categories on beezy. Returns category ids, names, paths and page urls. Optionally scope to a single shop.
- get_url_guidelines: Returns guidelines for building correct beezy page urls. Call this before linking to pages.
- submit_feedback: Leave feedback about the site or its data (e.g. wrong product data, missing information, or a suggestion). The feedback is sent to the beezy team.

Feature-detect WebMCP with `'modelContext' in document`. If WebMCP is not available, fall back to the URL patterns below.

The same tools are also served as an MCP server at [/mcp](https://spellenenpuzzels.nl/mcp) (Streamable HTTP). MCP clients can connect to that endpoint to use the same search tools. The server's machine-readable metadata (identity, transport endpoint, capabilities) is published as an MCP Server Card at [/.well-known/mcp/server-card.json](https://spellenenpuzzels.nl/.well-known/mcp/server-card.json) for pre-connection discovery.

## Markdown for Agents

Every public page on this site is also available as a clean, formatting-stripped Markdown document. Request it either by sending an `Accept: text/markdown` header, or by appending `.md` to any URL (for example `https://spellenenpuzzels.nl/products.md` or `https://spellenenpuzzels.nl/product/{id}.md`). The response is a Markdown document with YAML frontmatter (page title and description), a site header with navigation, the page content built from the data, and a footer with agent-discovery links. Browsers (without the header and without the .md suffix) get HTML as usual.

Prefer the WebMCP/MCP tools for structured search and for real product/shop urls. Use Markdown negotiation to read the actual content of a specific page.


## Pages

- [Home](https://spellenenpuzzels.nl/): Discover products and shops in the area.
- [Products](https://spellenenpuzzels.nl/products): Browse all products.
- [Categories](https://spellenenpuzzels.nl/products/categories): Browse product categories.
- [Shops](https://spellenenpuzzels.nl/locations): Browse all shops in the area.

## URL patterns

- A product page lives at /product/{id}.
- A shop page lives at /winkel/{id}/{slug} (slug is the url-safe shop title).
- A shop product page lives at /winkel/{id}/{slug}/product/{productId}.
- A brand page lives at /merk/{id}/{slug}.
- A category/assortiment page lives at /assortiment/{slug}.