@squawk/mcp 0.11.0 → 0.12.0

package/README.md

@@ -98,7 +98,7 @@ version explicitly in the client config:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "@squawk/mcp@0.11.0"]
+      "args": ["-y", "@squawk/mcp@0.12.0"]
     }
   }
 }
@@ -164,7 +164,7 @@ Pinning works the same way:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "-p", "@squawk/icao-registry-data@0.8.10", "@squawk/mcp@0.11.0"]
+      "args": ["-y", "-p", "@squawk/icao-registry-data@0.8.12", "@squawk/mcp@0.12.0"]
     }
   }
 }
@@ -193,8 +193,8 @@ the absolute path to a modern node + the absolute path to the installed `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.
+The server logs `[squawk-mcp] node <version> on <platform>/<arch>` and how many tool groups
+registered to stderr on every startup so you can verify the right runtime is being used.
 
 ### Example prompts
 
@@ -226,6 +226,17 @@ const server = createSquawkMcpServer();
 await server.connect(new StdioServerTransport());
 ```
 
+Pass `toolGroups` to register part of the catalog. An explicit list takes precedence over
+the environment variables described under [Configuration](#configuration); omit the option
+entirely to honor them. `TOOL_GROUP_NAMES` holds every valid group name, and an unknown one
+throws a `ToolGroupConfigError`.
+
+```typescript
+import { createSquawkMcpServer, TOOL_GROUP_NAMES } from '@squawk/mcp';
+
+const server = createSquawkMcpServer({ toolGroups: ['airports', 'navaids', 'geo'] });
+```
+
 ## Tool catalog
 
 Tools are grouped by domain. Every tool returns both a human-readable text block and a structured
@@ -390,9 +401,74 @@ left to the model itself.
 
 ## 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. |
+| Environment variable       | Effect                                                                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SQUAWK_MCP_TOOLS`         | Register only the named tool groups. See [Choosing which tools to register](#choosing-which-tools-to-register).                                                          |
+| `SQUAWK_MCP_DISABLE_TOOLS` | Register every tool group except the named ones. Mutually exclusive with `SQUAWK_MCP_TOOLS`.                                                                             |
+| `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. |
+
+### Choosing which tools to register
+
+The full catalog is 79 tools, which costs roughly 18k tokens of context in every session
+before you ask anything. If you only reach for part of it, register only that part and the
+rest never reaches your client.
+
+Each tool group is one row below. Set `SQUAWK_MCP_TOOLS` to the groups you want, or
+`SQUAWK_MCP_DISABLE_TOOLS` to the groups you do not. With neither set, every group is
+registered.
+
+| Group           | Tools | ~Tokens |
+| --------------- | ----: | ------: |
+| `geo`           |     5 |   1,100 |
+| `flight-math`   |    24 |   5,300 |
+| `airports`      |     4 |     900 |
+| `airspace`      |     5 |   1,700 |
+| `navaids`       |     5 |   1,300 |
+| `fixes`         |     4 |   1,000 |
+| `airways`       |     4 |     800 |
+| `procedures`    |     8 |   1,900 |
+| `icao-registry` |     1 |     250 |
+| `weather`       |    12 |   2,100 |
+| `notams`        |     2 |     300 |
+| `flightplan`    |     4 |   1,400 |
+| `datasets`      |     1 |     180 |
+
+A VFR pilot who wants airport, navaid, and fix lookups plus a distance calculator:
+
+```json
+{
+  "mcpServers": {
+    "squawk": {
+      "command": "npx",
+      "args": ["-y", "@squawk/mcp"],
+      "env": { "SQUAWK_MCP_TOOLS": "airports,navaids,fixes,geo" }
+    }
+  }
+}
+```
+
+That registers 18 tools for roughly 4.3k tokens, down from 79 and 18k. Dropping just
+`flight-math` and `weather` - the two largest groups - takes the catalog to 43 tools and
+roughly 11k tokens while leaving every lookup tool in place.
+
+Names are case-insensitive and whitespace around them is ignored. The server refuses to
+start, with an explanation on stderr, when a group name is unrecognized, when both
+variables are set, or when the result would leave it with no tools at all. Check your
+host's MCP log if the server fails to come up after a config change; the startup
+diagnostic also reports how many groups registered and names the ones that did not.
+
+Two things worth knowing before you trim:
+
+- **`datasets` is a group like any other.** It holds `get_dataset_status`, the tool that
+  reports which NASR and CIFP cycles the running server is serving. An allowlist that
+  leaves it out means you can no longer ask how current the data is, so include it unless
+  you are sure you do not want it. It is the cheapest group in the catalog.
+- **Groups gate the catalog, not the data.** The bundled snapshots are loaded and indexed
+  at startup no matter which groups you register, so trimming the catalog does not reduce
+  the server's startup time or memory use. It also means a group you kept keeps working
+  even when it reads data belonging to a group you dropped - `flightplan` still resolves
+  airports and navaids in a route string with `airports` and `navaids` disabled, because
+  you disabled those tools, not that data.
 
 ## Notes
 
@@ -403,7 +479,7 @@ left to the model itself.
 - 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 snapshots are decompressed and indexed once when the server starts. Expect a few
-  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.
+- The bundled snapshots are decompressed and indexed once when the server starts, which takes on
+  the order of a second and is unaffected by which tool groups you register. 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/bin.js

@@ -8,21 +8,31 @@
  * 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';
+import { createSquawkMcpServer, PACKAGE_NAME, PACKAGE_VERSION } from './server.js';
+import { TOOL_GROUP_NAMES, resolveToolGroupsFromEnv } from './tool-groups.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.
+ * package version, which tool groups ended up registered, 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.
+ * diagnose from the host's MCP log without bisecting tool failures. Naming the
+ * disabled groups does the same for a mistyped tool-group variable, which
+ * otherwise shows up only as tools the model never calls.
+ *
+ * @param enabledGroups - Tool groups the server is about to register.
  */
-function logRuntimeDiagnostics() {
+function logRuntimeDiagnostics(enabledGroups) {
     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`);
+    console.error(`[squawk-mcp] ${PACKAGE_NAME} v${PACKAGE_VERSION}, ` +
+        `${enabledGroups.length}/${TOOL_GROUP_NAMES.length} tool groups registered`);
+    const disabled = TOOL_GROUP_NAMES.filter((name) => !enabledGroups.includes(name));
+    if (disabled.length > 0) {
+        console.error(`[squawk-mcp] disabled tool groups: ${disabled.join(', ')}`);
+    }
     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 ' +
@@ -30,12 +40,19 @@ function logRuntimeDiagnostics() {
     }
 }
 async function main() {
-    logRuntimeDiagnostics();
-    const server = createSquawkMcpServer();
+    const resolution = resolveToolGroupsFromEnv(process.env);
+    if (!resolution.ok) {
+        console.error(`[squawk-mcp] configuration error: ${resolution.error}`);
+        // eslint-disable-next-line n/no-process-exit -- serving a catalog the user did not ask for is worse than refusing to start; the host surfaces this line in its MCP log.
+        process.exit(1);
+    }
+    logRuntimeDiagnostics(resolution.toolGroups);
+    const server = createSquawkMcpServer({ toolGroups: resolution.toolGroups });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 main().catch((err) => {
     console.error('[squawk-mcp] fatal error:', err);
+    // eslint-disable-next-line n/no-process-exit -- a failed stdio connect can leave the transport holding stdin; exiting beats hanging the host that spawned us.
     process.exit(1);
 });

package/dist/index.d.ts

@@ -19,6 +19,15 @@
  * const server = createSquawkMcpServer();
  * await server.connect(new StdioServerTransport());
  * ```
+ *
+ * Pass `toolGroups` to register only part of the catalog:
+ *
+ * ```typescript
+ * const server = createSquawkMcpServer({ toolGroups: ['airports', 'navaids', 'geo'] });
+ * ```
  */
 export { createSquawkMcpServer } from './server.js';
+export { TOOL_GROUP_NAMES, ToolGroupConfigError } from './tool-groups.js';
+export type { CreateSquawkMcpServerOptions } from './server.js';
+export type { ToolGroupName } from './tool-groups.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,YAAY,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -19,5 +19,12 @@
  * const server = createSquawkMcpServer();
  * await server.connect(new StdioServerTransport());
  * ```
+ *
+ * Pass `toolGroups` to register only part of the catalog:
+ *
+ * ```typescript
+ * const server = createSquawkMcpServer({ toolGroups: ['airports', 'navaids', 'geo'] });
+ * ```
  */
 export { createSquawkMcpServer } from './server.js';
+export { TOOL_GROUP_NAMES, ToolGroupConfigError } from './tool-groups.js';

package/dist/resolvers.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,IACrC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAEzD"}

package/dist/server.d.ts

@@ -1,15 +1,22 @@
 /**
  * @packageDocumentation
- * Server factory for @squawk/mcp. Assembles an {@link McpServer} preloaded
- * with every squawk aviation tool module.
+ * Server factory for @squawk/mcp. Assembles an {@link McpServer} carrying the
+ * squawk aviation tool modules the caller asked for, defaulting to all of them.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolGroupName } from './tool-groups.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.
+ * Options accepted by {@link createSquawkMcpServer}.
  */
-export declare const TOOL_MODULE_COUNT: number;
+export interface CreateSquawkMcpServerOptions {
+    /**
+     * Tool groups to register. Omit to resolve the set from the
+     * `SQUAWK_MCP_TOOLS` / `SQUAWK_MCP_DISABLE_TOOLS` environment variables,
+     * which default to every group. Order is ignored; groups always register in
+     * `TOOL_GROUP_NAMES` order.
+     */
+    readonly toolGroups?: readonly ToolGroupName[];
+}
 /**
  * Package name as published to npm. Convenient for diagnostic logs that want
  * to identify the running server without re-reading `package.json`.
@@ -21,7 +28,14 @@ export declare const PACKAGE_NAME: string;
  */
 export declare const PACKAGE_VERSION: string;
 /**
- * Creates an MCP server preloaded with every squawk aviation tool module.
+ * Creates an MCP server carrying the requested squawk aviation tool groups,
+ * defaulting to all of them.
+ *
+ * Disabling a group keeps its tools out of the catalog the LLM client sees,
+ * which is the point: the full catalog is roughly 18k tokens of context on
+ * every session. It does not reduce the server's startup time or memory
+ * footprint - the bundled snapshots are imported and indexed at module load
+ * regardless of which groups register.
  *
  * Tool registration triggers eager construction of the shared resolver
  * singletons in `./resolvers.js` for every domain except the ICAO aircraft
@@ -33,13 +47,17 @@ export declare const PACKAGE_VERSION: string;
  * import { createSquawkMcpServer } from '@squawk/mcp';
  * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
  *
- * const server = createSquawkMcpServer();
+ * const server = createSquawkMcpServer({ toolGroups: ['airports', 'geo'] });
  * await server.connect(new StdioServerTransport());
  * ```
  *
+ * @param options - Server options. Omit to honor the environment variables.
  * @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.
+ * @throws {ToolGroupConfigError} when `options.toolGroups` names an unknown
+ *         group or is empty, or when the environment variables cannot be
+ *         honored (both set at once, unknown names, or nothing left enabled).
  */
-export declare function createSquawkMcpServer(): McpServer;
+export declare function createSquawkMcpServer(options?: CreateSquawkMcpServerOptions): McpServer;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2CpE;;;;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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AA0C1B;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAyB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAA4B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,4BAA4B,GAAG,SAAS,CAsBvF"}

package/dist/server.js

@@ -1,12 +1,13 @@
 /**
  * @packageDocumentation
- * Server factory for @squawk/mcp. Assembles an {@link McpServer} preloaded
- * with every squawk aviation tool module.
+ * Server factory for @squawk/mcp. Assembles an {@link McpServer} carrying the
+ * squawk aviation tool modules the caller asked for, defaulting to all of them.
  */
 import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ToolGroupConfigError, normalizeToolGroups, resolveToolGroupsFromEnv, } from './tool-groups.js';
 import { registerAirportTools } from './tools/airports.js';
 import { registerAirspaceTools } from './tools/airspace.js';
 import { registerAirwayTools } from './tools/airways.js';
@@ -23,32 +24,26 @@ import { registerWeatherTools } from './tools/weather.js';
 const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), '../package.json');
 const packageMeta = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 /**
- * Ordered list of tool-module registrars invoked during server construction.
- * Holding them in a single array keeps {@link createSquawkMcpServer} symmetric
- * across modules and lets {@link TOOL_MODULE_COUNT} stay accurate without
- * manual bookkeeping.
+ * Registrar for each toggleable tool group. Keying by {@link ToolGroupName}
+ * makes the mapping exhaustive: adding a name to `TOOL_GROUP_NAMES` without
+ * wiring its registrar here is a compile error, so the group list and the
+ * modules it toggles cannot drift apart.
  */
