Duffel MCP Server

Instructions

Implementation Reference

• duffel_mcp/tools/flights.py:369-458 (handler)

  The handler function that implements the core logic of duffel_get_order: makes API call to retrieve order details and formats the output in JSON or Markdown.
  async def get_order(params: GetOrderInput) -> str: """ Retrieve complete details for an existing flight order. This tool fetches: - Order status and booking reference - Flight itinerary and schedule - Passenger information - Payment and pricing details - Documents and tickets - Change and cancellation options Use this when: - User needs to review their booking - Checking order status - Before making changes or cancellations - Retrieving booking reference for airline website Returns order details in specified format (JSON or Markdown). """ try: response = await make_api_request( method="GET", endpoint=f"/air/orders/{params.order_id}" ) order = response["data"] if params.response_format == ResponseFormat.JSON: return truncate_text(format_json_response(order)) else: # Markdown format lines = [ "# Flight Order Details", "", f"**Order ID**: `{order['id']}`", f"**Booking Reference**: {order.get('booking_reference', 'N/A')}", f"**Status**: {order.get('status', 'N/A')}", f"**Total**: {format_currency(order['total_amount'], order['total_currency'])}", f"**Booked**: {order.get('created_at', 'N/A')}", "", "## Passengers" ] for i, pax in enumerate(order.get("passengers", []), 1): lines.append(f"{i}. {pax.get('given_name')} {pax.get('family_name')}") if pax.get('born_on'): lines.append(f" - DOB: {pax['born_on']}") lines.append("") lines.append("## Flight Itinerary") for i, slice_info in enumerate(order.get("slices", []), 1): origin = slice_info["origin"] destination = slice_info["destination"] lines.append(f"\n### Slice {i}: {origin['city_name']} → {destination['city_name']}") lines.append(f"**Departure**: {slice_info['departure_at']} ({origin['iata_code']})") lines.append(f"**Arrival**: {slice_info['arrival_at']} ({destination['iata_code']})") lines.append(f"**Duration**: {format_duration(slice_info.get('duration', ''))}") for j, segment in enumerate(slice_info.get("segments", []), 1): carrier = segment.get("marketing_carrier", {}) lines.append(f"\n**Flight {j}**: {carrier.get('name', 'N/A')} {segment.get('marketing_carrier_flight_number', '')}") lines.append(f"- Aircraft: {segment.get('aircraft', {}).get('name', 'N/A')}") conditions = order.get("conditions", {}) if conditions: lines.append("\n## Booking Conditions") change_before = conditions.get("change_before_departure", {}) if change_before: allowed = "✅ Yes" if change_before.get("allowed") else "❌ No" lines.append(f"- Changes before departure: {allowed}") if change_before.get("penalty_amount"): penalty = format_currency( change_before["penalty_amount"], change_before.get("penalty_currency", "") ) lines.append(f" - Change fee: {penalty}") refund_before = conditions.get("refund_before_departure", {}) if refund_before: allowed = "✅ Yes" if refund_before.get("allowed") else "❌ No" lines.append(f"- Refund before departure: {allowed}") return truncate_text("\n".join(lines)) except Exception as e: return f"Error retrieving order: {str(e)}\n\nTroubleshooting:\n- Verify the order ID is correct (starts with 'ord_')\n- Check if you have access to this order\n- Order might not exist or might have been cancelled"
• duffel_mcp/models/flights.py:221-234 (schema)

  Pydantic model defining the input schema for the tool: requires order_id matching 'ord_*' pattern and optional response_format.
  class GetOrderInput(BaseModel): """Input for retrieving order details.""" model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid') order_id: str = Field( ..., description="Duffel order ID (e.g., 'ord_00009hthhsUZ8W4LxQgkjo')", pattern="^ord_[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:359-368 (registration)

  MCP tool registration decorator that registers the get_order function as the 'duffel_get_order' tool with appropriate annotations.
  @mcp.tool( name="duffel_get_order", annotations={ "title": "Get Order Details", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True } )