@squawk/mcp 0.8.13 → 0.9.0

package/README.md

@@ -98,7 +98,7 @@ version explicitly in the client config:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "@squawk/mcp@0.8.13"]
+      "args": ["-y", "@squawk/mcp@0.9.0"]
     }
   }
 }
@@ -130,6 +130,50 @@ again, or fall back to a pinned version. The host process itself also has to res
 update to take effect, since each MCP server is a long-running stdio subprocess that loads its
 code once at spawn time.
 
+### Enabling the aircraft registry (optional peer)
+
+`@squawk/icao-registry-data` is the largest snapshot in the suite (roughly 8 MB on disk after
+gzip). Most sessions never need a tail-number lookup, so the package is declared as an optional
+**peer dependency** of `@squawk/mcp` rather than a required dep - npm 7+ does not auto-install
+optional peers, which keeps the default `npx @squawk/mcp` install lean.
+
+When the data package is not installed, `lookup_aircraft_by_icao_hex` is still listed in the tool
+catalog. The first invocation returns a structured `isError: true` result whose
+`structuredContent.missingDataPackage.installCommand` field names the exact command to run; the
+rest of the server keeps working normally. If you do not need aircraft lookups, no further action
+is required.
+
+To enable lookups, install the data package alongside `@squawk/mcp`. Through `npx` the cleanest
+option is the `-p` flag, which adds extra packages to the temporary install npx builds:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "npx",
+      "args": ["-y", "-p", "@squawk/icao-registry-data", "@squawk/mcp"]
+    }
+  }
+}
+```
+
+Pinning works the same way:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "npx",
+      "args": ["-y", "-p", "@squawk/icao-registry-data@0.8.3", "@squawk/mcp@0.9.0"]
+    }
+  }
+}
+```
+
+For non-`npx` setups (a local install, a global install, a Docker image), add
+`@squawk/icao-registry-data` to the same dependency manifest that pulls in `@squawk/mcp` and the
+runtime will resolve it through ordinary Node module resolution.
+
 ### Pinning a specific Node binary
 
 `npx` resolves `node` through whatever PATH the host launches with. On macOS, GUI apps often
