Atithi Driver Booking MCP Server

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

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 overrides:

Build & Run Instructions

• Build project:

  npm run build

• Start MCP server (stdio transport):

  npm start

• Development mode (compile & start):

  npm run dev

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

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