Force an immediate ATCSCC ops plan snapshot.

Triggers a fetch and parse of the current ATCSCC National Operations Plan outside the normal polling schedule. Requires DISPATCH_TOKEN env var to be set.

Returns: str: JSON confirmation or error string.

Examples: - "Force opsplan refresh" -> call with no params

Force an immediate recomputation of the Critical Predictability State (CPS).

CPS is normally recomputed after each feed update. Use this to trigger recomputation immediately, e.g. after a manual feed refresh. Requires DISPATCH_TOKEN env var to be set.

Returns: str: JSON with new CPS state and score, or error string.

Examples: - "Recompute CPS now" -> call with no params

Get the dispatch platform audit log (append-only, 90-day retention).

Returns recent audit log entries. Log is append-only and never leaves the Pi. Requires DISPATCH_TOKEN env var to be set.

Returns: str: JSON list of audit log entries with timestamp, action, and detail.

Examples: - "Show recent audit log entries" -> call (token required)

Get extended admin health check for the dispatch platform (requires token).

Returns more detailed health data than the public /healthz endpoint, including internal queue state, container status, and error counts. Requires DISPATCH_TOKEN env var to be set.

Returns: str: JSON admin health object, or error string if token missing/invalid.

Examples: - "Show admin health status" -> call (token required)

Force an immediate refresh of a specific dispatch data feed.

Bypasses the normal polling interval and triggers an immediate fetch for the named feed. Useful when a feed is stale or in an error state. Requires DISPATCH_TOKEN env var to be set.

Args: params (RefreshFeedInput): - feed_name (str): One of: metar, nws, tfr, notam, amtrak, atcscc_opsplan, runsheet

Returns: str: JSON confirmation with refresh result, or error string.

Examples: - "Refresh the TFR feed" -> params.feed_name='tfr' - "Force weather update" -> params.feed_name='metar'

Send a push notification via ntfy through the dispatch platform.

Fires a notification to the configured ntfy topics on the Pi. Use priority 5 for urgent alerts (e.g. Marine One TFR, weather emergency). Requires DISPATCH_TOKEN env var to be set.

Args: params (PushAlertInput): - message (str): Alert text, max 1000 chars - title (str, optional): Notification title (default: 'Dispatch Alert') - priority (int, optional): 1-5, default 3 (4=high, 5=urgent)

Returns: str: JSON confirmation or error string.

Examples: - "Send test alert" -> params.message='Test alert from MCP', priority=3 - "Send urgent Marine One alert" -> params.message='Marine One TFR active P-56', priority=5

Get active National Weather Service alerts for the DC metro region.

Pulls from api.weather.gov for the DC area. Returns warnings, watches, advisories, and statements currently in effect.

Returns: str: JSON list of alert objects. Each alert includes: id (str), event (str, e.g. 'Winter Storm Warning'), headline (str), description (str), severity (str), certainty (str), urgency (str), effective (str), expires (str), areas (list[str]).

Examples: - "Are there any weather alerts for DC?" -> call, check array length - "Any tornado warnings active?" -> call, filter by event containing 'Tornado'

Get current Amtrak train status at Washington Union Station (WAS/WASH).

Returns arrival and departure status for trains at WAS. Covers Acela and NE Regional services on the NEC corridor. Requires AMTRAK_FEED_URL to be configured on the Pi (push-primary ingest or poller fallback).

Returns: str: JSON object with 'trains' list. Each train: train_number (str), route_name (str), direction (str: NORTH/SOUTH), scheduled_time (str), estimated_time (str|null), status (str), delay_minutes (int), platform (str|null), last_updated (str).

Examples: - "Is the Acela arriving on time?" -> call, filter route_name by 'Acela' - "How delayed is train 95?" -> call, find by train_number, check delay_minutes

Get the AI-generated daily operational brief for CS Executive Services.

Synthesizes TFR status, weather, CPS score, NWS alerts, and ATCSCC ops plan into a concise executive brief suitable for morning standup or client briefing. Brief is cached and regenerated periodically by the poller.

Returns: str: JSON object with: brief_text (str: full plain-language brief), generated_at (str: ISO timestamp), cps_state (str: GO/CAUTION/NO-GO at brief generation time), tfr_count (int), alert_count (int).

Examples: - "What's the daily brief?" -> call, return brief_text to user - "Summarize today's operational picture" -> call, synthesize brief_text

Get the current Critical Predictability State (CPS) — the HEMS go/no-go score.

CPS is computed from six factors: ceiling, visibility, wind, precipitation, airspace restriction, and GDP (Ground Delay Program). Final state is one of: GO, CAUTION, or NO-GO per Part 135.609 thresholds.

Returns: str: JSON object with: state (str: GO/CAUTION/NO-GO), score (float: 0.0-1.0), factors: { ceiling: {value, score, label}, visibility: {value, score, label}, wind: {value, score, label}, precip: {value, score, label}, airspace: {value, score, label}, gdp: {value, score, label} }, computed_at (str: ISO timestamp).

