all air routes#

Use this skill when the task needs route-discovery data grounded in this repo without depending on hosted All Routes MCP credentials.

Public destination policy#

This marketplace bundle is local/offline-first. Do not disclose staging, preview, Pages, or deployment hostnames. If a user asks for a hosted product URL, point them to the public product name only unless the operator provides an approved public URL in the current conversation.

Quick Start#

1. Prefer local repo surfaces over hosted services or third-party browsing.
2. Normalize natural user phrasing before endpoint selection: read references/query-normalization.md when the query uses city/airport nicknames, airline names, alliance names, or ambiguous metro areas.
3. Extract route filters before constructing requests: read references/filter-intelligence.md when the query mentions nonstop/direct service, one-stop limits, alliance preference, regional preference, or route direction.
4. If the web app is available locally, use its /api/* endpoints first.
5. If the worker is available locally, you may use the local anonymous /mcp endpoint as an optional secondary path.
6. If neither server is running, inspect the repo-backed handlers and schemas directly and label the answer as code-backed/offline rather than live endpoint output.
7. Read references/local-surfaces.md for concrete endpoint mappings and startup commands.

Workflow#

1) Normalize the query, then choose the narrowest local surface#

• For exact IATA/ICAO or airline codes, proceed directly to the matching local surface.
• For natural phrasing like NYC, London, Bay Area, American, or Star Alliance, read references/query-normalization.md, convert aliases into candidate codes/filters, and keep any ambiguity visible.
• For filter phrasing like nonstop, direct, one stop, Star Alliance only, to Europe, from X to Y, or either direction, read references/filter-intelligence.md, map supported filters to local query parameters, and preserve unsupported filters as visible limitations.
• If a city or region maps to multiple airports, either ask one concise clarification question or query the candidate set when the user asked for broad city/region coverage.
• When filters affect the lookup, include an Applied: line that names the direction, max-stop/alliance/region filters, and any filter that could not be enforced by the local surface.
• airport search / lookup: use the local airport API surfaces.
• routes from airport / city pair: use the local routes API.
• airline route map: use the airline routes API.
• timetable context: use the timetables API.
• dataset health: use the data health API, and treat it as an ops/debug surface.

2) Prefer the no-worker path#

• The primary path is local web APIs and repo-backed handlers, not hosted MCP.
• If you need live local responses, start the web app with pnpm --filter @all-routes/web dev.
• If the app is not running, inspect the local route handlers and shared schemas instead of inventing undocumented requests.

3) Use local MCP only when helpful#

• If the worker is already running, or the task clearly benefits from MCP tools/resources, use the local /mcp endpoint.
• Local anonymous MCP is intended for localhost flows only; do not assume hosted credentials or ALL_ROUTES_MCP_TOKEN.
• Keep MCP requests narrow and prefer exact airport or airline codes when possible.

4) Stay read-only and grounded#

• Do not require hosted secrets.
• Do not scrape arbitrary third-party sites.
• Do not invent write actions, browser automation, or remote fetch flows around this skill.
• Prefer exact IATA, ICAO, or airline codes over fuzzy queries when the user can provide them.
• Always say whether the answer came from local MCP, a local API, or offline code inspection.

5) Use prompts and explanations carefully#

• When local MCP is available, plan_route_options and explain_route_coverage are valid explanation surfaces.
• Without MCP, explain route coverage using the local API response or code-backed repository behavior instead of pretending a prompt tool exists.

Reference Files#

• Read references/query-normalization.md for airport/city/airline/alliance aliases, ambiguity handling, and alias fallback patterns.
• Read references/filter-intelligence.md for nonstop/stop-limit, alliance, region, direction, bidirectional-search handling, and applied-filter acknowledgement patterns.
• Read references/local-surfaces.md for local endpoint mappings, startup commands, and fallback guidance.