README.md•4.11 kB
# 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
## 🧪 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!** 🌍✨