--- title: CelebrateAI emoji: 🎉 colorFrom: purple colorTo: pink sdk: gradio sdk_version: 5.49.1 app_file: app.py pinned: false license: mit short_description: AI-powered end-to-end celebration planning assistant tags: - mcp-in-action-track-consumer --- # 🎉 CelebrateAI - Your AI Celebration Planning Assistant > **Built for the [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)** hosted by Anthropic and Gradio CelebrateAI is an intelligent, end-to-end celebration planning assistant powered by the Model Context Protocol (MCP). From brainstorming creative ideas to detailed execution plans with shopping lists and invitations — we've got your celebration covered! ## 📺 Demo Video [Watch Demo Video](https://www.youtube.com/watch?v=s9tLkk25de0) ## 👥 Team **Team Name:** CelebrateAI **Team Members:** - **Shubham Setia** - [@ShubhamSetia](https://huggingface.co/ShubhamSetia) - Lead Developer - **Kanishka Khunteta** - [@Kkhunteta](https://huggingface.co/Kkhunteta) - Product Manager ## 📱 Social Media 🐦 **[Post on Twitter/X](https://x.com/shubhamsetia12/status/1994801305492345056)** ## 🌟 Features ### 🧠 Two Powerful MCP Servers | Server | Purpose | Tools | |--------|---------|-------| | **Ideation MCP** | Generate creative, personalized celebration ideas | `generate_celebration_concepts` | | **Research MCP** | Deep research & execution planning | `web_search`, `visit_page`, `amazon_search`, `generate_message` | ### 💡 Ideation Agent - Generates 3 tailored celebration ideas based on: - Occasion type (Birthday, Anniversary, Graduation, etc.) - Budget tier (Low → Luxury) - Honoree preferences & interests - Location & constraints - Each idea includes: summary, highlights, estimated budget, effort level, and next steps ### 🔬 Research Agent (NEW!) A **ReAct-style agent** that creates detailed, actionable execution plans: - **🔍 Web Search**: Finds relevant party planning guides, venue ideas, and inspiration - **📄 Page Visitor**: Extracts detailed content from promising URLs - **🛒 Amazon Search**: Finds specific products (decorations, supplies, gifts) - **✉️ Message Generator**: Creates themed party invitations #### Output Includes: - **Detailed Timeline**: Step-by-step action plan (2 weeks before → day of event) - **Shopping List**: Specific Amazon products with direct links - **Sample Invitation**: Ready-to-use party invitation - **References**: Curated resources for further planning ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Gradio Chat UI │ │ (Occasion, Budget, Location, Honoree Profile, Constraints) │ └─────────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Orchestrator │ │ (Routes requests to appropriate MCP server) │ └──────────┬─────────────────────────────────┬────────────────┘ │ │ ▼ ▼ ┌──────────────────────┐ ┌─────────────────────────────┐ │ Ideation MCP │ │ Research MCP │ │ (FastMCP Server) │ │ (ReAct Agent + Tools) │ │ │ │ │ │ • Nebius LLM Mode │ │ • Web Search (DuckDuckGo) │ │ • Mock Fallback │ │ • Page Visitor (httpx) │ │ │ │ • Amazon Search │ │ │ │ • Message Generator │ └──────────────────────┘ └─────────────────────────────┘ ``` ## 🚀 Quick Start ### Prerequisites ```bash pip install -r requirements.txt ``` ### Environment Variables ```bash # Ideation Server export CELEBRATE_AI_IDEATION_PROVIDER=nebius export CELEBRATE_AI_IDEATION_NEBIUS_BASE_URL=https://api.studio.nebius.ai/v1 export CELEBRATE_AI_IDEATION_NEBIUS_API_KEY=your-key-here # Research Server export CELEBRATE_AI_RESEARCH_PROVIDER=agent export CELEBRATE_AI_RESEARCH_NEBIUS_BASE_URL=https://api.studio.nebius.ai/v1 export CELEBRATE_AI_RESEARCH_NEBIUS_API_KEY=your-key-here ``` ### Run the App ```bash python app.py ``` ## 📦 Project Structure ``` CelebrateAI_Gradio/ ├── app.py # Main Gradio app entry ├── ui/ │ └── chat.py # Chat interface & response formatting ├── core/ │ └── orchestrator.py # Routes between MCP servers ├── mcp_servers/ │ ├── ideation/ # Idea generation MCP server │ │ ├── server.py │ │ ├── provider.py # Nebius LLM & Mock providers │ │ └── config.py │ └── research/ # Research & planning MCP server │ ├── server.py │ ├── provider.py # ReAct agent with tools │ ├── tool_schemas.py # Pydantic models │ └── config.py └── models/ └── schemas.py # Shared data models ``` ## 🛠️ Technical Highlights ### ReAct Agent Loop The Research MCP uses a **Reasoning + Acting** cycle: 1. **Plan** - Determine which tools to use 2. **Execute** - Run tools (web search, Amazon, etc.) 3. **Observe** - Process results 4. **Synthesize** - Create user-friendly output ### Smart Search Filtering - Filters out irrelevant domains (tech support, forums) - Prioritizes product pages over search pages on Amazon - Extracts key information from visited pages ### Context-Aware Planning - Uses full idea context from Ideation for targeted searches - Incorporates honoree interests and preferences - Generates themed invitations based on celebration type ## 🎯 Example Output **Input:** "Plan a Harry Potter themed birthday party" **Research Agent Output:** ``` 📝 ACTION PLAN 📋 2 weeks before: Create guest list and budget for Wizarding Wonderland ✉️ 2 weeks before: Send themed Hogwarts acceptance letter invitations 🛒 1 week before: Order supplies from the shopping list below 🍽️ 1 week before: Order Harry Potter decorations and plan magical menu 🎮 3-4 days before: Prepare Sorting Hat ceremony and trivia game 🏠 1 day before: Set up decorations and prepare the venue ✅ Day of event: Final walkthrough, welcome guests, and enjoy! 🛒 SHOPPING LIST • Wizarding World Harry Potter Spellbinding Wand → amazon.com/... • Harry Potter Party Decorations Kit → amazon.com/... • Butterbeer Recipe Book → amazon.com/... ✉️ SAMPLE INVITATION 🎉 You're Invited to Wizarding Wonderland Birthday Bash! 🎉 Dear Friend, Get ready for an amazing celebration! 📅 Date: December 15, 2024 📍 Location: [Your venue] Please RSVP by [date] so we can plan accordingly. 🥳 See you there! ``` ## 🏆 Hackathon Track **Track:** MCP in Action - Consumer Applications This project demonstrates how MCP servers can power consumer-facing AI applications with: - Multiple specialized MCP tools working together - ReAct-style agentic reasoning - Real-world data integration (web search, e-commerce) - Practical, actionable outputs ## 🙏 Sponsors & APIs Used We're grateful to the hackathon sponsors whose APIs and platforms power CelebrateAI: ### 🤖 AI & LLM Services - **[Nebius](https://tokenfactory.nebius.com/)** - LLM API for ideation and research agent reasoning - Model: Meta-Llama-3.1-8B-Instruct - Used for: Generating celebration ideas and agent planning decisions ### 🔍 Search & Data Services - **[DuckDuckGo](https://duckduckgo.com/)** - Web search via `ddgs` library - Used for: Finding party planning guides, venue ideas, and inspiration - **Amazon** - Product search via DuckDuckGo site search - Used for: Finding specific decorations, supplies, and gifts ### 🛠️ Frameworks & Protocols - **[Gradio](https://gradio.app/)** - UI framework (v5.49.1) - Used for: Chat interface and user interaction - **[Anthropic MCP](https://modelcontextprotocol.io/)** - Model Context Protocol - Used for: Server architecture and tool communication - **[FastMCP](https://github.com/jlowin/fastmcp)** - MCP server framework - Used for: Building both Ideation and Research MCP servers ### 📚 Libraries - `httpx` - HTTP client for API calls and page visiting - `langgraph` & `langchain-core` - Agent orchestration - `pydantic` - Data validation and schemas - `beautifulsoup4` - HTML parsing for page content extraction ## 📊 Evaluation Highlights ### What Makes This Project Stand Out: 1. **Complete End-to-End Solution** - Not just ideation, but full execution planning - From brainstorming → research → actionable plan 2. **Advanced Agent Architecture** - ReAct-style reasoning loop - Multi-tool orchestration - Context-aware decision making 3. **Real-World Integration** - Live web search (not mocked) - Actual Amazon product links - Page content extraction 4. **User-Centric Design** - Timeline-based action plans - Ready-to-use invitations - Specific product recommendations 5. **Production-Ready Code** - Error handling and fallbacks - Configurable providers - Clean architecture with separation of concerns ### Technical Innovation: - **Two MCP servers** working in harmony - **ReAct agent** with 4 specialized tools - **Smart filtering** to avoid irrelevant results - **Context passing** between ideation and research phases --- **Built with ❤️ for [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)** *Powered by Gradio, Anthropic MCP, Nebius, DuckDuckGo, and our amazing sponsors!*