@squawk/mcp 0.4.1 → 0.5.0

package/README.md

@@ -98,7 +98,7 @@ version explicitly in the client config:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "@squawk/mcp@0.4.1"]
+      "args": ["-y", "@squawk/mcp@0.5.0"]
     }
   }
 }
@@ -241,12 +241,17 @@ directly.
 
 ### 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   |
+Covers SIDs, STARs, and Instrument Approach Procedures (IAPs) from FAA CIFP.
+
+| Tool                                      | Purpose                                                                                     |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `find_procedures_by_identifier`           | Every procedure publishing a CIFP identifier (same name often appears at multiple airports) |
+| `get_procedure_by_airport_and_identifier` | Resolve a specific procedure at a specific airport                                          |
+| `find_procedures_by_airport`              | Procedures associated with an airport                                                       |
+| `find_procedures_by_airport_and_runway`   | Procedures at an airport serving a specific runway (IAP runway match or RW\* transition)    |
+| `find_approaches_by_type`                 | Every IAP of a given approach classification (ILS, RNAV, VOR, etc.)                         |
+| `expand_procedure`                        | Expand a procedure into its leg sequence (with optional transition merge)                   |
+| `search_procedures`                       | Substring search by name or identifier, optionally filtered by procedure or approach type   |
 
 ### ICAO aircraft registry (`@squawk/icao-registry` + `@squawk/icao-registry-data`)
 
@@ -333,12 +338,13 @@ left to the model itself.
 
 ## 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.
+- The bundled datasets (airports, airspace, navaids, fixes, airways from FAA NASR; procedures from
+  FAA CIFP) cover the contiguous United States plus the territories included in the respective FAA
+  subscriptions. Outside the US the lookup tools will return empty results. Use `get_dataset_status`
+  to confirm which NASR and CIFP cycles 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
+- 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.

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

