Flights MCP

Instructions

Implementation Reference

• src/flights-mcp/main.py:193-212 (handler)

  The primary handler function for the 'get_flight_option_details' tool, decorated with @mcp.tool which registers it. Retrieves cached search results by search_id, finds the specific proposal by offer_id using get_proposal_by_id, and returns detailed description via get_full_description. Includes inline schema via Pydantic Field descriptions.

  @mcp.tool(description="Retrieve detailed information about a specific flight option from the search results. " \
      "This tool provides detailed information about a flight option, including its segments, price, baggage info. " \
      "It is useful for getting more granular information about a specific flight option.")
  def get_flight_option_details(
      search_id: str = Field(..., description="Search ID from the previous search_flights tool."),
      offer_id: str = Field(..., description="Offer ID of the flight option for which to request a booking link."),
  ) -> Dict[str, Any]:
      """Get detailed information about a specific flight option from the search results."""
      
      batch = search_results_cache.get(search_id)
      if not batch:
          raise ToolError(f"No search results found for search_id: {search_id}. " \
                          "It may have expired after 10 minutes. " \
                          "Please perform a search first using the `search_flights` tool.")
      
      proposal = batch.get_proposal_by_id(offer_id)
      if not proposal:
          raise ToolError(f"No flight details found for offer_id: {offer_id} in search_id: {search_id}.")
      
      return proposal.get_full_description()

• src/flights-mcp/proposal.py:511-515 (helper)

  Helper method on ProposalsBatchModel to find and return the Proposal instance matching the offer_id (stored as 'sign'). Called directly from the tool handler.

  def get_proposal_by_id(self, proposal_id: str) -> Optional[Proposal]:
      for proposal in self.proposals:
          if proposal.sign == proposal_id:
              return proposal
      return None

• src/flights-mcp/proposal.py:289-315 (helper)

  Helper method on Proposal class that generates comprehensive string description of the flight option, including detailed flights, layovers, agency prices, baggage, etc. Returned directly by the tool handler.

  def get_full_description(self) -> str:
      description_parts = [self.get_short_description(include_cheapest_price=False, include_aircraft=True)]
      if self.is_charter:
          description_parts.append("* This is a charter flight.")
      description_parts.append(f"* This ticket is offered by {len(self.terms)} agencies with the following terms:")
      for term_id, terms in self.terms.items():
          agency = self.batch_ref.gates_info.get(term_id)
          if agency:
              description_parts.append(f"* Agency {agency.label} (internal agency ID: {term_id})")
          else:
              description_parts.append(f"* Agency (internal agency ID: {term_id})")
          description_parts.append(f"  * **Price:** {terms.price} {terms.currency.upper()} " \
                                   f"(in user currency: {convert_unified_price_to_user(terms.unified_price, self.batch_ref.currency)} {self.batch_ref.currency.upper()})")
          
          description_parts.append(f"  * Baggage info:")
          for segment_idx, segment in enumerate(self.segment):
              for flight_idx, flight in enumerate(segment.flight):
                  baggage = terms.flights_baggage[segment_idx][flight_idx]
  
                  handbag = terms.flights_handbags[segment_idx][flight_idx]
                  description_parts.append(f"    * Flight {flight.get_full_flight_number()}: \n" \
                                           f"      * {parse_baggage_string(baggage)} \n" \
                                           f"      * {parse_carry_on_string(handbag)}")
      if self.tags:
          description_parts.append(f"* Tags: {', '.join(self.tags)}")
      
      return "\n".join(description_parts)

• src/flights-mcp/main.py:26-29 (helper)

  TTLCache instance used across tools to store search results (ProposalsBatchModel) temporarily for 10 minutes, accessed by search_id in get_flight_option_details.

  search_results_cache = TTLCache(
      maxsize=10000,  # Maximum number of cached items
      ttl=10 * 60,  # Time to live for each cached item (10 minutes)
  )