anilsharmay/mcp-demo

MCP Demo: Country Explorer with LangGraph

🌍 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:

   git clone https://github.com/anilsharmay/mcp-demo.git
   cd mcp-demo
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables: Create .env file with your API keys:

   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:

   uv run mcp dev server.py
   

2. Run the Country Explorer:

   uv run python country_explorer.py
   

3. Run tests:

   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:

# 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:

{
  "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! 🌍✨