# Surprise Buddy

> Surprise Buddy is an AI-powered gift recommendation app that helps users find the perfect gift for any occasion. It supports 70+ countries, 11 languages, and multiple currencies.

Surprise Buddy uses Google Gemini AI to generate personalized gift suggestions based on the recipient's age, gender, interests, occasion, and budget. Each recommendation includes a product name, description, and a direct link to shop (Amazon, Etsy, Mercado Libre, or other region-specific stores).

The app is available at [https://www.surprise-buddy.com](https://www.surprise-buddy.com).

## Supported Languages

- English (en), German (de), Spanish (es), French (fr), Italian (it), Portuguese (pt), Dutch (nl), Polish (pl), Swedish (sv), Danish (da), Norwegian (no)

All routes are locale-prefixed: `/{locale}/page`

## Main Pages

- [Home](https://www.surprise-buddy.com/en/): Gift finder form — select occasion, recipient details, interests, and budget to get AI-generated gift recommendations
- [FAQ](https://www.surprise-buddy.com/en/faq): Frequently asked questions about how Surprise Buddy works
- [Contact](https://www.surprise-buddy.com/en/contact): Contact form
- [Imprint](https://www.surprise-buddy.com/en/imprint): Legal imprint
- [Privacy](https://www.surprise-buddy.com/en/privacy): Privacy policy

## Occasion Pages

- [Birthday](https://www.surprise-buddy.com/en/birthday): Birthday gift ideas with countdown
- [Christmas](https://www.surprise-buddy.com/en/christmas): Christmas gift ideas with countdown
- [Easter](https://www.surprise-buddy.com/en/easter): Easter gift ideas with countdown
- [Valentine's Day](https://www.surprise-buddy.com/en/valentines): Valentine's Day gift ideas with countdown
- [Mother's Day](https://www.surprise-buddy.com/en/mothers-day): Mother's Day gift ideas with countdown
- [Father's Day](https://www.surprise-buddy.com/en/fathers-day): Father's Day gift ideas with countdown
- [Wedding](https://www.surprise-buddy.com/en/wedding): Wedding gift ideas
- [Thanksgiving](https://www.surprise-buddy.com/en/thanksgiving): Thanksgiving gift ideas
- [Halloween](https://www.surprise-buddy.com/en/halloween): Halloween gift ideas

### Locale-Specific Occasions

- [Einschulung](https://www.surprise-buddy.com/de/einschulung): First day of school gifts (German)
- [Nikolaus](https://www.surprise-buddy.com/de/nikolaus): St. Nicholas Day gifts (German)
- [Reyes Magos](https://www.surprise-buddy.com/es/reyes-magos): Three Kings Day gifts (Spanish)
- [Amor y Amistad](https://www.surprise-buddy.com/es/amor-y-amistad): Love and Friendship Day gifts (Spanish)
- [Quinceañera](https://www.surprise-buddy.com/es/quinceanera): Quinceañera gifts (Spanish)
- [Sinterklaas](https://www.surprise-buddy.com/nl/sinterklaas): Sinterklaas gifts (Dutch)
- [Koningsdag](https://www.surprise-buddy.com/nl/koningsdag): King's Day gifts (Dutch)
- [Midsommar](https://www.surprise-buddy.com/sv/midsommar): Midsummer gifts (Swedish)
- [Dia dos Namorados](https://www.surprise-buddy.com/pt/dia-dos-namorados): Brazilian Valentine's Day gifts (Portuguese)
- [Befana](https://www.surprise-buddy.com/it/befana): Befana gifts (Italian)
- [Imieniny](https://www.surprise-buddy.com/pl/imieniny): Name day gifts (Polish)
- [Fastelavn](https://www.surprise-buddy.com/da/fastelavn): Fastelavn gifts (Danish)
- [Syttende Mai](https://www.surprise-buddy.com/no/syttende-mai): Norwegian Constitution Day gifts (Norwegian)

## Blog

- [Last-Minute Valentinstag Geschenke 2026](https://www.surprise-buddy.com/de/blog/last-minute-valentinstag-geschenke-2026): Valentine's Day gift guide (German)
- [Ostergeschenke 2026](https://www.surprise-buddy.com/de/blog/ostergeschenke-2026): Easter gift guide (German)
- [Día de las Madres 2026](https://www.surprise-buddy.com/es/blog/dia-de-las-madres-2026): Mother's Day gift guide (Spanish)
- [Dzień Matki 2026](https://www.surprise-buddy.com/pl/blog/dzien-matki-2026): Mother's Day gift guide (Polish)

## API

- `POST /api/generate`: Generate gift recommendations. Requires a JSON body with fields: country, gender, age, occasion, interests, budget (min/max), currency. Returns a JSON array of gift objects. Not publicly accessible without server-side API key.

## For AI Agents (MCP)

Surprise Buddy hosts a public **MCP server** for AI agents — search the curated, country-scoped gift database from Claude, ChatGPT, or any MCP-compatible client.

- MCP endpoint (JSON-RPC 2.0): [https://www.surprise-buddy.com/api/mcp](https://www.surprise-buddy.com/api/mcp)
- Discovery manifest: [https://www.surprise-buddy.com/.well-known/mcp.json](https://www.surprise-buddy.com/.well-known/mcp.json)
- OpenAPI 3.1 spec (for non-MCP agents): [https://www.surprise-buddy.com/openapi.yaml](https://www.surprise-buddy.com/openapi.yaml)
- Agent instructions / skill: [https://github.com/sebastian1747/SurpriseBuddy/blob/master/SKILL.md](https://github.com/sebastian1747/SurpriseBuddy/blob/master/SKILL.md)

Tools exposed: `find_gifts`, `list_supported_countries`, `list_supported_occasions`, `list_supported_interests`. Authentication: none (open).

## Optional

### Interest Categories

Users can select from 100+ interest tags across 12 categories: Sports, Wellness, Learning, Tech & Gaming, Creative, Home, Outdoors, Entertainment, Fashion, Food & Drink, Music Genres, and Other.

### Supported Countries (70+)

Organized by language: German-speaking (DE, AT, CH), French-speaking (FR, BE, SN, CI, MA, and more), English-speaking (US, GB, CA, AU, IE, and more), Spanish-speaking (ES, MX, AR, CO, CL, PE, and more), Portuguese-speaking (PT, BR), Dutch (NL), Polish (PL), Swedish (SE), Danish (DK), Norwegian (NO), Italian (IT).

### Supported Currencies

EUR, USD, GBP, CHF, CAD, AUD, MXN, ARS, COP, BRL, CLP, PEN, UYU, PLN, SEK, DKK, NOK.