@squawk/mcp 0.2.0

package/README.md

@@ -0,0 +1,301 @@
+<h1><img src="../../assets/squawk-logo.svg" alt="squawk logo" width="48" height="48" style="vertical-align: middle">&nbsp; @squawk/mcp</h1>
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE.md) [![npm](https://img.shields.io/npm/v/@squawk/mcp)](https://www.npmjs.com/package/@squawk/mcp) ![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)
+
+Model Context Protocol (MCP) server that exposes the squawk aviation libraries as tools for LLM clients
+like Claude Desktop, Cursor, and any other MCP-compatible host. A single `npx @squawk/mcp` command starts
+a stdio server that surfaces airports, navaids, fixes, airways, procedures, airspace, ICAO aircraft
+registrations, weather (parsing and live AWC fetch), NOTAMs, flight plan parsing, great-circle geometry,
+and an E6B-style flight computer.
+
+Part of the [@squawk](https://www.npmjs.com/org/squawk) aviation library suite. See all packages on npm.
+
+## Quick start
+
+Pick the snippet for your MCP client. Each one tells the host to spawn `npx @squawk/mcp` over stdio.
+After editing the config, restart the client; a `squawk` (or `@squawk/mcp`) entry should appear in
+the tool picker.
+
+### Claude Desktop
+
+Open `claude_desktop_config.json` via Settings -> Developer -> Edit Config:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "npx",
+      "args": ["-y", "@squawk/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) - same shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "npx",
+      "args": ["-y", "@squawk/mcp"]
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot Chat)
+
+VS Code 1.99+ ships an MCP runtime that GitHub Copilot Chat can call into agent mode.
+Add to `.vscode/mcp.json` in your workspace, or to the user-level config via the
+`MCP: Add Server` command:
+
+```json
+{
+  "servers": {
+    "squawk": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@squawk/mcp"]
+    }
+  }
+}
+```
+
+Note the schema differs from the other clients: VS Code uses `servers` (not `mcpServers`)
+and requires an explicit `"type": "stdio"`.
+
+### Continue.dev
+
+Continue exposes MCP via its experimental config block. In `~/.continue/config.json`:
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@squawk/mcp"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Pinning a specific Node binary
+
+`npx` resolves `node` through whatever PATH the host launches with. On macOS, GUI apps often
+inherit a different PATH than your shell, so you may end up running an older Node than
+`which node` shows. Live weather fetch tools require Node >= 22 (for global `fetch`). If the
+startup log shows `WARNING: global fetch() is unavailable`, replace `"command": "npx"` with
+the absolute path to a modern node + the absolute path to the installed `bin.js`:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "/usr/local/bin/node",
+      "args": ["/absolute/path/to/node_modules/@squawk/mcp/dist/bin.js"]
+    }
+  }
+}
+```
+
+The server logs `[squawk-mcp] node <version> on <platform>/<arch>` and the tool-module count
+to stderr on every startup so you can verify the right runtime is being used.
+
+### Example prompts
+
+Once connected, the model can answer things like "what airspace is over KJFK at 4500 feet?",
+"give me the live METAR for KSFO and KOAK", "parse this route: KJFK DCT MERIT J60 MARTN DCT KLAX",
+or "look up the aircraft with ICAO hex AC82EC".
+
+## Standalone CLI
+
+You can run the server directly without an MCP host to verify that it starts and responds to protocol
+messages:
+
+```sh
+npx @squawk/mcp
+```
+
+The binary speaks MCP over stdio, so it expects an MCP client on the other end of stdin/stdout.
+Logs go to stderr.
+
+## Programmatic use
+
+Embed the server inside another MCP host or a custom transport:
+
+```typescript
+import { createSquawkMcpServer } from '@squawk/mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = createSquawkMcpServer();
+await server.connect(new StdioServerTransport());
+```
+
+## Tool catalog
+
+Tools are grouped by domain. Every tool returns both a human-readable text block and a structured
+JSON payload (`structuredContent`) so MCP clients with strict schemas can consume the results
+directly.
+
+### Geometry (`@squawk/geo`)
+
+| Tool                                | Purpose                                           |
+| ----------------------------------- | ------------------------------------------------- |
+| `great_circle_distance`             | Distance in nautical miles between two positions  |
+| `great_circle_bearing`              | Initial true bearing from one position to another |
+| `great_circle_bearing_and_distance` | Bearing + distance in one call                    |
+| `great_circle_midpoint`             | Midpoint along the great-circle arc               |
+| `great_circle_destination`          | Destination point given a bearing and distance    |
+
+### Airports (`@squawk/airports` + `@squawk/airport-data`)
+
+| Tool                    | Purpose                                                                                |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `get_airport_by_faa_id` | Look up an airport by FAA identifier                                                   |
+| `get_airport_by_icao`   | Look up an airport by ICAO code                                                        |
+| `find_nearest_airports` | Find airports nearest a position with optional facility-type and runway-length filters |
+| `search_airports`       | Substring search by airport name or city                                               |
+
+### 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 |
+
+### Navaids (`@squawk/navaids` + `@squawk/navaid-data`)
+
+| Tool                        | Purpose                                         |
+| --------------------------- | ----------------------------------------------- |
+| `get_navaid_by_ident`       | Look up navaids by identifier                   |
+| `find_navaids_by_frequency` | Find navaids tuned to a given MHz/kHz frequency |
+| `find_nearest_navaids`      | Find navaids nearest a position                 |
+| `search_navaids`            | Substring search by name or identifier          |
+
+### Fixes (`@squawk/fixes` + `@squawk/fix-data`)
+
+| Tool                 | Purpose                        |
+| -------------------- | ------------------------------ |
+| `get_fix_by_ident`   | Look up fixes by identifier    |
+| `find_nearest_fixes` | Find fixes nearest a position  |
+| `search_fixes`       | Substring search by identifier |
+
+### Airways (`@squawk/airways` + `@squawk/airway-data`)
+
+| Tool                        | Purpose                                               |
+| --------------------------- | ----------------------------------------------------- |
+| `get_airway_by_designation` | Look up airways by designation                        |
+| `expand_airway_segment`     | Expand an airway between an entry fix and an exit fix |
+| `find_airways_by_fix`       | Reverse lookup: airways that pass through a given fix |
+| `search_airways`            | Substring search by designation                       |
+
+### Procedures (`@squawk/procedures` + `@squawk/procedure-data`)
+
+| Tool                         | Purpose                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `get_procedure_by_code`      | Look up a SID/STAR by FAA computer code                                  |
+| `find_procedures_by_airport` | Procedures associated with an airport                                    |
+| `expand_procedure`           | Expand a procedure into its waypoint sequence (with optional transition) |
+| `search_procedures`          | Substring search by name or code, optionally filtered to SIDs or STARs   |
+
+### ICAO aircraft registry (`@squawk/icao-registry` + `@squawk/icao-registry-data`)
+
+| Tool                          | Purpose                                                       |
+| ----------------------------- | ------------------------------------------------------------- |
+| `lookup_aircraft_by_icao_hex` | Resolve a 24-bit ICAO hex address to an aircraft registration |
+
+The registry data (~40 MB raw) is loaded lazily on the first lookup so sessions that never need it
+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              |
+
+### NOTAMs (`@squawk/notams`)
+
+| Tool               | Purpose                              |
+| ------------------ | ------------------------------------ |
+| `parse_icao_notam` | Parse an ICAO-format NOTAM           |
+| `parse_faa_notam`  | Parse an FAA domestic (legacy) NOTAM |
+
+### Flight plans (`@squawk/flightplan`)
+
+| Tool                     | Purpose                                                    |
+| ------------------------ | ---------------------------------------------------------- |
+| `parse_flightplan_route` | Parse an ICAO Item 15 route into structured route elements |
+| `compute_route_distance` | Total great-circle route distance with optional ETE        |
+
+### Flight computer (`@squawk/flight-math`)
+
+Selected E6B calculations: any operation that embeds a non-trivial constant, formula, or model
+(WMM2025, NOAA solar, compressible-flow pitot equations, etc.) is exposed; trivial unit math is
+left to the model itself.
+
+| Tool                                             | Purpose                                                           |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| `compute_density_altitude`                       | Density altitude from field observations                          |
+| `compute_true_altitude`                          | True altitude from indicated altitude with temperature correction |
+| `compute_calibrated_airspeed_from_true_airspeed` | CAS from TAS via the ICAO compressible-flow equations             |
+| `solve_wind_triangle`                            | Heading + groundspeed from TAS, course, and wind                  |
+| `compute_headwind_crosswind`                     | Headwind/crosswind component breakdown                            |
+| `find_wind_from_track`                           | Reverse wind triangle from observed ground track                  |
+| `compute_crosswind_component`                    | Absolute crosswind for a runway                                   |
+| `compute_top_of_descent_distance`                | TOD from glidepath angle                                          |
+| `compute_top_of_descent_distance_from_rate`      | TOD from descent rate + groundspeed                               |
+| `compute_required_descent_rate`                  | Required descent rate over a distance                             |
+| `compute_required_climb_rate`                    | Required climb rate over a distance                               |
+| `compute_visual_descent_point`                   | VDP for a non-precision approach                                  |
+| `recommend_holding_pattern_entry`                | Direct/teardrop/parallel entry per AIM 5-3-8                      |
+| `compute_standard_rate_bank_angle`               | Bank angle for a 3 deg/sec turn at a given TAS                    |
+| `compute_turn_radius`                            | Turn radius for a given TAS and bank angle                        |
+| `compute_glide_distance_with_wind`               | Glide distance scaled by groundspeed/TAS ratio                    |
+| `compute_solar_times`                            | Sunrise, sunset, civil twilight (NOAA algorithm)                  |
+| `is_daytime`                                     | Daytime/nighttime per FAR 1.1 at a UTC instant                    |
+| `compute_magnetic_declination`                   | WMM2025 declination at a position                                 |
+| `convert_true_to_magnetic_bearing`               | True -> magnetic bearing using WMM2025                            |
+| `convert_magnetic_to_true_bearing`               | Magnetic -> true bearing using WMM2025                            |
+| `compute_fuel_required`                          | Fuel for a leg given distance, GS, and burn rate                  |
+| `compute_point_of_no_return`                     | PNR with separate outbound/return groundspeeds                    |
+| `compute_equal_time_point`                       | ETP with separate continuing/returning groundspeeds               |
+
+### Server diagnostics
+
+| Tool                 | Purpose                                                                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `get_dataset_status` | Report NASR cycle date, build timestamp, and record counts for every loaded snapshot (incl. lazy-load state) |
+
+## Configuration
+
+| Environment variable  | Effect                                                                                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SQUAWK_AWC_BASE_URL` | Override the Aviation Weather Center base URL used by every `fetch_*` tool. Defaults to `https://aviationweather.gov/api/data`. Useful for proxies and regional mirrors. |
+
+## Notes
+
+- All NASR-derived data sources cover the contiguous United States plus the territories included in
+  the FAA NASR 28-day subscription. Outside the US the lookup tools will return empty results. Use
+  `get_dataset_status` to confirm which NASR cycle the running server is serving.
+- Live weather tools issue HTTPS requests to `https://aviationweather.gov/api/data/...` (or the
+  override above). They are the only tools that touch the network at invocation time; everything
+  else operates against bundled snapshots in memory.
+- The bundled NASR snapshots are decompressed and indexed once when the server starts. Expect a few
+  hundred milliseconds of startup time. The aircraft registration snapshot (the largest) is loaded
+  lazily on the first `lookup_aircraft_by_icao_hex` call.

