# 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
```bash
# 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) 🚀
```bash
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)
```bash
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
```bash
python3 main.py
```

### Option 4: Legacy HTTP Server
```bash
python3 http_server.py --host 0.0.0.0 --port 8000
```

### Option 5: Demonstration Mode
```bash
python3 main.py --demo
```

### Option 6: Run Tests
```bash
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
```bash
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "search_countries", "params": {"query": "Brazil", "limit": 5}}'
```

#### Streaming API Call
```bash
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
```bash
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`:

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

```json
{
  "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)
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
python3 http_server.py --reload
```

### Production
```bash
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
```json
{
  "method": "search_countries",
  "params": {
    "query": "Brazil",
    "limit": 10
  }
}
```

**Example 2**: Search countries with "South America" (region) and limit of 5
```json
{
  "method": "search_countries",
  "params": {
    "query": "South America",
    "limit": 5
  }
}
```

**Example 3**: Search countries with "Americas" (region) and limit of 3
```json
{
  "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"
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "method": "get_popular_destinations",
  "params": {
    "limit": 5
  }
}
```

#### 7. Function: get_user_travel_history

**Example**: Get user travel history with user_id "user123"
```json
{
  "method": "get_user_travel_history",
  "params": {
    "user_id": "user123"
  }
}
```

#### 8. Function: get_server_statistics

**Example**: Get server statistics (no parameters required)
```json
{
  "method": "get_server_statistics",
  "params": {}
}
```

### Usage via HTTP API

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

```bash
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:

```bash
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.*