Travel Advisor AI 🌍✈️

An intelligent travel recommendation system built with Clean Architecture, Python 3, AI Agents, and HTTP Streamable MCP Protocol.

🎯 Project Overview

Travel Advisor AI is a sophisticated travel recommendation system that answers complex queries like:

"I want to travel with $4000, to a warm destination, safe, where the local currency is weaker than USD."

The system integrates multiple public APIs through HTTP streamable endpoints, uses intelligent agents for contextual analysis, and provides personalized travel recommendations with real-time streaming based on climate, currency exchange rates, safety, and budget constraints.

🚀 New Features - HTTP Streamable Protocol

• Real-time Streaming: Server-Sent Events (SSE) for live progress updates
• HTTP REST API: Easy integration with web applications and mobile apps
• Auto-generated Documentation: Interactive API docs at /docs
• Health Monitoring: Built-in health checks and service status
• CORS Support: Cross-origin requests enabled for web integration
• No Complex Handshake: Direct HTTP calls without MCP initialization

🏗️ Architecture & Methodologies

Clean Architecture Implementation

This project follows Clean Architecture principles with clear separation of concerns:

src/
├── domain/           # Business entities and rules (innermost layer)
│   ├── entities/     # Core business objects
│   ├── repositories/ # Abstract interfaces
│   └── value_objects/# Domain value objects
├── application/      # Use cases and application services
│   ├── services/     # Application services
│   └── use_cases/    # Business use cases
├── infrastructure/   # External concerns (outermost layer)
│   ├── adapters/     # External service implementations
│   └── container.py  # Dependency injection
└── presentation/     # UI and controllers
    ├── controllers/  # Request handlers
    └── ui/          # User interfaces

SOLID Principles Applied

• Single Responsibility: Each class has one reason to change
• Open/Closed: Open for extension, closed for modification
• Liskov Substitution: Interfaces can be substituted by implementations
• Interface Segregation: Small, focused interfaces
• Dependency Inversion: Depend on abstractions, not concretions

Design Patterns

• Repository Pattern: Data access abstraction
• Dependency Injection: Loose coupling between components
• Strategy Pattern: Multiple recommendation algorithms
• Factory Pattern: Object creation abstraction
• Observer Pattern: Event-driven architecture

🚀 Features

Core Functionality

• ✅ Multi-factor Analysis: Climate, currency, safety, and distance
• ✅ Personalized Recommendations: Budget-based intelligent suggestions
• ✅ Real-time Data: Live weather, exchange rates, and country information
• ✅ Persistent Storage: SQLite database for recommendations and history
• ✅ Rich CLI Interface: Interactive console with beautiful formatting
• ✅ HTTP/REST API: Web-accessible endpoints
• ✅ MCP Protocol: Native MCP server implementation

Technical Features

• ✅ Comprehensive Testing: Unit, integration, and end-to-end tests
• ✅ Type Safety: Full type hints with mypy support
• ✅ Error Handling: Robust error handling and fallbacks
• ✅ Async/Await: Asynchronous programming throughout
• ✅ Code Quality: Black formatting, flake8 linting
• ✅ Documentation: Comprehensive docstrings and comments

🌐 API Integrations

MCP Servers

• Countries Service: RestCountries API + geolocation data
• Currency Service: ExchangeRate API for real-time rates
• Climate Service: Open-Meteo API for weather data

External APIs Used

• RestCountries: Country information and geographical data
• ExchangeRate API: Currency exchange rates (free tier)
• Open-Meteo: Weather and meteorological data (no API key required)

📦 Installation

Prerequisites

• Python 3.11 or higher
• pip package manager

Setup

# Clone the repository
git clone <repository-url>
cd travelling_mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

🎮 Usage

Option 1: MCP Server (Native Protocol) 🚀

python3 mcp_travel_server.py

• Protocol: Native MCP over stdio
• Usage: For MCP-compatible clients (Claude Desktop, Cline, etc.)
• Features: Full MCP protocol support, tool calls, resources

Option 2: HTTP Streamable Server (Web API)

python3 http_server.py --host 0.0.0.0 --port 8000