Examples: - "Is it a go for HEMS operations?" -> call, check state field - "What's limiting the CPS score?" -> call, find lowest factor scores

Get freshness and error state for all dispatch data feeds.

Returns per-feed metadata: last_updated timestamp, age_seconds, whether the feed is in an error state, and the last error message if any.

Returns: str: JSON dict keyed by feed name (tfr, metar, nws, notam, amtrak, atcscc_opsplan, runsheet). Each entry includes last_updated, age_seconds, error (bool), error_msg (str|null).

Examples: - "Which feeds are stale or erroring?" -> call and filter error==true - "When was weather last updated?" -> call, check metar.last_updated

Get active NOTAMs (Notices to Air Missions) from the dispatch platform.

Requires FAA_NOTAM_API_KEY to be configured on the Pi. Returns NOTAMs from the FAA NOTAM API covering DC-area airports and airspace.

Returns: str: JSON list of NOTAM objects, or feed-error string if key not configured. Each NOTAM includes: id, type, location, effective_start, effective_end, text (raw NOTAM text).

Examples: - "Any NOTAMs for KIAD?" -> call, filter by location=='KIAD' - "Are there any runway closures at DCA?" -> call, filter by location and text

Get the current FAA ATCSCC National Operations Plan snapshot.

Returns the current day's ATCSCC ops plan from aviationweather.gov/node/1, which includes ground delay programs, ground stops, miles-in-trail restrictions, and other national ATCSCC advisories.

Returns: str: JSON object with: snapshot_time (str: ISO timestamp), programs (list[dict]): each entry has type, facility, reason, avg_delay_minutes, scope, start_time, end_time. raw_text (str: full ops plan text).

Examples: - "Are there any ground delays at IAD?" -> call, filter programs by facility - "What's the ATCSCC situation today?" -> call, return programs list

Get current ground route impact assessment for DC-area chauffeur operations.

Evaluates active TFRs, weather alerts, and airspace restrictions against common executive transportation corridors. Returns impact level and recommended route adjustments.

Returns: str: JSON object with: impact_level (str: NONE/LOW/MODERATE/HIGH/SEVERE), factors (list[str]: active impact sources), recommendations (list[str]: suggested route adjustments), computed_at (str: ISO timestamp).

Examples: - "Will TFRs affect our route today?" -> call, check impact_level - "Any route adjustments needed?" -> call, check recommendations list

Get the active trip runsheet for today's chauffeur operations.

