@squawk/mcp 0.6.0 → 0.8.0

package/README.md

@@ -98,7 +98,7 @@ version explicitly in the client config:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "@squawk/mcp@0.6.0"]
+      "args": ["-y", "@squawk/mcp@0.8.0"]
     }
   }
 }
@@ -209,9 +209,12 @@ directly.
 
 ### Airspace (`@squawk/airspace` + `@squawk/airspace-data`)
 
-| Tool                         | Purpose                                                                                             |
-| ---------------------------- | --------------------------------------------------------------------------------------------------- |
-| `query_airspace_at_position` | Class B/C/D/E and SUA features whose lateral polygon and vertical bounds contain a point + altitude |
+| Tool                         | Purpose                                                                                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query_airspace_at_position` | Class B/C/D/E, SUA, and ARTCC features whose lateral polygon and vertical bounds contain a point + altitude                                     |
+| `get_airspace_for_airport`   | Class B/C/D/E2 surface-area sectors associated with an airport, with full polygon boundaries                                                    |
+| `find_artcc_for_position`    | US ARTCC features containing a given position and altitude (typically one feature; multiple for oceanic CTA+FIR overlaps or stratum boundaries) |
+| `find_artcc_by_identifier`   | All ARTCC features for a 3-letter center code (e.g. "ZNY"), optionally narrowed to a single stratum, with full polygon boundaries               |
 
 ### Navaids (`@squawk/navaids` + `@squawk/navaid-data`)
 
@@ -264,18 +267,20 @@ do not pay the decompression cost.
 
 ### Weather (`@squawk/weather` + `@squawk/weather/fetch`)
 
-| Tool                          | Purpose                                                        |
-| ----------------------------- | -------------------------------------------------------------- |
-| `parse_metar`                 | Parse a user-supplied METAR/SPECI string                       |
-| `parse_taf`                   | Parse a user-supplied TAF                                      |
-| `parse_sigmet`                | Parse a US-domestic or ICAO SIGMET                             |
-| `parse_airmet`                | Parse an AIRMET bulletin                                       |
-| `parse_pirep`                 | Parse a PIREP report                                           |
-| `fetch_metar`                 | Fetch and parse live METARs from the Aviation Weather Center   |
-| `fetch_taf`                   | Fetch and parse live TAFs                                      |
-| `fetch_pirep`                 | Fetch PIREPs near a center station                             |
-| `fetch_sigmets`               | Fetch active US (CONUS) SIGMETs, optionally filtered by hazard |
-| `fetch_international_sigmets` | Fetch active international SIGMETs in ICAO format              |
+| Tool                          | Purpose                                                             |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `parse_metar`                 | Parse a user-supplied METAR/SPECI string                            |
+| `parse_taf`                   | Parse a user-supplied TAF                                           |
+| `parse_sigmet`                | Parse a US-domestic or ICAO SIGMET                                  |
+| `parse_airmet`                | Parse an AIRMET bulletin                                            |
+| `parse_pirep`                 | Parse a PIREP report                                                |
+| `parse_winds_aloft`           | Parse an FD (winds and temperatures aloft) bulletin                 |
+| `fetch_metar`                 | Fetch and parse live METARs from the Aviation Weather Center        |
+| `fetch_taf`                   | Fetch and parse live TAFs                                           |
+| `fetch_pirep`                 | Fetch PIREPs near a center station                                  |
+| `fetch_sigmets`               | Fetch active US (CONUS) SIGMETs, optionally filtered by hazard      |
+| `fetch_international_sigmets` | Fetch active international SIGMETs in ICAO format                   |
+| `fetch_winds_aloft`           | Fetch and parse a live FD winds-aloft forecast by region and period |
 
 ### NOTAMs (`@squawk/notams`)
 

package/dist/tools/airspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"airspace.d.ts","sourceRoot":"","sources":["../../src/tools/airspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmEzE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsE7D"}
+{"version":3,"file":"airspace.d.ts","sourceRoot":"","sources":["../../src/tools/airspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiFzE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmI7D"}

package/dist/tools/airspace.js

@@ -23,6 +23,16 @@ const AIRSPACE_TYPE_VALUES = [
     'WARNING',
     'ALERT',
     'NSA',
+    'ARTCC',
+];
+/** All {@link ArtccStratum} values, used for input validation. */
+const ARTCC_STRATUM_VALUES = [
+    'LOW',
+    'HIGH',
+    'UTA',
+    'CTA',
+    'FIR',
+    'CTA/FIR',
 ];
 /**
  * Strips the polygon boundary from a feature for tool output. The boundary
@@ -43,6 +53,7 @@ function summarizeFeature(feature) {
         state: feature.state,
         controllingFacility: feature.controllingFacility,
         scheduleDescription: feature.scheduleDescription,
+        artccStratum: feature.artccStratum,
         vertexCount: ring.length,
     };
 }
@@ -109,4 +120,49 @@ export function registerAirspaceTools(server) {
             structuredContent: { airport, features },
         };
     });
+    server.registerTool('find_artcc_for_position', {
+        title: 'Find the ARTCC center containing a position and altitude',
+        description: 'Returns the US Air Route Traffic Control Center (ARTCC) features whose lateral boundary contains the given position at the given altitude. Typically returns a single feature (one center, one stratum), but can return multiple in three cases: (1) oceanic positions covered by overlapping CTA and FIR strata; (2) positions exactly at a stratum boundary (e.g. FL180 matches both LOW and HIGH); (3) antimeridian-split centers like ZAK where a stratum is published as multiple sub-polygons that each cover part of the same geographic area. If the position falls outside any US ARTCC, returns an empty features array. Boundary geometry is summarized as a vertex count to keep responses compact - use find_artcc_by_identifier to retrieve full polygons.',
+        inputSchema: {
+            lat: z.number().min(-90).max(90).describe('Latitude in decimal degrees (WGS84).'),
+            lon: z.number().min(-180).max(180).describe('Longitude in decimal degrees (WGS84).'),
+            altitudeFt: z
+                .number()
+                .optional()
+                .describe('Altitude in feet MSL. Defaults to 0 (surface), which selects the LOW stratum where applicable. Pass FL180+ to target HIGH or FL600+ to target UTA.'),
+        },
+    }, ({ lat, lon, altitudeFt }) => {
+        const query = {
+            lat,
+            lon,
+            altitudeFt: altitudeFt ?? 0,
+            types: new Set(['ARTCC']),
+        };
+        const features = airspaceResolver.query(query).map(summarizeFeature);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ features }, null, 2) }],
+            structuredContent: { features },
+        };
+    });
+    server.registerTool('find_artcc_by_identifier', {
+        title: 'Find ARTCC features for a center identifier',
+        description: 'Returns every ARTCC feature for the given three-letter center code (e.g. "ZNY", "ZBW", "ZAK"), with full polygon boundary coordinates suitable for drawing. Each US center is published as multiple features (one per stratum: LOW, HIGH, plus oceanic UTA/CTA/FIR), all returned by default. A single stratum can map to more than one feature when the source data has multiple disjoint shapes (e.g. ZOA UTA spans four oceanic delegation areas) or when antimeridian-crossing shapes are split into eastern and western sub-polygons (ZAK and ZAP). Pass a stratum filter to narrow results. Lookup is case-insensitive. Returns an empty features array for unknown identifiers.',
+        inputSchema: {
+            artccId: z
+                .string()
+                .min(3)
+                .max(3)
+                .describe('Three-letter ARTCC center code (e.g. "ZNY", "ZBW").'),
+            stratum: z
+                .enum(ARTCC_STRATUM_VALUES)
+                .optional()
+                .describe('Restrict to a single stratum (LOW, HIGH, UTA, CTA, FIR, or CTA/FIR). Omit to return every published stratum for the center.'),
+        },
+    }, ({ artccId, stratum }) => {
+        const features = airspaceResolver.byArtcc(artccId, stratum);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ features }, null, 2) }],
+            structuredContent: { features },
+        };
+    });
 }

package/dist/tools/weather.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"weather.d.ts","sourceRoot":"","sources":["../../src/tools/weather.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyDzE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsO5D"}
+{"version":3,"file":"weather.d.ts","sourceRoot":"","sources":["../../src/tools/weather.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwFzE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAgS5D"}

package/dist/tools/weather.js

@@ -8,8 +8,8 @@
  * and return both the parsed records and any per-record parse errors so the
  * model can surface partial failures.
  */
-import { parseAirmet, parseMetar, parsePirep, parseSigmet, parseTaf } from '@squawk/weather';
-import { fetchInternationalSigmets, fetchMetar, fetchPirep, fetchSigmets, fetchTaf, } from '@squawk/weather/fetch';
+import { parseAirmet, parseMetar, parsePirep, parseSigmet, parseTaf, parseWindsAloft, } from '@squawk/weather';
+import { fetchInternationalSigmets, fetchMetar, fetchPirep, fetchSigmets, fetchTaf, fetchWindsAloft, } from '@squawk/weather/fetch';
 import { z } from 'zod';
 import { runParser, summarizeParseErrors } from './tool-helpers.js';
 /** Allowed values for the AWC SIGMET hazard filter. */
@@ -25,6 +25,24 @@ const PIREP_INTENSITY_VALUES = [
     'mod',
     'sev',
 ];
+/** Allowed geographic regions for the AWC winds-aloft (FD) endpoint. */
+const WINDS_ALOFT_REGION_VALUES = [
+    'contiguousUs',
+    'northeast',
+    'southeast',
+    'northCentral',
+    'southCentral',
+    'rockyMountain',
+    'pacificCoast',
+    'alaska',
+    'hawaii',
+    'westernPacific',
+];
+/** Allowed altitude bands for the AWC winds-aloft (FD) endpoint. */
+const WINDS_ALOFT_ALTITUDE_BAND_VALUES = [
+    'low',
+    'high',
+];
 /**
  * Optional override for the Aviation Weather Center base URL. Read once at
  * module load from the `SQUAWK_AWC_BASE_URL` environment variable. When set,
@@ -92,6 +110,13 @@ export function registerWeatherTools(server) {
             raw: z.string().min(1).describe('Raw PIREP report text.'),
         },
     }, ({ raw }) => runParser(raw, parsePirep, 'pirep'));
+    server.registerTool('parse_winds_aloft', {
+        title: 'Parse a winds-aloft (FD) forecast bulletin',
+        description: 'Parses a raw FD (Forecast Winds and Temperatures Aloft) bulletin - sometimes referred to by its older name "FB" - into a structured object with the issue time, valid time, usable period, altitude columns, and per-station forecast levels. Each level includes wind direction, wind speed, and (usually) temperature; light-and-variable winds are flagged, missing columns are flagged, and temperatures above the "TEMPS NEG ABV" threshold are decoded from the implicit-negative wire format.',
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw FD bulletin text.'),
+        },
+    }, ({ raw }) => runParser(raw, parseWindsAloft, 'windsAloft'));
     // ---------------------------------------------------------------------------
     // Fetch (Aviation Weather Center text API)
     // ---------------------------------------------------------------------------
@@ -212,4 +237,39 @@ export function registerWeatherTools(server) {
             structuredContent: payload,
         };
     });
+    server.registerTool('fetch_winds_aloft', {
+        title: 'Fetch a winds-aloft (FD) forecast from the Aviation Weather Center',
+        description: 'Fetches a winds-aloft forecast (FD product) from the Aviation Weather Center text API and parses the response. Returns a single parsed bulletin covering many reporting stations at several altitudes. All three inputs (region, altitudeBand, forecastHours) are optional - omit them to let AWC apply its own defaults.',
+        inputSchema: {
+            region: z
+                .enum(WINDS_ALOFT_REGION_VALUES)
+                .optional()
+                .describe('Optional geographic region. "contiguousUs" covers all 48 contiguous US sites; the per-center regions ("northeast", "southeast", "northCentral", "southCentral", "rockyMountain", "pacificCoast") cover subsets. "alaska", "hawaii", and "westernPacific" are separate regions.'),
+            altitudeBand: z
+                .enum(WINDS_ALOFT_ALTITUDE_BAND_VALUES)
+                .optional()
+                .describe('Optional altitude band. "low" covers 3000-39000 ft (9 altitude columns); "high" covers FL450 and above (typically 45000 and 53000 ft).'),
+            forecastHours: z
+                .union([z.literal(6), z.literal(12), z.literal(24)])
+                .optional()
+                .describe('Optional forecast horizon in hours from issue time. Must be 6, 12, or 24.'),
+        },
+    }, async ({ region, altitudeBand, forecastHours }) => {
+        const options = baseFetchOptions();
+        if (region !== undefined) {
+            options.region = region;
+        }
+        if (altitudeBand !== undefined) {
+            options.altitudeBand = altitudeBand;
+        }
+        if (forecastHours !== undefined) {
+            options.forecastHours = forecastHours;
+        }
+        const { forecast } = await fetchWindsAloft(options);
+        const payload = { forecast };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Model Context Protocol server exposing squawk's aviation libraries as tools for LLM clients",
   "author": "Neil Cochran",
@@ -38,26 +38,26 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@squawk/airport-data": "^0.6.0",
-    "@squawk/airports": "^0.5.0",
-    "@squawk/airspace": "^0.5.1",
-    "@squawk/airspace-data": "^0.3.2",
-    "@squawk/airway-data": "^0.4.1",
-    "@squawk/airways": "^0.3.1",
-    "@squawk/fix-data": "^0.5.1",
-    "@squawk/fixes": "^0.2.1",
+    "@squawk/airport-data": "^0.6.1",
+    "@squawk/airports": "^0.5.1",
+    "@squawk/airspace": "^0.6.0",
+    "@squawk/airspace-data": "^0.4.0",
+    "@squawk/airway-data": "^0.4.2",
+    "@squawk/airways": "^0.3.2",
+    "@squawk/fix-data": "^0.5.2",
+    "@squawk/fixes": "^0.2.2",
     "@squawk/flight-math": "^0.5.1",
-    "@squawk/flightplan": "^0.4.1",
-    "@squawk/geo": "^0.3.1",
-    "@squawk/icao-registry": "^0.3.1",
-    "@squawk/icao-registry-data": "^0.4.1",
-    "@squawk/navaid-data": "^0.5.1",
-    "@squawk/navaids": "^0.3.1",
-    "@squawk/notams": "^0.3.1",
-    "@squawk/procedure-data": "^0.5.1",
-    "@squawk/procedures": "^0.4.1",
-    "@squawk/types": "^0.6.0",
-    "@squawk/weather": "^0.4.1",
+    "@squawk/flightplan": "^0.4.2",
+    "@squawk/geo": "^0.3.2",
+    "@squawk/icao-registry": "^0.3.2",
+    "@squawk/icao-registry-data": "^0.4.2",
+    "@squawk/navaid-data": "^0.5.2",
+    "@squawk/navaids": "^0.3.2",
+    "@squawk/notams": "^0.3.2",
+    "@squawk/procedure-data": "^0.5.2",
+    "@squawk/procedures": "^0.4.2",
+    "@squawk/types": "^0.7.0",
+    "@squawk/weather": "^0.5.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {