duffel_search_airports

Instructions

Search for airports by name, city, or IATA code.

This tool helps users find correct airport codes for flight searches by:
- Searching airport names (e.g., "Heathrow", "Charles de Gaulle")
- Searching city names (e.g., "London", "Paris")
- Validating IATA codes (e.g., "LHR", "CDG")

Results include:
- Airport name and IATA code
- City and country information
- GPS coordinates
- Time zone

Use this when:
- User provides city/airport names instead of codes
- Verifying airport codes before search
- Finding all airports in a city
- User unsure of exact airport code

Returns matching airports in specified format (JSON or Markdown).

Implementation Reference

• duffel_mcp/tools/airports.py:20-99 (handler)

  The main handler function for the duffel_search_airports tool. It searches the Duffel API for airports matching the query in name, city, or IATA codes, filters results, and formats the output as JSON or Markdown.

  async def search_airports(params: SearchAirportsInput) -> str:
      """
      Search for airports by name, city, or IATA code.
      
      This tool helps users find correct airport codes for flight searches by:
      - Searching airport names (e.g., "Heathrow", "Charles de Gaulle")
      - Searching city names (e.g., "London", "Paris")
      - Validating IATA codes (e.g., "LHR", "CDG")
      
      Results include:
      - Airport name and IATA code
      - City and country information
      - GPS coordinates
      - Time zone
      
      Use this when:
      - User provides city/airport names instead of codes
      - Verifying airport codes before search
      - Finding all airports in a city
      - User unsure of exact airport code
      
      Returns matching airports in specified format (JSON or Markdown).
      """
      try:
          response = await make_api_request(
              method="GET",
              endpoint="/air/airports",
              params={"limit": 200}
          )
          
          airports = response["data"]
          query_lower = params.query.lower()
          
          matches = []
          for airport in airports:
              if (
                  query_lower in airport.get("name", "").lower() or
                  query_lower in airport.get("city_name", "").lower() or
                  query_lower == airport.get("iata_code", "").lower() or
                  query_lower in airport.get("iata_city_code", "").lower()
              ):
                  matches.append(airport)
                  if len(matches) >= params.limit:
                      break
          
          if not matches:
              return (
                  f"No airports found matching '{params.query}'.\n\n"
                  f"Try:\n"
                  f"- A different spelling\n"
                  f"- The city name instead of airport name\n"
                  f"- A broader search term"
              )
          
          if params.response_format == ResponseFormat.JSON:
              return truncate_text(format_json_response(matches))
          
          else:  # Markdown format
              lines = [
                  f"# Airport Search Results for '{params.query}'",
                  f"",
                  f"Found {len(matches)} matching airports:",
                  ""
              ]
              
              for airport in matches:
                  city = airport.get("city", {})
                  lines.append(f"## {airport.get('name', 'N/A')}")
                  lines.append(f"**IATA Code**: `{airport.get('iata_code', 'N/A')}`")
                  lines.append(f"**City**: {airport.get('city_name', 'N/A')}")
                  if city:
                      lines.append(f"**City Code**: `{city.get('iata_code', 'N/A')}`")
                  lines.append(f"**Country**: {airport.get('iata_country_code', 'N/A')}")
                  lines.append(f"**Time Zone**: {airport.get('time_zone', 'N/A')}")
                  lines.append("")
              
              return truncate_text("\n".join(lines))
              
      except Exception as e:
          return f"Error searching airports: {str(e)}\n\nTry a different search term or check your internet connection."

• duffel_mcp/models/airports.py:31-51 (schema)

  Pydantic model defining the input schema for the duffel_search_airports tool, including query, limit, and response_format fields.

  class SearchAirportsInput(BaseModel):
      """Input for searching airports by name or code."""
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid')
  
      query: str = Field(
          ...,
          description="Search query - airport name, city, or IATA code (e.g., 'London', 'Heathrow', 'LHR')",
          min_length=2,
          max_length=100
      )
      limit: int = Field(
          default=20,
          description="Maximum number of results to return (1-100)",
          ge=1,
          le=100
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'json' for raw data or 'markdown' for readable summary"
      )

• duffel_mcp/tools/airports.py:10-19 (registration)

  MCP tool registration decorator that binds the search_airports handler function to the name 'duffel_search_airports' with appropriate annotations.

  @mcp.tool(
      name="duffel_search_airports",
      annotations={
          "title": "Search Airports",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True
      }
  )