# Comprehensive Travel & Hospitality MCP Server (`hotel_search`)

A unified **FastMCP** server providing parallel hotel accommodations, gourmet dining and cafe searches (Tabelog Japan), multi-modal transit & routing, and verified traveler/diner reviews across global and regional platforms.

## Key Capabilities

### 🏨 Accommodations & Hotels
- 🔄 **Parallel Multi-Provider Search**: Query Agoda, Booking.com, and Hotels.com simultaneously with `search_hotels(..., provider="all")`.
- 🔑 **Silent Chrome Authentication**: Seamlessly loads user sessions for Agoda (VIP tier), Booking.com (Genius tier), and Hotels.com (OneKey rewards).
- ⚖️ **Cross-Platform Price Comparison**: Compare live rates across all three platforms in parallel using `compare_hotel_prices(...)` to find the cheapest provider.
- 🛏️ **Room Grid & Rate Packages**: Inspect bed configurations, room sizes, breakfast inclusions, cancellation policies, and rates.

### 🍽️ Dining, Restaurants & Cafes (Tabelog Japan)
- 🍣 **Gourmet Search & Ranking**: Search restaurants with Bayesian score curves (`>=3.50` top 3%, `>=4.00` legendary/Michelin tier) via `search_restaurants(...)` / `search_tabelog(...)`.
- 🏆 **Award Winner Highlights**: Filter and highlight *The Tabelog Award* winners (Gold, Silver, Bronze) and *Tabelog 100 Famous Stores* (*Hyakumeiten*).
- 🍱 **Budget & Amenities**: Separate lunch vs. dinner budgets, multilingual menus, private dining rooms, and barrier-free access.
- 📅 **Live Vacancy Calendar**: Check open reservation dates via `check_restaurant_reservation(...)`.

### 🧭 Multi-Modal Transit & Navigation
- 🚶🚇🚕 **Directions & Fares**: Calculate walking routes, public transit (subway/bus line names and transfers), and taxi fares via `get_transit_and_directions(...)`.

### ⭐ Verified Place Reviews
- 💬 **Cross-Platform Reviews**: Retrieve review scores, star distributions, and traveler feedback from Google Reviews, Kakao Maps, and Tabelog via `get_place_reviews(...)`.

---

## Project Structure

```text
hotels-mcp/
├── pyproject.toml        # PEP 517/518 build config, dependencies & CLI entrypoints
├── README.md             # Documentation & usage guide
├── AGENTS.md             # Agent guidelines & GitNexus code intelligence
├── CLAUDE.md             # Claude developer instructions
├── tests/
│   ├── __init__.py
│   └── test_server.py    # 17 live multi-provider integration test suites
└── src/
    └── travel_mcp/
        ├── __init__.py   # Package root
        ├── __main__.py   # CLI entrypoint (`python -m travel_mcp`)
        ├── server.py     # FastMCP server instance, tools, prompts & resources
        ├── models.py     # Normalized Pydantic DTOs for travel, dining, and transit
        └── providers/
            ├── __init__.py         # Unified provider factory & registry
            ├── accommodations/     # Hotel accommodation providers
            │   ├── __init__.py
            │   ├── base.py         # HotelProvider ABC & session loader
            │   ├── agoda.py        # Agoda accommodation provider
            │   ├── booking.py      # Booking.com accommodation provider
            │   └── hotels_com.py   # Hotels.com accommodation provider
            ├── dining/             # Restaurant & cafe providers
            │   ├── __init__.py     # Dining provider factory
            │   ├── base.py         # DiningProvider ABC
            │   └── tabelog.py      # Tabelog client & vacancy parser
            ├── routes/             # Multi-modal routing providers
            │   ├── __init__.py     # Route provider factory
            │   ├── base.py         # RouteProvider ABC
            │   └── kakao.py        # Kakao Maps routing provider
            └── reviews/            # Unified place review providers
                ├── __init__.py     # Review provider registry
                ├── base.py         # ReviewProvider ABC
                ├── agoda.py        # Agoda reviews provider
                ├── google.py       # Google Reviews provider
                ├── kakao.py        # Kakao Place reviews provider
                └── tabelog.py      # Tabelog reviews provider
```

---

## Installation & Setup

```bash
cd /Users/richardluo/Developer/hotels-mcp
uv sync
```

### Run Tests:
```bash
uv run python tests/test_server.py
```

### Run Server:
```bash
uv run travel-mcp
# or
uv run python -m travel_mcp
```

---

## Antigravity / MCP Configuration

Add to `~/.gemini/config/mcp_config.json` or your workspace `.agents/mcp_config.json`:

