Navifare Flight Validator

Prerequisites Check

Before executing the skill, verify Navifare MCP is available:

Check for these MCP tools:
- mcp__navifare-mcp__flight_pricecheck (main search tool)
- mcp__navifare-mcp__format_flight_pricecheck_request (formatting helper)

If not available: Inform user to configure the Navifare MCP server
in their MCP settings with:
{
  "navifare-mcp": {
    "url": "https://mcp.navifare.com/mcp"
  }
}

Execution Workflow

⚠️ IMPORTANT: Always follow this exact sequence:

1. Format with format_flight_pricecheck_request → resolve any missing info → search with flight_pricecheck
2. NEVER call flight_pricecheck directly without calling format_flight_pricecheck_request first

Step 1: Format the Request

This is always the first action. Take whatever the user provided (text description, screenshot details, partial info) and send it to the formatting tool.

⚠️ CRITICAL: You MUST call this tool before flight_pricecheck.

Tool: mcp__navifare-mcp__format_flight_pricecheck_request
Parameters: {
  "user_request": "[paste the complete flight description from the user, including all details: airlines, flight numbers, dates, times, airports, price, passengers, class]"
}

Example user_request value:
"Outbound Feb 19, 2026: QR124 MXP-DOH 08:55-16:40, QR908 DOH-SYD 20:40-18:50 (+1 day).
Return Mar 1, 2026: QR909 SYD-DOH 21:40-04:30 (+1 day), QR127 DOH-MXP 08:50-13:10.
Price: 1500 EUR, 1 adult, economy class."

What this tool does:

• Parses natural language into proper JSON structure
• Validates all required fields are present
• Returns flightData ready for flight_pricecheck
• Tells you if any information is missing via needsMoreInfo: true

Output handling:

• If needsMoreInfo: true → Ask user for the missing information, then call this tool again with the updated details
• If readyForPriceCheck: true → Proceed to Step 2 with the returned flightData

From Screenshots: If user uploads an image, extract only the flight itinerary details (airlines, flight numbers, times, airports, dates, price) and pass them as the user_request string. Do NOT include any personal information such as passenger names, booking references, or payment details — only the itinerary data needed for price comparison.

Resolving missing info: When the tool reports missing fields:

• For airports: Check references/AIRPORTS.md for common codes
• For airlines: Check references/AIRLINES.md for codes
• For times: Ask user: "What time does the flight depart/arrive?"
• For dates: Validate dates are in future, ask user if unclear
• For currency: Auto-detect from symbols (€→EUR, $→USD, £→GBP, CHF→CHF)

DO NOT skip this step. It ensures data is properly formatted and validated.

Step 2: Execute Price Search

Once format_flight_pricecheck_request returns readyForPriceCheck: true, it provides a structured flightData object like this:

{
  "trip": {
    "legs": [
      {
        "segments": [
          {
            "airline": "BA",
            "flightNumber": "553",
            "departureAirport": "JFK",
            "arrivalAirport": "LHR",
            "departureDate": "2025-06-15",
            "departureTime": "18:00",
            "arrivalTime": "06:30",
            "plusDays": 1
          }
        ]
      }
    ],
    "travelClass": "ECONOMY",
    "adults": 1,
    "children": 0,
    "infantsInSeat": 0,
    "infantsOnLap": 0
  },
  "source": "MCP",
  "price": "450",
  "currency": "USD",
  "location": "US"
}

Key fields in the output:

• plusDays: 1 if arrival is next day, 2 if two days later, etc.
• location: User's 2-letter ISO country code (e.g., "IT", "US", "GB"). Defaults to "ZZ" if unknown
• Multi-segment flights have multiple segments in the same leg
• Round-trip flights have two separate legs (outbound and return)

IMPORTANT VALIDATIONS before calling the search:

1. Check for one-way flights — Navifare only supports round-trip flights:

   if trip has only 1 leg:
     ❌ Return error: "Sorry, Navifare currently only supports round-trip flights.
        One-way flight price checking is not available yet."
     DO NOT proceed with the search.
   

