Surprise Buddy gift-search skill

A live MCP HTTP server at https://www.surprise-buddy.com/api/mcp exposes a small set of tools that query a curated, country-scoped database of gift ideas. International coverage — every result is a real product page on a real marketplace (Amazon, Etsy, Mercado Libre, Otto, Bol.com, Allegro, Jochen Schweizer) and the link can be presented to the user as-is.

Call list_supported_countries for the current list of countries; coverage grows over time.

Tools

find_gifts

Main search. country is required and is a hard filter — results never cross marketplaces.

Returns { gifts: [ { id, title, description, why_it_fits, product_url, image_url, price, currency, shop, shop_display_name, category, favorite_color, country_code } ] }.

list_supported_countries

Returns the country codes that currently have active entries.

list_supported_occasions(country?)

Returns occasion codes with active entries, optionally narrowed to a country.

list_supported_interests

Returns the canonical interest/hobby tag vocabulary (matches the tags shown in the website UI).

list_supported_colors

Returns the canonical favorite-color vocabulary (matches the color picker shown in the website UI).

How to use it in a chat

When a user asks for gift help:

1. Pull country, occasion, age, budget, interests from the conversation (ask if any are missing — country is mandatory).
2. Convert the budget to cents in the country's currency, not a foreign currency.
3. Call find_gifts.
4. Render each gift as a card: title, image, price (with currency), why-it-fits, and a markdown link Buy on Amazon. Do not strip query params from product_url — use the URL exactly as returned.

Example

User: "Geschenk für meinen 35-jährigen Bruder in Deutschland, mag Gaming, Budget 50-100€."

→ find_gifts({
    country: "DE",
    age: 35,
    gender: "male",
    occasion: "birthday",
    budget_min_cents: 5000,
    budget_max_cents: 10000,
    interests: ["gaming"],
    limit: 5
  })

What it is NOT

• Not a generic web search — only returns rows that exist in the curated DB.
• Not a price oracle — price_cents is the price at last verification, not live.
• Empty results are valid: try widening the budget, removing gender, or dropping interests.