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) )