Add travel mcp server and client

README.md

@@ -1,2 +1,96 @@
-# hf-mcp-2025
-Repo for Huggingface MCP hackathon 2025
+# Travel Documentation MCP Server
+
+> An AI-powered travel documentation assistant built with Gradio's MCP server capabilities and smolagents for the Hugging Face MCP Hackathon 2025.
+
+## What This Project Does
+
+This project creates an intelligent travel documentation agent that helps travelers understand what documents they need for international trips. It consists of:
+
+1. **MCP Server** (`travel_mcp_server.py`) - A Gradio interface that exposes travel documentation analysis as an MCP tool, mocking data is used for demonstration
+2. **MCP Client** (`travel_mcp_client.py`) - An AI agent that uses smolagents to interact with the MCP server and provide conversational assistance
+
+
+## Technical Implementation
+- **Gradio MCP Server**: Uses Gradio's built-in MCP server functionality
+- **smolagents Integration**: AI agent framework for tool execution and conversation
+- **Local LLM Support**: Uses Ollama for local AI inference
+
+## Installation & Setup
+
+### Prerequisites
+- Python 3.8+
+- Ollama (for local LLM)
+
+### 1. Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Set up Ollama (for the AI agent)
+```bash
+# Install Ollama from https://ollama.ai
+# Pull the required model
+ollama pull gemma3:4b
+```
+
+### 3. Start the MCP Server
+```bash
+python travel_mcp_server.py
+```
+The server will start at `http://127.0.0.1:7861` with MCP endpoint at `http://127.0.0.1:7861/gradio_api/mcp/sse`
+
+### 4. Start the AI Agent Client
+```bash
+python travel_mcp_client.py
+```
+
+## Usage
+
+### Direct Web Interface
+Visit `http://127.0.0.1:7861` to use the travel documentation tool directly:
+
+**Input Parameters:**
+- **Your Citizenship Country**: e.g., "Canada", "China", "India"
+- **Destination Country**: e.g., "Japan", "USA", "Germany"
+- **Trip Duration**: Number of days (1-365)
+- **Trip Purpose**: tourism, business, study, transit, work, family visit
+
+**Example Output:**
+```json
+{
+  "trip_info": {
+    "from_country": "Canada",
+    "to_country": "Japan",
+    "duration_days": 30,
+    "purpose": "Tourism"
+  },
+  "visa_requirements": {
+    "visa_required": false,
+    "max_stay": "90 days"
+  },
+  "required_documents": [
+    {
+      "document_type": "Passport",
+      "required": true,
+      "description": "Valid passport with at least 6 months validity remaining"
+    }
+  ],
+  "summary": {
+    "required_count": 5,
+    "optional_count": 1,
+    "visa_needed": false
+  }
+}
+```
+
+### AI Agent Chat Interface
+Use the conversational agent for natural language queries:
+
+**Example Conversations:**
+```
+User: "I'm a Canadian citizen planning to visit Japan for 2 weeks for tourism"
+Agent: "..."
+
+User: "What documents do I need for business travel from China to USA?"
+Agent: "..."
+```

mcp_config.json

@@ -0,0 +1,11 @@
+{
+  "servers": {
+    "travel-docs": {
+      "command": "python",
+      "args": ["travel_docs_server.py"],
+      "env": {
+        "PYTHONPATH": "."
+      }
+    }
+  }
+}

requirements.txt

@@ -0,0 +1,5 @@
+mcp
+gradio[mcp]
+smolagents
+smolagents[mcp]
+fastmcp

setup.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Setup script for Travel Documentation MCP Server
+
+echo "Setting up Travel Documentation MCP Server"
+echo "=============================================="
+
+# Check Python version
+python_version=$(python3 --version 2>&1)
+echo "Python version: $python_version"
+
+# Install dependencies
+echo "Installing dependencies..."
+pip3 install -r requirements.txt
+
+
+echo "Setup complete!"
+echo ""
+echo "To run the applications:"
+echo "  MCP Server: python travel_mcp_server.py"
+echo "  MCP Client with Agent: python travel_mcp_client.py"
+echo ""
+echo "Access the web interface at: http://127.0.0.1:7860"

travel_mcp_client.py

