# Travel MCP Server

Travel MCP Server provides travel package management, booking functionality, and itinerary planning through Model Context Protocol (MCP) compliant endpoints.

## Installation

```
npm install
```

## Running

```
npm start
```

Server runs on `http://localhost:3002`

## Available Tools

The server provides 26 tools organized into four categories:

**Package Management (12 tools):**
- list_packages
- get_package
- search_packages
- check_availability
- compare_packages
- get_package_itinerary
- get_packages_by_destination
- get_packages_by_price_range
- get_packages_by_duration
- get_packages_by_continent
- filter_packages_by_budget
- get_package_inclusions

**Booking Management (9 tools):**
- create_booking
- get_booking
- list_bookings
- cancel_booking
- update_booking
- get_booking_status
- get_bookings_by_email
- get_bookings_by_date
- get_booking_summary

**Price Calculations (4 tools):**
- calculate_booking_price
- calculate_total_price
- calculate_discount
- compare_package_prices

**Validation (1 tool):**
- validate_booking_data

## Protocol Endpoints

### POST /

Main MCP JSON-RPC endpoint that handles protocol initialization, tool discovery, and tool execution.

**Headers:**
- `mcp-protocol-version`: Protocol version (optional, defaults to '2024-11-05')
- `mcp-session-id`: Session identifier (required after initialization)

**Methods:**

#### initialize

Initializes MCP session and returns server capabilities.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "client-name",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "Travel MCP Server Enhanced",
      "version": "2.0.0"
    }
  }
}
```

#### tools/list

Returns list of all available tools.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [...]
  }
}
```

#### tools/call

