@squawk/mcp 0.2.0

package/dist/tools/tool-helpers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @packageDocumentation
+ * Shared helpers used by multiple tool modules. Internal to `@squawk/mcp` and
+ * not re-exported from the package entrypoint.
+ */
+/**
+ * A single per-record parse failure as returned by the AWC fetch helpers.
+ * Captures the raw record text and the thrown error.
+ */
+export interface ParseRecordErrorLike {
+    /** The raw input record that failed to parse. */
+    raw: string;
+    /** The error thrown by the underlying parser. */
+    error: unknown;
+}
+/**
+ * Summary form of a per-record parse failure suitable for MCP tool output.
+ * The error is reduced to its message string so the structured payload
+ * round-trips cleanly through JSON.
+ */
+export interface ParseRecordErrorSummary {
+    /** The raw input record that failed to parse. */
+    raw: string;
+    /** Human-readable message extracted from the parser's thrown error. */
+    message: string;
+}
+/**
+ * Reduces an array of {@link ParseRecordErrorLike} entries to a JSON-friendly
+ * shape. Used by every weather fetch tool to surface partial parse failures
+ * in `structuredContent` without leaking thrown error objects.
+ *
+ * @param errors - Per-record parse errors as returned by `@squawk/weather/fetch`.
+ * @returns The errors with each `error` value reduced to its message string.
+ */
+export declare function summarizeParseErrors(errors: readonly ParseRecordErrorLike[]): ParseRecordErrorSummary[];
+/**
+ * Runs a synchronous parser inside a tool handler and packages the outcome
+ * into the MCP result shape. On success the parsed record is returned as
+ * pretty JSON in `content` and as `structuredContent[resultKey]`. On failure
+ * the parser message is forwarded verbatim and the result is flagged
+ * `isError: true` so the model can react to the failure.
+ *
+ * The return type is intentionally an inline literal rather than a named
+ * interface: the MCP SDK's tool-result type carries an `[x: string]: unknown`
+ * index signature that nominal interfaces do not satisfy without explicit
+ * declaration, while inline object types are accepted at the call site
+ * through TypeScript's freshness rules.
+ *
+ * @param raw - The raw input string passed to the parser.
+ * @param parser - A pure parser function that may throw on bad input.
+ * @param resultKey - The key under which the parsed record is exposed in
+ *                    `structuredContent`.
+ * @returns The MCP tool result.
+ */
+export declare function runParser<T>(raw: string, parser: (raw: string) => T, resultKey: string): {
+    /** Standard MCP content blocks (always a single text block here). */
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    /** Structured payload exposed to the client, keyed by `resultKey`. */
+    structuredContent: Record<string, T | null>;
+    /** Set to `true` when the parser threw; omitted on success. */
+    isError?: boolean;
+};
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/tools/tool-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,oBAAoB,EAAE,GACtC,uBAAuB,EAAE,CAK3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,EAC1B,SAAS,EAAE,MAAM,GAChB;IACD,qEAAqE;IACrE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAeA"}

package/dist/tools/tool-helpers.js