• URL: http://localhost:8000
• Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Streaming: http://localhost:8000/stream
• Features: Real-time streaming, auto-docs, CORS support

Option 3: Interactive Console

python3 main.py

Option 4: Legacy HTTP Server

python3 http_server.py --host 0.0.0.0 --port 8000

Option 5: Demonstration Mode

python3 main.py --demo

Option 6: Run Tests

python3 main.py --test
# or
python3 run_tests.py

🌐 HTTP Streamable API Endpoints

Core Endpoints

• GET / - Server information and available endpoints
• GET /health - Health check and service status
• GET /tools - List all available tools/functions
• POST /mcp - Direct MCP tool calls (JSON-RPC style)
• POST /stream - Streaming responses with Server-Sent Events
• GET /resources/{path} - Access MCP resources (countries, regions)

Example Usage

Direct API Call

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "search_countries", "params": {"query": "Brazil", "limit": 5}}'

Streaming API Call

curl -X POST http://localhost:8000/stream \
  -H "Content-Type: application/json" \
  -d '{"method": "get_travel_recommendations", "params": {"user_id": "user123", "budget": 4000}}' \
  --no-buffer

Health Check

curl http://localhost:8000/health

🔧 MCP Client Configuration

The server can be used with MCP-compatible clients like Claude Desktop, Cline, or other MCP clients. Here are configuration examples:

Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "travel-server": {
      "command": "/usr/bin/python3",
      "args": [
        "/home/matheus/projetos_praticos/travelling_mcp/mcp_travel_server.py"
      ],
      "cwd": "/home/matheus/projetos_praticos/travelling_mcp"
    }
  }
}

Note: The MCP server uses the native MCP protocol over stdio, not HTTP. This is the correct way to integrate with MCP clients.

Cline/VSCode MCP Configuration

Add to your Cline MCP settings:

{
  "mcpServers": {
    "travel-server": {
      "command": "python3",
      "args": [
        "/path/to/your/travelling_mcp/mcp_travel_server.py"
      ],
      "cwd": "/path/to/your/travelling_mcp",
      "env": {
        "PYTHONPATH": "/path/to/your/travelling_mcp"
      }
    }
  }
}

Direct Execution Methods

The project provides two different MCP server implementations for different use cases:

1. Native MCP Server (stdio protocol)

# Run native MCP server with stdio protocol for MCP clients
python3 mcp_travel_server.py

Use case: Integration with MCP-compatible clients (Claude Desktop, etc.) Protocol: Native MCP over stdio Communication: Standard input/output streams

2. Streamable HTTP MCP Server

# Run MCP server with HTTP transport for web integration
python3 mcp_travel_server_proper.py --port 8000 --host 0.0.0.0

Use case: Web applications, REST API clients, HTTP-based integrations Protocol: MCP over Streamable HTTP Communication: HTTP POST/GET requests Endpoints:

• Root: http://localhost:8000/ - Server information
• Health: http://localhost:8000/health - Health check
• MCP: http://localhost:8000/mcp - MCP protocol endpoint

3. Legacy HTTP Server (deprecated)

# Run legacy HTTP server for web/REST API access
python3 http_server.py --host 0.0.0.0 --port 8000

Note: This is the legacy implementation. Use option 2 for new integrations.

4. Using the Main Module

# From project directory
python3 -m mcp_travel_server

🔧 Server Comparison

Feature	Native MCP (stdio)	Streamable HTTP MCP	Legacy HTTP
File	mcp_travel_server.py	mcp_travel_server_proper.py	http_server.py
Protocol	MCP over stdio	MCP over HTTP	Custom REST API
Use Case	MCP clients	Web applications	Legacy integrations
Communication	stdin/stdout	HTTP requests	HTTP requests
MCP Compatible	✅ Full	✅ Full	❌ No
Web Integration	❌ No	✅ Yes	✅ Yes
Documentation	-	Auto-generated	Manual
Real-time	✅ Yes	✅ Yes	❌ Limited

📁 Project Structure

Root Level Files

