update readme file

README.md

@@ -22,224 +22,62 @@ tags:
   - ai-routing
 ---
 
-# 🚚 FleetMind MCP Server
-
-**🏆 MCP 1st Birthday Hackathon - Track 1: Building MCP Servers (Enterprise Category)**
-
-Industry-standard Model Context Protocol server for AI-powered delivery dispatch management. Exposes **29 AI tools** (including Gemini 2.0 Flash intelligent assignment) and 2 real-time resources for managing delivery operations through any MCP-compatible client. Features **multi-tenant authentication** with complete data isolation and a professional web landing page.
-
-[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.0-blue)](https://github.com/jlowin/fastmcp)
-[![Python](https://img.shields.io/badge/Python-3.10%2B-brightgreen)](https://www.python.org/)
-[![MCP](https://img.shields.io/badge/MCP-1.0-orange)](https://modelcontextprotocol.io)
-
----
+<div align="center">
 
-## 🔗 Links
-
-- **GitHub Repository:** https://github.com/mashrur-rahman-fahim/fleetmind-mcp
-- **HuggingFace Space (Landing Page):** https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
-- **Live Space URL:** https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space
-- **MCP SSE Endpoint:** https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse
-- **Generate API Key:** https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key
-- **Note:** Visit the Space URL above to see connection instructions and tool documentation
-
-## 📺 Demo & Submission
-
-- **Demo Video:** [Coming Soon - Will showcase Gemini 2.0 Flash AI assignment in action]
-- **Social Media Post:** [Will be added upon submission]
-- **Submission Date:** November 2025
-
----
+# 🚚 FleetMind MCP Server
 
-## 👥 Team
+### AI-Powered Delivery Dispatch for the Modern Enterprise
 
-**FleetMind Development Team**
+**The Problem:** Delivery dispatch is complex—coordinating drivers, optimizing routes, handling weather delays, and meeting SLAs requires constant human oversight.
 
-This project is submitted as part of the **MCP 1st Birthday Hackathon** (Track 1: Building MCP - Enterprise Category).
+**The Solution:** FleetMind exposes **29 AI-accessible tools** that let Claude (or any MCP client) manage your entire delivery operation through natural conversation.
 
-**Team Information:**
-- Team members and HuggingFace profile links will be added before final submission
-- For collaboration inquiries, please open an issue on the GitHub repository
+**The Impact:** Dispatch managers can now say *"Assign this urgent fragile delivery to the best available driver considering weather and traffic"* and watch AI handle the complexity.
 
----
+[![Demo Video](https://img.shields.io/badge/▶_Watch_Demo-FF0000?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/watch?v=demo_video_id)
+[![Try It Live](https://img.shields.io/badge/🚀_Try_It_Live-7C3AED?style=for-the-badge)](https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space)
+[![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github)](https://github.com/mashrur-rahman-fahim/fleetmind-mcp)
 
-## 🎯 What is FleetMind MCP?
-
-FleetMind is a production-ready **Model Context Protocol (MCP) server** that transforms delivery dispatch management into AI-accessible tools.
-
-**Access Methods:**
-- **Web Landing Page**: Professional HTML page with connection instructions and tool documentation
-- **MCP SSE Endpoint**: Direct API access for Claude Desktop, Continue, Cline, or any MCP client
-
-### Key Features
-
-✅ **🔑 Multi-Tenant API Key Authentication** - Secure access with personal API keys and complete data isolation
-✅ **29 AI Tools** - Order, Driver & Assignment Management (including Gemini 2.0 Flash AI)
-✅ **2 Real-Time Resources** - Live data feeds (orders://all, drivers://all)
-✅ **Google Maps Integration** - Geocoding & Route Calculation with traffic data
-✅ **PostgreSQL Database** - Production-grade data storage (Neon)
-✅ **SSE Endpoint** - Standard MCP protocol via Server-Sent Events
-✅ **Multi-Client Support** - Works with any MCP-compatible client
-✅ **Proxy-Based Auth** - Seamless authentication via URL query parameters
-
-### ⭐ Unique Features
-
-#### 🤖 Gemini 2.0 Flash AI Assignment
-- Latest Google Gemini 2.0 Flash model (`gemini-2.0-flash-exp`) analyzes 10+ parameters
-- Considers order priority, driver skills, traffic, weather, and complex tradeoffs
-- Returns detailed AI reasoning explaining why each driver was selected
-- Confidence scoring for transparency and accountability
-
-#### 🌦️ Weather-Aware Routing
-- OpenWeatherMap API integration for real-time conditions
-- Weather impact analysis for delivery planning and safety
-- Safety-first routing during adverse conditions (rain, fog, snow)
-- Vehicle-specific weather safety warnings (especially for motorcycles)
-
-#### 🏍️ Vehicle-Specific Optimization
-- Motorcycle (TWO_WHEELER), Bicycle, Car/Van/Truck routing modes
-- Different route optimization for each vehicle type
-- Toll detection and avoidance capabilities
-- Highway and ferry avoidance options for cost optimization
-
-#### 📊 SLA & Performance Tracking
-- Mandatory delivery deadlines with configurable grace periods
-- Automatic on-time vs late vs very_late classification
-- Structured failure reason tracking (9 categories: customer unavailable, wrong address, etc.)
-- Delivery performance analytics for reporting and optimization
-
-#### 🚦 Real-Time Traffic Integration
-- Google Routes API with live traffic data
-- Traffic delay breakdown and alternative routes
-- Triple fallback system (Routes API → Directions API → Mock calculation)
-- 17+ traffic segments analyzed per route
-
-#### 🎯 Three Assignment Methods
-1. **Manual Assignment** - Direct driver selection for specific needs
-2. **Auto Assignment** - Nearest driver with capacity/skill validation
-3. **Intelligent AI Assignment** - Gemini 2.0 Flash analyzes all parameters with detailed reasoning
+</div>
 
 ---
 
-## 🏗️ System Architecture
-
-FleetMind uses a **proxy-based authentication architecture** that enables seamless multi-tenant access:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     MCP Clients                                  │
-│   (Claude Desktop, Continue, Cline, Custom Applications)        │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      │ SSE Connection: /sse?api_key=fm_xxx
-                      ↓
-┌─────────────────────────────────────────────────────────────────┐
-│               Authentication Proxy (port 7860)                   │
-│                         proxy.py                                 │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │ 1. Captures api_key from initial SSE connection         │   │
-│  │ 2. Stores api_key mapped to session_id                  │   │
-│  │ 3. Injects api_key into /messages requests              │   │
-│  │ 4. SSE keep-alive pings every 30 seconds                │   │
-│  └─────────────────────────────────────────────────────────┘   │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      │ Forwarded requests with api_key
-                      ↓
-┌─────────────────────────────────────────────────────────────────┐
-│                FastMCP Server (port 7861)                        │
-│                    server.py + app.py                            │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │ • ApiKeyAuthMiddleware validates api_key                │   │
-│  │ • Extracts user_id from authenticated user              │   │
-│  │ • Injects user context into FastMCP state               │   │
-│  │ • 29 MCP tools with user_id filtering                   │   │
-│  │ • 2 MCP resources with user_id filtering                │   │
-│  └─────────────────────────────────────────────────────────┘   │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-        ┌─────────────┼─────────────┬─────────────┐
-        ↓             ↓             ↓             ↓
-┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
-│ PostgreSQL  │ │  Google   │ │  Google   │ │ OpenWeather│
-│ Database    │ │ Maps API  │ │ Gemini AI │ │ Map API   │
-│ (Neon)      │ │           │ │           │ │           │
-│ user_id FK  │ │ Geocoding │ │ Intelligent│ │ Weather   │
-│ isolation   │ │ Routing   │ │ Assignment │ │ Data      │
-└─────────────┘ └───────────┘ └───────────┘ └───────────┘
-```
-
-### Why Proxy-Based Authentication?
-
-MCP clients like Claude Desktop use `mcp-remote` which doesn't forward environment variables to remote servers. The proxy solves this by:
-
-1. **Capturing API keys** from the initial SSE connection URL (`?api_key=fm_xxx`)
-2. **Linking sessions** - Maps `session_id` to `api_key` for subsequent tool calls
-3. **Injecting authentication** - Adds `api_key` to all `/messages` requests automatically
-4. **Maintaining connections** - SSE keep-alive pings prevent timeout disconnections
-
----
+## 📺 See It In Action
 
-## 🏆 Why Track 1: Building MCP Servers (Enterprise Category)?
+> **🎬 Demo Video:** [Watch FleetMind in action →](https://www.youtube.com/watch?v=demo_video_id)
+>
+> Watch Gemini 2.0 Flash AI analyze weather, traffic, and driver capabilities to make intelligent assignment decisions with full reasoning transparency.
 
-FleetMind demonstrates **enterprise-grade MCP server development** with cutting-edge AI integration and production-ready architecture:
+<details>
+<summary><b>📸 Screenshots (Click to expand)</b></summary>
 
-### 🤖 Advanced AI Integration
-- **Gemini 2.0 Flash** - Latest Google AI model for intelligent decision-making
-- **Weather-Aware Routing** - OpenWeatherMap API integration for safety-first planning
-- **Real-Time Traffic Analysis** - Google Routes API with live traffic data and delay predictions
-- **AI Reasoning & Transparency** - Detailed explanations for every intelligent assignment decision
+### Landing Page
+![FleetMind Landing Page](screenshots/landing-page.png)
+*Professional web interface with connection instructions and API key generation*
 
-### 🏢 Enterprise-Ready Features
-- **PostgreSQL Database** - Production-grade data storage with Neon serverless PostgreSQL
-- **Multi-Tenant Isolation** - Complete data separation per user via deterministic user_id
-- **SLA Tracking & Analytics** - Automatic performance monitoring with grace periods and violation detection
-- **Triple Fallback System** - Routes API → Directions API → Mock calculation for 99.9% uptime
-- **Multi-Client Support** - Standard MCP protocol works with Claude Desktop, Continue, Cline, and custom clients
-- **SSE Web Transport** - Server-Sent Events for web-based MCP connectivity
+### Claude Desktop Integration
+![Claude Desktop with FleetMind](screenshots/claude-desktop.png)
+*29 tools available in Claude Desktop's tool menu*
 
-### 🚀 Production Deployment
-- **HuggingFace Space** - Live production deployment with public SSE endpoint
-- **Docker Containerization** - Reproducible deployment with Python 3.11 slim base
-- **Environment Management** - Secure API key handling for Google Maps, Gemini, and OpenWeatherMap
-- **29 Production Tools** - Complete fleet management suite ready for real-world use
+### Intelligent Assignment in Action
+![AI Assignment](screenshots/ai-assignment.png)
+*Gemini 2.0 Flash analyzing order parameters and driver capabilities*
 
-### 📊 Innovation & Complexity
-- **Vehicle-Specific Optimization** - Motorcycle/Bicycle/Car/Van/Truck routing with toll detection
-- **Structured Failure Tracking** - 9 failure reason categories for analytics and reporting
-- **Cascading Status Updates** - Order → Assignment → Driver state management with FK constraints
-- **Three Assignment Methods** - Manual, Auto (distance-based), and Intelligent AI (parameter-based)
+### Weather-Aware Routing
+![Weather Routing](screenshots/weather-routing.png)
+*Real-time weather and traffic data affecting route decisions*
 
-FleetMind isn't just an MCP server—it's a **blueprint for enterprise AI integration** showcasing how MCP can transform complex logistics workflows into AI-accessible tools.
+</details>
 
 ---
 
-## 🚀 Quick Start
+## ⚡ Quick Start (2 Minutes)
 
-### Connect from Claude Desktop
+### Step 1: Get Your API Key
+👉 **[Generate API Key](https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key)** (copy immediately—shown once!)
 
-#### **Step 1: Get Your API Key** 🔑
-
-Visit the FleetMind server and generate your personal API key:
-
-👉 **https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key**
-
-1. Enter your email address
-2. Enter your name (optional)
-3. Click "Generate API Key"
-4. **Copy your API key immediately** - it won't be shown again!
-
-Your API key will look like: `fm_xxxxxxxxxxxxxxxxxxxxxxxx`
-
-#### **Step 2: Install Claude Desktop**
-
-Download from: https://claude.ai/download
-
-#### **Step 3: Configure MCP Server**
-
-Edit your `claude_desktop_config.json`:
-
-**For Production (HuggingFace Space):**
+### Step 2: Configure Claude Desktop
+Add to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
@@ -247,780 +85,240 @@ Edit your `claude_desktop_config.json`:
       "command": "npx",
       "args": [
         "mcp-remote",
-        "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse?api_key=fm_your_api_key_here"
-      ]
-    }
-  }
-}
-```
-
-⚠️ **Important:** Replace `fm_your_api_key_here` with your actual API key from Step 1!
-
-💡 **Note:** The API key is passed as a **query parameter** (`?api_key=...`) in the URL. This is because `mcp-remote` doesn't forward environment variables to remote servers.
-
-**For Local Development (with API Key):**
-```json
-{
-  "mcpServers": {
-    "fleetmind_local": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:7860/sse?api_key=your_local_api_key"
-      ]
-    }
-  }
-}
-```
-
-**For Local Development (SKIP_AUTH mode):**
-```json
-{
-  "mcpServers": {
-    "fleetmind_local": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:7860/sse"
+        "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse?api_key=YOUR_KEY_HERE"
       ]
     }
   }
 }
 ```
-*Set `SKIP_AUTH=true` in your `.env` file for local testing without API keys*
 
-**Both (Production + Local):**
-```json
-{
-  "mcpServers": {
-    "fleetmind_local": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:7860/sse?api_key=your_local_key"
-      ]
-    },
-    "fleetmind": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse?api_key=your_production_key"
-      ]
-    }
-  }
-}
+### Step 3: Start Dispatching!
 ```
+You: "Create an urgent delivery for Sarah at 456 Oak Ave, San Francisco,
+     then use AI to find the best driver considering the current rain"
 
-#### **Step 4: Restart Claude Desktop**
-
-Restart Claude Desktop - FleetMind tools will appear automatically!
-
-#### **Step 5: Try It Out!**
-   - "Create an urgent delivery order for Sarah at 456 Oak Ave, San Francisco"
-   - "Use intelligent AI assignment to find the best driver for this order"
-   - "Show me all available drivers"
-   - "Calculate route from downtown SF to Oakland Airport with weather conditions"
-
-### Connect from VS Code (Continue)
-
-1. Install Continue extension
-2. Add FleetMind to MCP servers in settings
-3. Use tools directly in your editor
-
-### Connect from Custom App
-
-```python
-import mcp
-
-client = mcp.Client(
-    url="https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse"
-)
-
-# Use any of the 29 tools
-result = client.call_tool("create_order", {
-    "customer_name": "John Doe",
-    "delivery_address": "123 Main St, SF CA 94102",
-    "delivery_lat": 37.7749,
-    "delivery_lng": -122.4194
-})
+Claude: Uses geocode_address → create_order → intelligent_assign_order
+        Returns: "Order ORD-... assigned to Mike (DRV-...).
+        AI selected Mike because: closest driver with cold-storage van,
+        safest route in current weather, 15 min ETA."
 ```
 
 ---
 
-## 🛠️ Available Tools (29 Total)
-
-### Geocoding & Routing (3 tools)
-
-| Tool | Description | Example Use |
-|------|-------------|-------------|
-| `geocode_address` | Convert address to GPS coordinates | "Geocode 123 Main St, San Francisco" |
-| `calculate_route` | Vehicle-specific routing with real-time traffic | "Route from SF City Hall to Oakland Airport for motorcycle" |
-| `calculate_intelligent_route` | **AI-powered weather + traffic aware routing** | "Calculate smart route considering weather and traffic" |
-
-### Order Management (8 tools)
-
-| Tool | Description | Example Use |
-|------|-------------|-------------|
-| `create_order` | Create new delivery orders with mandatory deadlines | "Create delivery for Sarah at 456 Oak Ave" |
-| `count_orders` | Count orders with filters | "How many urgent orders are pending?" |
-| `fetch_orders` | Retrieve orders with pagination | "Show me the 10 most recent orders" |
-| `get_order_details` | Get complete order information with SLA data | "Show details for order ORD-20251114..." |
-| `search_orders` | Search by customer/ID | "Find orders for customer John Smith" |
-| `get_incomplete_orders` | List active deliveries | "Show all orders not yet delivered" |
-| `update_order` | Update order details with cascading | "Mark order ORD-... as delivered" |
-| `delete_order` | Safely remove orders with checks | "Delete test order ORD-TEST-001" |
-
-### Driver Management (8 tools)
-
-| Tool | Description | Example Use |
-|------|-------------|-------------|
-| `create_driver` | Onboard new drivers with skills validation | "Add driver Mike with plate ABC-123, motorcycle, fragile_handler skill" |
-| `count_drivers` | Count drivers with filters | "How many active drivers are online?" |
-| `fetch_drivers` | Retrieve drivers with pagination | "List all drivers sorted by name" |
-| `get_driver_details` | Get driver info + location with reverse geocoding | "Show details for driver DRV-..." |
-| `search_drivers` | Search by name/plate/ID | "Find driver with plate XYZ-789" |
-| `get_available_drivers` | List drivers ready for dispatch | "Show available drivers near downtown" |
-| `update_driver` | Update driver information with validation | "Update driver DRV-... status to busy" |
-| `delete_driver` | Safely remove drivers with assignment checks | "Remove driver DRV-TEST-001" |
-
-### Assignment Management (8 tools) ⭐ NEW
-
-| Tool | Description | Example Use |
-|------|-------------|-------------|
-| `create_assignment` | Manually assign order to specific driver | "Assign order ORD-... to driver DRV-..." |
-| **`auto_assign_order`** | **Automatic nearest driver assignment with validation** | **"Auto-assign this order to nearest available driver"** |
-| **`intelligent_assign_order`** | **🤖 Gemini 2.0 Flash AI-powered assignment with reasoning** | **"Use AI to find the best driver for this urgent fragile delivery"** |
-| `get_assignment_details` | View assignment details with route data | "Show assignment details for ASN-..." |
-| `update_assignment` | Update assignment status with cascading | "Mark assignment ASN-... as in_progress" |
-| `unassign_order` | Remove driver assignment safely | "Unassign order ORD-... from current driver" |
-| `complete_delivery` | Mark delivery complete + auto-update driver location | "Complete delivery for assignment ASN-..." |
-| `fail_delivery` | Track failed deliveries with GPS + structured reason | "Mark delivery failed: customer not available at current location" |
-
-### Bulk Operations (2 tools)
-
-| Tool | Description | Example Use |
-|------|-------------|-------------|
-| `delete_all_orders` | Bulk delete orders by status with safety checks | "Delete all cancelled orders" |
-| `delete_all_drivers` | Bulk delete drivers by status with assignment checks | "Delete all offline drivers" |
-
----
-
-## 📊 Real-Time Resources (2 Total)
-
-### `orders://all`
-Live orders dataset (last 30 days, max 1000 orders)
-
-**Example:**
-```
-"What's the status of recent orders?"
-```
-
-Claude automatically accesses this resource to provide context-aware answers.
-
-### `drivers://all`
-Live drivers dataset with current locations
+## 🏆 Why FleetMind?
 
-**Example:**
-```
-"Which drivers are currently available?"
-```
+| Feature | What It Does | Why It Matters |
+|---------|--------------|----------------|
+| **🤖 Gemini 2.0 Flash AI** | Analyzes 10+ parameters for intelligent driver assignment | Better decisions than rule-based systems |
+| **🌦️ Weather-Aware Routing** | OpenWeatherMap integration for safety-first planning | Reduces weather-related delivery failures |
+| **🔐 Multi-Tenant Auth** | Complete data isolation via deterministic user_id | Enterprise-ready security out of the box |
+| **📊 SLA Tracking** | Automatic on-time/late/very-late classification | Built-in performance analytics |
+| **🚦 Real-Time Traffic** | Google Routes API with live traffic data | Accurate ETAs, not guesstimates |
+| **🏍️ Vehicle Optimization** | Motorcycle, bicycle, car, van, truck routing | Right routes for each vehicle type |
 
 ---
 
-## 🔧 Technology Stack
-
-**MCP Framework:**
-- FastMCP 2.13.0 - MCP server implementation
-- Model Context Protocol 1.0 - Standardized AI tool protocol
-
-**AI & APIs:**
-- Google Gemini 2.0 Flash (gemini-2.0-flash-exp) - Intelligent assignment
-- Google Routes API - Real-time traffic routing
-- Google Directions API - Fallback routing
-- Google Geocoding API - Address conversion
-- OpenWeatherMap API - Weather data integration
-
-**Backend:**
-- Python 3.10+ - Server runtime
-- PostgreSQL (Neon) - Production database
-- SSE (Server-Sent Events) - Web transport
-- Docker - Containerized deployment
+## 🛠️ The 29 Tools
+
+<details>
+<summary><b>📍 Geocoding & Routing (3 tools)</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| `geocode_address` | Convert address → GPS coordinates |
+| `calculate_route` | Vehicle-specific routing with traffic, tolls, fuel estimates |
+| `calculate_intelligent_route` | AI-powered routing with weather + traffic analysis |
+
+</details>
+
+<details>
+<summary><b>📦 Order Management (8 tools)</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create_order` | Create delivery with mandatory deadline & SLA tracking |
+| `count_orders` | Count by status/priority with breakdowns |
+| `fetch_orders` | Paginated list with filters |
+| `get_order_details` | Full order info including timing data |
+| `search_orders` | Find by customer name/email/phone/ID |
+| `get_incomplete_orders` | Active deliveries shortcut |
+| `update_order` | Modify order with cascading updates |
+| `delete_order` | Safe deletion with assignment checks |
+
+</details>
+
+<details>
+<summary><b>👥 Driver Management (8 tools)</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create_driver` | Onboard with vehicle type, skills, capacity |
+| `count_drivers` | Count by status/vehicle with breakdowns |
+| `fetch_drivers` | Paginated list with filters |
+| `get_driver_details` | Full info with reverse-geocoded location |
+| `search_drivers` | Find by name/plate/phone/ID |
+| `get_available_drivers` | Ready-for-dispatch shortcut |
+| `update_driver` | Modify with location auto-timestamp |
+| `delete_driver` | Safe deletion with assignment checks |
+
+</details>
+
+<details>
+<summary><b>🔗 Assignment Management (8 tools) ⭐</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create_assignment` | Manual driver selection |
+| **`auto_assign_order`** | **Nearest driver + capacity/skill validation** |
+| **`intelligent_assign_order`** | **🤖 Gemini 2.0 Flash AI with full reasoning** |
+| `get_assignment_details` | Query by assignment/order/driver ID |
+| `update_assignment` | Status transitions with cascading |
+| `unassign_order` | Revert to pending safely |
+| `complete_delivery` | Mark done + auto-update driver location |
+| `fail_delivery` | Track failure with GPS + structured reason |
+
+</details>
+
+<details>
+<summary><b>🗑️ Bulk Operations (2 tools)</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| `delete_all_orders` | Mass delete with status filter & safety checks |
+| `delete_all_drivers` | Mass delete with assignment safety blocks |
+
+</details>
 
 ---
 
-## 🏗️ Detailed Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     MCP Clients                                  │
-│   (Claude Desktop, Continue, Cline, Custom Applications)        │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      │ SSE Connection: /sse?api_key=fm_xxx
-                      ↓
-┌─────────────────────────────────────────────────────────────────┐
-│               Authentication Proxy (port 7860)                   │
-│                         proxy.py                                 │
-│  • Captures api_key from SSE connection URL                      │
-│  • Links session_id → api_key                                    │
-│  • Injects api_key into tool call requests                       │
-│  • SSE keep-alive pings (30s intervals)                          │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-                      ↓
-┌─────────────────────────────────────────────────────────────────┐
-│                FastMCP Server (port 7861)                        │
-│                    server.py + app.py                            │
-│  • ApiKeyAuthMiddleware - validates every tool call              │
-│  • 29 MCP tools (Order/Driver/Assignment management)             │
-│  • 2 MCP resources (orders://all, drivers://all)                 │
-│  • User context injection via FastMCP state                      │
-└─────────────────────┬───────────────────────────────────────────┘
-                      │
-        ┌─────────────┼─────────────┬─────────────┐
-        ↓             ↓             ↓             ↓
-┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
-│ PostgreSQL  │ │  Google   │ │  Google   │ │ OpenWeather│
-│ Database    │ │ Maps API  │ │ Gemini AI │ │ Map API   │
-│ (Neon)      │ │           │ │           │ │           │
-│ multi-tenant│ │ Geocoding │ │ Intelligent│ │ Weather   │
-│ user_id FK  │ │ Routing   │ │ Assignment │ │ Data      │
-└─────────────┘ └───────────┘ └───────────┘ └───────────┘
+## 🏗️ Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      MCP Clients                              │
+│     Claude Desktop  •  Continue  •  Cline  •  Custom Apps    │
+└─────────────────────────────┬────────────────────────────────┘
+                              │ SSE: /sse?api_key=fm_xxx
+                              ▼
+┌─────────────────────────────────���────────────────────────────┐
+│              Authentication Proxy (proxy.py)                  │
+│  • Captures API key from SSE connection                       │
+│  • Links session_id → api_key for tool calls                  │
+│  • Keep-alive pings every 30s                                 │
+└─────────────────────────────┬────────────────────────────────┘
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│              FastMCP Server (server.py)                       │
+│  • ApiKeyAuthMiddleware validates every call                  │
+│  • 29 tools with user_id filtering                            │
+│  • 2 real-time resources (orders://all, drivers://all)        │
+└──────────┬──────────┬────────────┬──────────┬────────────────┘
+           ▼          ▼            ▼          ▼
+    ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────────┐
+    │PostgreSQL│ │ Google  │ │  Gemini  │ │OpenWeather│
+    │  (Neon)  │ │Maps API │ │2.0 Flash │ │  Map API  │
+    │ user_id  │ │Geocoding│ │Intelligent││  Weather  │
+    │isolation │ │ Routing │ │Assignment│ │   Data    │
+    └──────────┘ └─────────┘ └──────────┘ └───────────┘
 ```
 
-**Key Architecture Benefits:**
-- ✅ **Multi-client support** - Works with Claude Desktop, VS Code, mobile apps
-- ✅ **Standardized protocol** - MCP is industry-standard for AI tool integration
-- ✅ **Multi-tenant isolation** - Complete data separation via user_id
-- ✅ **Proxy-based auth** - Seamless API key handling for MCP clients
-- ✅ **Real-time data access** - Resources provide live context to AI
-- ✅ **Tool composability** - AI combines tools intelligently for complex workflows
-- ✅ **Easy integration** - Any MCP client can connect via SSE
-
 ---
 
-## 📖 Usage Examples
+## 🔐 Authentication & Security
 
-### Example 1: Create & Assign Order
+FleetMind uses a **3-layer authentication system** for enterprise-grade security:
 
-**Prompt:**
-```
-Create an urgent delivery for Sarah Johnson at 456 Oak Ave, San Francisco CA.
-Phone: 555-1234. Then assign it to the nearest available driver.
-```
+| Layer | Component | Function |
+|-------|-----------|----------|
+| 1 | **Proxy** | Captures API key from URL, links sessions |
+| 2 | **Middleware** | Validates every tool call, injects user context |
+| 3 | **Database** | All queries filter by `user_id` (complete isolation) |
 
-**What happens:**
-1. Claude calls `geocode_address("456 Oak Ave, San Francisco CA")`
-2. Gets coordinates: `(37.7749, -122.4194)`
-3. Calls `create_order(...)` with all details
-4. Calls `get_available_drivers(limit=10)`
-5. Calls `calculate_route(...)` for each driver to find nearest
-6. Calls `update_order(...)` to assign driver
-7. Returns: "Order ORD-... created and assigned to John Smith (DRV-...), 5.2 km away, ETA 12 mins"
+**Security Features:**
+- ✅ SHA-256 hashed key storage (never plaintext)
+- ✅ One-time key display (can't retrieve later)
+- ✅ Deterministic user_id from email (key rotation preserves data)
+- ✅ Production safeguards (SKIP_AUTH blocked when ENV=production)
 
-### Example 2: Track Active Deliveries
+<details>
+<summary><b>View Complete Auth Flow</b></summary>
 
-**Prompt:**
 ```
-Show me all urgent orders that are currently in transit, sorted by deadline.
+1. Generate API Key → user_id = user_{MD5(email)[:12]}
+2. Configure Claude → URL includes ?api_key=fm_xxx
+3. SSE Connection → Proxy captures and stores key
+4. Tool Call → Proxy injects key, middleware validates
+5. Database Query → WHERE user_id = 'user_xxx'
+6. Result → Only user's own data returned
 ```
 
-**What happens:**
-1. Claude calls `fetch_orders(status="in_transit", priority="urgent", sort_by="time_window_end")`
-2. Returns formatted list with customer names, addresses, drivers, and ETAs
-
-### Example 3: Driver Management
-
-**Prompt:**
-```
-How many drivers do we have available right now? Where are they located?
-```
-
-**What happens:**
-1. Claude accesses `drivers://all` resource automatically
-2. Filters for `status="active"`
-3. Calls `get_driver_details(...)` for location addresses
-4. Returns summary with driver count and locations
+</details>
 
 ---
 
-## 🗄️ Database Schema
-
-### Orders Table (26 columns)
-
-```sql
-CREATE TABLE orders (
-    order_id VARCHAR(50) PRIMARY KEY,
-    customer_name VARCHAR(255) NOT NULL,
-    customer_phone VARCHAR(20),
-    customer_email VARCHAR(255),
-    delivery_address TEXT NOT NULL,
-    delivery_lat DECIMAL(10,8),
-    delivery_lng DECIMAL(11,8),
-    status VARCHAR(20) CHECK (status IN ('pending','assigned','in_transit','delivered','failed','cancelled')),
-    priority VARCHAR(20) CHECK (priority IN ('standard','express','urgent')),
-    time_window_end TIMESTAMP,
-    assigned_driver_id VARCHAR(50),
-    weight_kg DECIMAL(10,2),
-    special_instructions TEXT,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-    -- ... additional fields
-);
-```
+## 🚀 Deployment
 
-### Drivers Table (15 columns)
-
-```sql
-CREATE TABLE drivers (
-    driver_id VARCHAR(50) PRIMARY KEY,
-    name VARCHAR(255) NOT NULL,
-    phone VARCHAR(20),
-    email VARCHAR(255),
-    status VARCHAR(20) CHECK (status IN ('active','busy','offline','unavailable')),
-    vehicle_type VARCHAR(50),
-    vehicle_plate VARCHAR(20),
-    capacity_kg DECIMAL(10,2),
-    current_lat DECIMAL(10,8),
-    current_lng DECIMAL(11,8),
-    last_location_update TIMESTAMP,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-```
-
----
-
-## 🔧 Local Development
-
-### Prerequisites
-
-- Python 3.10+
-- PostgreSQL database (or use Neon serverless)
-- Google Maps API key
-- Google Gemini API key (for AI features)
-
-### Setup
+### Production (HuggingFace Space)
+Already deployed at: **https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space**
 
+### Local Development
 ```bash
-# Clone repository
 git clone https://github.com/mashrur-rahman-fahim/fleetmind-mcp.git
 cd fleetmind-mcp
-
-# Install dependencies
 pip install -r requirements.txt
 
-# Configure environment
-cp .env.example .env
-# Edit .env with your credentials:
-#   DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
-#   GOOGLE_MAPS_API_KEY
-#   GOOGLE_API_KEY (for Gemini)
-#   SKIP_AUTH=true  # For local development without API keys
-
-# Run database migrations
-python database/migrations/001_initial_schema.py
-# ... run all migrations
-
-# Run locally (SSE mode for web clients)
-python app.py
-```
-
-### API Key Management (Local)
-
-**Generate API Keys:**
-```bash
-# Interactive mode
-python generate_api_key.py
-
-# With arguments
-python generate_api_key.py --email user@example.com --name "Test User"
-
-# List all keys
-python generate_api_key.py --list
-
-# Revoke a key
-python generate_api_key.py --revoke user@example.com
-```
-
-**Web Interface:**
-Visit http://localhost:7860/generate-key to generate keys via web form.
-
-**Development Mode (No API Keys):**
-Set `SKIP_AUTH=true` in `.env` to bypass authentication for local testing.
-
-### Testing
-
-```bash
-# Test with MCP Inspector
-npx @modelcontextprotocol/inspector python server.py
-
-# Test with Claude Desktop
-# Add to claude_desktop_config.json:
-{
-  "mcpServers": {
-    "fleetmind-local": {
-      "command": "python",
-      "args": ["F:\\path\\to\\fleetmind-mcp\\server.py"]
-    }
-  }
-}
+# Configure .env with your API keys
+python start_with_proxy.py  # Runs proxy (7860) + FastMCP (7861)
 ```
 
 ---
 
-## 🚀 Deployment to HuggingFace Space
-
-This project is designed for **Track 1: Building MCP Servers** deployment on HuggingFace Spaces.
-
-### Automatic Deployment
-
-1. **Fork this repository** to your GitHub account
-
-2. **Create HuggingFace Space:**
-   - Go to https://huggingface.co/new-space
-   - Name: `fleetmind-mcp` (or your choice)
-   - SDK: Docker
-   - Link to GitHub repository
-
-3. **Configure Secrets** in HF Space settings:
-   - `DB_HOST` - PostgreSQL host
-   - `DB_PORT` - PostgreSQL port (5432)
-   - `DB_NAME` - Database name
-   - `DB_USER` - Database user
-   - `DB_PASSWORD` - Database password
-   - `GOOGLE_MAPS_API_KEY` - Google Maps API key
+## 📊 Technical Specifications
 
-4. **Push to GitHub** - Space auto-updates via GitHub Actions!
-
-### Manual Deployment
-
-Upload files directly to HF Space:
-- `app.py` (entry point)
-- `server.py` (MCP server)
-- `requirements.txt`
-- `chat/`, `database/` directories
-- `.env` (configure secrets in HF Space settings instead)
+| Metric | Value |
+|--------|-------|
+| **Tools** | 29 |
+| **Resources** | 2 (orders://all, drivers://all) |
+| **Database** | PostgreSQL (Neon serverless) |
+| **AI Model** | Gemini 2.0 Flash (gemini-2.0-flash-exp) |
+| **Transport** | SSE (Server-Sent Events) |
+| **Framework** | FastMCP 2.13.0 |
+| **Language** | Python 3.10+ |
 
 ---
 
-## 🔒 Authentication & Security
-
-FleetMind uses a **multi-layered authentication system** with proxy-based API key capture and FastMCP middleware for secure multi-tenant access:
-
-### Authentication Architecture
-
-The authentication system consists of three layers:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Layer 1: Authentication Proxy (proxy.py)                        │
-│ ���────────────────────────────────────────────────────────────── │
-│ • Captures api_key from SSE connection URL                      │
-│ • Maps session_id → api_key for tool calls                      │
-│ • Injects api_key into /messages requests                       │
-│ • Maintains session_api_keys dictionary                         │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ Layer 2: FastMCP Middleware (server.py - ApiKeyAuthMiddleware)  │
-│ ─────────────────────────────────────────────────────────────── │
-│ • Intercepts all tool calls via on_call_tool()                  │
-│ • Validates api_key using verify_api_key()                      │
-│ • Injects user context into FastMCP state:                      │
-│   - user_id, user_email, user_scopes, user_name                 │
-│ • Blocks unauthenticated requests in production                 │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ Layer 3: Tool-Level Authentication (each MCP tool)              │
-│ ─────────────────────────────────────────────────────────────── │
-│ • get_authenticated_user() extracts user from context           │
-│ • check_permission() validates required scopes                  │
-│ • All database queries filter by user_id                        │
-│ • Complete multi-tenant data isolation                          │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Complete Authentication Flow
-
-```
-1️⃣ USER GENERATES API KEY
-   └─→ POST /generate-key (email: user@example.com)
-   └─→ user_id = user_{MD5(email)[:12]} = "user_a85ddf4d664b"
-   └─→ api_key = fm_3bGKV40B47NJ43zQ_4d3j-60a2gyoeLOVffoyyhRtBc
-   └─→ api_key_hash = SHA-256(api_key) stored in database
-   └─→ Key shown ONCE - user must copy immediately
-
-2️⃣ USER CONFIGURES CLAUDE DESKTOP
-   └─→ claude_desktop_config.json:
-       {
-         "mcpServers": {
-           "fleetmind": {
-             "command": "npx",
-             "args": ["mcp-remote", "https://...hf.space/sse?api_key=fm_xxx"]
-           }
-         }
-       }
-
-3️⃣ SSE CONNECTION ESTABLISHED
-   └─→ Client connects: GET /sse?api_key=fm_xxx
-   └─→ Proxy (proxy.py) captures api_key
-   └─→ Stores: session_api_keys['_pending_api_key'] = api_key
-   └─→ Forwards to FastMCP (port 7861)
-
-4️⃣ TOOL CALL MADE
-   └─→ Client sends: POST /messages/?session_id=xxx
-   └─→ Proxy links: session_api_keys[session_id] = pending_api_key
-   └─→ Proxy injects: api_key into query params
-   └─→ Forwards to FastMCP with api_key
-
-5️⃣ FASTMCP MIDDLEWARE VALIDATES
-   └─→ ApiKeyAuthMiddleware.on_call_tool() intercepts
-   └─→ Extracts api_key from request.query_params
-   └─→ verify_api_key(api_key) → hashes and queries database
-   └─→ Returns: {user_id, email, name, scopes}
-   └─→ Sets FastMCP context state with user info
-
-6️⃣ TOOL EXECUTES WITH USER CONTEXT
-   └─→ get_authenticated_user(ctx) reads from context state
-   └─→ Extracts user_id: "user_a85ddf4d664b"
-   └─→ Database query: WHERE user_id = 'user_a85ddf4d664b'
-   └─→ Returns only user's own data
-
-7️⃣ COMPLETE ISOLATION ACHIEVED
-   └─→ User A sees only User A's orders/drivers/assignments
-   └─→ User B sees only User B's orders/drivers/assignments
-   └─→ Database enforces via user_id foreign keys
-```
-
-### User ID Generation (Deterministic)
-
-```python
-# database/api_keys.py
-user_id = f"user_{hashlib.md5(email.encode()).hexdigest()[:12]}"
-
-# Examples:
-# "admin@gmail.com"      → "user_a85ddf4d664b"
-# "user@example.com"     → "user_b45fa8c9e12d"
-```
-
-**Benefits:**
-- Same email always generates same user_id
-- Key rotation doesn't lose data ownership
-- Enables consistent multi-tenant isolation
-
-### API Key Storage
-
-```sql
-CREATE TABLE api_keys (
-    key_id SERIAL PRIMARY KEY,
-    user_id VARCHAR(100) NOT NULL UNIQUE,      -- Deterministic from email
-    email VARCHAR(255) NOT NULL,                -- For lookup/revocation
-    name VARCHAR(255),                          -- Display name (optional)
-    api_key_hash VARCHAR(64) NOT NULL UNIQUE,  -- SHA-256 hash (never plaintext!)
-    api_key_prefix VARCHAR(20) NOT NULL,       -- First 12 chars for display
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    last_used_at TIMESTAMP,                    -- Updated on each use
-    is_active BOOLEAN DEFAULT true             -- For revocation
-);
-```
-
-### Security Features
-
-| Feature | Implementation |
-|---------|---------------|
-| ✅ **Hashed Storage** | SHA-256 hashing, API keys never stored in plaintext |
-| ✅ **One-Time Display** | Keys shown only once during generation |
-| ✅ **Deterministic User IDs** | Same email always gets same user_id |
-| ✅ **Multi-Tenant Isolation** | All tables have user_id column with FK constraints |
-| ✅ **Database-Level Enforcement** | Every query includes `WHERE user_id = %s` |
-| ✅ **FastMCP Middleware** | Validates authentication before every tool call |
-| ✅ **Proxy Session Linking** | session_id → api_key mapping for tool calls |
-| ✅ **ContextVar Storage** | Thread-safe per-request user context |
-| ✅ **Scope-Based Permissions** | Tools check required scopes before execution |
-| ✅ **Production Safeguards** | SKIP_AUTH blocked when ENV=production |
-| ✅ **Easy Revocation** | Keys can be deactivated via CLI or web interface |
-
-### API Key Format
-
-```
-fm_LAISKBMKmQxoapDbLIhr_KqbVL69AS58wBtdpYfbQ10
-│  └──────────────────────────────────────────────┘
-│                43 random characters
-└── Prefix: "fm_" (FleetMind)
-
-Generated with: secrets.token_urlsafe(32)
-```
-
-### Managing API Keys
-
-**Web Interface:**
-```
-https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key
-```
-
-**Command Line:**
-```bash
-# Generate new key
-python generate_api_key.py --email user@example.com --name "John Doe"
-
-# List all keys (shows user_id, email, key preview)
-python generate_api_key.py --list
-
-# Revoke a key (deactivates, doesn't delete)
-python generate_api_key.py --revoke user@example.com
-
-# Verify a key (test authentication)
-python generate_api_key.py --verify fm_your_api_key_here
-```
-
-### Database Tables with Multi-Tenant Isolation
-
-All core tables include `user_id` column for data isolation:
-
-```sql
--- orders table
-CREATE TABLE orders (
-    order_id VARCHAR(50) PRIMARY KEY,
-    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
-    customer_name VARCHAR(255),
-    ...
-    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
-);
-CREATE INDEX idx_orders_user_id ON orders(user_id);
-CREATE INDEX idx_orders_user_status ON orders(user_id, status);
-
--- drivers table
-CREATE TABLE drivers (
-    driver_id VARCHAR(50) PRIMARY KEY,
-    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
-    name VARCHAR(255),
-    ...
-    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
-);
-CREATE INDEX idx_drivers_user_id ON drivers(user_id);
-CREATE INDEX idx_drivers_user_status ON drivers(user_id, status);
-
--- assignments table
-CREATE TABLE assignments (
-    assignment_id VARCHAR(50) PRIMARY KEY,
-    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
-    order_id VARCHAR(50),
-    driver_id VARCHAR(50),
-    ...
-    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
-);
-CREATE INDEX idx_assignments_user_id ON assignments(user_id);
-```
-
-### Environment Configuration
-
-```bash
-# Environment mode (controls SKIP_AUTH behavior)
-ENV=development  # Options: development, staging, production
-
-# Authentication bypass (ONLY works when ENV != production)
-SKIP_AUTH=false  # Set to true ONLY for local testing
-
-# Database connection (multi-tenant PostgreSQL)
-DB_HOST=your-postgres-host.neon.tech
-DB_PORT=5432
-DB_NAME=fleetmind
-DB_USER=your_user
-DB_PASSWORD=your_password
-```
-
-**Security Note**: `SKIP_AUTH=true` is automatically blocked when `ENV=production`, preventing accidental authentication bypass in production deployments.
-
----
-
-## 📝 Environment Variables
-
-Required:
-```bash
-# Database (PostgreSQL/Neon)
-DB_HOST=your-postgres-host.neon.tech
-DB_PORT=5432
-DB_NAME=fleetmind
-DB_USER=your_user
-DB_PASSWORD=your_password
-
-# Google Maps API
-GOOGLE_MAPS_API_KEY=your_api_key
-
-# Google Gemini API
-GOOGLE_API_KEY=your_gemini_key
-AI_PROVIDER=gemini
-```
+## 🔗 Links
 
-Optional:
-```bash
-# Server configuration
-PORT=7860
-HOST=0.0.0.0
-LOG_LEVEL=INFO
-SERVER_URL=http://localhost:7860
-
-# Authentication
-SKIP_AUTH=true  # Set to false for production
-```
+| Resource | URL |
+|----------|-----|
+| **Live Demo** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space |
+| **MCP Endpoint** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse |
+| **Generate API Key** | https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/generate-key |
+| **GitHub** | https://github.com/mashrur-rahman-fahim/fleetmind-mcp |
+| **HuggingFace Space** | https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai |
 
 ---
 
-## 🏆 Why FleetMind for Track 1?
-
-### Production-Ready MCP Server ✅
-
-- **Real Business Value:** Solves actual delivery dispatch problems
-- **29 Tools:** Comprehensive order, driver & assignment management (including Gemini 2.0 Flash AI)
-- **2 Resources:** Live data feeds for contextual AI responses
-- **Industry Standard:** Uses FastMCP framework and MCP protocol
-- **Scalable:** PostgreSQL database, stateless design
-- **Well-Documented:** Comprehensive API reference and examples
-
-### Enterprise Category Perfect Fit ✅
-
-- **Complex Operations:** Order creation, assignment, routing, tracking
-- **External Integrations:** Google Maps API (geocoding + directions)
-- **Database Operations:** Production PostgreSQL with 6 tables
-- **Real-Time Data:** Live resources for orders and drivers
-- **Multi-Tool Workflows:** Tools compose together (geocode → create → assign)
+## 👥 Team
 
-### Technical Excellence ✅
+**FleetMind Development Team**
 
-- **882 lines** of well-structured MCP server code
-- **2,099 lines** of battle-tested tool handlers
-- **Type hints** throughout for reliability
-- **Error handling** with graceful fallbacks
-- **Logging infrastructure** for debugging
-- **SSE transport** for web connectivity
+*MCP 1st Birthday Hackathon - Track 1: Building MCP Servers (Enterprise Category)*
 
 ---
 
 ## 📄 License
 
-MIT License - see LICENSE file for details.
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! Please:
-1. Fork the repository
-2. Create a feature branch
-3. Commit your changes
-4. Push and open a Pull Request
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-## 📞 Support
+<div align="center">
 
-- **Issues:** https://github.com/mashrur-rahman-fahim/fleetmind-mcp/issues
-- **Hackathon:** https://huggingface.co/MCP-1st-Birthday
+**Built with ❤️ using [FastMCP](https://gofastmcp.com) for the MCP 1st Birthday Hackathon**
 
----
-
-**Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) for the MCP 1st Birthday Hackathon**
+[![MCP](https://img.shields.io/badge/MCP-1.0-orange)](https://modelcontextprotocol.io)
+[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.0-blue)](https://gofastmcp.com)
+[![Python](https://img.shields.io/badge/Python-3.10+-brightgreen)](https://python.org)
 
-**Track 1: Building MCP Servers - Enterprise Category**
+</div>