-const TOOL_MODULE_REGISTRARS = [
-    registerGeoTools,
-    registerFlightMathTools,
-    registerAirportTools,
-    registerAirspaceTools,
-    registerNavaidTools,
-    registerFixTools,
-    registerAirwayTools,
-    registerProcedureTools,
-    registerIcaoRegistryTools,
-    registerWeatherTools,
-    registerNotamTools,
-    registerFlightplanTools,
-    registerDatasetTools,
-];
-/**
- * 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 const TOOL_MODULE_COUNT = TOOL_MODULE_REGISTRARS.length;
+const TOOL_GROUP_REGISTRARS = {
+    geo: registerGeoTools,
+    'flight-math': registerFlightMathTools,
+    airports: registerAirportTools,
+    airspace: registerAirspaceTools,
+    navaids: registerNavaidTools,
+    fixes: registerFixTools,
+    airways: registerAirwayTools,
+    procedures: registerProcedureTools,
+    'icao-registry': registerIcaoRegistryTools,
+    weather: registerWeatherTools,
+    notams: registerNotamTools,
+    flightplan: registerFlightplanTools,
+    datasets: registerDatasetTools,
+};
 /**
  * Package name as published to npm. Convenient for diagnostic logs that want
  * to identify the running server without re-reading `package.json`.
@@ -60,7 +55,14 @@ export const PACKAGE_NAME = packageMeta.name;
  */
 export const PACKAGE_VERSION = packageMeta.version;
 /**
- * Creates an MCP server preloaded with every squawk aviation tool module.
+ * Creates an MCP server carrying the requested squawk aviation tool groups,
+ * defaulting to all of them.
+ *
+ * Disabling a group keeps its tools out of the catalog the LLM client sees,
+ * which is the point: the full catalog is roughly 18k tokens of context on
+ * every session. It does not reduce the server's startup time or memory
+ * footprint - the bundled snapshots are imported and indexed at module load
+ * regardless of which groups register.
  *
  * Tool registration triggers eager construction of the shared resolver
  * singletons in `./resolvers.js` for every domain except the ICAO aircraft
@@ -72,21 +74,36 @@ export const PACKAGE_VERSION = packageMeta.version;
  * import { createSquawkMcpServer } from '@squawk/mcp';
  * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
  *
- * const server = createSquawkMcpServer();
+ * const server = createSquawkMcpServer({ toolGroups: ['airports', 'geo'] });
  * await server.connect(new StdioServerTransport());
  * ```
  *
+ * @param options - Server options. Omit to honor the environment variables.
  * @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.
+ * @throws {ToolGroupConfigError} when `options.toolGroups` names an unknown
+ *         group or is empty, or when the environment variables cannot be
+ *         honored (both set at once, unknown names, or nothing left enabled).
  */