@@ -0,0 +1,50 @@
+import gradio as gr
+
+from smolagents import CodeAgent, tool, LiteLLMModel
+from smolagents.mcp_client import MCPClient
+
+@tool
+def self_introduction() -> str:
+    """
+    Provides information about the agent's identity and capabilities.
+    
+    This tool should be triggered when the user asks questions like:
+    - "What's your name?"
+    - "Who are you?"
+    - "What can you do?"
+    - "Tell me about yourself"
+    - "What are your capabilities?"
+    - Any other introductory or identity-related queries
+    
+    Returns:
+        str: A friendly introduction explaining the agent's purpose and capabilities. You are free to rewrite the introduction but need to keep the same meaning.
+    """
+    return "Hello! I am your travel documentation Agent. I can help you find out what documetations are required for your trip, get me your original coutry, destionation country, trip duration and purpose and I can help you."
+
+
+mcp_client = MCPClient(
+        {"url": "http://127.0.0.1:7861/gradio_api/mcp/sse"}
+    )
+
+try:
+    tools = mcp_client.get_tools()
+
+    # for local testing
+    model = LiteLLMModel(
+        model_id="ollama_chat/gemma3:4b",
+        api_base="http://127.0.0.1:11434",
+        num_ctx=8192,
+    )
+    agent = CodeAgent(tools=[*tools], model=model)
+
+    demo = gr.ChatInterface(
+        fn=lambda message, history: str(agent.run(message)),
+        type="messages",
+        examples=["Your trip plan..."],
+        title="Travel documentation agent",
+        description="This is a simple agent that uses MCP tools to help you find out required documentations for your international trip.",
+    )
+
+    demo.launch()
+finally:
+    mcp_client.disconnect()

travel_mcp_server.py

