Atithi Driver Booking 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

• Overview
• Architecture
• Repository Structure
• Installation & Setup
• Environment Configuration
• Build & Run Instructions
• Verification & Testing
• MCP Tools Summary
• Integration with Claude Desktop
• Documentation & License

---

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

• Architecture: docs/ARCHITECTURE.md
• Tool Schemas: docs/TOOLS.md
• License: MIT © Atithi Platform