```json
{
  "mcpServers": {
    "travel_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/richardluo/Developer/hotels-mcp",
        "run",
        "python",
        "-m",
        "travel_mcp"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

---

## Available Tools

### 🍽️ Dining, Restaurants & Cafes
| Tool | Parameters | Description |
|---|---|---|
| `search_restaurants` | `query, prefecture=None, area=None, genre=None, sort_by='rating', meal_type='all', provider='tabelog', page=1, limit=10` | Searches top-rated restaurants across Japan on Tabelog (tabelog.com). Includes Bayesian scores (3.5+ top 3%, 4.0+ legendary), Award winners (Gold/Silver/Bronze), Hyakumeiten (100 Famous Stores), lunch/dinner budgets, and booking status. |
| `get_restaurant_details` | `restaurant_id_or_url, provider='tabelog'` | Fetches complete restaurant profile, award history, exact address, GPS coordinates, phone, budget, amenities, and high-res food photos. |
| `suggest_dining` | `query, provider='tabelog', limit=5` | Autocompletes search keywords for restaurants, stations, areas, and food genres. |
| `check_restaurant_reservation` | `restaurant_id, provider='tabelog'` | Checks live upcoming online booking vacancy calendar and available reservation dates for a restaurant. |
| `search_tabelog` | *(same as search_restaurants)* | Direct shortcut to Tabelog restaurant search. |
| `get_tabelog_restaurant_details` | *(same as get_restaurant_details)* | Direct shortcut to Tabelog restaurant profile. |
| `suggest_tabelog` | *(same as suggest_dining)* | Direct shortcut to Tabelog autocomplete. |
| `check_tabelog_reservation` | *(same as check_restaurant_reservation)* | Direct shortcut to Tabelog vacancy calendar. |

### 🧭 Multi-Modal Transit & Routing
| Tool | Parameters | Description |
|---|---|---|
| `get_transit_and_directions` | `origin, destination, travel_mode='all', country='KR', provider=None` | Calculates walking steps, public transit (subway/bus lines, transfers, fares), and driving taxi fares between any two places (hotels, restaurants, cafes, stations, airports). |
| `get_hotel_distance_and_transit` | `origin, destination, travel_mode='all', country='KR', provider=None` | Alias for `get_transit_and_directions`. |

### ⭐ Place & Venue Reviews
| Tool | Parameters | Description |
|---|---|---|
| `get_place_reviews` | `place_or_hotel, provider='kakao', page=1, page_size=10` | Fetches verified user reviews, star distributions, and reviewer feedback from Kakao Maps, Google Reviews (`provider='google'`), or Tabelog (`provider='tabelog'`). |

### 🏨 Accommodations & Hotels
| Tool | Parameters | Description |
|---|---|---|
| `search_hotels` | `query, check_in, check_out, adults=2, children=0, rooms=1, min_price=None, max_price=None, provider='all', logged_in=True, limit=10` | Searches Agoda, Booking.com, and/or Hotels.com in parallel with date, occupancy, and price filters. |
| `compare_hotel_prices` | `hotel_name, check_in, check_out, adults=2, rooms=1` | Runs a 3-way parallel price check across Agoda, Booking.com, and Hotels.com to find the cheapest rate. |
| `suggest_locations` | `query, provider='all', limit=5` | Autocompletes destination cities, districts, landmarks, and properties across Agoda, Booking.com, and Hotels.com. |
| `get_property_details` | `hotel_id, provider='agoda', check_in=None, check_out=None, adults=2, children=0, rooms=1, logged_in=True` | Fetches property overview, address, amenities, and policies. |
| `get_room_grid` | `hotel_id, provider='agoda', check_in="", check_out="", adults=2, children=0, rooms=1, logged_in=True` | Inspects room types, bed setups, breakfast inclusion, cancellation policies, and rates. |
| `get_hotel_reviews` | `hotel_id, provider='agoda', page=1, page_size=10` | Fetches verified traveler reviews and category scores. |
| `get_hotel_faq` | `hotel_id, provider='agoda'` | Retrieves official verified hotel FAQs. |
| `get_login_status` | `provider='all'` | Checks active authentication for Agoda (VIP), Booking.com (Genius), and Hotels.com (OneKey). |
| `interactive_login` | `provider='agoda'` | Opens Chrome to sign-in portal if session expired (supports `'agoda'`, `'booking.com'`, or `'hotels.com'`). |

---

## MCP Prompts & Resources (MCP 2.0)

### Prompts
- `plan_trip_itinerary(destination, check_in, check_out, adults, dining_preferences)`: End-to-end trip planning combining hotels, dining recommendations, and transit routes.
- `search_japan_dining(query, prefecture, genre, meal_type)`: Discover top-rated dining spots and award winners in Japan.
- `compare_hotel_deals(hotel_name, check_in, check_out, adults, rooms)`: 3-way price comparison and perk evaluation.
- `search_destination_hotels(destination, check_in, check_out, adults, rooms)`: Search and rank accommodations.

### Resources
- `travel://providers` (and `hotels://providers`): Registry of accommodation, dining, routing, and review providers.
- `travel://capabilities`: Full capability breakdown across all travel domains.
- `travel://status` (and `hotels://status`): Live session & cookie health across all providers.