Country Explorer MCP Server

# MCP Demo: Country Explorer with LangGraph <p align="center"> <img src="https://github.com/AI-Maker-Space/LLM-Dev-101/assets/37101144/d1343317-fa2f-41e1-8af1-1dbb18399719" width="200px" height="auto"/> </p> ## 🌍 Country Explorer: MCP + LangGraph Integration This project demonstrates a complete **MCP (Model Context Protocol) server** integrated with **LangGraph** to create beautiful country profiles with embedded images. ## ✨ Features - 🔍 **MCP Server** with Unsplash Search API integration - 🤖 **LangGraph Agent** for intelligent country exploration - 🖼️ **10 Images per Country** with photographer credits - 📄 **Beautiful Markdown Profiles** with embedded images - 🧪 **Comprehensive Test Suite** for validation - 📁 **Organized Project Structure** with `profiles/` and `tests/` folders ## 🏗️ Project Structure ``` mcp-demo/ ├── country_explorer.py # Main LangGraph app (10 images) ├── server.py # MCP server with Unsplash API ├── profiles/ # 📁 Generated country profiles │ ├── india_profile.md │ ├── japan_profile.md │ ├── uganda_profile.md │ └── usa_profile.md ├── tests/ # 📁 Test files │ ├── test_country_explorer.py │ ├── test_unsplash.py │ └── search_5_mountains.py └── .env # API keys ``` ## 🚀 Quick Start ### Prerequisites - Python 3.13+ - Unsplash API key - OpenAI API key ### Installation 1. **Clone the repository**: ```bash git clone https://github.com/anilsharmay/mcp-demo.git cd mcp-demo ``` 2. **Install dependencies**: ```bash uv sync ``` 3. **Configure environment variables**: Create `.env` file with your API keys: ```bash UNSPLASH_API_KEY=your_unsplash_api_key_here OPENAI_API_KEY=your_openai_api_key_here TAVILY_API_KEY=your_tavily_api_key_here ``` ### Running the Country Explorer 1. **Start the MCP server**: ```bash uv run mcp dev server.py ``` 2. **Run the Country Explorer**: ```bash uv run python country_explorer.py ``` 3. **Run tests**: ```bash cd tests && uv run python test_country_explorer.py ``` ## 🎯 MCP Server Tools The MCP server provides these tools: - **`unsplash_search`**: Search for beautiful images with orientation filters - **`web_search`**: Search the web for country information - **`roll_dice`**: Roll dice with custom notation ## 🤖 LangGraph Agent The Country Explorer agent: - Researches countries using web search - Finds 10 beautiful images via Unsplash - Creates rich markdown profiles with embedded images - Includes photographer credits and links ## 📸 Sample Output Each country profile includes: - **Cultural information** and history - **Geographic details** and landmarks - **10 high-quality images** with credits - **Clean markdown formatting** for easy viewing ### 🎬 Demo GIFs **India Profile:**  **Switzerland Profile:**  **USA Profile:**  ## 🧪 Testing Run the comprehensive test suite: ```bash # Test MCP server uv run python tests/test_unsplash.py # Test Country Explorer cd tests && uv run python test_country_explorer.py # Test mountain search uv run python tests/search_5_mountains.py ``` ## 🔧 MCP Configuration Add to your Cursor MCP settings: ```json { "mcpServers": { "unsplash-mcp-server": { "command": "uv", "args": ["--directory", ".", "run", "server.py"] } } } ``` ## 📚 Technologies Used - **MCP (Model Context Protocol)** - Server framework - **LangGraph** - Agent orchestration - **LangChain MCP Adapters** - Tool integration - **Unsplash API** - Image search - **OpenAI GPT-4** - Language model - **Python 3.13** - Runtime environment ## 🎉 Showcase This project demonstrates: - ✅ **MCP Server Development** with custom API integration - ✅ **LangGraph Agent Creation** with tool orchestration - ✅ **Beautiful Output Generation** with embedded images - ✅ **Clean Project Organization** and testing - ✅ **Real-world Application** of AI agent frameworks **Perfect for showcasing MCP + LangGraph integration!** 🌍✨