Travel Hacking Toolkit – Points search and trip planning with AI!

#travelhacking #ai #pointsandmiles #tripplanning

The intricate domain of travel optimization, colloquially known as "travel hacking," presents a significant computational and logistical challenge. Individuals seeking to leverage loyalty points and miles for travel often encounter a multi-faceted decision matrix, requiring simultaneous evaluation of disparate data sources. This involves comparing award availability across numerous airline and hotel loyalty programs, assessing cash prices from various aggregators, tracking personal loyalty point balances, understanding complex transfer partner ratios, and applying dynamic point valuation metrics. The manual aggregation and synthesis of this information across a multitude of browser tabs and proprietary interfaces is inherently inefficient and prone to human error. This technical analysis explores an AI-driven toolkit designed to automate and streamline this complex decision-making process.

The Core Problem: Multi-Variable Travel Optimization

The fundamental problem addressed by the toolkit is the optimization decision between utilizing loyalty points versus paying cash for travel. This decision is not static; it is highly dynamic and context-dependent, influenced by:

Award Availability: The presence of redeemable seats or rooms in specific booking classes within loyalty programs. This data is often siloed and requires program-specific queries.
Cash Pricing: Real-time market prices for flights, hotels, and other travel components across multiple booking platforms, which can fluctuate rapidly.
Loyalty Balances: The current accumulated points or miles across a user's various loyalty accounts.
Transfer Partner Ratios: The conversion rates between transferable point currencies (e.g., Chase Ultimate Rewards, Amex Membership Rewards) and specific airline/hotel loyalty programs. These ratios can vary, and promotional bonuses may further complicate calculations.
Point Valuations: Subjective but empirically derived monetary values assigned to different loyalty points, used to normalize comparisons between point redemptions and cash outlays. These valuations are typically sourced from specialist publications and represent an estimated average value per point.

A human user attempting this process manually typically navigates a dozen or more independent web services, manually transcribes data, and performs calculations. The overhead of context switching and data integration renders comprehensive analysis impractical for most users.

Architectural Foundation: AI-driven Orchestration with Skills and MCP Servers

The toolkit's architecture is predicated on an AI-driven orchestration model. This model leverages advanced AI agents, specifically Claude Code and OpenCode, to act as a control plane, interpreting user queries, planning execution flows, and synthesizing results. The core components enabling this are "skills" and "MCP servers."

Skills: The AI's Interface to Capabilities

Skills are declarative descriptions of tools or capabilities available to the AI agent. In this architecture, skills are defined using Markdown files, incorporating API documentation and curl examples. This design choice provides several advantages:

Human Readability: Markdown is a widely understood, lightweight markup language, making skill definitions accessible to developers for review and modification.
AI Interpretability: AI models, particularly large language models, are adept at parsing and understanding natural language and structured text. Markdown provides a clear, consistent format for the AI to infer the purpose, parameters, and expected outputs of a tool.
Interoperability: By adhering to a common, open format, these skills can theoretically be utilized by any AI agent or platform supporting similar "tool-use" or "function calling" paradigms.

A skill file typically contains:

Description: A high-level explanation of the tool's purpose.
API Endpoint: The URI for the tool's invocation.
Method: HTTP method (e.g., GET, POST).
Parameters: A detailed breakdown of input parameters, including type, description, and whether they are required.
Example Request/Response: Illustrative curl commands and their corresponding JSON responses, demonstrating typical usage and output structure.

Consider a hypothetical skill definition for searching award flights:

## Skill: Search Award Flights

This skill allows the AI to query award availability for flights across various airline mileage programs. It leverages the Seats.aero integration to access real-time award space.

### Endpoint
`POST /api/v1/award_flights/search`

### Parameters

