npm package: @markesphere/amadeus-mcp-server
Description: MCP server for Amadeus flight/hotel search and booking - Fixed port conflicts and timeouts
Author: Privilege Mendes
Latest version: 1.1.3

# Amadeus MCP Server

This is a Model Context Protocol (MCP) server that connects to the Amadeus API to provide flight search, booking, and analysis capabilities for AI assistants.

## Features

- **Flight Search**: Find flights between airports with various parameters
- **Airport Information**: Search for airports by keyword, city, or country
- **Price Analysis**: Get price metrics for routes to determine if current prices are high or low
- **Cheapest Dates**: Find the most economical dates to travel
- **Flight Details**: Get detailed information about specific flight offers
- **Hotel Search**: Find hotels by location, city, or coordinates
- **Hotel Offers**: Get hotel availability and pricing information with detailed room options

## Prompts

The server provides several pre-configured prompts for common travel planning scenarios:

1. **Analyze Flight Prices** (`analyze-flight-prices`): Analyze flight prices for a route with insights on pricing trends
2. **Find Best Deals** (`find-best-deals`): Find the best flight deals for a specific route and date
3. **Plan Multi-City Trip** (`plan-multi-city-trip`): Plan a complete multi-city itinerary with optimal routing
4. **Find Cheapest Travel Dates** (`find-cheapest-travel-dates`): Identify the most economical dates to travel

*Note: Hotel-related prompts will be added once the hotel search tools are fully implemented.*

## Setup

### Prerequisites

- Node.js 16.x or higher
- Amadeus API credentials (Client ID and Secret)

### Installation

1. Clone the repository:
```
git clone https://github.com/yourusername/amadeus-mcp-server.git
cd amadeus-mcp-server
```

2. Install dependencies:
```
npm install
```

3. Create a `.env` file in the root directory with your Amadeus API credentials:
```
AMADEUS_CLIENT_ID=your_client_id
AMADEUS_CLIENT_SECRET=your_client_secret
```

### Running the Server

The server automatically detects the transport mode:

**For Claude Desktop (via npx):**
```
npx @markesphere/amadeus-mcp-server
```

**For HTTP/SSE mode (web applications):**
```
npm run build
npm start
```

**Force specific transport modes:**
```
# Force stdio transport
npx @markesphere/amadeus-mcp-server --stdio

# Force HTTP transport  
npx @markesphere/amadeus-mcp-server --http
```

For development:
```
npm run dev
```

### Testing and Development

This project uses Jest for testing and Biome for linting and formatting.

Run unit tests:
```
npx jest
```

Run tests with watch mode:
```
npx jest --watch
```

Run tests with coverage:
```
npx jest --coverage
```

Run integration tests (requires Amadeus API credentials):
```
npm run test:integration
```

Run hotel-specific integration tests:
```
npm run test:hotels
```

Run linting:
```
npm run lint
```

Format code:
```
npm run format
```

## Integration Testing

The project includes comprehensive integration tests that verify the server's interaction with the real Amadeus API. These tests help ensure that our API clients work correctly with the actual API endpoints and handle responses appropriately.

### Requirements for Integration Tests

- **Amadeus API Credentials**: Tests require valid Amadeus API credentials in the `.env` file:
  ```
  AMADEUS_CLIENT_ID=your_client_id
  AMADEUS_CLIENT_SECRET=your_client_secret
  ```

- **Test Environment**: Tests are configured to use the Amadeus Test Environment, not the production API.

### Running Integration Tests

```
npm run test:integration
```

The integration tests are located in `__tests__/integration` and validate the following API features:

- **Airport Search**: Searching for airports by code or keyword
- **Flight Search**: Finding flights for one-way and round-trip journeys
- **Price Analysis**: Getting price metrics for specific routes
- **Hotel Search**: Finding hotels by city, coordinates, and location
- **Hotel Offers**: Getting hotel availability, pricing, and booking options

### Best Practices for Integration Testing

1. **API Rate Limits**: The tests include automatic rate limit handling with exponential backoff to avoid API throttling. When running tests frequently, you may still encounter rate limits.

2. **Conditional Testing**: Tests are designed to skip automatically if API credentials are missing, allowing the test suite to run without errors in environments without credentials.

3. **Test in Isolation**: When developing a new feature, you can run specific test files:
   ```
   npx jest __tests__/integration/flight-search.test.js
   npx jest __tests__/integration/hotel-search.test.js
   npx jest __tests__/integration/hotel-booking.test.js
   ```

4. **Longer Timeouts**: Integration tests use longer timeouts (60 seconds) to accommodate network latency and retries.

5. **Mock for CI/CD**: For continuous integration pipelines where real API access isn't available, use `__tests__/amadeus-mock.test.js` which runs without actual API calls.

### Hotel Integration Tests

The hotel integration tests in `__tests__/integration/` validate hotel search and booking functionality:

- **`hotel-search.test.js`**: Tests core hotel search by city, coordinates, and location with offer retrieval
- **`hotel-booking.test.js`**: Tests advanced booking scenarios including multi-room bookings and price analysis

These tests include comprehensive scenarios for:
- Finding hotels by city code (e.g., Paris, London)
- Searching hotels by geographic coordinates 
- Retrieving hotel offers with availability and pricing
- Testing multi-room group bookings
- Validating hotel details and rate policies

## Integration

To use this MCP server with OpenAI's Assistant API or other compatible AI systems, configure the assistant to connect to this server's endpoint.

## Tools

The server provides the following tools:

### `search-flights`
Search for flight offers between two locations.

### `search-airports`
Search for airports by keyword, city name, or IATA code.

### `flight-price-analysis`
Get price metrics for a flight route to determine if current prices are high or low.

### `get-flight-details`
Get detailed information about a specific flight offer.

### `find-cheapest-dates`
Find the cheapest dates to fly for a given route.

### `search-hotels-by-location`
Search for hotels by city, coordinates, or location keywords.

### `search-hotel-offers`
Get hotel availability and pricing information with detailed room options and booking policies.

*Note: Hotel tools are currently in development. Integration tests are complete and ready for implementation.*

## Resources

The server provides schema resources for:

- Flight offers (`schema://flight-offers`)
- Airports (`schema://airports`)
- Hotels (`schema://hotels`)
- Hotel offers (`schema://hotel-offers`)

## License

MIT