@@ -0,0 +1,55 @@
+/**
+ * @packageDocumentation
+ * Shared helpers used by multiple tool modules. Internal to `@squawk/mcp` and
+ * not re-exported from the package entrypoint.
+ */
+/**
+ * Reduces an array of {@link ParseRecordErrorLike} entries to a JSON-friendly
+ * shape. Used by every weather fetch tool to surface partial parse failures
+ * in `structuredContent` without leaking thrown error objects.
+ *
+ * @param errors - Per-record parse errors as returned by `@squawk/weather/fetch`.
+ * @returns The errors with each `error` value reduced to its message string.
+ */
+export function summarizeParseErrors(errors) {
+    return errors.map((err) => ({
+        raw: err.raw,
+        message: err.error instanceof Error ? err.error.message : String(err.error),
+    }));
+}
+/**
+ * Runs a synchronous parser inside a tool handler and packages the outcome
+ * into the MCP result shape. On success the parsed record is returned as
+ * pretty JSON in `content` and as `structuredContent[resultKey]`. On failure
+ * the parser message is forwarded verbatim and the result is flagged
+ * `isError: true` so the model can react to the failure.
+ *
+ * The return type is intentionally an inline literal rather than a named
+ * interface: the MCP SDK's tool-result type carries an `[x: string]: unknown`
+ * index signature that nominal interfaces do not satisfy without explicit
+ * declaration, while inline object types are accepted at the call site
+ * through TypeScript's freshness rules.
+ *
+ * @param raw - The raw input string passed to the parser.
+ * @param parser - A pure parser function that may throw on bad input.
+ * @param resultKey - The key under which the parsed record is exposed in
+ *                    `structuredContent`.
+ * @returns The MCP tool result.
+ */
+export function runParser(raw, parser, resultKey) {
+    try {
+        const parsed = parser(raw);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
+            structuredContent: { [resultKey]: parsed },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Parse failed: ${message}` }],
+            structuredContent: { [resultKey]: null },
+            isError: true,
+        };
+    }
+}

package/dist/tools/weather.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @packageDocumentation
+ * MCP tool module wrapping `@squawk/weather` parsing utilities and the live
+ * `@squawk/weather/fetch` client for the Aviation Weather Center text API.
+ *
+ * Parsing tools accept user-pasted METAR/TAF/SIGMET/AIRMET/PIREP strings and
+ * return the parsed objects. Fetch tools issue HTTP requests to the AWC API
+ * and return both the parsed records and any per-record parse errors so the
+ * model can surface partial failures.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers weather parsing and live-fetch tools on the given MCP server.
+ *
+ * @param server - The MCP server instance to register tools on.
+ */
+export declare function registerWeatherTools(server: McpServer): void;
+//# sourceMappingURL=weather.d.ts.map

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

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

package/dist/tools/weather.js

@@ -0,0 +1,215 @@
+/**
+ * @packageDocumentation
+ * MCP tool module wrapping `@squawk/weather` parsing utilities and the live
+ * `@squawk/weather/fetch` client for the Aviation Weather Center text API.
+ *
+ * Parsing tools accept user-pasted METAR/TAF/SIGMET/AIRMET/PIREP strings and
+ * return the parsed objects. Fetch tools issue HTTP requests to the AWC API
+ * and return both the parsed records and any per-record parse errors so the
+ * model can surface partial failures.
+ */
+import { parseAirmet, parseMetar, parsePirep, parseSigmet, parseTaf } from '@squawk/weather';
+import { fetchInternationalSigmets, fetchMetar, fetchPirep, fetchSigmets, fetchTaf, } from '@squawk/weather/fetch';
+import { z } from 'zod';
+import { runParser, summarizeParseErrors } from './tool-helpers.js';
+/** Allowed values for the AWC SIGMET hazard filter. */
+const SIGMET_HAZARD_VALUES = [
+    'conv',
+    'turb',
+    'ice',
+    'ifr',
+];
+/** Allowed values for the AWC PIREP minimum intensity filter. */
+const PIREP_INTENSITY_VALUES = [
+    'lgt',
+    'mod',
+    'sev',
+];
+/**
+ * Optional override for the Aviation Weather Center base URL. Read once at
+ * module load from the `SQUAWK_AWC_BASE_URL` environment variable. When set,
+ * every live `fetch_*` tool routes its request through the override - useful
+ * for proxies, regional mirrors, and pointing tests at a local stub server.
+ * Empty/whitespace values are treated as unset.
+ */
+const AWC_BASE_URL_OVERRIDE = (() => {
+    const raw = process.env.SQUAWK_AWC_BASE_URL;
+    if (raw === undefined) {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+})();
+/**
+ * Returns a fresh {@link FetchWeatherOptions} object pre-populated with the
+ * AWC base-URL override when one is configured. Each fetch tool spreads its
+ * own options on top of the result.
+ */
+function baseFetchOptions() {
+    return AWC_BASE_URL_OVERRIDE !== undefined ? { baseUrl: AWC_BASE_URL_OVERRIDE } : {};
+}
+/**
+ * Registers weather parsing and live-fetch tools on the given MCP server.
+ *
+ * @param server - The MCP server instance to register tools on.
+ */
+export function registerWeatherTools(server) {
+    // ---------------------------------------------------------------------------
+    // Parsers
+    // ---------------------------------------------------------------------------
+    server.registerTool('parse_metar', {
+        title: 'Parse a METAR or SPECI report',
+        description: 'Parses a raw METAR or SPECI observation string into a structured object including wind, visibility, RVR, weather phenomena, sky condition, temperature, dewpoint, altimeter, remarks, and a derived flight category (VFR/MVFR/IFR/LIFR).',
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw METAR or SPECI report text.'),
+        },
+    }, ({ raw }) => runParser(raw, parseMetar, 'metar'));
+    server.registerTool('parse_taf', {
+        title: 'Parse a TAF forecast',
+        description: 'Parses a raw TAF (Terminal Aerodrome Forecast) string into a structured object with the validity period and ordered forecast change groups (FM, BECMG, TEMPO, PROB).',
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw TAF report text.'),
+        },
+    }, ({ raw }) => runParser(raw, parseTaf, 'taf'));
+    server.registerTool('parse_sigmet', {
+        title: 'Parse a SIGMET bulletin',
+        description: 'Parses a raw SIGMET (Significant Meteorological Information) bulletin in either US domestic or international ICAO format, returning a structured object with the FIR/area, hazard type, validity period, geometry, and movement.',
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw SIGMET bulletin text.'),
+        },
+    }, ({ raw }) => runParser(raw, parseSigmet, 'sigmet'));
+    server.registerTool('parse_airmet', {
+        title: 'Parse an AIRMET bulletin',
+        description: "Parses a raw AIRMET (Airmen's Meteorological Information) bulletin into a structured object with the issuing center, validity period, hazard type, and area.",
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw AIRMET bulletin text.'),
+        },
+    }, ({ raw }) => runParser(raw, parseAirmet, 'airmet'));
+    server.registerTool('parse_pirep', {
+        title: 'Parse a PIREP report',
+        description: 'Parses a raw PIREP (Pilot Report) string into a structured object with location, time, aircraft type, altitude, sky cover, weather, turbulence, icing, and remarks.',
+        inputSchema: {
+            raw: z.string().min(1).describe('Raw PIREP report text.'),
+        },
+    }, ({ raw }) => runParser(raw, parsePirep, 'pirep'));
+    // ---------------------------------------------------------------------------
+    // Fetch (Aviation Weather Center text API)
+    // ---------------------------------------------------------------------------
+    server.registerTool('fetch_metar', {
+        title: 'Fetch live METARs from the Aviation Weather Center',
+        description: "Fetches current METARs for one or more stations from the Aviation Weather Center text API and parses each record. Returns both the parsed METARs and any per-record parse errors. Use the parsed METAR's flightCategory field to summarize conditions.",
+        inputSchema: {
+            stations: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe('One or more ICAO station identifiers (e.g. ["KJFK", "KLAX"]). The AWC API joins these with commas in a single request.'),
+        },
+    }, async ({ stations }) => {
+        const { metars, parseErrors } = await fetchMetar(stations, baseFetchOptions());
+        const payload = { metars, parseErrors: summarizeParseErrors(parseErrors) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+    server.registerTool('fetch_taf', {
+        title: 'Fetch live TAFs from the Aviation Weather Center',
+        description: 'Fetches current TAFs for one or more stations from the Aviation Weather Center text API and parses each record. Returns both the parsed TAFs and any per-record parse errors.',
+        inputSchema: {
+            stations: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe('One or more ICAO station identifiers (e.g. ["KJFK", "KLAX"]).'),
+        },
+    }, async ({ stations }) => {
+        const { tafs, parseErrors } = await fetchTaf(stations, baseFetchOptions());
+        const payload = { tafs, parseErrors: summarizeParseErrors(parseErrors) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+    server.registerTool('fetch_pirep', {
+        title: 'Fetch live PIREPs from the Aviation Weather Center',
+        description: 'Fetches recent PIREPs centered on a single 4-letter ICAO station (e.g. "KDEN") from the Aviation Weather Center text API. Returns the parsed PIREPs and any per-record parse errors.',
+        inputSchema: {
+            station: z
+                .string()
+                .min(4)
+                .max(4)
+                .describe('4-letter ICAO station identifier used as the search center (the API rejects shorter forms).'),
+            radiusNm: z
+                .number()
+                .positive()
+                .optional()
+                .describe('Optional search radius in nautical miles around the center station.'),
+            ageHours: z
+                .number()
+                .positive()
+                .optional()
+                .describe('Optional hours back to search for reports.'),
+            levelHundredsFt: z
+                .number()
+                .positive()
+                .optional()
+                .describe('Optional altitude in hundreds of feet; the AWC API widens +/-3000 ft around this value.'),
+            minimumIntensity: z
+                .enum(PIREP_INTENSITY_VALUES)
+                .optional()
+                .describe('Optional minimum report intensity ("lgt" = light, "mod" = moderate, "sev" = severe).'),
+        },
+    }, async ({ station, radiusNm, ageHours, levelHundredsFt, minimumIntensity }) => {
+        const options = baseFetchOptions();
+        if (radiusNm !== undefined) {
+            options.distance = radiusNm;
+        }
+        if (ageHours !== undefined) {
+            options.age = ageHours;
+        }
+        if (levelHundredsFt !== undefined) {
+            options.level = levelHundredsFt;
+        }
+        if (minimumIntensity !== undefined) {
+            options.inten = minimumIntensity;
+        }
+        const { pireps, parseErrors } = await fetchPirep(station, options);
+        const payload = { pireps, parseErrors: summarizeParseErrors(parseErrors) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+    server.registerTool('fetch_sigmets', {
+        title: 'Fetch active US (CONUS) SIGMETs',
+        description: 'Fetches all currently active US domestic SIGMETs from the Aviation Weather Center. The endpoint is not station-filtered; it returns the full active set. Optionally restrict to a single hazard type.',
+        inputSchema: {
+            hazard: z
+                .enum(SIGMET_HAZARD_VALUES)
+                .optional()
+                .describe('Optional hazard filter: "conv" (convective), "turb" (turbulence), "ice" (icing), or "ifr" (IFR conditions).'),
+        },
+    }, async ({ hazard }) => {
+        const options = baseFetchOptions();
+        if (hazard !== undefined) {
+            options.hazard = hazard;
+        }
+        const { sigmets, parseErrors } = await fetchSigmets(options);
+        const payload = { sigmets, parseErrors: summarizeParseErrors(parseErrors) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+    server.registerTool('fetch_international_sigmets', {
+        title: 'Fetch active international (ICAO-format) SIGMETs',
+        description: 'Fetches all currently active international SIGMETs (ICAO format) from the Aviation Weather Center. Excludes US domestic SIGMETs - use fetch_sigmets for those.',
+        inputSchema: {},
+    }, async () => {
+        const { sigmets, parseErrors } = await fetchInternationalSigmets(baseFetchOptions());
+        const payload = { sigmets, parseErrors: summarizeParseErrors(parseErrors) };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            structuredContent: payload,
+        };
+    });
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@squawk/mcp",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Model Context Protocol server exposing squawk's aviation libraries as tools for LLM clients",
+  "author": "Neil Cochran",
+  "license": "MIT",
+  "homepage": "https://github.com/neilcochran/squawk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neilcochran/squawk.git",
+    "directory": "packages/mcp"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "typedocMain": "src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "squawk-mcp": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/bin.js",
+    "test": "node --test 'dist/**/*.spec.js'",
+    "lint": "tsc --noEmit && eslint src"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@squawk/airport-data": "*",
+    "@squawk/airports": "*",
+    "@squawk/airspace": "*",
+    "@squawk/airspace-data": "*",
+    "@squawk/airway-data": "*",
+    "@squawk/airways": "*",
+    "@squawk/fix-data": "*",
+    "@squawk/fixes": "*",
+    "@squawk/flight-math": "*",
+    "@squawk/flightplan": "*",
+    "@squawk/geo": "*",
+    "@squawk/icao-registry": "*",
+    "@squawk/icao-registry-data": "*",
+    "@squawk/navaid-data": "*",
+    "@squawk/navaids": "*",
+    "@squawk/notams": "*",
+    "@squawk/procedure-data": "*",
+    "@squawk/procedures": "*",
+    "@squawk/types": "*",
+    "@squawk/weather": "*",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  },
+  "keywords": [
+    "aviation",
+    "typescript",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "claude",
+    "anthropic"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}