verint.com/gds-mock-mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
gds-mock-mcp/specs/001-mock-gds-server/contracts/mcp-tools.md

16 KiB
Raw Permalink Blame History

MCP Tool Contracts: Mock GDS MCP Server

Branch: 001-mock-gds-server | Date: 2026-04-07

Overview

This document defines the MCP tool schemas exposed by the Mock GDS MCP server. All tools follow the MCP JSON-RPC 2.0 protocol and include comprehensive JSON Schema validation.

Tool Categories

  1. Flight Operations: searchFlights, bookFlight
  2. Hotel Operations: searchHotels, bookHotel
  3. Car Rental Operations: searchCars, bookCar
  4. Booking Management: retrieveBooking, cancelBooking, listBookings

Flight Operations

searchFlights

Search for available flight options.

Tool Name: searchFlights

Description: Search for flights between two airports on a specific date. Returns mock flight options with realistic pricing, schedules, and availability.

Input Schema:

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Origin airport IATA code (3 letters, e.g., 'JFK')"
    },
    "destination": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Destination airport IATA code (3 letters, e.g., 'LAX')"
    },
    "departureDate": {
      "type": "string",
      "format": "date",
      "description": "Departure date in ISO 8601 format (YYYY-MM-DD)"
    },
    "passengers": {
      "type": "object",
      "properties": {
        "adults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9,
          "default": 1
        },
        "children": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9,
          "default": 0
        },
        "infants": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9,
          "default": 0
        }
      },
      "required": ["adults"]
    },
    "cabin": {
      "type": "string",
      "enum": ["economy", "premium_economy", "business", "first"],
      "default": "economy"
    }
  },
  "required": ["origin", "destination", "departureDate"]
}

Example Request:

{
  "origin": "JFK",
  "destination": "LAX",
  "departureDate": "2026-06-15",
  "passengers": { "adults": 2 },
  "cabin": "economy"
}

bookFlight

Create a flight booking.

Tool Name: bookFlight

Description: Book one or more flight segments with passenger details. Creates a PNR (Passenger Name Record) with TEST- prefix.

Input Schema:

{
  "type": "object",
  "properties": {
    "flightIds": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "description": "Array of flight IDs from search results"
    },
    "passengers": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["adult", "child", "infant"]
          },
          "firstName": { "type": "string", "minLength": 1, "maxLength": 50 },
          "lastName": { "type": "string", "minLength": 1, "maxLength": 50 },
          "dateOfBirth": { "type": "string", "format": "date" },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "frequentFlyerNumber": { "type": "string" }
        },
        "required": ["type", "firstName", "lastName"]
      }
    },
    "contactEmail": {
      "type": "string",
      "format": "email",
      "description": "Primary contact email"
    },
    "contactPhone": {
      "type": "string",
      "description": "Primary contact phone"
    }
  },
  "required": ["flightIds", "passengers"],
  "anyOf": [
    { "required": ["contactEmail"] },
    { "required": ["contactPhone"] }
  ]
}

Hotel Operations

searchHotels

Tool Name: searchHotels

Description: Search for hotel properties in a city with check-in/check-out dates.

Input Schema:

{
  "type": "object",
  "properties": {
    "cityCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "City IATA code (3 letters, e.g., 'LAX')"
    },
    "checkInDate": {
      "type": "string",
      "format": "date"
    },
    "checkOutDate": {
      "type": "string",
      "format": "date"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 1
    },
    "starRating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "Minimum star rating filter (optional)"
    }
  },
  "required": ["cityCode", "checkInDate", "checkOutDate"]
}

bookHotel

Tool Name: bookHotel

Description: Book a hotel reservation. Can create a new PNR or add to an existing flight booking.

Input Schema:

{
  "type": "object",
  "properties": {
    "hotelId": { "type": "string" },
    "existingPnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$",
      "description": "Optional: Add hotel to existing booking"
    },
    "guests": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "firstName": { "type": "string" },
          "lastName": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        },
        "required": ["firstName", "lastName"]
      }
    },
    "specialRequests": { "type": "string" }
  },
  "required": ["hotelId", "guests"]
}

Car Rental Operations

searchCars

Tool Name: searchCars

Description: Search for car rental options at an airport or city location.

Input Schema:

{
  "type": "object",
  "properties": {
    "pickupLocationCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "dropoffLocationCode": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Defaults to pickup location if not specified"
    },
    "pickupDate": {
      "type": "string",
      "format": "date-time"
    },
    "dropoffDate": {
      "type": "string",
      "format": "date-time"
    },
    "driverAge": {
      "type": "integer",
      "minimum": 21,
      "maximum": 99,
      "default": 30
    }
  },
  "required": ["pickupLocationCode", "pickupDate", "dropoffDate"]
}

