# Atithi Driver Booking MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-v1.3.0-green.svg)](https://modelcontextprotocol.io/)
[![SQLite](https://img.shields.io/badge/SQLite-3-blue.svg)](https://www.sqlite.org/)
[![Tests](https://img.shields.io/badge/Tests-120%2F120%20Passing-brightgreen.svg)]()

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](#overview)
- [Architecture](#architecture)
- [Repository Structure](#repository-structure)
- [Installation & Setup](#installation--setup)
- [Environment Configuration](#environment-configuration)
- [Build & Run Instructions](#build--run-instructions)
- [Verification & Testing](#verification--testing)
- [MCP Tools Summary](#mcp-tools-summary)
- [Integration with Claude Desktop](#integration-with-claude-desktop)
- [Documentation & License](#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.

```text
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](docs/ARCHITECTURE.md).

---

## Repository Structure

```text
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**:
   ```bash
   git clone https://github.com/atithi/driver-booking-mcp.git
   cd driver-booking-mcp
   ```

2. **Install dependencies**:
   ```bash
   npm install
   ```

3. **Build the TypeScript source**:
   ```bash
   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)**:
  ```bash
  npm start
  ```
- **Development mode (compile & start)**:
  ```bash
  npm run dev
  ```

### 2. Streamable HTTP Mode (Atithi Platform Integration)
- **Start MCP server (Streamable HTTP transport on http://127.0.0.1:3000/mcp)**:
  ```bash
  npm run start:http
  ```
- **Custom Port/Host via CLI flags**:
  ```bash
  node dist/index.js --transport=http --port=8080 --host=0.0.0.0
  ```
### 3. Docker Container Deployment

- **Build Production Docker Image**:
  ```bash
  docker build -t atithi-driver-booking-mcp:latest .
  ```

- **Run Container (Default Streamable HTTP Mode on Port 3000)**:
  ```bash
  docker run -d -p 3000:3000 --name atithi-mcp-server atithi-driver-booking-mcp:latest
  ```

- **Run with Custom Host SQLite Database Volume Mounting**:
  ```bash
  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**:
  ```bash
  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**:
  ```bash
  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**:
  ```bash
  npm run verify
  ```

- **Run Full Integration Test Suite (120 Tests)**:
  ```bash
  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](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`:

```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](docs/ARCHITECTURE.md)
- Tool Schemas: [docs/TOOLS.md](docs/TOOLS.md)
- License: MIT © Atithi Platform