Skip to main content
Glama
Atithi Driver Booking MCP Server

Atithi Driver Booking MCP Server

by SATISHUD

Atithi Driver Booking MCP Server

TypeScript Model Context Protocol SQLite Tests

Production-ready Model Context Protocol (MCP) server for the Atithi Platform, providing an AI-powered automated driver dispatch and cab booking system for hotel guests.


Table of Contents


Related MCP server: Beckn Mobility MCP Server

Overview

The Atithi Driver Booking MCP Server allows AI Agents (like Claude Desktop or Voice Assistants) to seamlessly manage cab bookings, estimate fares using a $20 \times 20$ distance matrix, and dispatch cab drivers using a 2-tier priority matching algorithm (Hotel Preferred Pool $\rightarrow$ Global Pool).

Key Features

  • 18 Automated MCP Tools: Covering driver onboarding, preferred hotel mapping, fare pricing, 2-tier dispatch, call attempt tracking, and ride lifecycle completion.

  • 2-Tier Dispatch Algorithm: Prioritizes hotel preferred drivers before searching the global driver pool at the pickup location, ordered by driver performance score (driver_score DESC).

  • Driver Score & Penalty Engine: Dynamically awards points (+10 for completion) and applies penalties (-10 for rejection, -20 for driver cancellation) with auto-suspensions (<500 score).

  • Embedded SQLite Persistence: Fast, synchronous local database backed by better-sqlite3.


Architecture

The server communicates via standard I/O (stdio) using JSON-RPC 2.0 protocol specifications defined by Anthropic's Model Context Protocol SDK.

AI Client (Claude Desktop / Voice AI)
  │
  ├─► JSON-RPC over Stdio ──► MCP Server (dist/index.js)
  │                              │
  │                              ├─► Pricing Engine (Matrix Lookup)
  │                              ├─► 2-Tier Dispatch Algorithm
  │                              └─► SQLite Database (better-sqlite3)

For detailed architectural diagrams and state machines, see docs/ARCHITECTURE.md.


Repository Structure

mcpserver3/
├── .gitignore               # Git ignore rules
├── package.json             # NPM scripts and dependencies
├── tsconfig.json            # TypeScript compiler configuration
├── README.md                # Project documentation
├── docs/                    # Technical documentation
│   ├── ARCHITECTURE.md      # Architectural design & PERSISTENCE
│   ├── TOOLS.md             # Complete 18-tool API reference
│   ├── DB_AUDIT_REPORT.md   # Database audit report
│   └── IMPLEMENTATION_PLAN.md # Implementation roadmap
├── src/                     # TypeScript source code
│   ├── config/              # Configuration files
│   ├── tools/               # MCP Tool implementation handlers
│   │   ├── booking.ts       # Booking creation & 2-Tier dispatch
│   │   ├── dispatch.ts      # Call attempt logger & response status
│   │   ├── driver.ts        # Driver onboarding & verification
│   │   ├── hotel.ts         # Preferred driver mapping
│   │   ├── lifecycle.ts     # Ride completion & penalties
│   │   ├── pricing.ts       # Fare estimation & distance matrix
│   │   └── query.ts         # System inspection & status queries
│   ├── db.ts                # SQLite connection & auto-migrations
│   ├── idgen.ts             # Primary key generators
│   ├── index.ts             # Server entry point & stdio transport
│   ├── response.ts          # ToolResult JSON envelope builders
│   ├── seed_distances.ts    # 400 location pair distance seeder
│   ├── seed_expanded_dataset.ts # 150 Drivers & 150 Vehicles dataset generator
│   ├── setup_test_db.ts     # Sandbox DB test seeder
│   ├── test.ts              # 120-test integration test suite
│   ├── types.ts             # TypeScript interfaces & DTO models
│   └── verify.ts            # Verification suite

Installation & Setup

Prerequisites

  • Node.js: v18.0.0 or higher

  • npm: v9.0.0 or higher