@@ -1 +1 @@
-{"version":3,"file":"datasets.d.ts","sourceRoot":"","sources":["../../src/tools/datasets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6D5D"}
+{"version":3,"file":"datasets.d.ts","sourceRoot":"","sources":["../../src/tools/datasets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}

package/dist/tools/datasets.js

@@ -23,7 +23,7 @@ import { getIcaoRegistryMetadata, isIcaoRegistryLoaded } from '../resolvers.js';
 export function registerDatasetTools(server) {
     server.registerTool('get_dataset_status', {
         title: 'Report status of every bundled dataset',
-        description: 'Returns the FAA NASR cycle effective date, build timestamp, and record counts for each dataset the server loads (airports, airspace, navaids, fixes, airways, procedures, ICAO aircraft registry). Use this when a user asks "how current is the data?" or before answering a question that depends on procedure/navaid currency. The aircraft registry is lazily loaded and reports its load state without forcing initialization.',
+        description: 'Returns the cycle effective date (FAA NASR for airports/airspace/navaids/fixes/airways; FAA CIFP for procedures), build timestamp, and record counts for each dataset the server loads (airports, airspace, navaids, fixes, airways, procedures, ICAO aircraft registry). Use this when a user asks "how current is the data?" or before answering a question that depends on procedure/navaid currency. The aircraft registry is lazily loaded and reports its load state without forcing initialization.',
         inputSchema: {},
     }, () => {
         const registryMetadata = getIcaoRegistryMetadata();
@@ -55,12 +55,13 @@ export function registerDatasetTools(server) {
                 waypointCount: usBundledAirways.properties.waypointCount,
             },
             procedures: {
-                nasrCycleDate: usBundledProcedures.properties.nasrCycleDate,
+                cifpCycleDate: usBundledProcedures.properties.cifpCycleDate,
                 generatedAt: usBundledProcedures.properties.generatedAt,
                 recordCount: usBundledProcedures.properties.recordCount,
                 sidCount: usBundledProcedures.properties.sidCount,
                 starCount: usBundledProcedures.properties.starCount,
-                waypointCount: usBundledProcedures.properties.waypointCount,
+                iapCount: usBundledProcedures.properties.iapCount,
+                legCount: usBundledProcedures.properties.legCount,
             },
             icaoRegistry: registryMetadata !== undefined
                 ? {

package/dist/tools/procedures.d.ts

@@ -1,13 +1,14 @@
 /**
  * @packageDocumentation
- * MCP tool module wrapping `@squawk/procedures` SID/STAR lookup, filtering,
- * and expansion methods, backed by the US NASR snapshot in
+ * MCP tool module wrapping `@squawk/procedures` SID / STAR / IAP lookup,
+ * filtering, and expansion methods, backed by the FAA CIFP snapshot in
  * `@squawk/procedure-data`.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
- * Registers SID/STAR procedure lookup tools on the given MCP server. Uses
- * the shared {@link procedureResolver} built at module load time.
+ * Registers procedure lookup tools (SIDs, STARs, and IAPs) on the given
+ * MCP server. Uses the shared {@link procedureResolver} built at module
+ * load time from the bundled FAA CIFP snapshot.
  *
  * @param server - The MCP server instance to register tools on.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../../src/tools/procedures.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAgI9D"}
+{"version":3,"file":"procedures.d.ts","sourceRoot":"","sources":["../../src/tools/procedures.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8BzE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2M9D"}

package/dist/tools/procedures.js

@@ -1,35 +1,76 @@
 /**
  * @packageDocumentation
- * MCP tool module wrapping `@squawk/procedures` SID/STAR lookup, filtering,
- * and expansion methods, backed by the US NASR snapshot in
+ * MCP tool module wrapping `@squawk/procedures` SID / STAR / IAP lookup,
+ * filtering, and expansion methods, backed by the FAA CIFP snapshot in
  * `@squawk/procedure-data`.
  */
 import { z } from 'zod';
 import { procedureResolver } from '../resolvers.js';
 /** All {@link ProcedureType} values, used for input validation. */
-const PROCEDURE_TYPE_VALUES = ['SID', 'STAR'];
+const PROCEDURE_TYPE_VALUES = ['SID', 'STAR', 'IAP'];
+/** All {@link ApproachType} values, used for input validation. */
+const APPROACH_TYPE_VALUES = [
+    'ILS',
+    'LOC',
+    'LOC_BC',
+    'RNAV',
+    'RNAV_RNP',
+    'VOR',
+    'VOR_DME',
+    'NDB',
+    'NDB_DME',
+    'TACAN',
+    'GLS',
+    'IGS',
+    'LDA',
+    'SDF',
+    'GPS',
+    'FMS',
+    'MLS',
+];
 /**
- * Registers SID/STAR procedure lookup tools on the given MCP server. Uses
- * the shared {@link procedureResolver} built at module load time.
+ * Registers procedure lookup tools (SIDs, STARs, and IAPs) on the given
+ * MCP server. Uses the shared {@link procedureResolver} built at module
+ * load time from the bundled FAA CIFP snapshot.
  *
  * @param server - The MCP server instance to register tools on.
  */
 export function registerProcedureTools(server) {
-    server.registerTool('get_procedure_by_code', {
-        title: 'Get procedure by FAA computer code',
-        description: 'Looks up a US instrument procedure (SID or STAR) by its FAA computer code (e.g. "AALLE4", "ACCRA5"). Returns null when no match is found.',
+    server.registerTool('find_procedures_by_identifier', {
+        title: 'Find procedures by CIFP identifier',
+        description: 'Looks up every US instrument procedure (SID, STAR, or IAP) whose CIFP identifier matches (case-insensitive). The same identifier is often published at multiple airports (e.g. the approach "I04L" exists at any airport with an ILS 04L), so this returns all matches. Returns an empty array when no match is found.',
         inputSchema: {
-            computerCode: z
+            identifier: z
                 .string()
                 .min(1)
-                .describe('FAA computer code for the procedure (case-insensitive).'),
+                .describe('CIFP procedure identifier (case-insensitive). Examples: "AALLE4", "NUBLE4", "I04L", "R13".'),
         },
-    }, ({ computerCode }) => {
-        const procedure = procedureResolver.byName(computerCode);
+    }, ({ identifier }) => {
+        const procedures = procedureResolver.byIdentifier(identifier);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(procedures, null, 2) }],
+            structuredContent: { procedures },
+        };
+    });
+    server.registerTool('get_procedure_by_airport_and_identifier', {
+        title: 'Get a specific procedure at an airport',
+        description: 'Looks up a single US instrument procedure at a specific airport by CIFP identifier. Use this when the same procedure identifier is published at multiple airports and the caller knows which airport is intended. Returns null when no match is found.',
+        inputSchema: {
+            airportId: z
+                .string()
+                .min(1)
+                .describe('Airport identifier (ICAO or FAA, case-insensitive).'),
+            identifier: z.string().min(1).describe('CIFP procedure identifier (case-insensitive).'),
+        },
+    }, ({ airportId, identifier }) => {
+        const procedure = procedureResolver.byAirportAndIdentifier(airportId, identifier);
         if (procedure === undefined) {
             return {
                 content: [
-                    { type: 'text', text: `No procedure found with computer code "${computerCode}".` },
+                    {
+                        type: 'text',
+                        text: `No procedure with identifier "${identifier}" found at "${airportId}".`,
+                    },
                 ],
                 structuredContent: { procedure: null },
             };
@@ -41,9 +82,9 @@ export function registerProcedureTools(server) {
     });
     server.registerTool('find_procedures_by_airport', {
         title: 'Find procedures associated with an airport',
-        description: 'Finds all US instrument procedures (SIDs and STARs) associated with a given airport identifier (FAA ID). Returns an empty array when no match is found.',
+        description: 'Finds all US instrument procedures (SIDs, STARs, and IAPs) associated with a given airport identifier. Returns an empty array when no match is found.',
         inputSchema: {
-            airportId: z.string().min(1).describe('Airport FAA identifier (case-insensitive).'),
+            airportId: z.string().min(1).describe('Airport identifier (case-insensitive).'),
         },
     }, ({ airportId }) => {
         const procedures = procedureResolver.byAirport(airportId);
@@ -52,28 +93,58 @@ export function registerProcedureTools(server) {
             structuredContent: { procedures },
         };
     });
-    server.registerTool('expand_procedure', {
-        title: 'Expand a procedure into a waypoint sequence',
-        description: "Expands a procedure into an ordered waypoint sequence. Without a transition, returns the first common route. With a transition name, returns the matching transition's waypoints followed by the first common route's waypoints (with overlapping connecting fixes deduplicated). Returns null when the procedure or transition is not found.",
+    server.registerTool('find_procedures_by_airport_and_runway', {
+        title: 'Find procedures serving a runway at an airport',
+        description: 'Finds procedures at an airport that serve a specific runway. Matches IAPs whose runway field equals the runway, and SIDs/STARs with a runway transition named "RW<runway>" (for example "RW04L"). Returns an empty array when no match is found.',
         inputSchema: {
-            computerCode: z
+            airportId: z.string().min(1).describe('Airport identifier (case-insensitive).'),
+            runway: z
                 .string()
                 .min(1)
-                .describe('FAA computer code for the procedure (case-insensitive).'),
+                .describe('Runway identifier, without the "RW" prefix (e.g. "04L", "13", "27R").'),
+        },
+    }, ({ airportId, runway }) => {
+        const procedures = procedureResolver.byAirportAndRunway(airportId, runway);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(procedures, null, 2) }],
+            structuredContent: { procedures },
+        };
+    });
+    server.registerTool('find_approaches_by_type', {
+        title: 'Find approaches by approach type',
+        description: 'Returns every Instrument Approach Procedure of a given approach classification (ILS, LOC, RNAV, VOR, NDB, etc.).',
+        inputSchema: {
+            approachType: z
+                .enum(APPROACH_TYPE_VALUES)
+                .describe('Approach classification. Use LOC_BC for localizer back-course approaches.'),
+        },
+    }, ({ approachType }) => {
+        const procedures = procedureResolver.byApproachType(approachType);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(procedures, null, 2) }],
+            structuredContent: { procedures },
+        };
+    });
+    server.registerTool('expand_procedure', {
+        title: 'Expand a procedure into an ordered leg sequence',
+        description: "Expands a procedure at an airport into an ordered leg sequence. Without a transition name, returns the procedure's common route. With a transition name, merges the named transition's legs with the common route in flying order (SID: common then transition for enroute exits, transition then common for runway transitions; STAR: transition then common for enroute entries; IAP: approach transition then final approach segment). Returns null when the airport, procedure, or transition is not found.",
+        inputSchema: {
+            airportId: z.string().min(1).describe('Airport identifier (case-insensitive).'),
+            identifier: z.string().min(1).describe('CIFP procedure identifier (case-insensitive).'),
             transitionName: z
                 .string()
                 .min(1)
                 .optional()
-                .describe('Optional transition name (typically the entry/exit fix identifier, case-insensitive). Omit to use the first common route.'),
+                .describe('Optional transition name. Omit to return just the common route.'),
         },
-    }, ({ computerCode, transitionName }) => {
-        const expansion = procedureResolver.expand(computerCode, transitionName);
+    }, ({ airportId, identifier, transitionName }) => {
+        const expansion = procedureResolver.expand(airportId, identifier, transitionName);
         if (expansion === undefined) {
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Could not expand procedure "${computerCode}"${transitionName ? ` with transition "${transitionName}"` : ''}.`,
+                        text: `Could not expand procedure "${identifier}" at "${airportId}"${transitionName ? ` with transition "${transitionName}"` : ''}.`,
                     },
                 ],
                 structuredContent: { expansion: null },
@@ -85,17 +156,21 @@ export function registerProcedureTools(server) {
         };
     });
     server.registerTool('search_procedures', {
-        title: 'Search procedures by name or code',
-        description: 'Searches US instrument procedures by case-insensitive substring matching against both the procedure name and computer code. Results are returned in alphabetical order by computer code.',
+        title: 'Search procedures by name or identifier',
+        description: 'Searches US instrument procedures (SIDs, STARs, IAPs) by case-insensitive substring matching against both the procedure name and identifier. Results are returned sorted by airport and identifier.',
         inputSchema: {
             text: z
                 .string()
                 .min(1)
-                .describe('Substring to match against the procedure name or computer code.'),
+                .describe('Substring to match against the procedure name or identifier.'),
             procedureType: z
                 .enum(PROCEDURE_TYPE_VALUES)
                 .optional()
-                .describe('Restrict results to SIDs or STARs only. Omit to include both.'),
+                .describe('Restrict results to SIDs, STARs, or IAPs only. Omit to include all types.'),
+            approachType: z
+                .enum(APPROACH_TYPE_VALUES)
+                .optional()
+                .describe('Restrict results to IAPs of a given approach classification.'),
             limit: z
                 .number()
                 .int()
@@ -103,11 +178,14 @@ export function registerProcedureTools(server) {
                 .optional()
                 .describe('Maximum number of results to return. Defaults to 20.'),
         },
-    }, ({ text, procedureType, limit }) => {
+    }, ({ text, procedureType, approachType, limit }) => {
         const query = { text };
         if (procedureType !== undefined) {
             query.type = procedureType;
         }
+        if (approachType !== undefined) {
+            query.approachType = approachType;
+        }
         if (limit !== undefined) {
             query.limit = limit;
         }

package/package.json

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