bookCar

Tool Name: bookCar

Description: Book a car rental. Can create a new PNR or add to an existing booking.

Booking Management Operations

retrieveBooking

Tool Name: retrieveBooking

Description: Fetch complete booking details including all segments.

Input Schema:

{
  "type": "object",
  "properties": {
    "pnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$"
    }
  },
  "required": ["pnr"]
}

cancelBooking

Tool Name: cancelBooking

Description: Cancel a confirmed booking.

Input Schema:

{
  "type": "object",
  "properties": {
    "pnr": {
      "type": "string",
      "pattern": "^TEST-[A-Z0-9]{6}$"
    },
    "reason": { "type": "string" }
  },
  "required": ["pnr"]
}

listBookings

Tool Name: listBookings

Description: Retrieve a list of all PNRs created in the current MCP session.

Input Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["all", "confirmed", "cancelled"],
      "default": "all"
    }
  }
}

Error Responses

All tools return standard MCP errors:

  • -32602: Invalid params (validation failure)
  • -32603: Internal error (server error)
  • -32001: Resource not found (invalid PNR, airport code, etc.)
  • -32002: Business logic error (cancelled booking, date in past, etc.)

Error Format:

{
  "code": -32602,
  "message": "Invalid airport code 'XYZ': must be a valid 3-letter IATA code",
  "data": {
    "field": "origin",
    "value": "XYZ"
  }
}

MCP Resource Endpoints

  • gds://session/current - Current session metadata
  • gds://session/bookings - List of all bookings
  • gds://mock-data/airports - Mock airport data
  • gds://mock-data/airlines - Mock airline data

Protocol Notes

  • All tools use JSON-RPC 2.0 over stdio (default) or SSE
  • Tool schemas validated before execution
  • Timestamps use ISO 8601 format
  • Prices in USD cents (integer)
  • All PNRs prefixed with "TEST-" for safety

Remote Access Endpoints (Added 2026-04-07)

The following endpoints are available when running in HTTP/2 remote transport mode.

Health Check Endpoint

Endpoint: GET /health

Description: Returns server operational status for monitoring and health checks. This endpoint is unauthenticated and exempt from rate limiting.

Use Cases:

  • Load balancer health checks
  • Monitoring system integration (Prometheus, Datadog, etc.)
  • Deployment validation
  • Debugging connection and memory issues

HTTP Method: GET

Authentication: None (publicly accessible)

Rate Limiting: Exempt (not subject to rate limits)

Request: No body required

Response Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["healthy", "degraded", "unhealthy"],
      "description": "Overall server health status"
    },
    "uptime": {
      "type": "integer",
      "description": "Server uptime in seconds since start"
    },
    "version": {
      "type": "string",
      "description": "Server version (from package.json)"
    },
    "connections": {
      "type": "object",
      "properties": {
        "stdio": {
          "type": "integer",
          "description": "Active stdio connections (0 or 1)"
        },
        "http": {
          "type": "integer",
          "description": "Active HTTP/2 connections"
        },
        "total": {
          "type": "integer",
          "description": "Total active connections"
        }
      },
      "required": ["stdio", "http", "total"]
    },
    "sessions": {
      "type": "object",
      "properties": {
        "active": {
          "type": "integer",
          "description": "Sessions with recent activity (within 5 minutes)"
        },
        "total": {
          "type": "integer",
          "description": "Total sessions in storage"
        }
      },
      "required": ["active", "total"]
    },
    "storage": {
      "type": "object",
      "properties": {
        "connected": {
          "type": "boolean",
          "description": "Valkey connection status"
        },
        "responseTime": {
          "type": "number",
          "description": "Valkey ping response time in milliseconds"
        }
      },
      "required": ["connected", "responseTime"]
    },
    "memory": {
      "type": "object",
      "properties": {
        "used": {
          "type": "number",
          "description": "Process memory used in MB"
        },
        "total": {
          "type": "number",
          "description": "Total system memory in MB"
        },
        "percentage": {
          "type": "number",
          "description": "Memory usage percentage (0-1)"
        }
      },
      "required": ["used", "total", "percentage"]
    },
    "timestamp": {
      "type": "integer",
      "description": "Health check timestamp (Unix milliseconds)"
    }
  },
  "required": ["status", "uptime", "version", "connections", "sessions", "storage", "memory", "timestamp"]
}

