MiniCab MCP

MiniCab MCP is a TypeScript Node.js backend for a small cab dispatch system exposed through the Model Context Protocol. It uses MySQL 8, raw SQL via mysql2, Zod validation, Pino logging, and the official @modelcontextprotocol/sdk.

Features

• MySQL schema with only the assignment tables: cities, drivers, vehicles, fare rules, bookings, and ledger.
• Fare rules support global defaults, time-of-day surge rows, and city-specific partial overrides without duplicating every vehicle type for every city.
• Hardcoded city route table for known pickup/drop points, as requested.
• MCP stdio server for Claude Desktop.
• Function-based repositories and services, with no app-owned classes or heavy framework abstractions.
• Transactional booking with SELECT ... FOR UPDATE to prevent two users booking the same cab.
• Server-side fare recalculation during booking.
• Ledger entry creation when a ride is completed.
• Jest tests for pure fare, route, and time helpers.

Requirements

• Node.js 18 or newer
• MySQL 8.0 or newer
• npm

Setup Without Docker

1. Install dependencies:

npm install

2. Create the database and seed it:

mysql -u root -p < schema.sql
mysql -u root -p < seed.sql

3. Copy the environment file:

cp .env.example .env

4. Update .env if your MySQL credentials differ.

5. Build the project:

npm run build

6. Start the MCP server:

npm start

The server uses stdio transport, so when Claude Desktop runs it, stdout is reserved for MCP protocol messages and logs go to stderr.

Claude Desktop Configuration

Build first with npm run build, then copy claude_desktop_config.example.json into your Claude Desktop config location and replace the placeholder path with your absolute project path.

Example:

{
  "mcpServers": {
    "minicab": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\minicab-mcp\\dist\\src\\index.js"
      ],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "root",
        "DB_NAME": "minicab"
      }
    }
  }
}

Restart Claude Desktop after saving the config.

MCP Tools

search_cabs

Searches available active vehicles in a city for a pickup/drop route and optional vehicle type.

Input:

{
  "city": "Hyderabad",
  "pickup": "Gachibowli",
  "drop": "RGIA Airport",
  "vehicle_type": "sedan"
}

get_fare_estimate

Returns fare estimates for all vehicle types without creating a booking.

Input:

{
  "pickup": "Gachibowli",
  "drop": "RGIA Airport",
  "time": "18:00"
}

book_ride

Creates a confirmed booking for a specific cab. The server recalculates the fare and does not trust client-provided fare amounts.

Input:

{
  "cab_id": 1,
  "pickup": "Gachibowli",
  "drop": "RGIA Airport",
  "rider_name": "Mohd Tabrez"
}

cancel_ride

Cancels a confirmed booking and releases the vehicle.

Input:

{
  "booking_id": 1
}

Tested Example Prompts

Prompt: "Get me a sedan from Gachibowli to the airport around 6pm in Hyderabad."

Expected tool call:

{
  "tool": "search_cabs",
  "arguments": {
    "city": "Hyderabad",
    "pickup": "Gachibowli",
    "drop": "RGIA Airport",
    "vehicle_type": "sedan"
  }
}

Prompt: "How much would an SUV from Connaught Place to IGI Airport cost at 8:30am in Delhi?"

Expected tool call:

{
  "tool": "get_fare_estimate",
  "arguments": {
    "pickup": "Connaught Place",
    "drop": "IGI Airport",
    "time": "08:30"
  }
}

Prompt: "Book cab 1 for Mohd Tabrez from Gachibowli to RGIA Airport at 6pm."

Expected tool call:

{
  "tool": "book_ride",
  "arguments": {
    "cab_id": 1,
    "pickup": "Gachibowli",
    "drop": "RGIA Airport",
    "rider_name": "Mohd Tabrez"
  }
}

Prompt: "Cancel booking 1."

Expected tool call:

{
  "tool": "cancel_ride",
  "arguments": {
    "booking_id": 1
  }
}

Tests

npm test

The included tests cover pure logic that does not need MySQL. A production submission should add integration tests with a disposable MySQL container for transaction and lock behavior.