# Wisnu MCP - Travel Booking Server 🌍

A Model Context Protocol (MCP) server for travel booking operations, built with [FastMCP](https://gofastmcp.com/).

## Features

This MCP server provides the following tools for travel booking:

### Available Tools

1. **search_flights** - Search for available flights
   - Origin/destination airport codes
   - Departure and optional return dates
   - Passenger count and cabin class selection

2. **search_hotels** - Search for hotels in a location
   - Location-based search
   - Check-in/check-out dates
   - Guest count, room requirements, and rating filters

3. **search_destinations** - Get destination recommendations
   - Interest-based suggestions (beach, culture, adventure, food, etc.)
   - Budget range filtering
   - Seasonal preferences

4. **calculate_trip_cost** - Estimate total trip costs
   - Flight and hotel cost inputs
   - Daily expense calculations
   - Per-person cost breakdown

5. **get_travel_tips** - Get travel tips for destinations
   - Destination-specific advice
   - Trip type considerations (business, leisure, adventure, family)

## Installation

This project uses [uv](https://astral.sh/uv) for dependency management.

### Prerequisites

- Python 3.13+
- uv package manager

### Setup

1. Clone or navigate to this repository:
```bash
cd wisnu-mcp
```

2. The virtual environment and dependencies are already set up. If you need to reinstall:
```bash
uv sync
```

## Usage

### Running the Server

Start the MCP server with:

```bash
uv run main.py
```

Or if you want to run it directly with Python:

```bash
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python main.py
```

### Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wisnu-travel": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/adrian/Dev/@wisatabook/wisnu-mcp",
        "run",
        "main.py"
      ]
    }
  }
}
```

After updating the configuration, restart Claude Desktop.

### Testing the Server

You can test individual tools by modifying [main.py](main.py) to call them directly:

```python
if __name__ == "__main__":
    # Test a tool
    result = search_flights(
        origin="JFK",
        destination="LHR",
        departure_date="2024-06-15",
        return_date="2024-06-22",
        passengers=2
    )
    print(result)

    # Or run the server
    # mcp.run()
```

## Development

### Project Structure

```
wisnu-mcp/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock             # Locked dependency versions
├── README.md           # This file
└── .venv/              # Virtual environment (auto-generated)
```

### Adding New Tools

To add a new tool to the MCP server:

1. Define a new function in [main.py](main.py)
2. Decorate it with `@mcp.tool()`
3. Add comprehensive docstrings (they become tool descriptions)
4. Use type hints for all parameters

Example:

```python
@mcp.tool()
def search_car_rentals(
    location: str,
    pickup_date: str,
    return_date: str,
    car_type: Literal["economy", "compact", "suv", "luxury"] = "economy"
) -> dict:
    """
    Search for available car rentals.

    Args:
        location: Pickup location
        pickup_date: Pickup date in YYYY-MM-DD format
        return_date: Return date in YYYY-MM-DD format
        car_type: Type of car needed

    Returns:
        Dictionary with car rental search results
    """
    return {
        "location": location,
        "pickup_date": pickup_date,
        "return_date": return_date,
        "car_type": car_type,
        "status": "success"
    }
```

### Adding Dependencies

To add new Python packages:

```bash
uv add package-name
```

For example, to add a real flight API client:

```bash
uv add amadeus
```

## Next Steps

The current implementation provides mock responses. To build a production-ready travel booking system:

1. **Integrate Real APIs**: Connect to actual flight, hotel, and destination APIs
   - [Amadeus API](https://developers.amadeus.com/) for flights and hotels
   - [Skyscanner API](https://www.partners.skyscanner.net/) for comprehensive travel search
   - [Booking.com API](https://developers.booking.com/) for accommodations

2. **Add Resources**: Use FastMCP's `@mcp.resource()` decorator to expose travel data

3. **Add Prompts**: Create `@mcp.prompt()` templates for common travel queries

4. **Error Handling**: Implement robust error handling for API failures

5. **Caching**: Add caching for frequently searched routes/destinations

6. **Authentication**: Add API key management for external services

7. **Testing**: Add unit and integration tests

## Resources

- [FastMCP Documentation](https://gofastmcp.com/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [uv Documentation](https://docs.astral.sh/uv/)

## License

MIT