Status Determination:

  • healthy (200 OK): All systems operational
    • Storage connected
    • Memory usage < 80%
    • Valkey response time < 100ms
  • degraded (200 OK): Some issues but still serving requests
    • Storage slow (ping 100-500ms)
    • Memory usage 80-90%
  • unhealthy (503 Service Unavailable): Critical issues
    • Storage disconnected
    • Memory usage > 90%
    • Unable to serve requests

Example Response (Healthy):

{
  "status": "healthy",
  "uptime": 3600,
  "version": "0.1.0",
  "connections": {
    "stdio": 0,
    "http": 12,
    "total": 12
  },
  "sessions": {
    "active": 8,
    "total": 15
  },
  "storage": {
    "connected": true,
    "responseTime": 2.5
  },
  "memory": {
    "used": 45.2,
    "total": 8192,
    "percentage": 0.0055
  },
  "timestamp": 1712486460000
}

Example Response (Degraded):

{
  "status": "degraded",
  "uptime": 7200,
  "version": "0.1.0",
  "connections": {
    "stdio": 0,
    "http": 45,
    "total": 45
  },
  "sessions": {
    "active": 42,
    "total": 50
  },
  "storage": {
    "connected": true,
    "responseTime": 150
  },
  "memory": {
    "used": 6553.6,
    "total": 8192,
    "percentage": 0.8
  },
  "timestamp": 1712490060000
}

Example Response (Unhealthy):

{
  "status": "unhealthy",
  "uptime": 10800,
  "version": "0.1.0",
  "connections": {
    "stdio": 0,
    "http": 0,
    "total": 0
  },
  "sessions": {
    "active": 0,
    "total": 0
  },
  "storage": {
    "connected": false,
    "responseTime": null
  },
  "memory": {
    "used": 120,
    "total": 8192,
    "percentage": 0.015
  },
  "timestamp": 1712493660000
}

cURL Example:

curl -i http://localhost:8080/health

Load Balancer Integration (Nginx):

upstream mcp_backend {
    server mcp-server:3000;
    health_check interval=10s uri=/health;
}

Prometheus Monitoring:

scrape_configs:
  - job_name: 'mcp-server'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: '/health'
    scrape_interval: 30s

Rate Limiting (HTTP Mode Only)

When running in HTTP/2 remote mode, all MCP tool endpoints are subject to rate limiting.

Algorithm: Sliding Window Counter (Hybrid)

Default Limits:

  • 100 requests per minute per client IP address
  • Window size: 60 seconds
  • Burst tolerance: ~150 requests in worst-case window overlap

Rate Limit Headers (included in all HTTP responses):

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1712486520

Rate Limit Exceeded Response (429 Too Many Requests):

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 100,
  "current": 105,
  "resetAt": "2026-04-07T10:02:00.000Z",
  "retryAfter": 15
}

HTTP Headers on 429:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712486520
Retry-After: 15
Content-Type: application/json

Exemptions:

  • Health check endpoint (/health) is exempt from rate limiting
  • CORS preflight requests (OPTIONS) are exempt

Configuration:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=100
RATE_LIMIT_WINDOW_SECONDS=60

CORS Headers (HTTP Mode Only)

When running in HTTP/2 remote mode, all endpoints support cross-origin requests.

CORS Policy: Permissive wildcard (Access-Control-Allow-Origin: *)

Preflight Request (OPTIONS):

OPTIONS /mcp HTTP/1.1
Origin: https://web-client.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, MCP-Session-ID

Preflight Response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, MCP-Session-ID, X-Requested-With
Access-Control-Max-Age: 86400

Actual Request Headers (added to all responses):

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: false
Access-Control-Expose-Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Security Note: Wildcard CORS is appropriate for development/testing with mock data only. Deploy within private networks (VPN, firewalls) for security.

Transport Mode Configuration

Environment Variables:

# Transport selection
TRANSPORT_MODE=stdio|http|both    # Default: stdio

# HTTP/2 configuration (when http or both)
HTTP_PORT=3000                    # Internal port (default: 3000)
HTTP_HOST=127.0.0.1              # Bind address (default: 127.0.0.1 for proxy)

# External access via reverse proxy
# Nginx listens on :8080 (HTTP/2 + TLS)
# Proxies to mcp-server:3000 (HTTP/1.1)

Protocol Notes (Updated):

  • stdio mode: JSON-RPC 2.0 over stdin/stdout (local only)
  • http mode: JSON-RPC 2.0 over SSE via StreamableHTTPServerTransport
  • HTTP/2: Provided by nginx reverse proxy (terminates HTTP/2, proxies HTTP/1.1)
  • CORS: Enabled in http mode, wildcard policy
  • Rate limiting: Enabled in http mode, IP-based tracking
  • Health checks: Available in http mode at /health
Reference in New Issue View Git Blame Copy Permalink