-export function createSquawkMcpServer() {
+export function createSquawkMcpServer(options) {
     const server = new McpServer({
         name: PACKAGE_NAME,
         version: PACKAGE_VERSION,
     });
-    for (const register of TOOL_MODULE_REGISTRARS) {
-        register(server);
+    let enabledGroups;
+    if (options?.toolGroups === undefined) {
+        const resolution = resolveToolGroupsFromEnv(process.env);
+        if (!resolution.ok) {
+            throw new ToolGroupConfigError(resolution.error);
+        }
+        enabledGroups = resolution.toolGroups;
+    }
+    else {
+        enabledGroups = normalizeToolGroups(options.toolGroups);
+    }
+    for (const group of enabledGroups) {
+        TOOL_GROUP_REGISTRARS[group](server);
     }
     return server;
 }

package/dist/tool-groups.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @packageDocumentation
+ * Tool-group identity and configuration parsing for @squawk/mcp. Every domain
+ * module under `src/tools/` is one toggleable group, so a client that only
+ * needs part of the catalog can keep the rest out of its context window.
+ *
+ * This module owns the canonical group-name list and turns the server's
+ * environment variables into the concrete set of groups to register.
+ */
+/**
+ * Every toggleable tool group, in the order they are registered on the
+ * server. Each name matches exactly one domain module filename under
+ * `src/tools/`, so `airports` maps to `src/tools/airports.ts`.
+ */
+export declare const TOOL_GROUP_NAMES: readonly ["geo", "flight-math", "airports", "airspace", "navaids", "fixes", "airways", "procedures", "icao-registry", "weather", "notams", "flightplan", "datasets"];
+/** Name of a single toggleable tool group. */
+export type ToolGroupName = (typeof TOOL_GROUP_NAMES)[number];
+/**
+ * Environment variable naming the only tool groups to register. Acts as an
+ * allowlist: groups absent from the list are not registered, including groups
+ * added by future releases.
+ */
+export declare const TOOL_ALLOWLIST_ENV_VAR = "SQUAWK_MCP_TOOLS";
+/**
+ * Environment variable naming tool groups to skip. Acts as a denylist: every
+ * group not listed is registered, including groups added by future releases.
+ */
+export declare const TOOL_DENYLIST_ENV_VAR = "SQUAWK_MCP_DISABLE_TOOLS";
+/**
+ * Successful resolution of the tool-group configuration.
+ */
+export interface ToolGroupResolutionSuccess {
+    /** Discriminant marking a successful resolution. */
+    readonly ok: true;
+    /** Groups to register, in {@link TOOL_GROUP_NAMES} order. Never empty. */
+    readonly toolGroups: readonly ToolGroupName[];
+}
+/**
+ * Failed resolution of the tool-group configuration, carrying a message ready
+ * to print for the user.
+ */
+export interface ToolGroupResolutionFailure {
+    /** Discriminant marking a failed resolution. */
+    readonly ok: false;
+    /** Human-readable explanation naming the offending value and the fix. */
+    readonly error: string;
+}
+/** Outcome of resolving the tool-group environment variables. */
+export type ToolGroupResolution = ToolGroupResolutionSuccess | ToolGroupResolutionFailure;
+/**
+ * Error thrown by `createSquawkMcpServer` when the tool-group configuration
+ * cannot be honored. A server has no partial-success shape to return - an
+ * unusable catalog is worse than a failed start, particularly for aviation
+ * data - so the factory throws rather than silently registering the wrong
+ * tools.
+ */
+export declare class ToolGroupConfigError extends Error {
+    /**
+     * Constructs a new configuration error.
+     *
+     * @param message - Human-readable explanation naming the offending value.
+     */
+    constructor(message: string);
+}
+/**
+ * Resolves which tool groups to register from the process environment.
+ *
+ * With neither variable set, every group is enabled, matching the behavior of
+ * a server that predates this configuration. {@link TOOL_ALLOWLIST_ENV_VAR}
+ * and {@link TOOL_DENYLIST_ENV_VAR} are mutually exclusive: setting both is an
+ * error rather than a precedence rule, so the resolved catalog is always
+ * readable straight off the configuration.
+ *
+ * ```typescript
+ * const resolution = resolveToolGroupsFromEnv({ SQUAWK_MCP_TOOLS: 'airports,geo' });
+ * if (resolution.ok) {
+ *   console.log(resolution.toolGroups); // ['geo', 'airports']
+ * }
+ * ```
+ *
+ * @param env - Environment to read, normally `process.env`.
+ * @returns The resolved groups, or a failure carrying a printable message.
+ */
+export declare function resolveToolGroupsFromEnv(env: Record<string, string | undefined>): ToolGroupResolution;
+/**
+ * Validates an explicitly supplied group list and returns it in registration
+ * order. Unlike {@link resolveToolGroupsFromEnv}, a bad value here is a
+ * programmer error rather than user misconfiguration, so it throws.
+ *
+ * @param toolGroups - Group names supplied by the caller.
+ * @returns The distinct groups in {@link TOOL_GROUP_NAMES} order.
+ * @throws {ToolGroupConfigError} when a name is unknown or the list is empty.
+ */
+export declare function normalizeToolGroups(toolGroups: readonly ToolGroupName[]): readonly ToolGroupName[];
+//# sourceMappingURL=tool-groups.d.ts.map

package/dist/tool-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-groups.d.ts","sourceRoot":"","sources":["../src/tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,sKAcnB,CAAC;AAEX,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,6BAA6B,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,0BAA0B,CAAC;AAE1F;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAsED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,mBAAmB,CAuCrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,aAAa,EAAE,GACnC,SAAS,aAAa,EAAE,CAU1B"}

package/dist/tool-groups.js

@@ -0,0 +1,190 @@
+/**
+ * @packageDocumentation
+ * Tool-group identity and configuration parsing for @squawk/mcp. Every domain
+ * module under `src/tools/` is one toggleable group, so a client that only
+ * needs part of the catalog can keep the rest out of its context window.
+ *
+ * This module owns the canonical group-name list and turns the server's
+ * environment variables into the concrete set of groups to register.
+ */
+/**
+ * Every toggleable tool group, in the order they are registered on the
+ * server. Each name matches exactly one domain module filename under
+ * `src/tools/`, so `airports` maps to `src/tools/airports.ts`.
+ */
+export const TOOL_GROUP_NAMES = [
+    'geo',
+    'flight-math',
+    'airports',
+    'airspace',
+    'navaids',
+    'fixes',
+    'airways',
+    'procedures',
+    'icao-registry',
+    'weather',
+    'notams',
+    'flightplan',
+    'datasets',
+];
+/**
+ * Environment variable naming the only tool groups to register. Acts as an
+ * allowlist: groups absent from the list are not registered, including groups
+ * added by future releases.
+ */
+export const TOOL_ALLOWLIST_ENV_VAR = 'SQUAWK_MCP_TOOLS';
+/**
+ * Environment variable naming tool groups to skip. Acts as a denylist: every
+ * group not listed is registered, including groups added by future releases.
+ */
+export const TOOL_DENYLIST_ENV_VAR = 'SQUAWK_MCP_DISABLE_TOOLS';
+/**
+ * Error thrown by `createSquawkMcpServer` when the tool-group configuration
+ * cannot be honored. A server has no partial-success shape to return - an
+ * unusable catalog is worse than a failed start, particularly for aviation
+ * data - so the factory throws rather than silently registering the wrong
+ * tools.
+ */
+export class ToolGroupConfigError extends Error {
+    /**
+     * Constructs a new configuration error.
+     *
+     * @param message - Human-readable explanation naming the offending value.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'ToolGroupConfigError';
+    }
+}
+/** Comma-separated list of every valid group name, for error messages. */
+const VALID_GROUPS_SUFFIX = `Valid groups: ${TOOL_GROUP_NAMES.join(', ')}.`;
+/**
+ * Returns `true` when an environment variable carries no usable value. Hosts
+ * routinely pass empty strings for unset entries, so a blank value means
+ * "not configured" rather than "configured to nothing".
+ *
+ * @param value - Raw environment variable value.
+ * @returns `true` when the value is absent or whitespace-only.
+ */
+function isBlank(value) {
+    return value === undefined || value.trim() === '';
+}
+/**
+ * Narrows an arbitrary string to a {@link ToolGroupName}.
+ *
+ * @param value - Candidate group name, already trimmed and lowercased.
+ * @returns `true` when the value names a known group.
+ */
+function isToolGroupName(value) {
+    return TOOL_GROUP_NAMES.some((name) => name === value);
+}
+/**
+ * Splits a comma-separated group list into normalized, deduplicated tokens.
+ * Tokens are trimmed and lowercased so `Airports, WEATHER` resolves the same
+ * way as `airports,weather`.
+ *
+ * @param value - Raw environment variable value.
+ * @returns The distinct tokens, in the order they first appeared.
+ */
+function parseGroupList(value) {
+    const tokens = value
+        .split(',')
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token !== '');
+    return [...new Set(tokens)];
+}
+/**
+ * Validates parsed tokens against {@link TOOL_GROUP_NAMES}.
+ *
+ * @param tokens - Normalized tokens from {@link parseGroupList}.
+ * @param envVar - Variable the tokens came from, named in the error message.
+ * @returns The validated group names, or a failure describing the bad tokens.
+ */
+function validateGroupList(tokens, envVar) {
+    if (tokens.length === 0) {
+        return {
+            ok: false,
+            error: `${envVar} names no tool groups. Remove it to use the default, or list at least one group. ${VALID_GROUPS_SUFFIX}`,
+        };
+    }
+    const unknown = tokens.filter((token) => !isToolGroupName(token));
+    if (unknown.length > 0) {
+        return {
+            ok: false,
+            error: `${envVar} names unknown tool ${unknown.length === 1 ? 'group' : 'groups'}: ${unknown.join(', ')}. ${VALID_GROUPS_SUFFIX}`,
+        };
+    }
+    return { ok: true, groups: tokens.filter(isToolGroupName) };
+}
+/**
+ * Resolves which tool groups to register from the process environment.
+ *
+ * With neither variable set, every group is enabled, matching the behavior of
+ * a server that predates this configuration. {@link TOOL_ALLOWLIST_ENV_VAR}
+ * and {@link TOOL_DENYLIST_ENV_VAR} are mutually exclusive: setting both is an
+ * error rather than a precedence rule, so the resolved catalog is always
+ * readable straight off the configuration.
+ *
+ * ```typescript
+ * const resolution = resolveToolGroupsFromEnv({ SQUAWK_MCP_TOOLS: 'airports,geo' });
+ * if (resolution.ok) {
+ *   console.log(resolution.toolGroups); // ['geo', 'airports']
+ * }
+ * ```
+ *
+ * @param env - Environment to read, normally `process.env`.
+ * @returns The resolved groups, or a failure carrying a printable message.
+ */
+export function resolveToolGroupsFromEnv(env) {
+    const rawAllowlist = env[TOOL_ALLOWLIST_ENV_VAR];
+    const rawDenylist = env[TOOL_DENYLIST_ENV_VAR];
+    const hasAllowlist = !isBlank(rawAllowlist);
+    const hasDenylist = !isBlank(rawDenylist);
+    if (hasAllowlist && hasDenylist) {
+        return {
+            ok: false,
+            error: `${TOOL_ALLOWLIST_ENV_VAR} and ${TOOL_DENYLIST_ENV_VAR} are mutually exclusive. Set one or the other, not both.`,
+        };
+    }
+    if (hasAllowlist && rawAllowlist !== undefined) {
+        const validated = validateGroupList(parseGroupList(rawAllowlist), TOOL_ALLOWLIST_ENV_VAR);
+        if (!validated.ok) {
+            return validated;
+        }
+        const allowed = new Set(validated.groups);
+        return { ok: true, toolGroups: TOOL_GROUP_NAMES.filter((name) => allowed.has(name)) };
+    }
+    if (hasDenylist && rawDenylist !== undefined) {
+        const validated = validateGroupList(parseGroupList(rawDenylist), TOOL_DENYLIST_ENV_VAR);
+        if (!validated.ok) {
+            return validated;
+        }
+        const denied = new Set(validated.groups);
+        const remaining = TOOL_GROUP_NAMES.filter((name) => !denied.has(name));
+        if (remaining.length === 0) {
+            return {
+                ok: false,
+                error: `${TOOL_DENYLIST_ENV_VAR} disables every tool group, leaving the server with no tools to offer.`,
+            };
+        }
+        return { ok: true, toolGroups: remaining };
+    }
+    return { ok: true, toolGroups: TOOL_GROUP_NAMES };
+}
+/**
+ * Validates an explicitly supplied group list and returns it in registration
+ * order. Unlike {@link resolveToolGroupsFromEnv}, a bad value here is a
+ * programmer error rather than user misconfiguration, so it throws.
+ *
+ * @param toolGroups - Group names supplied by the caller.
+ * @returns The distinct groups in {@link TOOL_GROUP_NAMES} order.
+ * @throws {ToolGroupConfigError} when a name is unknown or the list is empty.
+ */
+export function normalizeToolGroups(toolGroups) {
+    const validated = validateGroupList([...new Set(toolGroups.map((group) => group.trim().toLowerCase()))], 'toolGroups');
+    if (!validated.ok) {
+        throw new ToolGroupConfigError(validated.error);
+    }
+    const requested = new Set(validated.groups);
+    return TOOL_GROUP_NAMES.filter((name) => requested.has(name));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Model Context Protocol server exposing squawk's aviation libraries as tools for LLM clients",
   "author": "Neil Cochran",
@@ -31,7 +31,7 @@
     "!dist/**/*.spec.*"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/bin.js",
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/bin.js', 0o755)\"",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "lint": "tsc --noEmit && eslint src",
@@ -40,30 +40,30 @@
     "api:report": "api-extractor run --local --verbose"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@squawk/airport-data": "^0.7.3",
-    "@squawk/airports": "^0.7.0",
-    "@squawk/airspace": "^0.9.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@squawk/airport-data": "^0.7.12",
+    "@squawk/airports": "^0.7.1",
+    "@squawk/airspace": "^0.9.1",
     "@squawk/airspace-data": "^0.5.2",
-    "@squawk/airway-data": "^0.5.3",
-    "@squawk/airways": "^0.5.0",
-    "@squawk/fix-data": "^0.6.3",
-    "@squawk/fixes": "^0.5.0",
+    "@squawk/airway-data": "^0.5.12",
+    "@squawk/airways": "^0.5.1",
+    "@squawk/fix-data": "^0.6.12",
+    "@squawk/fixes": "^0.5.1",
     "@squawk/flight-math": "^0.5.3",
-    "@squawk/flightplan": "^0.6.0",
-    "@squawk/geo": "^0.4.3",
-    "@squawk/icao-registry": "^0.5.1",
-    "@squawk/navaid-data": "^0.6.3",
-    "@squawk/navaids": "^0.6.0",
-    "@squawk/notams": "^0.3.5",
-    "@squawk/procedure-data": "^0.7.2",
-    "@squawk/procedures": "^0.7.0",
-    "@squawk/types": "^0.8.0",
-    "@squawk/weather": "^0.6.0",
-    "zod": "^4.4.3"
+    "@squawk/flightplan": "^0.6.1",
+    "@squawk/geo": "^0.4.10",
+    "@squawk/icao-registry": "^0.5.8",
+    "@squawk/navaid-data": "^0.6.12",
+    "@squawk/navaids": "^0.6.1",
+    "@squawk/notams": "^0.3.12",
+    "@squawk/procedure-data": "^0.7.10",
+    "@squawk/procedures": "^0.7.1",
+    "@squawk/types": "^0.9.0",
+    "@squawk/weather": "^0.6.1",
+    "zod": "^4.6.2"
   },
   "peerDependencies": {
-    "@squawk/icao-registry-data": "^0.8.3"
+    "@squawk/icao-registry-data": "^0.8.12"
   },
   "peerDependenciesMeta": {
     "@squawk/icao-registry-data": {
@@ -71,8 +71,8 @@
     }
   },
   "devDependencies": {
-    "@squawk/icao-registry-data": "^0.8.3",
-    "@types/node": "^25.9.3"
+    "@squawk/icao-registry-data": "^0.8.12",
+    "@types/node": "^26.5.1"
   },
   "keywords": [
     "aviation",