@@ -0,0 +1,208 @@
+import gradio as gr
+from typing import Dict, List, Any
+
+class TravelDocumentationService:
+    """Service for fetching travel documentation requirements"""
+        
+    def get_visa_requirements(
+        self, 
+        from_country: str, 
+        to_country: str, 
+        trip_duration: int = 30
+    ) -> Dict[str, Any]:
+        """Get visa requirements for travel between countries"""
+        
+        # Mock data
+        visa_free_combinations = {
+            ("canada", "japan"): {"visa_required": False, "max_stay": "90 days"},
+            ("canada", "uk"): {"visa_required": False, "max_stay": "6 months"},
+            ("canada", "usa"): {"visa_required": False, "max_stay": "6 months"},
+            ("canada", "germany"): {"visa_required": False, "max_stay": "90 days"},
+            ("usa", "japan"): {"visa_required": False, "max_stay": "90 days"},
+            ("usa", "uk"): {"visa_required": False, "max_stay": "6 months"},
+            ("usa", "germany"): {"visa_required": False, "max_stay": "90 days"},
+            ("china", "japan"): {"visa_required": True, "visa_type": "Tourist Visa", "max_stay": "30 days", "processing_time": "5-7 business days", "fee": "$30 USD"},
+            ("india", "japan"): {"visa_required": True, "visa_type": "Tourist Visa", "max_stay": "90 days", "processing_time": "5-10 business days", "fee": "$50 USD"},
+            ("china", "usa"): {"visa_required": True, "visa_type": "B-2 Tourist Visa", "max_stay": "6 months", "processing_time": "3-5 weeks", "fee": "$160 USD"},
+            ("india", "usa"): {"visa_required": True, "visa_type": "B-2 Tourist Visa", "max_stay": "6 months", "processing_time": "3-5 weeks", "fee": "$160 USD"},
+        }
+        
+        key = (from_country.lower(), to_country.lower())
+        
+        if key in visa_free_combinations:
+            return visa_free_combinations[key]
+        else:
+            return {
+                "visa_required": True,
+                "visa_type": "Tourist Visa",
+                "max_stay": "30 days",
+                "processing_time": "5-10 business days",
+                "fee": "$50-150 USD"
+            }
+    
+    def get_document_requirements(
+        self,
+        from_country: str,
+        to_country: str,
+        trip_duration: int = 30,
+        trip_purpose: str = "tourism"
+    ) -> List[Dict[str, Any]]:
+        """Get comprehensive document requirements for travel"""
+        
+        requirements = []
+        
+        requirements.append({
+            "document_type": "Passport",
+            "required": True,
+            "description": "Valid passport with at least 6 months validity remaining",
+            "validity_period": "At least 6 months from travel date",
+            "additional_notes": "Must have at least 2 blank pages for stamps"
+        })
+        
+        visa_info = self.get_visa_requirements(from_country, to_country, trip_duration)
+        
+        if visa_info.get("visa_required", False):
+            requirements.append({
+                "document_type": "Visa",
+                "required": True,
+                "description": f"Required {visa_info.get('visa_type', 'Tourist Visa')}",
+                "processing_time": visa_info.get("processing_time", "5-10 business days"),
+                "additional_notes": f"Fee: {visa_info.get('fee', 'Varies by embassy')}"
+            })
+        
+        insurance_required_countries = ["schengen", "germany", "france", "italy", "spain", "netherlands", "austria", "belgium"]
+        if to_country.lower() in insurance_required_countries:
+            requirements.append({
+                "document_type": "Travel Insurance",
+                "required": True,
+                "description": "Travel insurance with minimum €30,000 coverage",
+                "additional_notes": "Required for Schengen area countries"
+            })
+        else:
+            requirements.append({
+                "document_type": "Travel Insurance",
+                "required": False,
+                "description": "Travel insurance (highly recommended)",
+                "additional_notes": "Covers medical emergencies, trip cancellation, etc."
+            })
+        
+        requirements.append({
+            "document_type": "Return/Onward Ticket",
+            "required": True,
+            "description": "Proof of return or onward travel",
+            "additional_notes": "Flight confirmation or travel itinerary"
+        })
+        
+        financial_amount = "$100-150 per day" if to_country.lower() in ["japan", "switzerland", "norway"] else "$50-100 per day"
+        requirements.append({
+            "document_type": "Financial Proof",
+            "required": True,
+            "description": f"Proof of sufficient funds ({financial_amount})",
+            "additional_notes": "Bank statements, credit cards, or traveler's checks"
+        })
+        
+        requirements.append({
+            "document_type": "Accommodation Proof",
+            "required": True,
+            "description": "Hotel booking or invitation letter",
+            "additional_notes": "Confirmation of where you'll be staying"
+        })
+        
+        if trip_purpose.lower() == "business":
+            requirements.append({
+                "document_type": "Business Invitation Letter",
+                "required": True,
+                "description": "Letter from host company",
+                "additional_notes": "Must include company details and purpose of visit"
+            })
+        elif trip_purpose.lower() == "study":
+            requirements.append({
+                "document_type": "Student Visa/Permit",
+                "required": True,
+                "description": "Student visa or study permit",
+                "additional_notes": "Issued by educational institution"
+            })
+            requirements.append({
+                "document_type": "Acceptance Letter",
+                "required": True,
+                "description": "Letter of acceptance from educational institution",
+                "additional_notes": "Must be from recognized institution"
+            })
+        
+        return requirements
+
+travel_service = TravelDocumentationService()
+
+def get_requirements(from_country, to_country, trip_duration, trip_purpose):
+    """
+    Analyze the documentation requirment for user's travel plan
+
+    Args:
+        from_country (str): User's original country
+        to_country (str): The destination country that the user plans to travel to
+        trip_duration (number): The days length that the user plans to stay in the destination country
+        trip_purpose (str): The purpose of the travel, the user is go for business, tourism, study or other purposes
+
+    Returns:
+        json: Contains the comprehensive documentation requires and suggestions based on the user input
+    """
+    try:
+        requirements = travel_service.get_document_requirements(
+            from_country, to_country, int(trip_duration), trip_purpose
+        )
+        
+        visa_info = travel_service.get_visa_requirements(from_country, to_country, int(trip_duration))
+        
+        required_docs = [req for req in requirements if req['required']]
+        optional_docs = [req for req in requirements if not req['required']]
+        
+        result = {
+            "trip_info": {
+                "from_country": from_country.title(),
+                "to_country": to_country.title(),
+                "duration_days": int(trip_duration),
+                "purpose": trip_purpose.title()
+            },
+            "visa_requirements": {
+                "visa_required": visa_info.get("visa_required", False),
+                "visa_type": visa_info.get("visa_type"),
+                "max_stay": visa_info.get("max_stay"),
+                "processing_time": visa_info.get("processing_time"),
+                "fee": visa_info.get("fee")
+            },
+            "required_documents": required_docs,
+            "optional_documents": optional_docs,
+            "total_documents": len(requirements),
+            "summary": {
+                "required_count": len(required_docs),
+                "optional_count": len(optional_docs),
+                "visa_needed": visa_info.get("visa_required", False)
+            }
+        }
+        
+        return result
+        
+    except Exception as e:
+        return {"error": str(e)}
+
+
+travel_demo = gr.Interface(
+    fn=get_requirements,
+    inputs=[
+        gr.Textbox(label="Your Citizenship Country", placeholder="e.g., Canada", value="Canada"),
+        gr.Textbox(label="Destination Country", placeholder="e.g., Japan", value="Japan"),
+        gr.Number(label="Trip Duration (days)", value=30, minimum=1, maximum=365),
+        gr.Dropdown(label="Trip Purpose", choices=["tourism", "business", "transit", "study", "work", "family visit"], value="tourism")
+    ],
+    outputs=gr.JSON(),
+    title="Travel Documentation Requirements",
+    description="Get the comprehensive travel documentation requirements for international travel"
+)
+
+if __name__ == "__main__":
+    travel_demo.launch(
+        # share=True,
+        show_error=True,
+        mcp_server=True,
+        server_port=7861
+    )