Duffel MCP Server

# Duffel MCP Server - Code Structure This document describes the modular organization of the Duffel MCP Server codebase. ## Directory Structure ``` duffel-mcp/ ├── duffel_mcp.py # Main entry point (~25 lines) ├── duffel_mcp/ # Main package directory │ ├── __init__.py # Package initialization │ ├── config.py # Configuration and constants │ ├── server.py # MCP server instance │ ├── models/ # Pydantic models │ │ ├── __init__.py # Model exports │ │ ├── common.py # Shared models (ResponseFormat, PaymentType) │ │ ├── flights.py # Flight-related models │ │ ├── stays.py # Accommodation-related models │ │ └── airports.py # Airport-related models │ ├── api/ # API client utilities │ │ ├── __init__.py # API exports │ │ └── client.py # HTTP client and auth │ ├── formatters/ # Response formatting │ │ ├── __init__.py # Formatter exports │ │ ├── common.py # Shared formatters │ │ ├── flights.py # Flight formatting │ │ └── stays.py # Accommodation formatting │ └── tools/ # MCP tools │ ├── __init__.py # Tool module imports │ ├── flights.py # Flight tools (~468 lines) │ ├── stays.py # Accommodation tools (~610 lines) │ └── airports.py # Airport tools (~165 lines) ├── README.md # User documentation └── STRUCTURE.md # This file (architecture guide) ``` ## Module Breakdown ### Core Modules #### `duffel_mcp.py` (Main Entry Point) - Imports the MCP server instance - Imports tool modules to register them - Runs the server when executed #### `duffel_mcp/config.py` - API configuration (base URL, version, timeout) - Response limits (character limit, pagination) - Centralized constants #### `duffel_mcp/server.py` - Initializes the FastMCP server instance - Shared by all tool modules ### Models (`duffel_mcp/models/`) Pydantic models for request/response validation: - **common.py**: Enums used across modules - `ResponseFormat`: JSON or Markdown output - `PaymentType`: Payment method types - **flights.py**: Flight-related models - `PassengerType`, `CabinClass` - `Slice`, `Passenger`, `PassengerDetails` - `FlightSearchInput`, `GetOfferInput`, `CreateOrderInput`, `GetOrderInput` - `Payment` - **stays.py**: Accommodation-related models - `GeographicLocation`, `AccommodationGuest`, `StaysGuestDetails` - `SearchAccommodationInput`, `GetAccommodationInput` - `GetAccommodationRatesInput`, `CreateStaysQuoteInput` - `CreateStaysBookingInput`, `GetStaysBookingInput` - **airports.py**: Airport-related models - `ListAirportsInput`, `SearchAirportsInput` ### API Client (`duffel_mcp/api/`) HTTP client and authentication: - **client.py** - `get_api_token()`: Retrieve API token from environment - `get_headers()`: Build auth headers - `make_api_request()`: Make HTTP requests with error handling ### Formatters (`duffel_mcp/formatters/`) Response formatting utilities: - **common.py**: Shared formatting functions - `format_currency()`: Format amounts with currency symbols - `format_duration()`: Convert ISO 8601 durations - `truncate_text()`: Limit response length - `format_json_response()`: Pretty-print JSON - **flights.py**: Flight-specific formatting - `format_markdown_flight_offer()`: Format flight offers - **stays.py**: Accommodation-specific formatting - `format_markdown_accommodation()`: Format property details - `format_markdown_accommodation_rate()`: Format room rates ### Tools (`duffel_mcp/tools/`) MCP tool implementations: - **flights.py** (4 tools): - `duffel_search_flights`: Search for flights - `duffel_get_offer`: Get flight offer details - `duffel_create_order`: Book a flight - `duffel_get_order`: Retrieve flight booking - **stays.py** (6 tools): - `duffel_search_accommodation`: Search for accommodations - `duffel_get_accommodation`: Get property details - `duffel_get_accommodation_rates`: Get room rates - `duffel_create_stays_quote`: Create booking quote - `duffel_create_stays_booking`: Book accommodation - `duffel_get_stays_booking`: Retrieve stays booking - **airports.py** (2 tools): - `duffel_search_airports`: Search airports by name/code - `duffel_list_airports`: List airports by country ## Benefits of Modular Structure ### Maintainability - **Separation of Concerns**: Each module has a single responsibility - **Easier Navigation**: Find code quickly by category - **Reduced Complexity**: Smaller files are easier to understand ### Scalability - **Easy to Extend**: Add new tools by creating new files in `tools/` - **Modular Testing**: Test each module independently - **Reusable Components**: Models and formatters can be imported anywhere ### Developer Experience - **Clear Organization**: Logical file structure - **Import Clarity**: Explicit imports show dependencies - **Type Safety**: Centralized models ensure consistency ## File Size Comparison | Component | Lines | Purpose | |-----------|-------|---------| | duffel_mcp.py | ~25 | Main entry point | | duffel_mcp/ package | ~2,000 | Organized modules | **Benefits**: Modular structure with clear separation of concerns ## Adding New Features ### Adding a New Tool 1. Create the tool function in the appropriate module (`tools/flights.py`, `tools/stays.py`, etc.) 2. Import required models from `duffel_mcp.models` 3. Use `@mcp.tool()` decorator (import from `..server`) 4. The tool will automatically register when the module is imported Example: ```python # In duffel_mcp/tools/flights.py from ..server import mcp from ..models import SomeNewInput @mcp.tool(name="new_flight_tool") async def new_flight_tool(params: SomeNewInput) -> str: """Tool description.""" # Implementation pass ``` ### Adding a New Model 1. Add the model to the appropriate file in `models/` 2. Export it in `models/__init__.py` 3. Import it where needed ### Adding a New Formatter 1. Add the formatter function to the appropriate file in `formatters/` 2. Export it in `formatters/__init__.py` 3. Import and use in tools ## Running the Server ```bash uv run python duffel_mcp.py ``` Or with direct Python: ```bash python3 duffel_mcp.py ``` ## Key Features - **12 MCP Tools**: 4 flights + 6 stays + 2 airports - **Type-Safe Models**: Pydantic validation throughout - **Clean Separation**: Models, API client, formatters, and tools in separate modules - **Easy to Extend**: Add new tools without touching existing code - **Comprehensive**: Both JSON and Markdown output formats