README.md

metadata

title: FleetMind MCP Server
emoji: 🚚
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
tags:
  - mcp
  - building-mcp-servers
  - model-context-protocol
  - delivery-management
  - postgresql
  - fastmcp
  - enterprise
  - logistics

🚚 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 18 AI tools and 2 real-time resources for managing delivery operations through any MCP-compatible client.

---

🔗 Links

• GitHub Repository: https://github.com/mashrur-rahman-fahim/fleetmind-mcp
• HuggingFace Space: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
• SSE Endpoint: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai/sse

---

👥 Team

Team Members:

• [Your Name] - @your-hf-username - Lead Developer
• [Partner Name] - @partner-username - [Role]

(Note: Update with actual team information for hackathon submission)

---

🎯 What is FleetMind MCP?

FleetMind is a production-ready Model Context Protocol (MCP) server that transforms delivery dispatch management into AI-accessible tools. Any MCP client (Claude Desktop, Continue, Cline, custom apps) can connect and use 18 powerful tools to manage orders, drivers, routes, and more.

Key Features

✅ 18 AI Tools - Order & Driver Management ✅ 2 Real-Time Resources - Live data feeds (orders://all, drivers://all) ✅ Google Maps Integration - Geocoding & Route Calculation ✅ PostgreSQL Database - Production-grade data storage (Neon) ✅ SSE Endpoint - Server-Sent Events for web connectivity ✅ Multi-Client Support - Works with any MCP-compatible client

---

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

{
  "mcpServers": {
    "fleetmind": {
      "url": "https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai/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"
   • "Show me all available drivers"
   • "Calculate route from downtown SF to Oakland Airport"

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://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai/sse"
)

# Use any of the 18 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 (18 Total)

Order Management (10 tools)

Tool	Description	Example Use
geocode_address	Convert address to GPS coordinates	"Geocode 123 Main St, San Francisco"
calculate_route	Find shortest route between locations	"Route from SF City Hall to Oakland Airport"
create_order	Create new delivery orders	"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	"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	"Mark order ORD-... as delivered"
delete_order	Permanently remove orders	"Delete test order ORD-TEST-001"

Driver Management (8 tools)

Tool	Description	Example Use
create_driver	Onboard new drivers	"Add driver Mike with plate ABC-123"
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	"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	"Update driver DRV-... status to busy"
delete_driver	Remove drivers from fleet	"Remove driver DRV-TEST-001"

---

📊 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?"

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│   MCP Clients                           │
│   (Claude Desktop, Continue, Custom)    │
└─────────────────┬───────────────────────┘
                  │ MCP Protocol (SSE)
                  ↓
┌─────────────────────────────────────────┐
│   FleetMind MCP Server (HF Space)       │
│   • app.py (SSE endpoint)               │
│   • server.py (18 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
• 18 Tools: Comprehensive order & driver management
• 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