Flights MCP

Instructions

Implementation Reference

• src/flights-mcp/main.py:165-191 (handler)

  The main handler function that implements the get_flight_options tool logic: retrieves cached search results, applies filters, paginates, and formats a list of flight options as a string.

  def get_flight_options(
      search_id: str,
      filters: FiltersModel,
      page: int = Field(0, description="Page number for pagination. Default is 0."),
      page_size: int = Field(10, description="Number of results per page. Default is 10.")
  ):
      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 or not been performed yet. " \
                          "Please perform a search first using the `search_flights` tool.")
      filtered_batch = batch.apply_filters(filters)
  
      if not filtered_batch.proposals:
          raise ToolError(f"No flight options found for search_id: {search_id} with the specified filters.")
      
      total_results = len(filtered_batch.proposals)
      start_index = page * page_size
      end_index = start_index + page_size
      paginated_results = filtered_batch.proposals[start_index:end_index]
      result = f'Retrieved {len(paginated_results)} flight options for search_id: {search_id} (Page {page}/{(total_results // page_size) + 1})\n\n'
  
      for i, proposal in enumerate(paginated_results):
          result += proposal.get_short_description()
          if i < len(paginated_results) - 1:
              result += "\n---\n"
      return result

• src/flights-mcp/main.py:159-164 (registration)

  The @mcp.tool decorator that registers the get_flight_options function as an MCP tool, including its description.

  @mcp.tool(
      description="Get flight options from the previously performed search. " \
      "This tool allows you to filter the found flight options by price, departure and arrival times, and airlines. " \
      "It returns a paginated list of flight options that match the specified filters and sorting option." \
      "IMPORTANT: This is very cheap operation, so you can call it as many times as needed to find the best flight options."
  )

• src/flights-mcp/proposal.py:62-70 (schema)

  Pydantic schema for the 'filters' input parameter of get_flight_options, defining all filtering options like price, duration, airlines, stops, time ranges, and sorting.

  class FiltersModel(BaseModel):
      """Model for filtering flight proposals"""
      max_total_duration: Optional[int] = Field(None, description="Maximum total duration of whole trip in minutes")
      max_price: Optional[int] = Field(None, description="Maximum price filter")
      allowed_airlines: Optional[List[str]] = Field(None, description="List of allowed airline IATA codes")
      segment_time_filters: Optional[List[SegmentTimeFilter]] = Field(None, description="Time filters for each segment")
      max_stops: Optional[int] = Field(None, description="Maximum number of stops allowed")
      sorting: Optional[SortingMethod] = Field(SortingMethod.CHEAP_FIRST, description="Sorting method")

• src/flights-mcp/proposal.py:517-553 (helper)

  Key helper method on ProposalsBatchModel that performs the filtering and sorting logic called by the tool handler.

  def apply_filters(self, filters: FiltersModel) -> 'ProposalsBatchModel':
      """
      Apply filters to the proposals and return a new ProposalsBatchModel with filtered results.
      
      Args:
          filters: FiltersModel containing all filter criteria
          
      Returns:
          New ProposalsBatchModel with filtered proposals
      """
      filtered_proposals = []
      
      for proposal in self.proposals:
          if self._proposal_matches_filters(proposal, filters):
              filtered_proposals.append(proposal)
      
      # Apply sorting
      if filters.sorting:
          filtered_proposals = self._sort_proposals(filtered_proposals, filters.sorting)
      
      # Create new instance with filtered proposals
      return ProposalsBatchModel(
          proposals=filtered_proposals,
          airports=self.airports,
          search_id=self.search_id,
          chunk_id=self.chunk_id,
          meta=self.meta,
          airlines=self.airlines,
          gates_info=self.gates_info,
          flight_info=self.flight_info,
          segments=self.segments,
          market=self.market,
          clean_marker=self.clean_marker,
          open_jaw=self.open_jaw,
          currency=self.currency,
          initiated_at=self.initiated_at
      )

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

  TTL cache used to store search results by search_id, enabling the get_flight_options tool to retrieve previous search batches.

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