@pipeworx/mcp-opensky 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipeworx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# mcp-opensky
+
+OpenSky MCP — OpenSky Network API (free, no auth for anonymous access)
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 965+ live data sources.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "opensky": {
+      "url": "https://gateway.pipeworx.io/opensky/mcp"
+    }
+  }
+}
+```
+
+Or connect to the full Pipeworx gateway for access to all 965+ data sources:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English:
+
+```
+ask_pipeworx({ question: "your question about Opensky data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [All tools and guides](https://github.com/pipeworx-io/examples)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pipeworx/mcp-opensky",
+  "version": "0.1.0",
+  "description": "OpenSky MCP — OpenSky Network API (free, no auth for anonymous access)",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "opensky"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pipeworx-io/mcp-opensky"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/opensky",
+  "title": "Opensky",
+  "description": "OpenSky MCP — OpenSky Network API (free, no auth for anonymous access)",
+  "version": "0.1.0",
+  "websiteUrl": "https://pipeworx.io/packs/opensky",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-opensky",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/opensky/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,307 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * OpenSky MCP — OpenSky Network API (free, no auth for anonymous access)
+ *
+ * Tools:
+ * - get_flights: get flights within a time interval (max 2 hours)
+ * - get_aircraft: get flights for a specific aircraft by ICAO24 address
+ * - get_states: get current state vectors of all aircraft (or filtered by ICAO24)
+ */
+
+
+const BASE_URL = 'https://opensky-network.org/api';
+
+// --- Raw API types ---
+
+type RawFlight = {
+  icao24?: string | null;
+  firstSeen?: number | null;
+  estDepartureAirport?: string | null;
+  lastSeen?: number | null;
+  estArrivalAirport?: string | null;
+  callsign?: string | null;
+  estDepartureAirportHorizDistance?: number | null;
+  estDepartureAirportVertDistance?: number | null;
+  estArrivalAirportHorizDistance?: number | null;
+  estArrivalAirportVertDistance?: number | null;
+  departureAirportCandidatesCount?: number | null;
+  arrivalAirportCandidatesCount?: number | null;
+};
+
+// State vector is returned as an array
+// [icao24, callsign, origin_country, time_position, last_contact,
+//  longitude, latitude, baro_altitude, on_ground, velocity,
+//  true_track, vertical_rate, sensors, geo_altitude, squawk,
+//  spi, position_source, category]
+type StateVector = (string | number | boolean | number[] | null)[];
+
+type StatesResponse = {
+  time?: number | null;
+  states?: StateVector[] | null;
+};
+
+// --- Formatters ---
+
+function formatFlight(f: RawFlight) {
+  return {
+    icao24: f.icao24 ?? null,
+    callsign: f.callsign?.trim() ?? null,
+    departure_airport: f.estDepartureAirport ?? null,
+    arrival_airport: f.estArrivalAirport ?? null,
+    first_seen: f.firstSeen ? new Date(f.firstSeen * 1000).toISOString() : null,
+    last_seen: f.lastSeen ? new Date(f.lastSeen * 1000).toISOString() : null,
+  };
+}
+
+function formatState(s: StateVector) {
+  return {
+    icao24: (s[0] as string) ?? null,
+    callsign: ((s[1] as string) ?? '').trim() || null,
+    origin_country: (s[2] as string) ?? null,
+    longitude: (s[5] as number) ?? null,
+    latitude: (s[6] as number) ?? null,
+    baro_altitude_m: (s[7] as number) ?? null,
+    on_ground: (s[8] as boolean) ?? null,
+    velocity_ms: (s[9] as number) ?? null,
+    true_track_deg: (s[10] as number) ?? null,
+    vertical_rate_ms: (s[11] as number) ?? null,
+    geo_altitude_m: (s[13] as number) ?? null,
+    squawk: (s[14] as string) ?? null,
+  };
+}
+
+// --- Tool definitions ---
+
+const tools: McpToolExport['tools'] = [
+  {
+    name: 'get_flights',
+    description:
+      'Get all flights within a time interval (max 2 hours). Returns ICAO24 address, callsign, departure/arrival airports. Provide begin and end as Unix timestamps. Example: get_flights(1696118400, 1696125600).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        begin: { type: 'number', description: 'Start of time interval as Unix timestamp (seconds)' },
+        end: { type: 'number', description: 'End of time interval as Unix timestamp (seconds, max 2h after begin)' },
+      },
+      required: ['begin', 'end'],
+    },
+  },
+  {
+    name: 'get_aircraft',
+    description:
+      'Get flights for a specific aircraft by its ICAO24 transponder address (hex string, e.g., "3c675a"). Returns departure/arrival airports and times. Optionally specify a time range.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        icao24: { type: 'string', description: 'ICAO24 transponder address in hex (e.g., "3c675a")' },
+        begin: { type: 'number', description: 'Start of time interval as Unix timestamp (optional, defaults to last 24h)' },
+        end: { type: 'number', description: 'End of time interval as Unix timestamp (optional, defaults to now)' },
+      },
+      required: ['icao24'],
+    },
+  },
+  {
+    name: 'get_states',
+    description:
+      'Get live ADS-B state vectors for all currently tracked aircraft (up to 100 returned), or filter to specific aircraft by passing comma-separated ICAO24 hex addresses. Returns position (lat/lon), barometric and geometric altitude (metres), velocity (m/s), heading (degrees), vertical rate, and on-ground flag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        icao24: {
+          type: 'string',
+          description: 'Filter by one or more ICAO24 addresses (comma-separated, e.g., "3c675a,3c675b")',
+        },
+      },
+    },
+  },
+  {
+    name: 'airspace_activity',
+    description:
+      'Summary of live flight activity over a named region — total aircraft count, by-country breakdown of operators, average altitude, ground vs in-air split. Built for "is airspace open / closed" style geopolitical bets (Polymarket "Iran closes its airspace by X", "Strait of Hormuz traffic returns to normal", "Russia closes airspace"). Supported regions: Iran, Israel, Syria, Ukraine, Russia, Taiwan, North Korea, South China Sea, Yemen, Strait of Hormuz, Taiwan Strait, Red Sea, Saudi Arabia, Gulf of Aden, Lebanon.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        region: {
+          type: 'string',
+          description: 'Region name (case-insensitive). Use one of the named regions above, or use get_states with an icao24 filter for custom areas.',
+        },
+      },
+      required: ['region'],
+    },
+  },
+];
+
+// Bounding boxes for common geopolitical-bet regions. Coords are
+// [lat_min, lon_min, lat_max, lon_max]. Used by airspace_activity.
+const REGION_BOXES: Record<string, [number, number, number, number]> = {
+  iran:               [25.0,  44.0,  40.0,  64.0],
+  'strait of hormuz': [24.5,  55.0,  27.5,  58.0],
+  israel:             [29.0,  34.0,  34.0,  36.5],
+  syria:              [32.0,  35.0,  37.5,  43.0],
+  lebanon:            [33.0,  35.0,  35.0,  36.7],
+  ukraine:            [44.0,  22.0,  53.0,  41.0],
+  russia:             [41.0,  19.0,  82.0, 180.0],
+  taiwan:             [21.5, 118.0,  26.5, 124.0],
+  'taiwan strait':    [22.0, 117.0,  27.0, 122.0],
+  'north korea':      [37.5, 124.0,  43.0, 131.0],
+  'south china sea':  [ 5.0, 105.0,  22.0, 122.0],
+  yemen:              [12.0,  42.0,  19.0,  54.0],
+  'red sea':          [12.0,  32.0,  28.0,  43.5],
+  'gulf of aden':     [10.0,  43.0,  15.0,  52.0],
+  'saudi arabia':     [16.0,  34.0,  32.0,  56.0],
+};
+
+// --- callTool dispatcher ---
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (name) {
+    case 'get_flights':
+      return getFlights(args.begin as number, args.end as number);
+    case 'get_aircraft':
+      return getAircraft(
+        args.icao24 as string,
+        args.begin as number | undefined,
+        args.end as number | undefined,
+      );
+    case 'get_states':
+      return getStates(args.icao24 as string | undefined);
+    case 'airspace_activity':
+      return airspaceActivity(String(args.region ?? '').trim().toLowerCase());
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+async function airspaceActivity(region: string) {
+  const bbox = REGION_BOXES[region];
+  if (!bbox) {
+    throw new Error(
+      `Unknown region "${region}". Supported: ${Object.keys(REGION_BOXES).join(', ')}.`,
+    );
+  }
+  const [latMin, lonMin, latMax, lonMax] = bbox;
+  const url = `${BASE_URL}/states/all?lamin=${latMin}&lomin=${lonMin}&lamax=${latMax}&lomax=${lonMax}`;
+  const res = await fetch(url, { headers: { 'User-Agent': 'Pipeworx-OpenSky/1.0 (https://pipeworx.io)' } });
+  if (res.status === 429) {
+    throw new Error('OpenSky rate limit (10 anonymous calls/minute). Wait then retry, or sign up at opensky-network.org for higher limits.');
+  }
+  if (!res.ok) throw new Error(`OpenSky API error: ${res.status}`);
+  const data = (await res.json()) as StatesResponse;
+  const states = data.states ?? [];
+  const byCountry: Record<string, number> = {};
+  let altSum = 0; let altCount = 0;
+  let onGround = 0;
+  for (const s of states) {
+    const c = (s[2] as string) || 'unknown';
+    byCountry[c] = (byCountry[c] ?? 0) + 1;
+    const alt = s[7] as number | null;
+    if (alt != null) { altSum += alt; altCount++; }
+    if (s[8] as boolean) onGround++;
+  }
+  const topCountries = Object.entries(byCountry)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 15)
+    .map(([country, count]) => ({ country, count }));
+  return {
+    region,
+    bbox: { lat_min: latMin, lon_min: lonMin, lat_max: latMax, lon_max: lonMax },
+    time: data.time ? new Date(data.time * 1000).toISOString() : null,
+    total_aircraft: states.length,
+    in_air: states.length - onGround,
+    on_ground: onGround,
+    avg_altitude_m: altCount > 0 ? Math.round(altSum / altCount) : null,
+    operators_by_country: topCountries,
+    note: 'OpenSky reflects live ADS-B transponder data. Military / state aircraft often disable transponders, so this undercounts non-civilian activity. Best used as a "civilian aviation normalcy" signal.',
+  };
+}
+
+// --- Tool implementations ---
+
+async function getFlights(begin: number, end: number) {
+  const params = new URLSearchParams({
+    begin: String(begin),
+    end: String(end),
+  });
+
+  const res = await fetch(`${BASE_URL}/flights/all?${params}`);
+  if (!res.ok) throw new Error(`OpenSky API error: ${res.status}`);
+
+  const data = (await res.json()) as RawFlight[];
+
+  return {
+    begin: new Date(begin * 1000).toISOString(),
+    end: new Date(end * 1000).toISOString(),
+    count: data.length,
+    flights: data.slice(0, 100).map(formatFlight),
+  };
+}
+
+async function getAircraft(icao24: string, begin?: number, end?: number) {
+  const now = Math.floor(Date.now() / 1000);
+  const effectiveEnd = end ?? now;
+  const effectiveBegin = begin ?? effectiveEnd - 86400;
+
+  const params = new URLSearchParams({
+    icao24: icao24.toLowerCase(),
+    begin: String(effectiveBegin),
+    end: String(effectiveEnd),
+  });
+
+  const res = await fetch(`${BASE_URL}/flights/aircraft?${params}`);
+  if (!res.ok) throw new Error(`OpenSky API error: ${res.status}`);
+
+  const data = (await res.json()) as RawFlight[];
+
+  return {
+    icao24: icao24.toLowerCase(),
+    begin: new Date(effectiveBegin * 1000).toISOString(),
+    end: new Date(effectiveEnd * 1000).toISOString(),
+    count: data.length,
+    flights: data.map(formatFlight),
+  };
+}
+
+async function getStates(icao24Filter?: string) {
+  const params = new URLSearchParams();
+  if (icao24Filter) {
+    // API accepts multiple icao24 params
+    for (const addr of icao24Filter.split(',')) {
+      params.append('icao24', addr.trim().toLowerCase());
+    }
+  }
+
+  const url = params.toString()
+    ? `${BASE_URL}/states/all?${params}`
+    : `${BASE_URL}/states/all`;
+
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`OpenSky API error: ${res.status}`);
+
+  const data = (await res.json()) as StatesResponse;
+  const states = data.states ?? [];
+
+  return {
+    time: data.time ? new Date(data.time * 1000).toISOString() : null,
+    count: states.length,
+    states: states.slice(0, 100).map(formatState),
+  };
+}
+
+export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}