README.md

metadata

title: FleetMind MCP Server
emoji: 🚚
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
short_description: >-
  Enterprise MCP server with 29 AI tools and Gemini 2.0 Flash intelligent
  assignment
tags:
  - mcp
  - building-mcp-track-enterprise
  - model-context-protocol
  - delivery-management
  - postgresql
  - fastmcp
  - gradio
  - enterprise
  - logistics
  - gemini
  - google-maps
  - 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 a professional web landing page with connection instructions.

---

🔗 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
• 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

---

👥 Team

FleetMind Development Team

This project is submitted as part of the MCP 1st Birthday Hackathon (Track 1: Building MCP - Enterprise Category).

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

---

🎯 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

✅ 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

⭐ 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

---

🏆 Why Track 1: Building MCP Servers (Enterprise Category)?

FleetMind demonstrates enterprise-grade MCP server development with cutting-edge AI integration and production-ready architecture:

🤖 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

🏢 Enterprise-Ready Features

• PostgreSQL Database - Production-grade data storage with Neon serverless PostgreSQL
• 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

🚀 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

📊 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)

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.

---

🚀 Quick Start

Connect from Claude Desktop

1. Install Claude Desktop from https://claude.ai/download

2. Configure MCP Server - Edit your claude_desktop_config.json:

For Production (HuggingFace Space):

{
  "mcpServers": {
    "fleetmind_Prod": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse"
      ]
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "fleetmind": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/sse"
      ]
    }
  }
}

Both (Production + Local):

{
  "mcpServers": {
    "fleetmind": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:7860/sse"]
    },
    "fleetmind_Prod": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse"]
    }
  }
}

3. Restart Claude Desktop - FleetMind tools will appear automatically!

4. 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

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
})

---

🛠️ 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

Example:

"Which drivers are currently available?"

---

🔧 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

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│   MCP Clients                           │
│   (Claude Desktop, Continue, Custom)    │
└─────────────────┬───────────────────────┘
                  │ MCP Protocol (SSE)
                  ↓
┌─────────────────────────────────────────┐
│   FleetMind MCP Server (HF Space)       │
│   • app.py (SSE endpoint)               │
│   • server.py (29 tools, 2 resources)   │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┴──────────┐
        ↓                    ↓
┌───────────────┐    ┌──────────────┐
│ Google Maps   │    │ PostgreSQL   │
│ Geocoding API │    │ Database     │
│ Directions API│    │ (Neon)       │
└───────────────┘    └──────────────┘

Benefits of MCP Architecture:

• ✅ Multi-client support (use from Claude, VS Code, mobile apps)
• ✅ Standardized protocol (MCP is industry-standard)
• ✅ Real-time data access (resources provide live context)
• ✅ Tool composability (AI combines tools intelligently)
• ✅ Easy integration (any MCP client can connect)

---

📖 Usage Examples

Example 1: Create & Assign Order

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.

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"

Example 2: Track Active Deliveries

Prompt:

Show me all urgent orders that are currently in transit, sorted by deadline.

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

---

🗄️ Database Schema

Orders Table (26 columns)

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
);

Drivers Table (15 columns)

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

Setup

# 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

# Test server
python -c "import server; print('Server ready!')"

# Run locally (stdio mode for Claude Desktop)
python server.py

# Run locally (SSE mode for web clients)
python app.py

Testing

# 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"]
    }
  }
}

---

🚀 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

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)

---

📝 Environment Variables

Required:

# 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

Optional:

# Server configuration
PORT=7860
HOST=0.0.0.0
LOG_LEVEL=INFO

---

🏆 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)

Technical Excellence ✅

• 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

---

📄 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

---

📞 Support

• Issues: https://github.com/mashrur-rahman-fahim/fleetmind-mcp/issues
• Hackathon: https://huggingface.co/MCP-1st-Birthday

---

Built with ❤️ using FastMCP for the MCP 1st Birthday Hackathon

Track 1: Building MCP Servers - Enterprise Category