Fleetsync

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.

---

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.

---

Architecture

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
Language	TypeScript 5 + Node.js
Schema validation	Zod
Logistics platform	FleetSync API v2

---

Setup

Prerequisites

• Node.js 18+
• FleetSync account with API key

1. Install

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

2. Configure environment

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

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

---

Route Distance Analysis

The fleetsync_analyze_route_distances tool uses the Haversine formula to compute great-circle distances between consecutive delivery stops using their GPS coordinates.

distance = 2R × arcsin(√(sin²(Δlat/2) + cos(lat₁)cos(lat₂)sin²(Δlon/2)))

Output includes per-segment distances, total route km, and a list of all threshold violations — useful for identifying poorly sequenced routes before dispatch.

---

License

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

---

Built by Robson Advincula — AI & Automation Consultant