Skill: sebastian1747/surprise-buddy (version 1.0.0)

--- name: surprise-buddy description: Look up curated gift ideas from the Surprise Buddy database — country-scoped product cards with title, image, price, and a ready-to-click product link. International coverage across many countries and marketplaces. Use when a user is looking for a gift for someone and you know at least their country and a rough idea of the occasion/age/interests. --- # 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. | arg | type | notes | |---|---|---| | `country` | string (ISO-2) | **required**, e.g. `DE`, `US`, `MX` | | `occasion` | string | `birthday`, `christmas`, `valentines`, `mothers-day`, `einschulung`, `sinterklaas`, `midsommar`, … | | `age` | integer | recipient age | | `gender` | `male`/`female`/`unisex` | `unisex` rows always included | | `budget_min_cents` / `budget_max_cents` | integer | in **country currency cents** | | `interests` | string[] | hobby/interest tags — call `list_supported_interests` for the full list | | `profession` | string | e.g. `teacher`, `developer`, `chef`, `athlete`, `photographer`, `gamer` | | `favorite_color` | string | one 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 set | | `limit` | integer (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 ``` 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`.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)