|
|
--- |
|
|
title: FleetMind MCP Server |
|
|
emoji: 🚚 |
|
|
colorFrom: blue |
|
|
colorTo: purple |
|
|
sdk: docker |
|
|
app_file: app.py |
|
|
pinned: true |
|
|
short_description: AI delivery dispatch MCP server with 29 management tools |
|
|
tags: |
|
|
- mcp |
|
|
- building-mcp-track-enterprise |
|
|
- model-context-protocol |
|
|
- delivery-management |
|
|
- postgresql |
|
|
- fastmcp |
|
|
- gradio |
|
|
- enterprise |
|
|
- logistics |
|
|
- gemini |
|
|
- google-maps |
|
|
- ai-routing |
|
|
--- |
|
|
|
|
|
<div align="center"> |
|
|
|
|
|
# 🚚 FleetMind MCP Server |
|
|
|
|
|
### AI-Powered Delivery Dispatch for the Modern Enterprise |
|
|
|
|
|
**The Problem:** Delivery dispatch is complex—coordinating drivers, optimizing routes, handling weather delays, and meeting SLAs requires constant human oversight. |
|
|
|
|
|
**The Solution:** FleetMind exposes **29 AI-accessible tools** that let Claude (or any MCP client) manage your entire delivery operation through natural conversation. |
|
|
|
|
|
**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. |
|
|
|
|
|
[](https://www.youtube.com/watch?v=IA9iD0VPvro) |
|
|
[](https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space) |
|
|
[](https://github.com/mashrur-rahman-fahim/fleetmind-mcp) |
|
|
[](https://www.linkedin.com/posts/kazi-wasif-amin-shammo-3a0307197_mcpbirthdayhackathon-ai-mcp-activity-7400938958521675776-Trax) |
|
|
[](https://www.facebook.com/share/v/1BdfnLbuEY/) |
|
|
|
|
|
</div> |
|
|
|
|
|
--- |
|
|
|
|
|
## 📺 See It In Action |
|
|
|
|
|
<div align="center"> |
|
|
<a href="https://www.youtube.com/watch?v=IA9iD0VPvro"> |
|
|
<img src="https://img.youtube.com/vi/IA9iD0VPvro/maxresdefault.jpg" alt="FleetMind Demo Video" width="560"> |
|
|
</a> |
|
|
<p><b>▶️ Click to watch the demo video</b></p> |
|
|
</div> |
|
|
|
|
|
> Watch Gemini 2.0 Flash AI analyze weather, traffic, and driver capabilities to make intelligent assignment decisions with full reasoning transparency. |
|
|
|
|
|
--- |
|
|
|
|
|
## ⚡ Quick Start (2 Minutes) |
|
|
|
|
|
### 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 2: Configure Claude Desktop |
|
|
Add to your `claude_desktop_config.json`: |
|
|
```json |
|
|
{ |
|
|
"mcpServers": { |
|
|
"fleetmind": { |
|
|
"command": "npx", |
|
|
"args": [ |
|
|
"mcp-remote", |
|
|
"https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space/sse?api_key=YOUR_KEY_HERE" |
|
|
] |
|
|
} |
|
|
} |
|
|
} |
|
|
``` |
|
|
|
|
|
### 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" |
|
|
|
|
|
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." |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
## 🏆 Why FleetMind? |
|
|
|
|
|
| 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 | |
|
|
|
|
|
--- |
|
|
|
|
|
## 🛠️ 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> |
|
|
|
|
|
--- |
|
|
|
|
|
## 🏗️ 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 │ |
|
|
└──────────┘ └─────────┘ └──────────┘ └───────────┘ |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
## 🔐 Authentication & Security |
|
|
|
|
|
FleetMind uses a **3-layer authentication system** for enterprise-grade security: |
|
|
|
|
|
| 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) | |
|
|
|
|
|
**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) |
|
|
|
|
|
<details> |
|
|
<summary><b>View Complete Auth Flow</b></summary> |
|
|
|
|
|
``` |
|
|
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 |
|
|
``` |
|
|
|
|
|
</details> |
|
|
|
|
|
--- |
|
|
|
|
|
## 🚀 Deployment |
|
|
|
|
|
### Production (HuggingFace Space) |
|
|
Already deployed at: **https://mcp-1st-birthday-fleetmind-dispatch-ai.hf.space** |
|
|
|
|
|
### Local Development |
|
|
```bash |
|
|
git clone <repository-url> |
|
|
cd fleetmind-mcp |
|
|
pip install -r requirements.txt |
|
|
|
|
|
# Configure .env with your API keys |
|
|
python start_with_proxy.py # Runs proxy (7860) + FastMCP (7861) |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
## 📊 Technical Specifications |
|
|
|
|
|
| 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+ | |
|
|
|
|
|
--- |
|
|
|
|
|
## 🔗 Links |
|
|
|
|
|
| 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 | |
|
|
| **HuggingFace Space** | https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai | |
|
|
|
|
|
--- |
|
|
|
|
|
## 👥 Team |
|
|
|
|
|
**FleetMind Development Team** |
|
|
|
|
|
*MCP 1st Birthday Hackathon - Track 1: Building MCP Servers (Enterprise Category)* |
|
|
|
|
|
--- |
|
|
|
|
|
## 📄 License |
|
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details. |
|
|
|
|
|
--- |
|
|
|
|
|
<div align="center"> |
|
|
|
|
|
**Built with ❤️ using [FastMCP](https://gofastmcp.com) for the MCP 1st Birthday Hackathon** |
|
|
|
|
|
[](https://modelcontextprotocol.io) |
|
|
[](https://gofastmcp.com) |
|
|
[](https://python.org) |
|
|
|
|
|
</div> |
|
|
|
