delivery-mcp-server

A local MCP server (Model Context Protocol) that plans capacitated vehicle routes with time windows (CVRPTW) for a last-mile delivery fleet. Built for CC3067 Redes — Proyecto 1, point 5 (own non-trivial local server).

• Transport: stdio, newline-delimited JSON.

• Protocol: JSON-RPC 2.0 implemented by hand — no MCP SDK.

• Solver: Google OR-Tools (CVRPTW) with an automatic pure-Python Clarke-Wright + 2-opt fallback.

• Storage: SQLite, auto-created and seeded on first run.

Why it is not trivial: it respects weight and unit capacity, hard time windows with per-stop service time, driver shift limits, mandatory return to the depot, and it reports infeasible deliveries with a reason instead of failing silently. It also supports what-if analysis (marginal cost of inserting a delivery) and fleet disruptions (vehicle out of service → reassignment).

Tools

Full request/response examples: examples/usage.md.

Related MCP server: ILP Drone Delivery MCP Server

Installation

git clone https://github.com/JPLopez23/delivery-mcp-server.git
cd delivery-mcp-server

uv sync
# or: python -m venv .venv && source .venv/bin/activate && pip install -e .

If OR-Tools does not install on your platform, remove it from pyproject.toml — the server automatically falls back to the built-in Clarke-Wright heuristic (capacity-aware; reports, but does not hard-enforce, time windows).

The SQLite database is created from data/schema.sql + data/seed.sql the first time the server starts. Delete data/routes.db to reset. Override the path with the ROUTE_DB environment variable.

Optional: set OSRM_URL to a running OSRM instance to use real road distances instead of haversine + urban detour factor.

Running

The server speaks MCP on stdin/stdout; a host (our chatbot, or Claude Desktop) launches it. Manual smoke test:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"plan_routes","arguments":{"date":"2026-08-30"}}}' \
| uv run python -m route_optimizer.server

Use from the chatbot host

In the host's config/servers.json:

{
  "name": "delivery",
  "transport": "stdio",
  "command": "uv",
  "args": ["run", "--directory", "../delivery-mcp-server", "python", "-m", "route_optimizer.server"],
  "env": { "ROUTE_DB": "data/routes.db" }
}

Use from Claude Desktop

{
  "mcpServers": {
    "delivery": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/delivery-mcp-server", "python", "-m", "route_optimizer.server"]
    }
  }
}

Specification

• Transport: stdio. One JSON-RPC 2.0 message per line, UTF-8.

• Methods: initialize, notifications/initialized, tools/list, tools/call, ping.

• Protocol version: 2025-06-18.

• Errors: standard JSON-RPC codes (-32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal). Tool failures come back as a normal result with isError: true and a text message, so the LLM can react.

• Coordinates: WGS-84 decimal degrees. Times: HH:MM, 24h, local.

Data model: depots, vehicles, deliveries, routes, route_stops (see data/schema.sql).

Tests

uv run --with pytest python -m pytest -q

18 tests in tests/test_tools.py: every tool, the three guide scenarios (plan the fleet's day / urgent insertion with marginal cost / vehicle breakdown + reassignment), and the constraints that make the server non-trivial — weight and unit capacity, hard time windows with per-stop service time, driver shifts, depot return, and explicit infeasibility reporting.

License / integrity

Public repository, developed individually for CC3067. OR-Tools usage follows its Apache-2.0 license. Generative AI was used per UVG policy.