*   `origin` (string, required): IATA code of the departure airport.
*   `destination` (string, required): IATA code of the arrival airport.
*   `departure_date` (string, required): Desired departure date in YYYY-MM-DD format.
*   `cabin_class` (string, optional): Desired cabin class (e.g., "economy", "business", "first"). Defaults to "economy".
*   `max_connections` (integer, optional): Maximum number of connections allowed. Defaults to 1.
*   `alliance` (string, optional): Filter by airline alliance (e.g., "Star Alliance", "Oneworld").

### Example Request

bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"origin": "LAX",
"destination": "NRT",
"departure_date": "2024-11-15",
"cabin_class": "business",
"alliance": "Star Alliance"
}' \
http://localhost:8000/api/v1/award_flights/search


### Example Response

json
{
"status": "success",
"data": [
{
"flight_number": "ANA 7",
"airline": "ANA",
"origin": "LAX",
"destination": "NRT",
"departure_time": "2024-11-15T11:00:00Z",
"arrival_time": "2024-11-16T15:30:00Z",
"cabin_class": "business",
"points_cost": 85000,
"program": "ANA Mileage Club",
"taxes_fees_usd": 120.50,
"connections": 0
},
{
"flight_number": "United 32",
"airline": "United",
"origin": "LAX",
"destination": "NRT",
"departure_time": "2024-11-15T13:00:00Z",
"arrival_time": "2024-11-16T17:30:00Z",
"cabin_class": "business",
"points_cost": 99000,
"program": "United MileagePlus",
"taxes_fees_usd": 75.00,
"connections": 0
}
]
}


This structured format allows the AI agent to dynamically select the appropriate skill based on a user's natural language query, extract relevant parameters, construct the necessary API call, and interpret the response.

### MCP Servers: The Backend Engines for Real-time Operations

MCP (Multi-Capability Provider) servers are the operational backbone of the toolkit. These are microservices responsible for executing the specific tasks defined by the skills. They encapsulate the logic for interacting with external APIs, performing web scraping, accessing local data stores, and standardizing output for consumption by the AI agent.

A significant design consideration for the MCP servers is the minimization of external API key dependencies. Five out of six servers operate without requiring proprietary API keys, enabling a frictionless setup process. This is achieved through a combination of:

*   **Public API Proxies/Wrappers:** Many services offer publicly accessible data through web interfaces, which can be programmatically accessed and parsed (with careful consideration for terms of service and rate limits).
*   **Local Data Caches:** Storing reference data locally, such as point valuations or transfer partner ratios.
*   **Direct Web Scraping:** For data not exposed via formal APIs, targeted scraping techniques are employed. This approach requires robust error handling and adaptability to website structural changes.

#### Key MCP Server Functions and Implementation Notes:

1.  **Award Flight Search (Seats.aero Integration):**
    *   **Function:** Queries award availability across 25+ mileage programs.
    *   **Implementation:** Integrates with Seats.aero, which aggregates award data. This likely involves a direct API integration with Seats.aero's service, or a locally hosted component that periodically scrapes/updates data from Seats.aero, acting as a proxy. The server would translate AI-friendly queries into Seats.aero compatible requests and parse the structured output.

2.  **Cash Price Comparison (Google Flights, Skiplagged, Kiwi.com, Duffel):**
    *   **Function:** Retrieves real-time cash prices for flights.
    *   **Implementation:** This server likely orchestrates calls to various flight aggregators. For Google Flights, it might involve leveraging public scraping or Google's QPX Express API (if accessible). Skiplagged and Kiwi.com might be accessed via their public web interfaces or unofficial APIs. Duffel, as an API-first travel platform, would likely have a direct API integration. The challenge here is normalizing the disparate data formats and pricing models from these diverse sources.

3.  **Loyalty Balance Retrieval (AwardWallet):**
    *   **Function:** Fetches current loyalty balances from a user's AwardWallet account.
    *   **Implementation:** AwardWallet offers an API for authorized users to retrieve their loyalty program balances. This server would implement the necessary OAuth or API key authentication flow to securely access and present this sensitive user data to the AI. This is one of the few components that might require user-provided credentials (for AwardWallet specifically).

