Often Travel MCP Server (TypeScript)

A TypeScript-based Model Context Protocol (MCP) server that provides access to the Often Travel API for hotel booking and travel management through LLM applications.

Features

• 🔐 Authentication Management: Token-based authentication with confirmation code support
• 🏨 Hotel Search: Search for hotel locations and available accommodations
• 📋 Booking Management: Create itineraries, select rooms, and manage bookings
• 💳 Payment Processing: Generate payment orders for bookings
• 🔄 Real-time Integration: Direct integration with Often Travel's Laravel API

Installation

1. Clone and navigate to the TypeScript MCP directory:

   cd often-mcp-ts

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env

   Edit .env and configure:

   LARAVEL_BASE_URL=http://localhost:8000/api

4. Build the project:

   npm run build

Development

Run in development mode with hot reload:

npm run dev

Build for production:

npm run build
npm start

Configuration

Environment Variables

• LARAVEL_BASE_URL: Base URL for the Often Travel Laravel API (default: http://localhost:8000/api)

MCP Client Configuration

Add this server to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "often-travel-ts": {
      "command": "node",
      "args": ["path/to/often-mcp-ts/dist/index.js"],
      "env": {
        "LARAVEL_BASE_URL": "http://localhost:8000/api"
      }
    }
  }
}

Available Tools

Authentication

• set_token(token: string) - Set authentication token manually
• authenticate_with_code(confirmation_code: string) - Authenticate using 6-character confirmation code
• check_auth_status() - Check current authentication status
• logout() - Clear stored authentication token

Hotel Search

• search_hotel_locations(search_keyword: string) - Search for hotel locations
• search_hotels() - Search for available hotels with detailed criteria
• get_hotel_static_content(hotel_id: string) - Get detailed hotel information

Booking Management

• create_hotel_itinerary() - Create a hotel itinerary
• select_room_rates() - Select specific room and rate combinations
• get_itinerary_details(booking_id: string) - Get detailed itinerary information
• allocate_guests_to_rooms() - Assign guest details to rooms
• generate_payment_order(booking_id: string) - Create payment order

Available Resources

• user://profile - Get authenticated user's profile information

Available Prompts

• auth_instructions - Step-by-step authentication guide
• hotel_booking_guide - Complete hotel booking workflow guide

Usage Examples

Quick Authentication (Recommended)

1. Get confirmation code from the Often Travel website:

   • Log in to Often Travel
   • Go to Profile → MCP Access Token
   • Click "Generate Confirmation Code"

2. Authenticate in your MCP client:

   authenticate_with_code("ABC123")

Hotel Booking Workflow

// 1. Search for locations
search_hotel_locations({ search_keyword: "Singapore" })

// 2. Search for hotels
search_hotels({
  check_in: "2025-05-01",
  check_out: "2025-05-05",
  nationality: "IN",
  location_id: 246673,
  occupancies: [{ numOfAdults: 2, childAges: [] }]
})

// 3. Get hotel details
get_hotel_static_content({ hotel_id: "HTLSG123" })

// 4. Create itinerary
create_hotel_itinerary({
  hotel_id: "HTLSG123",
  journey_id: "550e8400-e29b-41d4-a716-446655440000"
})

// 5. Select rooms and rates
select_room_rates({
  itinerary_id: "ITN12345",
  journey_id: "550e8400-e29b-41d4-a716-446655440000",
  recommendation_id: "REC001",
  rooms_and_rate_allocations: [
    {
      roomId: "DBL1",
      rateId: "RT001",
      occupancy: { adults: 2 }
    }
  ]
})

// 6. Add guest details
allocate_guests_to_rooms({
  booking_id: "550e8400-e29b-41d4-a716-446655440002",
  guests: [
    {
      title: "Mr",
      firstName: "John",
      lastName: "Doe",
      isLeadGuest: true,
      type: "adult",
      email: "[email protected]",
      isdCode: 91,
      contactNumber: "9876543210",
      roomIndex: 0
    }
  ],
  special_requests: "Non-smoking room preferred"
})

// 7. Generate payment order
generate_payment_order({ booking_id: "550e8400-e29b-41d4-a716-446655440002" })

Error Handling

The server provides comprehensive error handling for:

• Authentication failures
• Invalid API responses
• Network connectivity issues
• Token expiration
• Invalid confirmation codes

All errors are returned as structured text responses with descriptive messages.

Security

• ✅ Token Validation: All API tokens are validated against the Laravel backend
• ✅ Secure Storage: Tokens are stored in memory only (not persisted)
• ✅ Confirmation Codes: Time-limited confirmation codes for secure authentication
• ✅ Error Sanitization: Sensitive information is not exposed in error messages

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  TypeScript     │───▶│  Laravel API    │
│  (Claude, etc.) │    │  MCP Server     │    │   (Often.travel)│
└─────────────────┘    └─────────────────┘    └─────────────────┘

Comparison with Python Version

| Feature | Python Version | TypeScript Version | |---------|---------------|-------------------| | Runtime | Python 3.8+ | Node.js 18+ | | Package Manager | pip | npm | | Type Safety | Python types | TypeScript | | HTTP Client | httpx | axios | | Schema Validation | Pydantic | Zod | | MCP Framework | FastMCP | @modelcontextprotocol/sdk | | Performance | Good | Excellent | | Memory Usage | Higher | Lower |

Development

Project Structure

often-mcp-ts/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variable template
└── README.md            # This file

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run in development mode with hot reload
• npm start - Run the compiled server
• npm run clean - Remove compiled output

Dependencies

Runtime Dependencies

• @modelcontextprotocol/sdk - Official MCP TypeScript SDK
• axios - HTTP client for API requests
• dotenv - Environment variable management
• zod - Schema validation

Development Dependencies

• typescript - TypeScript compiler
• tsx - TypeScript execution for development
• @types/node - Node.js type definitions

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Create an issue in the GitHub repository
• Check the Often Travel API documentation
• Review the MCP specification at modelcontextprotocol.io