NOTE: This endpoint is Tier 1 — it requires Tailscale network access (100.x.x.x range) or will return 403. Set DISPATCH_BASE_URL to the Tailscale address (http://100.94.80.100:8000) to access this endpoint.

Returns: str: JSON object with 'trips' list. Each trip includes: trip_id (str), client_name (str), pickup_time (str), pickup_location (str), destination (str), notes (str), status (str: PENDING/ACTIVE/COMPLETE). Returns 403 error if not on Tailscale.

Examples: - "What trips do we have today?" -> call (requires Tailscale) - "What time is the first pickup?" -> call, find earliest pickup_time

Get all active Temporary Flight Restrictions (TFRs) from the dispatch platform.

Returns raw TFR list parsed from FAA tfr.faa.gov XML feed. Each TFR includes location, altitude floor/ceiling, effective time window, and type code. For AI-enriched TFRs with threat interpretation, use dispatch_get_tfr_enriched.

Returns: str: JSON list of active TFR objects, or error string. Each TFR includes: notam_id, type, location, floor_ft, ceiling_ft, effective_start, effective_end, description.

Examples: - "Are there any active TFRs?" -> call, check array length - "Are there VIP or POTUS TFRs active?" -> call, filter by type or description

Get active TFRs with AI-generated threat interpretation and enrichment.

Same TFR data as dispatch_get_tfr but with additional fields: threat_level, movement_type (e.g. POTUS, VVIP), pattern match flags for Marine One and Air Force One indicators, and plain-language summary of each TFR.

Returns: str: JSON list of enriched TFR objects. Additional fields beyond raw TFR: threat_level (str), movement_type (str|null), is_marine_one (bool), is_af1 (bool), summary (str).

Examples: - "Any Marine One TFRs right now?" -> call, filter is_marine_one==true - "What's the threat level of active TFRs?" -> call, check threat_level fields

Get the current METAR weather snapshot for DC-area airports.

Returns parsed METARs from AviationWeather.gov ADDS for stations in and around the DC area (KIAD, KDCA, KBWI, KJYO, KHEF, KCGS, etc.). Data includes ceiling, visibility, wind, temperature, altimeter.

Returns: str: JSON dict with 'stations' list. Each station entry: icao (str), obs_time (str), wind_dir (int|null), wind_speed_kt (int), wind_gust_kt (int|null), visibility_sm (float), ceiling_ft (int|null), temp_c (float), dewpoint_c (float), altimeter_inhg (float), flight_category (str: VFR/MVFR/IFR/LIFR), raw_metar (str).

Examples: - "What's the ceiling at Dulles?" -> call, find KIAD entry, check ceiling_ft - "Is it VFR at DC area airports?" -> call, check flight_category per station

Check the health of the CS Executive Services dispatch platform.

Returns service health summary including API status and snapshot age for each data feed. Use this first to verify the platform is reachable before querying individual feeds.

Returns: str: JSON with 'status' field and per-feed freshness, or error string.

Examples: - "Is the dispatch platform up?" -> call with no params - "How old is the TFR data?" -> call, check 'tfr.age_seconds' in response

Add a subject to the VIP watchlist for automated dispatch monitoring.

Creates a new watchlist session. For flight tracking, provide the confirmed ICAO hex address (use flight_get_by_callsign or flight_get_by_registration to resolve hex before adding). The dispatch poller will send ntfy push alerts for tracked events.

Args: params (WatchlistAddInput): - session_type (str): 'flight', 'ground', or 'person' - subject (str): Human label, e.g. 'KLM651' or 'POTUS' - hex (str, optional): ICAO 24-bit hex, required for flight sessions - registration (str, optional): Aircraft tail number - destination_icao (str, optional): 4-letter ICAO airport code

Returns: str: JSON with new session_id on success, or error string.

Examples: - "Start tracking KLM651" -> first resolve hex via flight_get_by_callsign, then call with session_type='flight', subject='KLM651', hex=

Get all active VIP watchlist sessions from the dispatch platform.

The watchlist tracks flights, persons, or other subjects of interest. Active sessions receive automatic ntfy push alerts when tracked events occur.

Returns: str: JSON list of watchlist session objects. Each session: session_id (str), session_type (str), subject (str), hex (str|null), registration (str|null), destination_icao (str|null), created_at (str), last_updated (str).

Examples: - "What's on the watchlist?" -> call, return sessions - "Is KLM651 being tracked?" -> call, filter by subject=='KLM651'

Remove a session from the VIP watchlist, stopping automated monitoring.

Provide either session_id (precise) or hex (removes all sessions for that aircraft). At least one of session_id or hex must be provided.

Args: params (WatchlistRemoveInput): - session_id (str, optional): Session ID from dispatch_watchlist_get - hex (str, optional): ICAO hex to remove all sessions for that aircraft

Returns: str: JSON confirmation or error string.

Examples: - "Stop tracking KLM651" -> get hex via flight_get_by_callsign, then call with hex= - "Remove watchlist session abc123" -> call with session_id='abc123'

Get current ADS-B position for a flight by ICAO callsign via airplanes.live.

WARNING: Callsign-to-hex mapping can be stale (yesterday's aircraft on today's flight number). After getting the hex from this call, verify it with flight_get_by_registration to confirm the physical airframe. Use the confirmed hex for all subsequent queries and watchlist entries.

Args: params (CallsignInput): - callsign (str): ICAO 3-letter callsign, e.g. 'KLM651', 'UAL925' (normalize: KL->KLM, UA->UAL, AA->AAL, BA->BAW, DL->DAL)

Returns: str: Pipe-delimited aircraft state line: hex | reg | type | callsign | lat lon | alt_baro | gs | hdg | baro_rate | seen_ago | rssi | squawk | nic | rc Or: "No aircraft found" message with guidance for overwater flights.

Examples: - "Where is KLM651 right now?" -> params.callsign='KLM651' - "Track UAL925" -> params.callsign='UAL925', then verify hex via registration

Get current ADS-B position for an aircraft by confirmed ICAO 24-bit hex address.

Hex queries are the most reliable — they bypass callsign privacy filters and avoid stale callsign-to-hex associations. Use this for all position polls once hex has been confirmed via flight_get_by_registration.

Args: params (HexInput): - hex (str): 6-character uppercase hex, e.g. '484150', 'A1B2C3'

Returns: str: Pipe-delimited aircraft state line with full telemetry, or "No aircraft found" (overwater, ground, or hex not in ADS-B coverage).

Examples: - "Poll position for hex 484150" -> params.hex='484150' - "Is hex A1B2C3 still airborne?" -> call, check alt field

Get ADS-B position and ICAO hex for an aircraft by tail/registration number.

Registration is airframe-bound, making this the preferred way to confirm ICAO hex before adding to watchlist. airplanes.live returns the aircraft's database entry including hex even when the aircraft is not currently transmitting.

Args: params (RegistrationInput): - registration (str): Tail number, e.g. 'N12345', 'PH-BKB', 'G-EUYA'

Returns: str: Pipe-delimited aircraft state line including confirmed hex. Or: "No aircraft found" message (aircraft may be on ground or not in DB).

Examples: - "What's the hex for N12345?" -> params.registration='N12345', extract hex from result - "Confirm the aircraft on KLM651 is PH-BKB" -> call with PH-BKB, verify hex matches callsign result