Step-by-Step Setup

  1. Clone the repository:

    git clone https://github.com/atithi/driver-booking-mcp.git
    cd driver-booking-mcp
  2. Install dependencies:

    npm install
  3. Build the TypeScript source:

    npm run build

Environment Configuration

The server supports the following environment variable and argument overrides:

Variable / Flag

Description

Default

MCP_TRANSPORT / --transport

Transport mode (stdio or http)

stdio

MCP_PORT / PORT / --port

HTTP server listening port (in http mode)

3000

MCP_HOST / HOST / --host

HTTP server bind host (in http mode)

127.0.0.1

ATITHI_DB_PATH

Absolute path to the SQLite database file

./atithi_dummy_dataset.db


Build & Run Instructions

1. STDIO Mode (Claude Desktop & CLI)

  • Start MCP server (stdio transport):

    npm start
  • Development mode (compile & start):

    npm run dev

2. Streamable HTTP Mode (Atithi Platform Integration)

  • Start MCP server (Streamable HTTP transport on http://127.0.0.1:3000/mcp):

    npm run start:http
  • Custom Port/Host via CLI flags:

    node dist/index.js --transport=http --port=8080 --host=0.0.0.0

3. Docker Container Deployment

  • Build Production Docker Image:

    docker build -t atithi-driver-booking-mcp:latest .
  • Run Container (Default Streamable HTTP Mode on Port 3000):

    docker run -d -p 3000:3000 --name atithi-mcp-server atithi-driver-booking-mcp:latest
  • Run with Custom Host SQLite Database Volume Mounting:

    docker run -d -p 3000:3000 \
      -v /path/to/host/atithi_dummy_dataset.db:/app/atithi_dummy_dataset.db \
      -e ATITHI_DB_PATH=/app/atithi_dummy_dataset.db \
      --name atithi-mcp-server atithi-driver-booking-mcp:latest
  • Run with Custom Port and Host Environment Overrides:

    docker run -d -p 8080:8080 \
      -e MCP_PORT=8080 \
      -e MCP_HOST=0.0.0.0 \
      --name atithi-mcp-server atithi-driver-booking-mcp:latest
  • Test HTTP MCP Endpoint from Host:

    curl -X POST http://127.0.0.1:3000/mcp \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Verification & Testing

The repository contains an automated verification suite and an integration test suite covering 120 test cases.

  • Run Quick System Verification:

    npm run verify
  • Run Full Integration Test Suite (120 Tests):

    npm test

MCP Tools Summary

Category

Tools Included

Driver Management

register_driver, verify_driver, update_driver_details, update_driver_availability, update_driver_location

Hotel Preferred

add_preferred_driver, remove_preferred_driver

Pricing & Booking

estimate_fare, create_booking

Dispatch Logic

get_next_driver, update_driver_response, timeout_driver_attempt

Ride Lifecycle

complete_booking, cancel_booking

Queries & Inspection

get_driver_details, get_booking_status, list_available_drivers, get_hotel_preferred_drivers, get_driver_attempt_log, get_locations

For full parameter details, refer to docs/TOOLS.md.


Integration with Claude Desktop

To connect this MCP server to Claude Desktop, add the following entry to your %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "atithi-driver-booking": {
      "command": "node",
      "args": [
        "C:/Users/satish u d/Desktop/atithiproject/mcpserver3/dist/index.js"
      ],
      "env": {
        "ATITHI_DB_PATH": "C:/Users/satish u d/Desktop/atithiproject/mcpserver3/atithi_dummy_dataset.db"
      }
    }
  }
}

Documentation & License

Available Tools

20 tools
add_preferred_driverA

Add a Verified driver to a hotel's preferred driver list. Caller must be a Hotel Manager for that hotel.

Inputs: hotel_id (required), driver_id (required), caller_user_id (required).

cancel_bookingA

Cancel a booking. If cancelled by Driver, applies a -20 score penalty. If no driver was found, set cancelled_by to 'No Driver Available'.

Inputs: booking_id (required), cancelled_by (required).

