# FleetSync MCP

> A Model Context Protocol (MCP) server that exposes the FleetSync last-mile delivery platform to AI agents — enabling LLMs to query orders, manage routes, track drivers, and analyse delivery performance through natural language.

![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-purple)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
![Delivery](https://img.shields.io/badge/FleetSync-Delivery_Platform-blue)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

---

## What It Does

Turns a logistics platform into a conversational interface. A dispatcher, operations manager, or automated agent can ask questions like:

- *"What orders are scheduled for tomorrow?"*
- *"Show me all deliveries on route R-04"*
- *"Which routes today have stops more than 10km apart?"*
- *"Create a new delivery order for customer João, Rua das Flores 12, for Friday"*

...and get structured, actionable answers — without opening the dashboard.

---

## Capabilities

This MCP server exposes **17 tools** across 4 operational domains:

| Domain | Tools | What it replaces |
|--------|-------|-----------------|
| Orders | 8 | Manual dashboard lookups, copy-paste into chat |
| Routes | 7 | Spreadsheet route planning, phone calls to dispatchers |
| Analytics | 1 | Manual haversine calculations, route quality reviews |
| Drivers & Auth | 2 | Directory lookups, credential validation |

**Route distance analysis** — computes haversine distances between consecutive stops, flags segments exceeding a configurable threshold, and returns total/avg/max km per route. Identifies poorly sequenced routes before dispatch.

**Reference implementation** — built on production logistics data patterns. Client code omitted; integration available on request.

---

## Architecture

```mermaid
flowchart LR
    A[AI Agent\nClaude / n8n / Custom] -->|MCP tool call| B[fleetsync-mcp\nMCP Server]
    B -->|REST API| C[FleetSync\nAPI v2]
    C -->|JSON response| B
    B -->|structured result| A

    subgraph Tools
        direction TB
        T1[Orders\nget · create · update · delete]
        T2[Routes\nget · create · update · delete]
        T3[Analytics\nanalyse route distances]
        T4[Drivers\nlist drivers]
    end
```

---

## Tools (17 total)

### Orders (8 tools)

| Tool | Description |
|------|-------------|
| `fleetsync_get_order` | Get order by number — status, client, address, driver, proof of delivery |
| `fleetsync_orders_by_date` | Get all orders scheduled for a date |
| `fleetsync_orders_by_route` | Get all orders assigned to a route code |
| `fleetsync_orders_status_changes` | Get orders with status changes after a datetime (last 24h max) |
| `fleetsync_order_history` | Get the last 25 history entries for an order |
| `fleetsync_create_order` | Create a new unscheduled order |
| `fleetsync_update_order` | Update an existing order's fields |
| `fleetsync_delete_order` | Delete an order (irreversible) |

### Routes (7 tools)

| Tool | Description |
|------|-------------|
| `fleetsync_get_routes` | List all routes |
| `fleetsync_routes_by_date` | Get all routes for a date with driver and order count |
| `fleetsync_get_route` | Get a specific route by code |
| `fleetsync_orders_by_route_date` | Get orders grouped by route for a date |
| `fleetsync_create_route` | Create a new route with optional driver, vehicle, and orders |
| `fleetsync_update_route` | Update an existing route |
| `fleetsync_delete_route` | Delete a route (irreversible) |

### Analytics (1 tool)

| Tool | Description |
|------|-------------|
| `fleetsync_analyze_route_distances` | Compute haversine distances between consecutive stops. Flags pairs exceeding a configurable threshold (default: 5km). Returns total km, avg km, max km, and all violations |

### Drivers & Auth (2 tools)

| Tool | Description |
|------|-------------|
| `fleetsync_get_drivers` | List all drivers with vehicle, phone, and active status |
| `fleetsync_test` | Validate API credentials and check rate limits |

---

## Stack

| Component | Tool |
|-----------|------|
| Protocol | [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) |
| Language | TypeScript 5 + Node.js |
| Schema validation | [Zod](https://zod.dev) |
| Logistics platform | FleetSync API v2 |

---

## Setup

### Prerequisites
- Node.js 18+
- FleetSync account with API key

### 1. Install

```bash
git clone https://github.com/RobsonAdvincula/fleetsync-mcp.git
cd fleetsync-mcp
npm install
npm run build
```

### 2. Configure environment

```env
FLEETSYNC_API_KEY=your_api_key
FLEETSYNC_BASE_URL=https://api.fleetsync.io/v2
```

### 3. Add to MCP host

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "fleetsync": {
      "command": "node",
      "args": ["/path/to/fleetsync-mcp/dist/index.js"],
      "env": {
        "FLEETSYNC_API_KEY": "your_api_key"
      }
    }
  }
}
```

---

## Example Interactions

**Operations check:**
```
User: "How many deliveries do we have tomorrow and which routes are active?"

→ fleetsync_orders_by_date({ date: "2026-03-26" })
← { count: 47, orders: [...] }
→ fleetsync_routes_by_date({ date: "2026-03-26" })
← { count: 4, routes: [{ code: "R-01", driver: "...", orders: 12 }, ...] }

Agent: "47 orders across 4 active routes tomorrow. Route R-03 has the most stops (18)."
```

**Route quality check:**
```
User: "Is route R-04 well optimised?"

→ fleetsync_analyze_route_distances({ code: "R-04", maxDistanceKm: 8 })
← {
    total_km: 34.2,
    avg_km: 2.1,
    violations_count: 2,
    violations: [
      { from: "ORD-112", to: "ORD-113", km: 11.4 },
      { from: "ORD-118", to: "ORD-119", km: 9.7 }
    ]
  }

Agent: "Route R-04 has 2 problematic segments exceeding 8km. Consider reordering stops 112-113 and 118-119."
```

---

## License

MIT — free to use, adapt, and build on.

---

*Built by [Robson Advincula](https://linkedin.com/in/robsonadvincula) — AI & Automation Consultant*