@@ -262,8 +306,11 @@ Covers SIDs, STARs, and Instrument Approach Procedures (IAPs) from FAA CIFP.
 | ----------------------------- | ------------------------------------------------------------- |
 | `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.
+`@squawk/icao-registry-data` is an optional peer dependency. Default installs of `@squawk/mcp` do
+not include it; the tool reports a structured "data not installed" error with the exact install
+command until the peer is added. See [Enabling the aircraft registry](#enabling-the-aircraft-registry-optional-peer)
+for how to add it. Once present, the registry (~40 MB raw) is decompressed lazily on the first
+lookup so sessions that never need it do not pay the cost.
 
 ### Weather (`@squawk/weather` + `@squawk/weather/fetch`)
 
@@ -351,5 +398,6 @@ left to the model itself.
   override above). They are the only tools that touch the network at invocation time; everything
   else operates against bundled snapshots in memory.
 - The bundled 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.
+  hundred milliseconds of startup time. The aircraft registration snapshot (the largest, and an
+  optional peer dependency) is decompressed lazily on the first `lookup_aircraft_by_icao_hex` call,
+  if the package is installed.

package/dist/resolvers.d.ts

@@ -4,10 +4,13 @@
  * 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.
+ * The ICAO registry is the only resolver that loads lazily, and its data
+ * package (`@squawk/icao-registry-data`) is declared as an optional peer
+ * dependency rather than a required dep. The registry is built on the first
+ * {@link getIcaoRegistry} call (decompressing ~40 MB on first access) and
+ * cached for subsequent calls. When the peer is not installed, the import
+ * throws `ERR_MODULE_NOT_FOUND` and {@link getIcaoRegistry} surfaces a
+ * {@link MissingDataPackageError} for the tool handler to format.
  */
 import { type AirportResolver } from '@squawk/airports';
 import { type AirspaceResolver } from '@squawk/airspace';
@@ -28,18 +31,57 @@ export declare const fixResolver: FixResolver;
 export declare const navaidResolver: NavaidResolver;
 /** Eagerly-built procedure resolver backed by the US NASR snapshot. */
 export declare const procedureResolver: ProcedureResolver;
+/**
+ * Error thrown when a tool tries to load an optional data package peer that
+ * has not been installed alongside `@squawk/mcp`. Tool handlers catch this
+ * and surface the install command to the MCP client so the user can resolve
+ * the missing dependency without inspecting the server logs.
+ */
+export declare class MissingDataPackageError extends Error {
+    /** Short dataset name shown to users (e.g. `"icao-registry"`). */
+    readonly datasetName: string;
+    /** npm package name the user must install (e.g. `"@squawk/icao-registry-data"`). */
+    readonly packageName: string;
+    /** Suggested install command, e.g. `"npm install @squawk/icao-registry-data"`. */
+    readonly installCommand: string;
+    /**
+     * Constructs a new error describing a missing optional data peer.
+     *
+     * @param datasetName - Short dataset name for the user-facing message.
+     * @param packageName - npm package name that needs to be installed.
+     */
+    constructor(datasetName: string, packageName: string);
+}
+/** Loader signature for the optional `@squawk/icao-registry-data` peer. */
+type IcaoRegistryDataLoader = () => Promise<typeof import('@squawk/icao-registry-data')>;
 /**
  * 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.
+ * The registry is initialized lazily because the underlying data package is
+ * the largest snapshot in the suite (roughly 40 MB raw) and is declared as an
+ * optional peer dependency rather than a required dep. Sessions that never
+ * look up an aircraft by ICAO hex avoid the cost entirely, and consumers who
+ * never install the peer see only the structured missing-package error
+ * surfaced by the tool handler.
  *
  * @returns The shared registry instance.
+ * @throws {MissingDataPackageError} when `@squawk/icao-registry-data` is not
+ *         installed alongside `@squawk/mcp`.
  */
 export declare function getIcaoRegistry(): Promise<IcaoRegistry>;
+/**
+ * @internal
+ *
+ * Test-only seam for swapping the optional data package loader. Production
+ * code must not call this. Pass `undefined` to restore the default loader
+ * and clear all cached state (instance, metadata, and the missing-peer
+ * sticky flag) so subsequent tests start from a clean slate.
+ *
+ * @param loader - Replacement loader, or `undefined` to reset.
+ */
+export declare function __setIcaoRegistryDataLoaderForTest(loader: IcaoRegistryDataLoader | undefined): void;
 /**
  * Reports whether the lazily-loaded ICAO aircraft registry has been
  * initialized in this process.
@@ -57,4 +99,5 @@ export declare function getIcaoRegistryMetadata(): {
     generatedAt: string;
     recordCount: number;
 } | undefined;
+export {};
 //# sourceMappingURL=resolvers.d.ts.map

package/dist/resolvers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAErF,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"}
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAErF,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;AAEH;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQrD;AAoBD,2EAA2E;AAC3E,KAAK,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,4BAA4B,CAAC,CAAC,CAAC;AA2BzF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAuB7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,sBAAsB,GAAG,SAAS,GACzC,IAAI,CAKN;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

@@ -4,10 +4,13 @@
  * 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.
+ * The ICAO registry is the only resolver that loads lazily, and its data
+ * package (`@squawk/icao-registry-data`) is declared as an optional peer
+ * dependency rather than a required dep. The registry is built on the first
+ * {@link getIcaoRegistry} call (decompressing ~40 MB on first access) and
+ * cached for subsequent calls. When the peer is not installed, the import
+ * throws `ERR_MODULE_NOT_FOUND` and {@link getIcaoRegistry} surfaces a
+ * {@link MissingDataPackageError} for the tool handler to format.
  */
 import { usBundledAirports } from '@squawk/airport-data';
 import { createAirportResolver } from '@squawk/airports';
@@ -44,6 +47,34 @@ export const navaidResolver = createNavaidResolver({
 export const procedureResolver = createProcedureResolver({
     data: usBundledProcedures.records,
 });
+/**
+ * Error thrown when a tool tries to load an optional data package peer that
+ * has not been installed alongside `@squawk/mcp`. Tool handlers catch this
+ * and surface the install command to the MCP client so the user can resolve
+ * the missing dependency without inspecting the server logs.
+ */
+export class MissingDataPackageError extends Error {
+    /** Short dataset name shown to users (e.g. `"icao-registry"`). */
+    datasetName;
+    /** npm package name the user must install (e.g. `"@squawk/icao-registry-data"`). */
+    packageName;
+    /** Suggested install command, e.g. `"npm install @squawk/icao-registry-data"`. */
+    installCommand;
+    /**
+     * Constructs a new error describing a missing optional data peer.
+     *
+     * @param datasetName - Short dataset name for the user-facing message.
+     * @param packageName - npm package name that needs to be installed.
+     */
+    constructor(datasetName, packageName) {
+        const installCommand = `npm install ${packageName}`;
+        super(`${datasetName} data is not installed. Run: ${installCommand}`);
+        this.name = 'MissingDataPackageError';
+        this.datasetName = datasetName;
+        this.packageName = packageName;
+        this.installCommand = installCommand;
+    }
+}
 /** Cached ICAO registry instance, populated on the first {@link getIcaoRegistry} call. */
 let icaoRegistryInstance;
 /**
@@ -52,20 +83,67 @@ let icaoRegistryInstance;
  * can return it without forcing another import.
  */
 let icaoRegistryMetadata;
+/**
+ * Sticky flag set once the optional `@squawk/icao-registry-data` peer is
+ * confirmed missing. Subsequent {@link getIcaoRegistry} calls short-circuit
+ * to a {@link MissingDataPackageError} without retrying the import; running
+ * `npm install` while the server is live is not a supported workflow.
+ */
+let icaoRegistryMissing = false;
+/** Default loader: a dynamic import of the actual peer package. */
+const defaultIcaoRegistryDataLoader = () => import('@squawk/icao-registry-data');
+/**
+ * Active loader used by {@link getIcaoRegistry}. Replaceable in tests via
+ * {@link __setIcaoRegistryDataLoaderForTest} so the missing-peer code path
+ * can be exercised without uninstalling the workspace-symlinked package.
+ */
+let icaoRegistryDataLoader = defaultIcaoRegistryDataLoader;
+/**
+ * Returns `true` when the given thrown value is Node's
+ * `ERR_MODULE_NOT_FOUND`, which the ESM loader raises both when the package
+ * specifier cannot be resolved and when a transitive resolution within the
+ * package fails. The latter is rare but should still surface as the missing-
+ * peer error so the user gets a single actionable message.
+ *
+ * @param err - The value caught from a dynamic import.
+ * @returns `true` when the value is an `ERR_MODULE_NOT_FOUND` error.
+ */
+function isModuleNotFoundError(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ERR_MODULE_NOT_FOUND';
+}
 /**
  * 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.
+ * The registry is initialized lazily because the underlying data package is
+ * the largest snapshot in the suite (roughly 40 MB raw) and is declared as an
+ * optional peer dependency rather than a required dep. Sessions that never
+ * look up an aircraft by ICAO hex avoid the cost entirely, and consumers who
+ * never install the peer see only the structured missing-package error
+ * surfaced by the tool handler.
  *
  * @returns The shared registry instance.
+ * @throws {MissingDataPackageError} when `@squawk/icao-registry-data` is not
+ *         installed alongside `@squawk/mcp`.
  */
 export async function getIcaoRegistry() {
+    if (icaoRegistryMissing) {
+        throw new MissingDataPackageError('icao-registry', '@squawk/icao-registry-data');
+    }
     if (icaoRegistryInstance === undefined) {
-        const { usBundledRegistry } = await import('@squawk/icao-registry-data');
+        let registryDataModule;
+        try {
+            registryDataModule = await icaoRegistryDataLoader();
+        }
+        catch (err) {
+            if (isModuleNotFoundError(err)) {
+                icaoRegistryMissing = true;
+                throw new MissingDataPackageError('icao-registry', '@squawk/icao-registry-data');
+            }
+            throw err;
+        }
+        const { usBundledRegistry } = registryDataModule;
         icaoRegistryInstance = createIcaoRegistry({ data: usBundledRegistry.records });
         icaoRegistryMetadata = {
             generatedAt: usBundledRegistry.properties.generatedAt,
@@ -74,6 +152,22 @@ export async function getIcaoRegistry() {
     }
     return icaoRegistryInstance;
 }
+/**
+ * @internal
+ *
+ * Test-only seam for swapping the optional data package loader. Production
+ * code must not call this. Pass `undefined` to restore the default loader
+ * and clear all cached state (instance, metadata, and the missing-peer
+ * sticky flag) so subsequent tests start from a clean slate.
+ *
+ * @param loader - Replacement loader, or `undefined` to reset.
+ */
+export function __setIcaoRegistryDataLoaderForTest(loader) {
+    icaoRegistryDataLoader = loader ?? defaultIcaoRegistryDataLoader;
+    icaoRegistryInstance = undefined;
+    icaoRegistryMetadata = undefined;
+    icaoRegistryMissing = false;
+}
 /**
  * Reports whether the lazily-loaded ICAO aircraft registry has been
  * initialized in this process.

package/dist/tools/icao-registry.d.ts

@@ -4,10 +4,12 @@
  * lookup, backed by the FAA ReleasableAircraft snapshot in
  * `@squawk/icao-registry-data`.
  *
- * Unlike the other domain modules, the registry data is loaded lazily on the
- * first tool invocation through {@link getIcaoRegistry}. The bundled data
- * package decompresses ~40 MB of records on import, which is wasteful for
- * sessions that never look up an aircraft.
+ * The registry data package is an **optional peer dependency** of
+ * `@squawk/mcp`. The tool is always registered with the MCP server so it
+ * appears in the catalog, but the data is loaded lazily on the first tool
+ * invocation through {@link getIcaoRegistry}. When the peer is not installed
+ * the tool returns a structured `isError: true` result naming the package and
+ * the install command, rather than crashing the server.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**

package/dist/tools/icao-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"icao-registry.d.ts","sourceRoot":"","sources":["../../src/tools/icao-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6BjE"}
+{"version":3,"file":"icao-registry.d.ts","sourceRoot":"","sources":["../../src/tools/icao-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+CjE"}

package/dist/tools/icao-registry.js

@@ -4,13 +4,15 @@
  * lookup, backed by the FAA ReleasableAircraft snapshot in
  * `@squawk/icao-registry-data`.
  *
- * Unlike the other domain modules, the registry data is loaded lazily on the
- * first tool invocation through {@link getIcaoRegistry}. The bundled data
- * package decompresses ~40 MB of records on import, which is wasteful for
- * sessions that never look up an aircraft.
+ * The registry data package is an **optional peer dependency** of
+ * `@squawk/mcp`. The tool is always registered with the MCP server so it
+ * appears in the catalog, but the data is loaded lazily on the first tool
+ * invocation through {@link getIcaoRegistry}. When the peer is not installed
+ * the tool returns a structured `isError: true` result naming the package and
+ * the install command, rather than crashing the server.
  */
 import { z } from 'zod';
-import { getIcaoRegistry } from '../resolvers.js';
+import { MissingDataPackageError, getIcaoRegistry } from '../resolvers.js';
 /** Pattern matching a valid 24-bit ICAO hex address (1-6 hex digits). */
 const ICAO_HEX_PATTERN = /^[0-9A-Fa-f]{1,6}$/;
 /**
@@ -21,7 +23,7 @@ const ICAO_HEX_PATTERN = /^[0-9A-Fa-f]{1,6}$/;
 export function registerIcaoRegistryTools(server) {
     server.registerTool('lookup_aircraft_by_icao_hex', {
         title: 'Look up an aircraft by ICAO hex address',
-        description: 'Looks up a US-registered aircraft by its 24-bit ICAO hex address (the same identifier transmitted by Mode S and ADS-B). Returns registration, make, model, operator, aircraft type, engine type, and year of manufacture when known. Returns null when no match is found. The first call may take a few hundred milliseconds while the bundled FAA registration snapshot decompresses.',
+        description: 'Looks up a US-registered aircraft by its 24-bit ICAO hex address (the same identifier transmitted by Mode S and ADS-B). Returns registration, make, model, operator, aircraft type, engine type, and year of manufacture when known. Returns null when no match is found. Backed by `@squawk/icao-registry-data`, which is an optional peer dependency of `@squawk/mcp`; if the package is not installed the tool returns an actionable error including the install command. The first successful call may take a few hundred milliseconds while the bundled FAA registration snapshot decompresses.',
         inputSchema: {
             icaoHex: z
                 .string()
@@ -29,17 +31,36 @@ export function registerIcaoRegistryTools(server) {
                 .describe('24-bit ICAO hex address (1-6 hex digits, case-insensitive).'),
         },
     }, async ({ icaoHex }) => {
-        const registry = await getIcaoRegistry();
-        const aircraft = registry.lookup(icaoHex);
-        if (aircraft === undefined) {
+        try {
+            const registry = await getIcaoRegistry();
+            const aircraft = registry.lookup(icaoHex);
+            if (aircraft === undefined) {
+                return {
+                    content: [{ type: 'text', text: `No aircraft found for ICAO hex "${icaoHex}".` }],
+                    structuredContent: { aircraft: null },
+                };
+            }
             return {
-                content: [{ type: 'text', text: `No aircraft found for ICAO hex "${icaoHex}".` }],
-                structuredContent: { aircraft: null },
+                content: [{ type: 'text', text: JSON.stringify(aircraft, null, 2) }],
+                structuredContent: { aircraft },
             };
         }
-        return {
-            content: [{ type: 'text', text: JSON.stringify(aircraft, null, 2) }],
-            structuredContent: { aircraft },
-        };
+        catch (err) {
+            if (err instanceof MissingDataPackageError) {
+                return {
+                    content: [{ type: 'text', text: err.message }],
+                    structuredContent: {
+                        aircraft: null,
+                        missingDataPackage: {
+                            datasetName: err.datasetName,
+                            packageName: err.packageName,
+                            installCommand: err.installCommand,
+                        },
+                    },
+                    isError: true,
+                };
+            }
+            throw err;
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/mcp",
-  "version": "0.8.13",
+  "version": "0.9.0",
   "type": "module",
   "description": "Model Context Protocol server exposing squawk's aviation libraries as tools for LLM clients",
   "author": "Neil Cochran",
@@ -51,7 +51,6 @@
     "@squawk/flightplan": "^0.5.1",
     "@squawk/geo": "^0.4.3",
     "@squawk/icao-registry": "^0.5.1",
-    "@squawk/icao-registry-data": "^0.8.3",
     "@squawk/navaid-data": "^0.6.3",
     "@squawk/navaids": "^0.4.1",
     "@squawk/notams": "^0.3.5",
@@ -61,7 +60,16 @@
     "@squawk/weather": "^0.5.5",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "@squawk/icao-registry-data": "^0.8.3"
+  },
+  "peerDependenciesMeta": {
+    "@squawk/icao-registry-data": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@squawk/icao-registry-data": "^0.8.3",
     "@types/node": "^25.6.0"
   },
   "keywords": [