Duffel MCP Server

Instructions

List airports with optional country filter.

This tool retrieves a paginated list of airports. Results can be filtered by country
using ISO 3166-1 alpha-2 country codes (e.g., 'US', 'GB', 'FR').

Use this when:
- Exploring available airports
- Getting airports in a specific country
- Building airport selection lists

Note: For finding a specific airport, use duffel_search_airports instead.

Returns airports in specified format (JSON or Markdown).

Implementation Reference

• duffel_mcp/tools/airports.py:111-164 (handler)

  The main handler function that executes the duffel_list_airports tool logic: processes input parameters, makes API request to /air/airports, filters by country if provided, and formats the response as JSON or Markdown.

  async def list_airports(params: ListAirportsInput) -> str:
      """
      List airports with optional country filter.
      
      This tool retrieves a paginated list of airports. Results can be filtered by country
      using ISO 3166-1 alpha-2 country codes (e.g., 'US', 'GB', 'FR').
      
      Use this when:
      - Exploring available airports
      - Getting airports in a specific country
      - Building airport selection lists
      
      Note: For finding a specific airport, use duffel_search_airports instead.
      
      Returns airports in specified format (JSON or Markdown).
      """
      try:
          query_params = {"limit": params.limit}
          if params.country_code:
              query_params["iata_country_code"] = params.country_code.upper()
          
          response = await make_api_request(
              method="GET",
              endpoint="/air/airports",
              params=query_params
          )
          
          airports = response["data"]
          
          if not airports:
              return "No airports found with the specified criteria."
          
          if params.response_format == ResponseFormat.JSON:
              return truncate_text(format_json_response(airports))
          
          else:  # Markdown format
              title = f"# Airports"
              if params.country_code:
                  title += f" in {params.country_code.upper()}"
              
              lines = [title, "", f"Showing {len(airports)} airports:", ""]
              
              for airport in airports:
                  lines.append(
                      f"- **{airport.get('iata_code', 'N/A')}**: "
                      f"{airport.get('name', 'N/A')} - "
                      f"{airport.get('city_name', 'N/A')}"
                  )
              
              return truncate_text("\n".join(lines))
              
      except Exception as e:
          return f"Error listing airports: {str(e)}"

• duffel_mcp/tools/airports.py:101-110 (registration)

  The @mcp.tool decorator that registers the list_airports function as the 'duffel_list_airports' tool with appropriate annotations.

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

• duffel_mcp/models/airports.py:9-29 (schema)

  Pydantic BaseModel defining the input parameters for the duffel_list_airports tool, including optional country_code filter, limit, and response_format.

  class ListAirportsInput(BaseModel):
      """Input for listing airports."""
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid')
  
      country_code: str | None = Field(
          default=None,
          description="Filter by ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'FR')",
          min_length=2,
          max_length=2
      )
      limit: int = Field(
          default=DEFAULT_PAGE_LIMIT,
          description="Number of results per page (1-200)",
          ge=1,
          le=MAX_PAGE_LIMIT
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'json' for raw data or 'markdown' for readable summary"
      )