2. Inform user FIRST — Tell them it will take time:

   "🔍 Searching for better prices across multiple booking sites...
   This typically takes 30-60 seconds as I check real-time availability."
   

Then call the search tool with the formatted data:

Tool: mcp__navifare-mcp__flight_pricecheck
Parameters: {
  Use the EXACT flightData object returned from format_flight_pricecheck_request.
  This includes: trip, source, price, currency, location
}

The MCP server will:
1. Submit the search request to Navifare API
2. Poll for results automatically (up to 90 seconds)
3. Return final ranked results when complete

CRITICAL: The tool call will block for 30-60 seconds. This is normal. Do NOT abort or assume it failed — wait for the response.

IF TOOL RUNS LONGER THAN 90 SECONDS:

• The server has a 90-second timeout
• If still running after 90s, there may be a client-side issue
• Results are likely already available but not displayed
• Try canceling and re-calling the tool

Step 3: Analyze Results

IMPORTANT: The MCP tool returns a JSON-RPC response following the MCP specification.

MCP Response Format:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"message\":\"...\",\"searchResult\":{...}}"
      }
    ],
    "isError": false
  }
}

How to extract results:

1. Parse result.content[0].text as JSON
2. Extract searchResult.results array from parsed data
3. Each result has: price, currency, source, booking_URL
4. Results are pre-sorted by price (cheapest first)

Example parsed data structure:

{
  "message": "Search completed. Found X results from Y booking sites.",
  "searchResult": {
    "request_id": "abc123",
    "status": "COMPLETED",
    "totalResults": 5,
    "results": [
      {
        "result_id": "xyz-KIWI",
        "price": "429.00",
        "currency": "USD",
        "convertedPrice": "395.00",
        "convertedCurrency": "EUR",
        "booking_URL": "https://...",
        "source": "Kiwi.com",
        "private_fare": "false",
        "timestamp": "2025-02-11T16:30:00Z"
      }
    ]
  }
}

Analysis to perform:

1. Compare with reference price: Calculate savings/difference
2. Identify best deal: Lowest price in results
3. Check price spread: Show range from cheapest to most expensive
4. Note fare types: Highlight "Special Fare" vs "Standard Fare"
5. Validate availability: Ensure results are recent (check timestamp)

Price difference calculation:

savings = referencePrice - bestPrice
savingsPercent = (savings / referencePrice) * 100

If savingsPercent > 5%: "Significant savings available"
If savingsPercent < -5%: "Prices have increased"
If abs(savingsPercent) <= 5%: "Price is competitive"

Step 4: Present Findings to User

Format results as a clear, actionable summary:

When better price found (savings > 5%):

✅ I found a better deal!

Your reference: $450 on [original site]
Best price found: $429 on Kiwi.com
💰 You save: $21 (4.7%)

Top 3 Options:
┌────┬──────────────┬────────┬──────────────┬─────────────────────┐
│ #  │ Website      │ Price  │ Fare Type    │ Booking Link        │
├────┼──────────────┼────────┼──────────────┼─────────────────────┤
│ 1  │ Kiwi.com     │ $429   │ Standard     │ [Book Now]          │
│ 2  │ Momondo      │ $445   │ Standard     │ [Book Now]          │
│ 3  │ eDreams      │ $450   │ Special Fare │ [Book Now]          │
└────┴──────────────┴────────┴──────────────┴─────────────────────┘

All prices checked: 2025-02-11 16:30 UTC

When price is validated (within 5%):

✅ Price verified!

Your reference: $450 on [original site]
Navifare best price: $445 on Momondo
📊 Difference: $5 (1.1%)

Your price is competitive. The best available price is very close to what you found.

Top 3 Options:
[Same table format as above]

When prices increased (reference price lower):

⚠️ Prices have changed

Your reference: $450 on [original site]
Current best price: $489 on Kiwi.com
📈 Increase: $39 (8.7%)

This flight may be in high demand. Prices have increased since you last checked.

Top 3 Options:
[Same table format as above]

💡 Tip: Consider booking soon if this route works for you, or check alternative dates.

When no results found:

❌ No results found

Navifare couldn't find current prices for this exact itinerary.

