hotel-mcp/README.md

Hotel MCP Server - Read-only hotel information with rich media support for Claude Desktop

# 🏨 Hotel MCP Server - Enterprise Edition

**Professional hotel information system with rich media support for Claude Desktop**

*Developed by DAOTOMATA FZE - Commercial Private Software*

[![NPM Version](https://img.shields.io/npm/v/hotel-mcp)](https://www.npmjs.com/package/hotel-mcp)
[![License](https://img.shields.io/badge/license-PROPRIETARY-red.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.8+-green.svg)](https://github.com/jlowin/fastmcp)

---

## ⚠️ PROPRIETARY SOFTWARE NOTICE

This software is proprietary to **DAOTOMATA FZE** and is licensed for commercial use only.
Unauthorized distribution, modification, or reverse engineering is strictly prohibited.

**For licensing inquiries**: contact@daotomata.com

---

## 🚀 Overview

The Hotel MCP Server is an enterprise-grade Model Context Protocol (MCP) server designed specifically for the hospitality industry. It provides seamless integration with Claude Desktop and other AI assistants, offering comprehensive access to hotel information, amenities, activities, and rich multimedia content.

### Key Benefits

- **🔒 Enterprise Security**: Proprietary codebase with commercial-grade security
- **🌐 Multi-language Support**: Native ES/EN/FR/CA translation engine
- **📱 Rich Media**: Automatic WebP optimization and responsive image delivery
- **⚡ High Performance**: Intelligent caching with adaptive strategies
- **🔧 Easy Integration**: NPX-based deployment for Claude Desktop
- **📊 Real-time Monitoring**: Built-in performance metrics and health checks

## 🏨 Features

### Core Functionality
- **Read-Only Access**: Safe, secure access to hotel data without modification capabilities
- **Rich Media Display**: Optimized photos, videos, and gallery presentations
- **Intelligent Search**: Advanced search across rooms, activities, facilities, and dining
- **Real-time Data**: Live connection to Supabase backend with instant updates

### Technical Features
- **31 MCP Tools**: Comprehensive hotel management toolkit with intelligent URL builder utilities
- **Adaptive Caching**: LRU/LFU/TTL/Adaptive caching strategies
- **Media Optimization**: Automatic WebP conversion and resizing
- **Translation Engine**: Real-time content translation
- **Performance Monitoring**: Built-in metrics and health monitoring
- **Cross-platform**: macOS, Linux, and Windows support

## 📋 Available Tools

### 🛏️ Room Management
- `list_rooms` - Browse available rooms and suites
- `get_room_details` - Detailed room information with gallery
- `search_rooms` - Intelligent room search with filters

### 🎯 Activities & Experiences
- `list_activities` - Discover hotel activities and experiences
- `get_activity_details` - Complete activity information with pricing
- `search_activities` - Find activities by type, location, or interest

### 🏢 Facilities & Services
- `list_facilities` - Explore hotel facilities and amenities
- `get_facility_details` - Detailed facility information and hours
- `search_facilities` - Locate specific services and amenities

### 🍽️ Dining & Menu
- `list_menu_items` - Browse restaurant menus and offerings
- `get_menu_item_details` - Detailed dish information with allergens
- `search_menu_items` - Find dishes by dietary restrictions or cuisine

### 📸 Galleries & Media
- `list_galleries` - Browse photo galleries and collections
- `get_gallery_details` - View complete gallery with metadata
- `search_galleries` - Find galleries by theme or location

### 🔗 Intelligent URL Builder Utilities
- `build_url` - Construct URLs with query parameters and fragments
- `parse_url` - Parse URLs into components with validation
- `encode_url_component` - URL encode text for different components
- `decode_url_component` - URL decode text from different components
- `build_url_from_template` - Build URLs from templates with parameter substitution
- `validate_url` - Validate URL format and components
- `build_hotel_reservation_url` - **🎯 Smart reservation URLs using real room data**
- `build_room_reservation_url_from_search` - **🔍 Find rooms and generate booking URLs**
- `build_multiple_reservation_urls` - **📋 Bulk reservation URL generation**

### 📊 System Monitoring
- `get_server_info` - Server status and configuration
- `health_check` - System health and connectivity
- `get_performance_metrics` - Real-time performance data
- `get_cache_statistics` - Cache performance and optimization

## 🛠️ Installation & Setup

### Prerequisites
- Node.js 16.0+
- Python 3.10+
- Claude Desktop or compatible MCP client

### Quick Start

```bash
# Install via NPX (recommended)
npx hotel-mcp@latest --help

# Or install globally
npm install -g hotel-mcp@1.0.2
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "hotel-mcp": {
      "command": "npx",
      "args": ["hotel-mcp@1.1.0"],
      "env": {
        "HOTEL_BASE_URL": "https://your-hotel-website.com",
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_ANON_KEY": "your-service-role-key",
        "DEFAULT_SITE_ID": "your-site-id",
        "DEFAULT_LANGUAGE": "es"
      }
    }
  }
}
```

### Environment Variables

- **`HOTEL_BASE_URL`**: Your hotel website base URL (e.g., "https://your-hotel.com")
  - Used by URL builder tools to generate reservation links automatically
  - If not set, domain must be provided explicitly in each URL builder call
- **`SUPABASE_URL`**: Your Supabase project URL
- **`SUPABASE_ANON_KEY`**: Your Supabase service role key for database access
- **`DEFAULT_SITE_ID`**: Default hotel site ID for filtering content
- **`DEFAULT_LANGUAGE`**: Default language for content (es, en, fr, ca)

#### UTM Tracking for Conversion Analytics

Track AI agent conversions with automatic UTM parameters:

- **`UTM_SOURCE`**: Source identifier (default: "hotel-mcp")
- **`UTM_MEDIUM`**: Medium identifier (default: "ai-agent")
- **`UTM_CAMPAIGN`**: Campaign name for tracking specific initiatives
- **`UTM_TERM`**: Keywords for paid search tracking
- **`UTM_CONTENT`**: Content variant for A/B testing

All URL builder tools automatically append these UTM parameters to generated URLs for comprehensive conversion tracking.

### URL Builder Tools

The Hotel MCP includes intelligent URL builder tools with robust validation and automatic UTM tracking:

```javascript
// With HOTEL_BASE_URL configured, domain is optional:
build_hotel_reservation_url({
  room_id: "room-123",
  check_in: "2024-07-01",
  check_out: "2024-07-05",
  adults: 2,
  guest_name: "John Doe",
  guest_email: "john@email.com"
})

// Without HOTEL_BASE_URL, domain is required:
build_hotel_reservation_url({
  domain: "https://your-hotel.com",
  room_id: "room-123",
  // ... other parameters
})
```

#### Data Validation & Security

All URL builder tools include comprehensive validation:

- **Email Validation**: RFC-compliant email format checking
- **Date Validation**: YYYY-MM-DD format with logical date range checks
- **Phone Validation**: International phone number format support
- **Guest Count Validation**: Reasonable limits (1-20 adults, 0-10 children)
- **Data Sanitization**: XSS protection and input cleaning
- **Error Prevention**: Clear validation messages prevent booking failures

#### Automatic UTM Tracking

Every generated URL includes UTM parameters for conversion analytics:

```
https://hotel.com/accommodation/reservations?
  roomType=ocean-deluxe&
  checkIn=2025-07-01&
  adults=2&
  utm_source=hotel-mcp&
  utm_medium=ai-agent&
  utm_campaign=summer-2025
```

## 🏢 Enterprise Support

### Commercial Licensing
- **Internal Use**: Licensed for DAOTOMATA FZE operations
- **Partner Access**: Available for authorized partners and clients
- **Custom Development**: Tailored solutions for specific requirements
- **Integration Support**: Professional integration assistance

### Support Services
- **Technical Support**: Direct access to DAOTOMATA development team
- **Custom Features**: Bespoke development for specific needs
- **Training**: Staff training and onboarding assistance
- **Maintenance**: Regular updates and security patches

### Contact Information
- **Company**: DAOTOMATA FZE
- **Email**: contact@daotomata.com
- **Support**: Available through service agreement

## 📊 Technical Specifications

### Performance
- **Response Time**: < 500ms average
- **Concurrent Users**: 100+ simultaneous connections
- **Cache Hit Rate**: 85%+ with adaptive strategies
- **Uptime**: 99.9% availability target

### Security
- **Data Encryption**: TLS 1.3 for all communications
- **Access Control**: Role-based permissions
- **Audit Logging**: Comprehensive activity tracking
- **Compliance**: Enterprise security standards

### Scalability
- **Horizontal Scaling**: Multi-instance deployment
- **Load Balancing**: Automatic traffic distribution
- **Database Optimization**: Intelligent query optimization
- **CDN Integration**: Global content delivery

## 📄 License

This software is proprietary to DAOTOMATA FZE. See [LICENSE](LICENSE) for complete terms and conditions.

**Copyright © 2025 DAOTOMATA FZE. All rights reserved.**

---

*For technical documentation, API references, and integration guides, please contact DAOTOMATA FZE support.*