Executes a specific tool with provided arguments.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {...}
  },
  "id": 3
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "..."
      }
    ]
  }
}
```

## Available Tools

### Package Management

#### list_packages

Retrieves comprehensive list of all available travel packages with basic information.

**Parameters:** None

**Returns:** List of packages with id, name, destination, duration, price, currency, and availability status

#### get_package

Retrieves complete detailed information about a specific travel package.

**Parameters:**
- `packageId` (string, required): Unique package identifier

**Returns:** Complete package details including itinerary, inclusions, and full description

#### search_packages

Searches and filters travel packages by multiple criteria.

**Parameters:**
- `destination` (string, optional): Destination city or country name
- `minDuration` (number, optional): Minimum trip duration in days
- `maxDuration` (number, optional): Maximum trip duration in days
- `maxPrice` (number, optional): Maximum price per person in USD

**Returns:** Matching packages sorted by relevance

#### check_availability

Checks if a specific travel package is currently available for booking.

**Parameters:**
- `packageId` (string, required): Package identifier

**Returns:** Availability status boolean

#### compare_packages

Compares multiple travel packages side by side.

**Parameters:**
- `packageIds` (array, required): Array of 2-5 package IDs

**Returns:** Detailed comparison of packages

#### get_package_itinerary

Retrieves complete day-by-day itinerary for a travel package.

**Parameters:**
- `packageId` (string, required): Package identifier

**Returns:** Detailed itinerary with activities and scheduled times

#### get_packages_by_destination

Retrieves all travel packages for a specific destination.

**Parameters:**
- `destination` (string, required): Destination city or country name

**Returns:** All packages matching destination

#### get_packages_by_price_range

Retrieves packages within a specified price range.

**Parameters:**
- `minPrice` (number, required): Minimum price per person in USD
- `maxPrice` (number, required): Maximum price per person in USD

**Returns:** Packages sorted by price

#### get_packages_by_duration

Retrieves packages matching a specific duration range.

**Parameters:**
- `minDays` (number, required): Minimum trip duration in days
- `maxDays` (number, required): Maximum trip duration in days

**Returns:** Packages sorted by duration

#### get_packages_by_continent

Retrieves all packages for destinations in a specific continent.

**Parameters:**
- `continent` (string, required): Continent name (Europe, Asia, North America, South America, Africa, Oceania, Australia)

**Returns:** Packages for specified continent

#### filter_packages_by_budget

Filters packages by maximum budget amount.

**Parameters:**
- `maxBudget` (number, required): Maximum budget per person in USD

**Returns:** Packages priced at or below budget, sorted by price

#### get_package_inclusions

Retrieves list of inclusions and amenities for a package.

**Parameters:**
- `packageId` (string, required): Package identifier

**Returns:** List of inclusions

### Booking Management

#### create_booking

Creates a new confirmed booking for a travel package.

**Parameters:**
- `packageId` (string, required): Package identifier
- `travelerName` (string, required): Full name of primary traveler
- `travelerEmail` (string, required): Email address
- `travelDate` (string, required): Travel start date in YYYY-MM-DD format
- `numberOfTravelers` (number, required): Number of travelers

**Returns:** Complete booking details with booking ID

#### get_booking

Retrieves complete details of a specific booking.

**Parameters:**
- `bookingId` (string, required): Booking identifier

**Returns:** Complete booking information

#### list_bookings

Retrieves list of all bookings with optional filtering.

**Parameters:**
- `email` (string, optional): Filter by traveler email

**Returns:** List of bookings with complete details

#### cancel_booking

Cancels an existing confirmed booking.

**Parameters:**
- `bookingId` (string, required): Booking identifier

**Returns:** Updated booking with cancelled status

#### update_booking

Updates existing booking details.

**Parameters:**
- `bookingId` (string, required): Booking identifier
- `travelDate` (string, optional): New travel start date in YYYY-MM-DD format
- `numberOfTravelers` (number, optional): New number of travelers

**Returns:** Updated booking with new details

#### get_booking_status

Retrieves current status of a booking.

**Parameters:**
- `bookingId` (string, required): Booking identifier

**Returns:** Booking status and timestamps

#### get_bookings_by_email

Retrieves all bookings for a specific traveler email.

**Parameters:**
- `email` (string, required): Email address

**Returns:** All bookings associated with email

#### get_bookings_by_date

Retrieves bookings matching specific date or date range.

**Parameters:**
- `travelDate` (string, optional): Specific travel date in YYYY-MM-DD format
- `startDate` (string, optional): Start date of range in YYYY-MM-DD format
- `endDate` (string, optional): End date of range in YYYY-MM-DD format

**Returns:** Bookings filtered by date criteria

#### get_booking_summary

Retrieves concise summary of a booking.

**Parameters:**
- `bookingId` (string, required): Booking identifier

**Returns:** Essential booking information in compact format

### Price Calculations

#### calculate_booking_price

Calculates total price for a potential booking without creating it.

**Parameters:**
- `packageId` (string, required): Package identifier
- `numberOfTravelers` (number, required): Number of travelers

**Returns:** Calculated total price, price per person, and currency

#### calculate_total_price

Calculates total price based on package price and number of travelers.

**Parameters:**
- `packagePrice` (number, required): Price per person in USD
- `numberOfTravelers` (number, required): Number of travelers

**Returns:** Price breakdown with total amount

#### calculate_discount

Calculates discount amount and discounted price.

**Parameters:**
- `originalPrice` (number, required): Original price in USD
- `discountPercentage` (number, required): Discount percentage (0-100)

**Returns:** Original price, discount amount, and discounted price

#### compare_package_prices

Compares prices of multiple packages and identifies cheapest and most expensive.

**Parameters:**
- `packageIds` (array, required): Array of at least 2 package IDs

**Returns:** Price comparison with rankings

### Validation

#### validate_booking_data

Validates booking data before creating a booking.

**Parameters:**
- `packageId` (string, required): Package identifier
- `travelerEmail` (string, required): Email address to validate
- `travelDate` (string, required): Travel date in YYYY-MM-DD format
- `numberOfTravelers` (number, required): Number of travelers

**Returns:** Validation results with any errors found

## Data Formats

### Package Structure

```json
{
  "id": "pkg-001",
  "name": "Package Name",
  "destination": "City, Country",
  "duration": 5,
  "price": 2999,
  "currency": "USD",
  "description": "Package description",
  "itinerary": [
    {
      "day": 1,
      "activity": "Activity name",
      "time": "14:00"
    }
  ],
  "includes": ["Hotel", "Breakfast", "Transfers"],
  "available": true
}
```

### Booking Structure

```json
{
  "bookingId": "BK-000001",
  "packageId": "pkg-001",
  "packageName": "Package Name",
  "destination": "City, Country",
  "travelerName": "John Doe",
  "travelerEmail": "john@example.com",
  "travelDate": "2024-06-15",
  "numberOfTravelers": 2,
  "totalPrice": 5998,
  "currency": "USD",
  "status": "confirmed",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "cancelledAt": null
}
```

## Response Format

All responses use Server-Sent Events (SSE) format:

```
event: message
data: {"jsonrpc":"2.0","id":1,"result":{...}}

```

## Error Handling

Errors follow JSON-RPC 2.0 error format:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Error description"
  }
}
```

Common error codes:
- -32601: Method not found
- -32603: Internal error
- -32000: Invalid or missing session ID

## Security

This endpoint should not be exposed directly to AI agents. Route all requests through ArmorIQ proxy layer for authentication, authorization, rate limiting, and audit logging.

## Supported Destinations

The server includes 15 predefined travel packages covering destinations in Europe, Asia, North America, Oceania, and Africa including Paris, Tokyo, Bali, New York, Santorini, London, Dubai, Rome, Barcelona, Iceland, Singapore, Sydney, Thailand, Switzerland, and Morocco.