Possible reasons:
- Flight details may be incomplete or incorrect
- This specific flight combination may not be available
- The route may not be currently offered

Would you like to:
1. Verify the flight details (times, dates, airports)
2. Search for alternative flights on this route
3. Try different dates

Step 5: Provide Booking Guidance

After presenting results:

1. Make booking links clickable: Format as [Book on Kiwi.com](https://...)

2. Highlight key considerations:

   • Fare restrictions (if mentioned in results)
   • Baggage policies (if available)
   • Refund policies (Standard vs Special fares)

3. Offer next steps:

   • "Click any booking link to complete your purchase"
   • "Would you like me to check alternative dates?"
   • "Should I search for different flight options?"

4. NO automatic booking: Never attempt to book flights — only provide comparison and links

Data Format Examples

Example 1: Round-Trip Flight

User: "Kayak shows €599 for Milan to Barcelona and back, June 20-27, ITA Airways"

What you send to format_flight_pricecheck_request:

"Kayak shows €599 for Milan to Barcelona and back, June 20-27, ITA Airways AZ78 departing 08:30 arriving 10:15, return AZ79 departing 18:00 arriving 19:45. 1 adult, economy."

What the tool returns as flightData (ready for flight_pricecheck):

{
  "trip": {
    "legs": [
      {"segments": [
        {
          "airline": "AZ",
          "flightNumber": "78",
          "departureAirport": "MXP",
          "arrivalAirport": "BCN",
          "departureDate": "2025-06-20",
          "departureTime": "08:30",
          "arrivalTime": "10:15",
          "plusDays": 0
        }
      ]},
      {"segments": [
        {
          "airline": "AZ",
          "flightNumber": "79",
          "departureAirport": "BCN",
          "arrivalAirport": "MXP",
          "departureDate": "2025-06-27",
          "departureTime": "18:00",
          "arrivalTime": "19:45",
          "plusDays": 0
        }
      ]}
    ],
    "travelClass": "ECONOMY",
    "adults": 1,
    "children": 0,
    "infantsInSeat": 0,
    "infantsOnLap": 0
  },
  "source": "MCP",
  "price": "599",
  "currency": "EUR"
}

Example 2: Multi-Segment Connection (Round-Trip)

User: "Found $890 LAX to Tokyo via Seattle on Alaska/ANA, July 10, returning July 20"

What you send to format_flight_pricecheck_request:

"LAX to Tokyo via Seattle, July 10. AS338 LAX-SEA 10:00-12:30, NH178 SEA-NRT 14:30-17:00 (+1 day). Return July 20: NH177 NRT-SEA 18:00-11:00, AS339 SEA-LAX 14:00-17:00. Price $890, 1 adult, economy."

What the tool returns as flightData:

{
  "trip": {
    "legs": [
      {"segments": [
        {
          "airline": "AS",
          "flightNumber": "338",
          "departureAirport": "LAX",
          "arrivalAirport": "SEA",
          "departureDate": "2025-07-10",
          "departureTime": "10:00",
          "arrivalTime": "12:30",
          "plusDays": 0
        },
        {
          "airline": "NH",
          "flightNumber": "178",
          "departureAirport": "SEA",
          "arrivalAirport": "NRT",
          "departureDate": "2025-07-10",
          "departureTime": "14:30",
          "arrivalTime": "17:00",
          "plusDays": 1
        }
      ]},
      {"segments": [
        {
          "airline": "NH",
          "flightNumber": "177",
          "departureAirport": "NRT",
          "arrivalAirport": "SEA",
          "departureDate": "2025-07-20",
          "departureTime": "18:00",
          "arrivalTime": "11:00",
          "plusDays": 0
        },
        {
          "airline": "AS",
          "flightNumber": "339",
          "departureAirport": "SEA",
          "arrivalAirport": "LAX",
          "departureDate": "2025-07-20",
          "departureTime": "14:00",
          "arrivalTime": "17:00",
          "plusDays": 0
        }
      ]}
    ],
    "travelClass": "ECONOMY",
    "adults": 1,
    "children": 0,
    "infantsInSeat": 0,
    "infantsOnLap": 0
  },
  "source": "MCP",
  "price": "890",
  "currency": "USD"
}

Error Handling

API Timeout

If search exceeds 90 seconds:

⏱️ Search is taking longer than expected.

Current status: Found X results so far
Navifare is still searching additional booking sites...

[Present partial results if available]

Invalid Airport Codes

If user provides unclear airports:

❓ I need to verify the airports.

You mentioned: "New York" and "London"

Did you mean:
- New York: JFK (Kennedy) or EWR (Newark) or LGA (LaGuardia)?
- London: LHR (Heathrow) or LGW (Gatwick) or STN (Stansted)?

Please specify the exact airports.

See references/AIRPORTS.md for complete list.

Missing Critical Information

❓ I need more details to search accurately.

Current information:
✅ Route: JFK → LHR
✅ Date: 2025-06-15
❌ Departure time: Not specified
❌ Arrival time: Not specified

Please provide:
- What time does the flight depart? (e.g., "6:00 PM")
- What time does it arrive? (e.g., "6:30 AM next day")

Currency Conversion

If currency symbols are ambiguous:

💱 Currency Clarification

You mentioned "$450" - is this:
1. USD (US Dollar) - Recommended
2. CAD (Canadian Dollar)
3. AUD (Australian Dollar)
4. Other?

Please specify for accurate price comparison.

Date Validation

If dates are in the past:

⚠️ Date Issue

The date you provided (2024-12-20) is in the past.

Did you mean:
- 2025-12-20 (this year)
- 2026-12-20 (next year)

Please confirm the correct travel date.

Best Practices

1. Always Verify Before Searching

• Confirm all required fields are present
• Validate airports using IATA codes
• Ensure dates are reasonable and in future
• Check times are in 24-hour format

2. Handle Ambiguity Gracefully

• Ask specific questions when data is unclear
• Provide options rather than making assumptions
• Reference documentation files for validation

3. Present Results Clearly

• Use tables for easy comparison
• Highlight savings/differences prominently
• Make booking links immediately actionable
• Include timestamps for price freshness

4. Consider User Context

• Multi-city trips: Ensure all segments are captured
• Business travel: Note refund/change policies
• Budget conscious: Emphasize savings opportunities
• Time sensitive: Highlight price trends

5. Progressive Disclosure

• Start with top 3-5 results
• Offer to show more if user wants
• Don't overwhelm with excessive details
• Focus on actionable insights

6. Respect Search Limitations

• 90-second polling window
• Results may be incomplete if timeout
• Some booking sites may not be covered
• Prices update in real-time (may change quickly)

Technical Notes

MCP Tool Integration

The Navifare MCP provides these tools:

• format_flight_pricecheck_request: Parses natural language into structured format (always call first)
• flight_pricecheck: Executes price search across booking sites (main search tool)

Workflow:

1. Call format_flight_pricecheck_request with the user's natural language description
2. If needsMoreInfo: true → ask user for missing fields, then call again
3. If readyForPriceCheck: true → use the returned flightData to call flight_pricecheck
4. flight_pricecheck handles polling automatically and returns complete results

Data Quality

• Navifare scrapes real-time prices from booking sites
• Results include booking URLs that redirect to provider sites
• Prices are accurate at time of search but may change
• Some providers may show different prices based on location/cookies

Performance

• Typical search: 30-60 seconds
• Maximum search time: 90 seconds
• Results stream in as they're found
• More results = higher confidence in best price

Supported Routes

• Round-trip flights only (one-way NOT supported)
• International and domestic flights
• Multi-city with connections (as long as outbound + return = 2 legs)
• All major airlines and booking platforms
• Same origin/destination required (open-jaw routes NOT supported)

Additional Resources

• AIRPORTS.md: Complete IATA airport codes by region
• AIRLINES.md: Complete IATA airline codes with full names
• EXAMPLES.md: Real conversation examples with screenshots

For complete Navifare MCP documentation, see the main repository.

Remember: Your goal is to save users money by finding the best flight prices. Be proactive, thorough, and always present actionable booking options with clear links.