fixing jsonSchema validation by using zod
This commit is contained in:
261
QUICKSTART.md
Normal file
261
QUICKSTART.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user