Routes & stops module — JetSetGo MCP reference

The routes module manages the physical backbone of a transport network: stops (real-world locations a vehicle calls at), routes (named, ordered sequences of stops served by one resource), and route stops (each stop's position, travel minutes, and fare sectors within a sequence). It exposes the largest tool surface among the JetSetGo MCP modules and serves as the reference implementation of the platform's read / guarded-write tool pattern.

What the operator uses it for

Operators maintain reusable stops — name, short code, address, latitude/longitude, and an active/inactive status — and assemble them into routes. A route belongs to exactly one resource (a vessel, bus, or vehicle): the same corridor operated by two different vessels is two routes. A route carries operational timing (boarding_before_in_minutes, how long before departure boarding opens) and an optional bidirectional link to its return-direction counterpart.

Each leg of a route records minutes_to_next (travel time to the following stop) and sections_to_next (fare sectors crossed on that leg). These per-leg values make a route timed and priceable rather than a list of places: downstream they are summed into journey duration and journey sector counts, which drive sector-based fares. Operators also reorder route display positions, replace whole stop sequences, and — for road routes — run an optimiser that reorders intermediate stops and estimates leg minutes from road-network routing data.

Where it sits

Routes sit near the base of the platform. Upstream they depend on the resources catalog: creating or updating a route requires a valid operating resource. Downstream:

Schedule creates timetabled services that run on a route; without routes there is nothing to schedule.
Bookings and pricing derive departure point, arrival point, journey minutes, and journey sectors from the route's stop sequence — editing leg times or sectors changes durations and fares downstream.
Sellable capacity is attached per service, which runs on the route's resource.
Boarding and check-in use boarding_before_in_minutes to open boarding and treat the stop sequence as physical call points.

Key concepts

Stop — a physical location (code, name, address, coordinates), reusable across many routes.
Route — an ordered, timed stop sequence served by one resource; typically created in forward/return pairs linked via reverse_id.
Leg — one stop's membership in a route: order_no, minutes_to_next (required, defaults to 0), and sections_to_next (numeric, may be fractional).
Sector — a fare unit crossed on a leg; summed across a journey for sector-based pricing.
Reverse route — the return-direction counterpart; setting or clearing the link updates both routes.
Boarding-before minutes — how long before departure boarding opens for services on the route (required, ≥ 0).
Protected system records — hidden sentinel stop and route rows backing the platform's "unscheduled" plumbing; never listed by reads, refused by writes.
Resource dwell — the operating resource's per-stop wait time, folded into every optimised leg's minutes.

Tools

Tool	Class	Purpose
`routes_list_stops`	Read	List stops (name/code contains, status filters); excludes the protected system stop.
`routes_get_stop`	Read	Fetch one stop by id.
`routes_list_routes`	Read	List routes ordered by display position; name/status/resource filters.
`routes_get_route`	Read	Fetch a route with its ordered stops and per-leg values.
`routes_geocode_address`	Read	Resolve a free-text address to candidate coordinates for stop writes.
`routes_list_resources`	Read	Cross-module read of the resources catalog usable as `resource_id`.
`routes_create_stop`	Guarded write	Create a stop from explicit coordinates or an address (resolved once at preview).
`routes_update_stop`	Guarded write	Partial stop update; code can change but never be cleared.
`routes_deactivate_stop`	Guarded write (destructive)	Retire a stop by setting status inactive — never a hard delete.
`routes_create_route`	Guarded write	Create a route; `resource_id` required and validated against the catalog.
`routes_update_route`	Guarded write	Partial update; reverse-link changes rewrite both routes in one transaction.
`routes_deactivate_route`	Guarded write (destructive)	Retire a route by setting status inactive.
`routes_set_route_stops`	Guarded write (destructive)	Replace a route's entire stop sequence atomically (delete + insert).
`routes_reorder_routes`	Guarded write	Rewrite every route's display position to 1..n from a full ordered id list.
`routes_optimize_route_order`	Guarded write (destructive)	Reorder intermediate stops and/or estimate leg minutes via road routing.

Rules worth knowing

Deactivate, never delete. Stops and routes are retired by status change. The only true row deletions are route-stop entries replaced when a sequence is rewritten.
Route writes are never cosmetic. Any route update fires a server-side trigger rebuilding the route-to-resource mapping that feeds scheduling; resource_id is therefore always written (preserved, never nulled) — even by deactivate.
Geocode-once handshake. Address-based stop writes resolve coordinates once, at preview. Confirm must echo the resolved coordinates (or the optimiser's resolved sequence) — confirming with a bare address is rejected so no second external call runs.
Ambiguous addresses are not auto-picked. When geocoding returns multiple candidates they are returned for the agent to choose; a single candidate binds automatically. Geocoding degrades gracefully when unavailable.
Anti-double-create rechecks. At confirm, creates re-query for an existing active stop with the same code (or active route with the same name) and fail with a re-preview error on a hit.
Sequence replaces are atomic and validated. Every supplied stop must exist, be active, and not be the protected system stop; an empty sequence is refused (retire the route instead); repeating a stop id is allowed — a route may legitimately call at the same stop twice.
Reorder is set-equality guarded. routes_reorder_routes rejects a partial, stale, or duplicated id list; it must contain exactly the current non-system routes.
Optimiser constraints. Road routes only (ferry/sea timings are entered manually); first and last stops are fixed anchors, optionally overridden via origin/destination; at most 25 intermediate stops; the last stop always keeps its existing minutes; at least one of reorder/estimate must be enabled.

Schedule — services are timetabled departures running on a route.
Resources — owns the vessels, buses, and vehicles each route requires.