4.  **Hotel Search (Trivago, LiteAPI, Airbnb, Booking.com):**
    *   **Function:** Finds hotel and accommodation options.
    *   **Implementation:** Similar to flight search, this server integrates multiple hotel booking platforms. Trivago aggregates prices from various sources, making it a valuable target for searching. LiteAPI is likely a service offering simplified access to multiple hotel APIs. Airbnb and Booking.com would require direct integration, potentially via their public APIs or through targeted scraping. The server must handle varying room types, cancellation policies, and pricing structures.

5.  **Ferry Route Search:**
    *   **Function:** Identifies ferry routes across 33 countries.
    *   **Implementation:** This server likely maintains an internal database of ferry operators, routes, and schedules, possibly populated by scraping public ferry operator websites or aggregating data from specialized maritime travel APIs. The absence of specific third-party service names suggests a more custom data aggregation approach.

6.  **Hidden Gem Discovery (Atlas Obscura):**
    *   **Function:** Locates unique and unusual attractions near a destination.
    *   **Implementation:** Atlas Obscura provides a rich dataset of offbeat travel destinations. This server would interact with Atlas Obscura's API (or scrape its website) to retrieve points of interest based on geographic coordinates or destination names, enriching the trip planning experience.

A conceptual Python Flask endpoint for one of these MCP servers might look like this:

python

In an MCP server responsible for cash flight prices

from flask import Flask, request, jsonify
import requests

app = Flask(name)

@app.route('/api/v1/cash_flights/search', methods=['POST'])
def search_cash_flights():
data = request.json
origin = data.get('origin')
destination = data.get('destination')
departure_date = data.get('departure_date')
return_date = data.get('return_date')
cabin_class = data.get('cabin_class', 'economy')

if not all([origin, destination, departure_date]):
    return jsonify({"status": "error", "message": "Missing required parameters"}), 400

results = []

# --- Simulate Google Flights query (in reality, this would be an API call or scraping) ---
google_flights_data = {
    "source": "Google Flights",
    "price_usd": 750,
    "currency": "USD",
    "carrier": "United Airlines",
    "flight_number": "UA123",
    "departure_time": "2024-11-15T10:00:00Z"
}
results.append(google_flights_data)

# --- Simulate Kiwi.com query ---
try:
    kiwi_api_url = f"https://api.kiwi.com/v2/search?fly_from={origin}&fly_to={destination}&date_from={departure_date}&date_to={departure_date}&partner=YOUR_PARTNER_CODE"
    kiwi_response = requests.get(kiwi_api_url, headers={"apikey": "YOUR_KIWI_API_KEY"}) # Example with API key
    kiwi_response.raise_for_status()
    kiwi_data = kiwi_response.json()
    if kiwi_data and 'data' in kiwi_data and kiwi_data['data']:
        # Parse and add relevant data
        first_flight = kiwi_data['data'][0]
        results.append({
            "source": "Kiwi.com",
            "price_usd": first_flight['price'], # Assume price is USD
            "currency": "EUR", # Kiwi often uses EUR, conversion needed
            "carrier": first_flight['airlines'][0],
            "flight_number": first_flight['route'][0]['flight_no'],
            "departure_time": first_flight['route'][0]['local_departure']
        })
except requests.exceptions.RequestException as e:
    print(f"Error querying Kiwi.com: {e}")
    # Log error, continue without Kiwi results

# Further integrations for Skiplagged, Duffel would follow...

return jsonify({"status": "success", "data": results})

if name == 'main':
app.run(port=8001) # Example port


## Data Management and Contextual Intelligence

Beyond real-time API integrations, the toolkit provides crucial reference data, which forms the basis for intelligent decision-making. This data is likely stored in local databases or configuration files, accessible to the MCP servers or directly to the AI agent during its reasoning process.

