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.

argtypenotescountrystring (ISO-2)required, e.g. DE, US, MX``occasionstringbirthday, christmas, valentines, mothers-day, einschulung, sinterklaas, midsommar, …ageintegerrecipient agegender``male/ female/ unisex``unisex rows always includedbudget_min_cents / budget_max_centsintegerin country currency centsinterestsstring[]hobby/interest tags — call list_supported_interests for the full listprofessionstringe.g. teacher, developer, chef, athlete, photographer, gamer``favorite_colorstringone of red, blue, green, yellow, purple, pink, orange, black, white, gold, silver — only matches gifts whose favorite_color is exactly this; color-agnostic gifts are skipped when this filter is setlimitinteger (1–20, default 5)

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](product_url). Do not strip query params from product_url — use the URL exactly as returned.

Example#

text

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.