Duffel MCP Server

Instructions

Implementation Reference

• duffel_mcp/tools/flights.py:127-189 (handler)

  The handler function that implements the core logic of the duffel_get_offer tool, fetching offer details from Duffel API, validating expiration, and formatting output.
  async def get_offer(params: GetOfferInput) -> str: """ Retrieve detailed information and current pricing for a specific flight offer. This tool fetches the latest version of an offer, including: - Up-to-date pricing and availability - Complete flight schedule and routing - Passenger requirements and restrictions - Baggage allowance and cabin details - Cancellation and change policies Use this when: - User selects a flight from search results - Before booking to confirm current price - To check if an offer is still available - To get passenger IDs needed for booking Important: Always retrieve the offer immediately before booking to ensure pricing is current, as offers expire after 15-30 minutes. Returns offer details in specified format (JSON or Markdown). """ try: response = await make_api_request( method="GET", endpoint=f"/air/offers/{params.offer_id}" ) offer = response["data"] expires_at = datetime.fromisoformat(offer["expires_at"].replace("Z", "+00:00")) if expires_at < datetime.now().astimezone(): return ( f"⚠️ This offer has expired at {offer['expires_at']}.\n\n" "Offers typically expire 15-30 minutes after creation. " "Please perform a new flight search to get current offers." ) if params.response_format == ResponseFormat.JSON: return truncate_text(format_json_response(offer)) else: # Markdown format result = format_markdown_flight_offer(offer) passengers = offer.get("passengers", []) if passengers: result += "\n### Passengers\n" for i, pax in enumerate(passengers, 1): result += f"{i}. **ID**: `{pax['id']}` - Type: {pax.get('type', 'N/A')}\n" conditions = offer.get("conditions", {}) if conditions: result += "\n### Booking Conditions\n" if conditions.get("change_before_departure"): result += f"- Change allowed: {conditions['change_before_departure'].get('allowed', False)}\n" if conditions.get("refund_before_departure"): result += f"- Refund allowed: {conditions['refund_before_departure'].get('allowed', False)}\n" return truncate_text(result) except Exception as e: return f"Error retrieving offer: {str(e)}\n\nTroubleshooting:\n- Verify the offer ID is correct (starts with 'off_')\n- Check if the offer has expired\n- Offer might have been booked by someone else"
• duffel_mcp/models/flights.py:117-130 (schema)

  Pydantic input schema defining parameters for duffel_get_offer: offer_id (required, validated pattern) and response_format.
  class GetOfferInput(BaseModel): """Input for retrieving a specific flight offer.""" model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid') offer_id: str = Field( ..., description="Duffel offer ID (e.g., 'off_00009htYpSCXrwaB9DnUm0')", pattern="^off_[a-zA-Z0-9]+$" ) response_format: ResponseFormat = Field( default=ResponseFormat.MARKDOWN, description="Output format: 'json' for raw data or 'markdown' for readable summary" )
• duffel_mcp/tools/flights.py:117-126 (registration)

  MCP decorator registering the tool with name 'duffel_get_offer' and operational annotations.
  @mcp.tool( name="duffel_get_offer", annotations={ "title": "Get Flight Offer Details", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True } )