gds-mock-mcp/QUICKSTART.md

# Quick Start Guide - GDS Mock MCP Server

## Prerequisites
- Node.js 20 LTS
- Docker and Docker Compose (recommended)
- Valkey 8.0+ or Redis

## Running the Server

### Option 1: Docker Compose (Recommended)
```bash
# Start all services (GDS server + Valkey)
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f gds-mock-mcp

# Stop services
docker compose down
```

### Option 2: Local Development
```bash
# Start Valkey
docker run -d --name valkey -p 6379:6379 valkey/valkey:8-alpine

# Start the HTTP server
node src/index.js

# Server will listen on http://127.0.0.1:3000
```

## Testing the Server

### Health Check
```bash
curl http://localhost:3000/health
```

Expected response:
```json
{
  "status": "healthy",
  "service": "gds-mock-mcp",
  "uptime": 10.5,
  "timestamp": "2026-04-08T03:00:00.000Z"
}
```

### MCP Initialize

First, initialize an MCP session to get a session ID:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": 1,
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
```

The response will include a session ID in the `mcp-session-id` header. Extract this for subsequent requests.

Example response:
```
< mcp-session-id: 550e8400-e29b-41d4-a716-446655440000

data: {"jsonrpc":"2.0","result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"gds-mock-mcp","version":"0.1.0"}},"id":1}
```

### List Available Tools

Use the session ID from the initialize response:

```bash
# Replace SESSION_ID with the actual session ID from initialization
SESSION_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-11-25" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2,
    "params": {}
  }'
```

### Search for Flights

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-11-25" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "searchFlights",
      "arguments": {
        "origin": "LAX",
        "destination": "JFK",
        "departureDate": "2026-05-15",
        "passengers": 1
      }
    }
  }'
```

## Available Tools

The server provides 11 MCP tools:

### Flight Operations
- `searchFlights` - Search for available flights
- `bookFlight` - Book a flight with passenger details

### Hotel Operations  
- `searchHotels` - Search for hotels by city
- `bookHotel` - Book a hotel room

### Car Rental Operations
- `searchCars` - Search for rental cars
- `bookCar` - Book a rental car

### Booking Management
- `retrieveBooking` - Get booking details by PNR
- `cancelBooking` - Cancel an existing booking
- `listBookings` - List all bookings in current session

### Session Management
- `getSessionInfo` - Get current session information
- `clearSession` - Clear all bookings from session

## Environment Variables

### Server Configuration
- `PORT` - HTTP server port (default: `3000`)
- `HOST` - HTTP server host (default: `127.0.0.1`, use `0.0.0.0` for Docker)
- `LOG_LEVEL` - Logging level (`trace`, `debug`, `info`, `warn`, `error`, default: `info`)
- `NODE_ENV` - Environment (`development` or `production`, default: `development`)

### Valkey/Redis Configuration
- `VALKEY_HOST` - Valkey host (default: `localhost`)
- `VALKEY_PORT` - Valkey port (default: `6379`)
- `VALKEY_PASSWORD` - Valkey password (optional)
- `VALKEY_DB` - Valkey database number (default: `0`)

### Rate Limiting & CORS
- `RATE_LIMIT_MAX` - Max requests per minute (default: `100`)
- `CORS_ORIGINS` - Allowed CORS origins (comma-separated, default: `*`)

## Command Line Arguments

```bash
node src/index.js [options]

Options:
  --port <number>       HTTP server port (default: 3000)
  --host <address>      HTTP server host (default: 127.0.0.1)
  --verbose             Enable verbose logging (sets LOG_LEVEL=debug)
  --log-level <level>   Set log level (trace|debug|info|warn|error)
  --help                Show help message
```

## Example Usage

### Start HTTP server on custom port
```bash
node src/index.js --port 8080 --host 0.0.0.0
```

### Start with debug logging
```bash
node src/index.js --verbose
```

### Docker with custom port
```bash
PORT=8080 docker compose up -d
```

## Troubleshooting

### Server won't start
1. Check Valkey is running: `docker ps | grep valkey`
2. Check port is available: `lsof -i :3000`
3. Check logs: `docker compose logs gds-mock-mcp`

### "Connection refused" errors
- Ensure Valkey is running on port 6379
- Check `VALKEY_HOST` environment variable

### "Empty reply from server"
- This error was fixed in the latest version
- Ensure you're using the updated code

### Rate limit errors (429)
- Default: 100 requests per minute per IP
- Wait 60 seconds or adjust rate limit in `src/middleware/rate-limit.js`

## Development

### Install dependencies
```bash
npm install
```

### Run linter
```bash
npm run lint
```

### Build Docker image
```bash
npm run docker:build
```

## Safety Notes

⚠️ **This is a MOCK server for testing and demonstration purposes only.**

- All PNRs are prefixed with `TEST-` to prevent production confusion
- Uses in-memory Valkey for session storage (data is not persistent)
- CORS is configured with wildcard (`*`) for development
- Not suitable for production without security enhancements

For production use, implement:
- Real GDS API integrations (Amadeus, Sabre, Travelport)
- Proper authentication and authorization
- TLS/SSL encryption
- Persistent database storage
- Restricted CORS policy
- Rate limiting based on authenticated users

---

**Version**: 0.1.0  
**MCP Protocol**: 2025-11-25  
**Last Updated**: 2026-04-08