package/dist/bin.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * @packageDocumentation
+ * Stdio entrypoint for @squawk/mcp. Connects the server from
+ * {@link createSquawkMcpServer} to a `StdioServerTransport` so the binary
+ * behaves as an MCP server spawned by clients like Claude Desktop.
+ *
+ * All logs go to stderr; stdout is reserved for MCP protocol messages.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/bin.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * @packageDocumentation
+ * Stdio entrypoint for @squawk/mcp. Connects the server from
+ * {@link createSquawkMcpServer} to a `StdioServerTransport` so the binary
+ * behaves as an MCP server spawned by clients like Claude Desktop.
+ *
+ * All logs go to stderr; stdout is reserved for MCP protocol messages.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createSquawkMcpServer, PACKAGE_NAME, PACKAGE_VERSION, TOOL_MODULE_COUNT, } from './server.js';
+/**
+ * Logs the Node.js version this process is running on, the running build's
+ * package version, the tool-module count, and warns when the environment is
+ * missing capabilities the live weather fetch tools require.
+ *
+ * GUI MCP hosts (Claude Desktop, etc.) often launch child processes with a
+ * different PATH than the user's interactive shell, so `node` may resolve to
+ * an older binary than `which node` suggests. Surfacing the actual runtime
+ * version and the running package version up front makes mismatches easy to
+ * diagnose from the host's MCP log without bisecting tool failures.
+ */
+function logRuntimeDiagnostics() {
+    console.error(`[squawk-mcp] node ${process.version} on ${process.platform}/${process.arch}`);
+    console.error(`[squawk-mcp] ${PACKAGE_NAME} v${PACKAGE_VERSION}, ${TOOL_MODULE_COUNT} tool modules registered`);
+    if (typeof fetch !== 'function') {
+        console.error('[squawk-mcp] WARNING: global fetch() is unavailable in this Node runtime. ' +
+            'Live weather fetch_* tools will fail. Upgrade to Node >=22, or pin an ' +
+            'absolute path to a modern node binary in your MCP host config.');
+    }
+}
+async function main() {
+    logRuntimeDiagnostics();
+    const server = createSquawkMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('[squawk-mcp] fatal error:', err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ * @squawk/mcp - Model Context Protocol server exposing squawk's aviation
+ * libraries (geo, airports, airspace, weather, flightplan, and more) as
+ * tools for LLM clients like Claude Desktop, Cursor, and other MCP hosts.
+ *
+ * Run via the CLI:
+ *
+ * ```sh
+ * npx @squawk/mcp
+ * ```
+ *
+ * Or embed the server programmatically in another MCP host:
+ *
+ * ```typescript
+ * import { createSquawkMcpServer } from '@squawk/mcp';
+ * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ *
+ * const server = createSquawkMcpServer();
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+export { createSquawkMcpServer } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ * @squawk/mcp - Model Context Protocol server exposing squawk's aviation
+ * libraries (geo, airports, airspace, weather, flightplan, and more) as
+ * tools for LLM clients like Claude Desktop, Cursor, and other MCP hosts.
+ *
+ * Run via the CLI:
+ *
+ * ```sh
+ * npx @squawk/mcp
+ * ```
+ *
+ * Or embed the server programmatically in another MCP host:
+ *
+ * ```typescript
+ * import { createSquawkMcpServer } from '@squawk/mcp';
+ * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ *
+ * const server = createSquawkMcpServer();
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+export { createSquawkMcpServer } from './server.js';

package/dist/resolvers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * Shared resolver instances used across the squawk MCP tool modules. Each
+ * resolver is constructed once at module load time so the bundled FAA data
+ * snapshots are decoded and indexed exactly once per server process.
+ *
+ * The ICAO registry is the only resolver that loads lazily: its bundled data
+ * package decompresses ~40 MB of records on import, which is wasted work for
+ * sessions that never call the tail-number lookup. The registry is built on
+ * the first {@link getIcaoRegistry} call and cached for subsequent calls.
+ */
+import { type AirportResolver } from '@squawk/airports';
+import { type AirspaceResolver } from '@squawk/airspace';
+import { type AirwayResolver } from '@squawk/airways';
+import { type FixResolver } from '@squawk/fixes';
+import { type NavaidResolver } from '@squawk/navaids';
+import { type ProcedureResolver } from '@squawk/procedures';
+import { type IcaoRegistry } from '@squawk/icao-registry';
+/** Eagerly-built airport resolver backed by the US NASR snapshot. */
+export declare const airportResolver: AirportResolver;
+/** Eagerly-built airspace resolver backed by the US NASR airspace GeoJSON snapshot. */
+export declare const airspaceResolver: AirspaceResolver;
+/** Eagerly-built airway resolver backed by the US NASR snapshot. */
+export declare const airwayResolver: AirwayResolver;
+/** Eagerly-built fix resolver backed by the US NASR snapshot. */
+export declare const fixResolver: FixResolver;
+/** Eagerly-built navaid resolver backed by the US NASR snapshot. */
+export declare const navaidResolver: NavaidResolver;
+/** Eagerly-built procedure resolver backed by the US NASR snapshot. */
+export declare const procedureResolver: ProcedureResolver;
+/**
+ * Returns the shared {@link IcaoRegistry} instance, decompressing and indexing
+ * the bundled FAA aircraft registration snapshot on the first call. Subsequent
+ * calls reuse the cached instance.
+ *
+ * The registry is initialized lazily because the underlying bundled data
+ * package is the largest snapshot in the suite (roughly 40 MB raw). Sessions
+ * that never look up an aircraft by ICAO hex avoid the cost entirely.
+ *
+ * @returns The shared registry instance.
+ */
+export declare function getIcaoRegistry(): Promise<IcaoRegistry>;
+/**
+ * Reports whether the lazily-loaded ICAO aircraft registry has been
+ * initialized in this process.
+ *
+ * @returns `true` once {@link getIcaoRegistry} has resolved at least once.
+ */
+export declare function isIcaoRegistryLoaded(): boolean;
+/**
+ * Returns the cached metadata for the loaded ICAO registry, or `undefined`
+ * when the registry has not been initialized yet. Does not trigger a load.
+ *
+ * @returns The registry metadata if loaded, otherwise `undefined`.
+ */
+export declare function getIcaoRegistryMetadata(): {
+    generatedAt: string;
+    recordCount: number;
+} | undefined;
+//# sourceMappingURL=resolvers.d.ts.map

package/dist/resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE9E,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,eAE5B,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAE,gBAE7B,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,cAE3B,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,WAAW,EAAE,WAAiE,CAAC;AAE5F,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,cAE3B,CAAC;AAEH,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,EAAE,iBAE9B,CAAC;AAYH;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAU7D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IACnC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5C,SAAS,CAEZ"}

package/dist/resolvers.js

@@ -0,0 +1,94 @@
+/**
+ * @packageDocumentation
+ * Shared resolver instances used across the squawk MCP tool modules. Each
+ * resolver is constructed once at module load time so the bundled FAA data
+ * snapshots are decoded and indexed exactly once per server process.
+ *
+ * The ICAO registry is the only resolver that loads lazily: its bundled data
+ * package decompresses ~40 MB of records on import, which is wasted work for
+ * sessions that never call the tail-number lookup. The registry is built on
+ * the first {@link getIcaoRegistry} call and cached for subsequent calls.
+ */
+import { usBundledAirports } from '@squawk/airport-data';
+import { usBundledAirspace } from '@squawk/airspace-data';
+import { usBundledAirways } from '@squawk/airway-data';
+import { usBundledFixes } from '@squawk/fix-data';
+import { usBundledNavaids } from '@squawk/navaid-data';
+import { usBundledProcedures } from '@squawk/procedure-data';
+import { createAirportResolver } from '@squawk/airports';
+import { createAirspaceResolver } from '@squawk/airspace';
+import { createAirwayResolver } from '@squawk/airways';
+import { createFixResolver } from '@squawk/fixes';
+import { createNavaidResolver } from '@squawk/navaids';
+import { createProcedureResolver } from '@squawk/procedures';
+import { createIcaoRegistry } from '@squawk/icao-registry';
+/** Eagerly-built airport resolver backed by the US NASR snapshot. */
+export const airportResolver = createAirportResolver({
+    data: usBundledAirports.records,
+});
+/** Eagerly-built airspace resolver backed by the US NASR airspace GeoJSON snapshot. */
+export const airspaceResolver = createAirspaceResolver({
+    data: usBundledAirspace,
+});
+/** Eagerly-built airway resolver backed by the US NASR snapshot. */
+export const airwayResolver = createAirwayResolver({
+    data: usBundledAirways.records,
+});
+/** Eagerly-built fix resolver backed by the US NASR snapshot. */
+export const fixResolver = createFixResolver({ data: usBundledFixes.records });
+/** Eagerly-built navaid resolver backed by the US NASR snapshot. */
+export const navaidResolver = createNavaidResolver({
+    data: usBundledNavaids.records,
+});
+/** Eagerly-built procedure resolver backed by the US NASR snapshot. */
+export const procedureResolver = createProcedureResolver({
+    data: usBundledProcedures.records,
+});
+/** Cached ICAO registry instance, populated on the first {@link getIcaoRegistry} call. */
+let icaoRegistryInstance;
+/**
+ * Cached metadata captured the first time the registry is loaded. Held
+ * separately from the registry instance so {@link getIcaoRegistryMetadata}
+ * can return it without forcing another import.
+ */
+let icaoRegistryMetadata;
+/**
+ * Returns the shared {@link IcaoRegistry} instance, decompressing and indexing
+ * the bundled FAA aircraft registration snapshot on the first call. Subsequent
+ * calls reuse the cached instance.
+ *
+ * The registry is initialized lazily because the underlying bundled data
+ * package is the largest snapshot in the suite (roughly 40 MB raw). Sessions
+ * that never look up an aircraft by ICAO hex avoid the cost entirely.
+ *
+ * @returns The shared registry instance.
+ */
+export async function getIcaoRegistry() {
+    if (icaoRegistryInstance === undefined) {
+        const { usBundledRegistry } = await import('@squawk/icao-registry-data');
+        icaoRegistryInstance = createIcaoRegistry({ data: usBundledRegistry.records });
+        icaoRegistryMetadata = {
+            generatedAt: usBundledRegistry.properties.generatedAt,
+            recordCount: usBundledRegistry.properties.recordCount,
+        };
+    }
+    return icaoRegistryInstance;
+}
+/**
+ * Reports whether the lazily-loaded ICAO aircraft registry has been
+ * initialized in this process.
+ *
+ * @returns `true` once {@link getIcaoRegistry} has resolved at least once.
+ */
+export function isIcaoRegistryLoaded() {
+    return icaoRegistryInstance !== undefined;
+}
+/**
+ * Returns the cached metadata for the loaded ICAO registry, or `undefined`
+ * when the registry has not been initialized yet. Does not trigger a load.
+ *
+ * @returns The registry metadata if loaded, otherwise `undefined`.
+ */
+export function getIcaoRegistryMetadata() {
+    return icaoRegistryMetadata;
+}

package/dist/server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @packageDocumentation
+ * Server factory for @squawk/mcp. Assembles an {@link McpServer} preloaded
+ * with every squawk aviation tool module.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Number of tool modules registered by {@link createSquawkMcpServer}. Exposed
+ * so the stdio entrypoint can include the count in its startup diagnostic
+ * without re-counting at runtime.
+ */
+export declare const TOOL_MODULE_COUNT: number;
+/**
+ * Package name as published to npm. Convenient for diagnostic logs that want
+ * to identify the running server without re-reading `package.json`.
+ */
+export declare const PACKAGE_NAME: string;
+/**
+ * Package version pulled from `package.json` at module load. Mirrored as the
+ * server's `version` field and reused by the stdio entrypoint diagnostic.
+ */
+export declare const PACKAGE_VERSION: string;
+/**
+ * Creates an MCP server preloaded with every squawk aviation tool module.
+ *
+ * Tool registration triggers eager construction of the shared resolver
+ * singletons in `./resolvers.js` for every domain except the ICAO aircraft
+ * registry, which loads on first lookup. Live weather fetch tools issue
+ * outbound HTTPS requests to the Aviation Weather Center text API only when
+ * invoked.
+ *
+ * ```typescript
+ * import { createSquawkMcpServer } from '@squawk/mcp';
+ * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+ *
+ * const server = createSquawkMcpServer();
+ * await server.connect(new StdioServerTransport());
+ * ```
+ *
+ * @returns A fully configured MCP server instance. Connect it to a transport
+ *          (typically `StdioServerTransport` for CLI use) via
+ *          `server.connect(transport)` to begin handling protocol messages.
+ */
+export declare function createSquawkMcpServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6CpE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAsC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAyB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAA4B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAWjD"}