README.md

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

[![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)

---

## 🔗 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](https://huggingface.co/your-hf-username) - Lead Developer
- **[Partner Name]** - [@partner-username](https://huggingface.co/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`:

```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

```python
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)

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

### 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

### Setup

```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

# 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

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

---

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

Optional:
```bash
# 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](https://github.com/jlowin/fastmcp) for the MCP 1st Birthday Hackathon**

**Track 1: Building MCP Servers - Enterprise Category**