travelling_mcp/
├── main.py                      # Main application entry point
├── mcp_travel_server.py         # Native MCP Server (stdio protocol)
├── mcp_travel_server_proper.py  # Streamable HTTP MCP Server
├── http_server.py               # Legacy HTTP/REST API server
├── start_server.py              # Server launcher utility
├── demo.py                      # Demonstration script
├── test_apis.py                 # API testing utilities
├── run_tests.py                 # Test runner
├── requirements.txt             # Python dependencies
├── pytest.ini                  # Pytest configuration
├── .coveragerc                  # Coverage configuration
└── README.md                    # This file

Core Modules

MCP Servers (mcp_servers/)

• countries_server.py: Country data and geographical information
• currency_server.py: Exchange rates and purchasing power analysis
• climate_server.py: Weather data and climate information

Intelligent Agent (agent/)

• travel_agent.py: AI agent for contextual travel recommendations

Database Layer (database/)

• travel_database.py: SQLite database operations and data persistence

Services Layer (services/)

• travel_service.py: Business logic coordination

Controllers (controllers/)

• travel_controller.py: Request handling and response formatting

User Interface (ui/)

• console_interface.py: Rich CLI interface with interactive menus

Clean Architecture (src/)

• Domain Layer: Core business logic and entities
• Application Layer: Use cases and application services
• Infrastructure Layer: External integrations and adapters
• Presentation Layer: Controllers and user interfaces

Testing (tests/)

• Unit Tests: Individual component testing
• Integration Tests: Component interaction testing
• End-to-End Tests: Full system workflow testing

Data Storage (data/)

• cache/: Temporary data storage
• queries/: Query history and indexing

🧪 Testing

Test Coverage

• 42 Tests: Comprehensive test suite
• Unit Tests: Database, services, controllers, agents
• Integration Tests: End-to-end workflows, HTTP server, MCP server
• Mocking: External API calls mocked for reliability

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test categories
pytest tests/unit/          # Unit tests only
pytest tests/integration/   # Integration tests only

🔧 Configuration

Environment Variables

# Optional: Set custom API endpoints
export COUNTRIES_API_URL="https://restcountries.com/v3.1"
export EXCHANGE_API_URL="https://api.exchangerate-api.com/v4/latest"
export WEATHER_API_URL="https://api.open-meteo.com/v1"

Database Configuration

• Default: SQLite database (travel_recommendations.db)
• Location: Project root directory
• Auto-creation: Database and tables created automatically

🚀 Deployment

Development

python3 http_server.py --reload

Production

python3 http_server.py --host 0.0.0.0 --port 8000

Docker Support

Docker configuration files are available but currently unused:

• Dockerfile: Container configuration
• docker-compose.yml: Multi-service orchestration
• docker-entrypoint.sh: Container entry point

📊 API Endpoints

HTTP Server Endpoints

• GET /: API information and status
• GET /health: Health check with service status
• GET /tools: Available MCP tools
• POST /mcp: MCP protocol endpoint
• POST /stream: Streaming MCP responses
• GET /resources/{path}: MCP resources

MCP Tools

• get_travel_recommendations: Get personalized travel suggestions
• search_countries: Search and filter countries
• get_weather_forecast: Weather data for locations
• convert_currency: Currency conversion
• analyze_purchasing_power: Purchasing power analysis
• get_user_travel_history: User query history
• get_popular_destinations: Popular destination statistics
• get_server_statistics: System statistics

🛠️ MCP Server Function Examples

The following examples demonstrate how to use the MCP server functions. These can be called through MCP-compatible clients or via the HTTP API endpoints.

Main Functions

1. Function: search_countries

Example 1: Search countries with "Brazil" and limit of 10

{
  "method": "search_countries",
  "params": {
    "query": "Brazil",
    "limit": 10
  }
}

Example 2: Search countries with "South America" (region) and limit of 5

{
  "method": "search_countries",
  "params": {
    "query": "South America",
    "limit": 5
  }
}

Example 3: Search countries with "Americas" (region) and limit of 3

{
  "method": "search_countries",
  "params": {
    "query": "Americas",
    "limit": 3
  }
}

2. Function: get_travel_recommendations

Example: Get travel recommendations with user_id "user123", budget 3000, duration 10, preferences ["tropical climate", "beach", "culture activities"] and origin_country "Brazil"