*   **Transfer Partner Ratios:** Comprehensive mappings for major transferable point currencies: Chase Ultimate Rewards (UR), Amex Membership Rewards (MR), Bilt Rewards, Capital One Miles, and Citi ThankYou Points (TY). This data includes not only the standard 1:1 ratios but also any non-standard conversions or temporary promotional bonuses.
    ```

json
    {
      "Chase UR": {
        "United MileagePlus": {"ratio": "1:1", "min_transfer": 1000},
        "Hyatt Globalist": {"ratio": "1:1", "min_transfer": 1000},
        "Southwest Rapid Rewards": {"ratio": "1:1", "min_transfer": 1000}
      },
      "Amex MR": {
        "Delta SkyMiles": {"ratio": "1:1", "min_transfer": 1000},
        "Air Canada Aeroplan": {"ratio": "1:1", "min_transfer": 1000},
        "ANA Mileage Club": {"ratio": "1:1", "min_transfer": 1000, "bonus_history": {"2023-Q4": "20%"}}
      }
    }


    ```
*   **Point Valuations:** Sourced from reputable travel hacking publications such as The Points Guy (TPG), Upgraded Points, One Mile At A Time (OMAAT), and View From The Wing. These valuations are typically dynamic and vary by program and redemption type. The toolkit likely stores an aggregated or averaged valuation for each major loyalty currency.
    ```

json
    {
      "program_valuations": {
        "United MileagePlus": {"tpg": 0.012, "upgraded_points": 0.013, "omaat": 0.011},
        "Hyatt Globalist": {"tpg": 0.017, "upgraded_points": 0.018, "omaat": 0.016},
        "ANA Mileage Club": {"tpg": 0.018, "upgraded_points": 0.019, "omaat": 0.020}
      },
      "transferable_currency_valuations": {
        "Chase UR": 0.018,
        "Amex MR": 0.019,
        "Bilt Rewards": 0.015
      }
    }

Alliance Membership: Mapping airlines to their respective alliances (Star Alliance, Oneworld, SkyTeam) facilitates cross-program award searches.
Sweet Spot Redemptions: Pre-identified high-value redemption opportunities for specific routes or cabins, allowing the AI to prioritize certain search strategies.
Booking Windows: Knowledge of optimal booking windows (e.g., 330 days out for international premium cabins) to advise users on timing.
Hotel Chain Brand Lookups: Mapping specific hotel brands to their parent loyalty programs.

This comprehensive reference data empowers the AI agent to move beyond mere data retrieval, enabling sophisticated reasoning such as: "Given 100,000 Amex MR points and a target business class flight costing 85,000 ANA miles, is this a good redemption if Amex MR points are valued at 1.9 cents each and the cash fare is $4000?" The AI can perform the necessary calculations and provide a nuanced recommendation.

Integration and Workflow

The end-to-end workflow for a user leveraging the toolkit is designed for simplicity from an operational standpoint, abstracting the underlying complexity.

Setup: The user clones the GitHub repository and executes setup.sh. This script is responsible for:
- Installing necessary dependencies (e.g., Python packages, container runtimes if applicable).
- Configuring MCP servers.
- Ensuring the AI agent (Claude Code, OpenCode) has access to the skill definitions. This likely involves placing the Markdown skill files in a designated directory that the AI agent monitors or is explicitly configured to read.
Launching MCP Servers: The user starts the various MCP servers, which then expose their endpoints, typically via localhost ports.
AI Interaction: The user interacts with the AI agent directly (e.g., through a chat interface).

Example AI Interaction Flow:

User Query: "I want to find a business class flight from London to New York in early December, preferably using American Express Membership Rewards points. Also, suggest some unique places to visit near New York."

AI Agent's Internal Reasoning Process:

Parse Query: Identify intent: flight search, points utilization, destination exploration.
Skill Selection (Flight):
- Recognize need for Search Award Flights skill (for points) and Search Cash Flights skill (for comparison).
- Extract parameters: origin=LHR, destination=NYC, departure_date=2024-12-XX (AI might ask for specific date or iterate over range), cabin_class=business.
- Note specific points currency: Amex MR.
Execute Award Flight Search:
- Step 1: Use Search Award Flights to query LHR-NYC business class availability.
- Step 2: Retrieve Amex MR transfer partners from reference data (e.g., Delta SkyMiles, Air Canada Aeroplan, ANA Mileage Club, British Airways Avios via IAG).
- Step 3: For each relevant partner, invoke the Search Award Flights skill to check award availability for LHR-NYC on target dates.
- Step 4: Collect results, noting points cost and taxes/fees for each program.
Execute Cash Flight Search:
- Invoke Search Cash Flights skill with same parameters to get market cash prices.
Retrieve Loyalty Balances (if needed):
- If user has not specified their Amex MR balance, AI might prompt or use Get Loyalty Balances skill via AwardWallet integration.
Comparison and Recommendation:
- Calculate effective value of point redemptions: (Cash Price - Taxes/Fees) / Points Cost.
- Compare against point valuations from reference data.
- Factor in transfer ratios and potential bonuses.
- Present a ranked list of options, highlighting "good" or "sweet spot" redemptions.
Skill Selection (Exploration):
- Recognize need for Discover Hidden Gems skill.
- Extract parameter: location=New York City.
- Invoke Discover Hidden Gems skill (Atlas Obscura integration).
Synthesize and Present: Combine flight recommendations with unique local attractions, formatted in a digestible manner.

This orchestrated process transforms a complex, multi-manual-step operation into a seamless, AI-driven interaction.

Technical Challenges and Future Directions

Developing and maintaining a toolkit of this complexity presents several technical challenges:

API Volatility: External APIs (Seats.aero, Google Flights, etc.) can change their structure, authentication methods, or rate limits without notice, requiring constant maintenance of the MCP servers. Robust error handling and logging are critical.
Web Scraping Resilience: For components relying on web scraping, changes to website HTML structures can break parsers. This necessitates flexible parsing logic and potentially AI-driven adaptation or human intervention for updates.
Data Freshness: Point valuations, transfer bonuses, and cash prices are highly dynamic. Ensuring the reference data and real-time queries provide sufficiently fresh information is an ongoing challenge. Caching strategies and scheduled updates are necessary.
Scalability: While designed for personal use, scaling the MCP servers for concurrent users or more intensive query loads might require more robust infrastructure and rate limit management.
AI Reasoning Depth: The quality of recommendations relies heavily on the AI agent's ability to interpret nuanced context, perform complex multi-step reasoning, and gracefully handle ambiguity. Continuous advancements in LLMs will improve this, but the skill definitions must be precise.

Future directions for enhancement include:

Expanded Coverage: Integrating more loyalty programs, travel aggregators, and niche travel services.
Predictive Analytics: Leveraging historical data to predict award availability trends or optimal booking times.
Personalization: Deeper integration with user preferences, travel history, and specific loyalty program statuses (e.g., elite benefits).
Enhanced UI/UX: While the core is AI interaction, a complementary graphical user interface could provide visual breakdowns of options and comparisons.
Community Contribution: The open-source nature invites contributions, enabling faster expansion and maintenance of skills and MCP servers.

The Travel Hacking Toolkit represents a sophisticated application of AI agent technology to a real-world, data-intensive problem. By abstracting the complexity of disparate data sources and integrating them through a modular skill-based architecture, it offers a compelling paradigm for automated travel optimization. The careful balance of proprietary APIs, intelligent scraping, and robust reference data management positions this toolkit as a powerful assistant for navigating the intricacies of loyalty travel.

For further insights into advanced technical solutions, data integration, and AI-driven automation, we invite you to visit https://www.mgatc.com for professional consulting services.

Originally published in Spanish at www.mgatc.com/blog/travel-hacking-toolkit-points-search-trip-planning-with-ai/