complete_bookingA

Mark a booking as completed when the guest reaches the destination. Frees the driver and awards +10 score.

Inputs: booking_id (required).

create_bookingA

Create a new guest ride booking with passenger count and estimated fare. Returns booking_id. Then call get_next_driver() to begin driver search.

Inputs: hotel_id (required), guest_name (required), booking_type (required), drop_location_id (required), +5 more.

estimate_fareA

Calculate distance and estimated fare in INR for a ride based on pickup, drop-off, passenger count, and vehicle type. Present this fare to the guest for confirmation before calling create_booking().

Inputs: drop_location_id (required), pickup_location_id (required), hotel_id, vehicle_type, +1 more.

get_booking_statusB

Get the current status and full details of a booking, including assigned driver info.

Inputs: booking_id (required).

get_driver_attempt_logA

Get the full call attempt history for a booking, ordered by attempt number.

Inputs: booking_id (required).

get_driver_detailsA

Get full profile, vehicle info, and performance score for a driver.

Inputs: driver_id (required).

get_hotel_preferred_driversA

Get all preferred drivers for a hotel, sorted by driver score.

Inputs: hotel_id (required).

get_locationsA

Get all available pickup/drop locations. Optionally filter by location type.

Inputs: location_type.

get_next_driverA

Get the next best available driver for a booking. Searches Preferred Pool first, then Global Pool, matching passenger seating capacity. Returns driver & full vehicle contact info.

Inputs: booking_id (required).

list_available_driversB

List all currently available Verified drivers. Optionally filter by current location.

Inputs: location_id.

register_driverB

Register a new driver and their vehicle in the Atithi system.

Inputs: email (required), phone (required), full_name (required), make_model (required), +5 more.

remove_preferred_driverA

Remove a driver from a hotel's preferred driver list. Caller must be a Hotel Manager for that hotel.

Inputs: hotel_id (required), driver_id (required), caller_user_id (required).

timeout_driver_attemptA

Record a 30-second timeout or dropped voice call for a driver. Automatically logs 'No Response' and returns next_action: GET_NEXT_DRIVER.

Inputs: driver_id (required), booking_id (required), pool_source.

update_driver_availabilityA

Replace a driver's entire weekly schedule. All existing entries are replaced.

Inputs: schedule (required), driver_id (required).

update_driver_detailsA

Update a driver's personal or vehicle details. Only provide fields you want to change.

Inputs: driver_id (required), email, phone, make_model, +5 more.

update_driver_locationB

Update a driver's current real-time location.

Inputs: driver_id (required), location_id (required).

update_driver_responseA

Record a driver's response to a booking call. Updates driver score. Returns next_action: RIDE_STARTED or GET_NEXT_DRIVER.

Inputs: response (required), driver_id (required), booking_id (required), pool_source (required), +2 more.

verify_driverB

Admin: Approve or reject a pending driver registration.

Inputs: decision (required), driver_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, such as driver registration/verification/updates, booking lifecycle, and queries. The workflow tools (get_next_driver, update_driver_response, timeout_driver_attempt) are clearly sequenced and separated.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, e.g., verify_driver, create_booking, get_booking_status. There are no mixed conventions or vague verbs.

    Tool Count4/5

    With 20 tools, the server is slightly above the typical 3-15 range, but each tool is necessary for the driver booking domain, covering driver management, booking workflow, and queries. The count is well-scoped for its purpose.

    Completeness5/5

    The tool set covers the full lifecycle: driver registration/verification/updates, booking creation, driver assignment, response handling, completion/cancellation, and a rich set of queries. No major gaps that would block core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      Hotel booking MCP server — the first transaction-complete hotel booking integration for AI agents. Search 300K+ properties in 140+ countries, get live rates and room details, and generate secure checkout URLs. No payment in the AI conversation — guests complete booking at a hosted checkout page and receive a real hotel confirmation number. Set your own booking fee via Stripe Connect.
      8
      30 npm
      3
      -