{
  "method": "get_travel_recommendations",
  "params": {
    "user_id": "user123",
    "budget": 3000,
    "duration": 10,
    "preferences": {
      "climate": "tropical climate",
      "activities": ["beach", "culture activities"]
    },
    "origin_country": "Brazil"
  }
}

3. Function: get_weather_forecast

Example: Get weather forecast for Rio de Janeiro (latitude -22.9068, longitude -43.1729) for 5 days

{
  "method": "get_weather_forecast",
  "params": {
    "location": "Rio de Janeiro",
    "days": 5
  }
}

4. Function: convert_currency

Example: Convert currency from BRL to USD with amount 1000

{
  "method": "convert_currency",
  "params": {
    "from_currency": "BRL",
    "to_currency": "USD",
    "amount": 1000
  }
}

5. Function: analyze_purchasing_power

Example: Analyze purchasing power for Argentina with budget_usd 2000

{
  "method": "analyze_purchasing_power",
  "params": {
    "origin_country": "Brazil",
    "destination_country": "Argentina",
    "budget_usd": 2000
  }
}

Auxiliary Functions

6. Function: get_popular_destinations

Example: Get popular destinations with limit 5

{
  "method": "get_popular_destinations",
  "params": {
    "limit": 5
  }
}

7. Function: get_user_travel_history

Example: Get user travel history with user_id "user123"

{
  "method": "get_user_travel_history",
  "params": {
    "user_id": "user123"
  }
}

8. Function: get_server_statistics

Example: Get server statistics (no parameters required)

{
  "method": "get_server_statistics",
  "params": {}
}

Usage via HTTP API

You can call these functions via HTTP POST to the /mcp endpoint:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "search_countries", "params": {"query": "Brazil", "limit": 5}}'

For streaming responses, use the /stream endpoint:

curl -X POST http://localhost:8000/stream \
  -H "Content-Type: application/json" \
  -d '{"method": "get_travel_recommendations", "params": {"user_id": "user123", "budget": 3000}}' \
  --no-buffer

🤝 Contributing

Code Quality Standards

• Formatting: Black code formatter
• Linting: Flake8 for code quality
• Type Checking: mypy for type safety
• Testing: Pytest with high coverage requirements
• Documentation: Comprehensive docstrings

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Format code with Black
6. Submit a pull request

📈 Performance

Optimization Features

• Async/Await: Non-blocking I/O operations
• Connection Pooling: Efficient HTTP client usage
• Caching: Response caching for external APIs
• Database Indexing: Optimized query performance
• Memory Management: Efficient data structures

Monitoring

• Health Checks: Service availability monitoring
• Error Tracking: Comprehensive error logging
• Performance Metrics: Response time tracking
• Resource Usage: Memory and CPU monitoring

🔒 Security

Security Measures

• Input Validation: Pydantic models for data validation
• SQL Injection Prevention: Parameterized queries
• CORS Configuration: Controlled cross-origin access
• Error Sanitization: Safe error message exposure
• Dependency Security: Regular security updates

📚 Documentation

Additional Resources

• DEMO_RESULTS.md: Demonstration results and examples
• DADOS_TESTE_APIS.md: API testing data and examples
• deploy_guide.md: Deployment guide and best practices

Code Documentation

• Docstrings: Comprehensive function and class documentation
• Type Hints: Full type annotation coverage
• Comments: Inline code explanations
• Architecture Diagrams: Visual system overview

🎉 Acknowledgments

Technologies Used

• Python 3: Core programming language
• FastAPI: Modern web framework
• FastMCP: MCP protocol implementation
• SQLite: Embedded database
• Rich: Beautiful terminal formatting
• Pytest: Testing framework
• Pydantic: Data validation
• HTTPX: Async HTTP client

Design Principles

• Clean Architecture: Robert C. Martin's architectural pattern
• SOLID Principles: Object-oriented design principles
• Domain-Driven Design: Business logic focus
• Test-Driven Development: Quality assurance approach

---

Developed with ❤️ using Clean Architecture + Python 3 + AI Agents + MCP

For questions, issues, or contributions, please refer to the project documentation or create an issue in the repository.