@ktmcp-cli/airportweb 1.0.0

package/AGENT.md

@@ -0,0 +1,78 @@
+# AGENT.md — Airport Web CLI for AI Agents
+
+This document explains how to use the Airport Web CLI as an AI agent.
+
+## Overview
+
+The `airportweb` CLI provides access to the Airport Web API. No authentication is required — it is a public API.
+
+## All Commands
+
+### Config
+
+```bash
+airportweb config get <key>
+airportweb config set <key> <value>
+airportweb config list
+```
+
+### Airports
+
+```bash
+# Search airports
+airportweb airports search "London"
+airportweb airports search "JFK"
+
+# Get specific airport
+airportweb airports get JFK
+airportweb airports get LHR
+
+# List airports
+airportweb airports list
+airportweb airports list --limit 100
+
+# By country code
+airportweb airports by-country US
+airportweb airports by-country GB
+```
+
+### Airlines
+
+```bash
+# List airlines
+airportweb airlines list
+
+# Get specific airline
+airportweb airlines get AA
+airportweb airlines get BA
+
+# Search airlines
+airportweb airlines search "American"
+```
+
+### Routes
+
+```bash
+# Get routes
+airportweb routes get --from JFK
+airportweb routes get --to LHR
+airportweb routes get --from JFK --to LHR
+
+# Search routes with filters
+airportweb routes search --from JFK --airline AA
+airportweb routes search --from LAX --to SFO
+```
+
+## JSON Output
+
+All commands support `--json`:
+
+```bash
+airportweb airports get JFK --json
+airportweb airlines list --json
+airportweb routes get --from JFK --json
+```
+
+## Error Handling
+
+The CLI exits with code 1 on error and prints to stderr.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KTMCP
+
+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,104 @@
+> "Six months ago, everyone was talking about MCPs. And I was like, screw MCPs. Every MCP would be better as a CLI."
+>
+> — [Peter Steinberger](https://twitter.com/steipete), Founder of OpenClaw
+> [Watch on YouTube (~2:39:00)](https://www.youtube.com/@lexfridman) | [Lex Fridman Podcast #491](https://lexfridman.com/peter-steinberger/)
+
+# Airport Web CLI
+
+Production-ready CLI for the Airport Web API. Search airports, airlines, and routes directly from your terminal.
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/airportweb
+```
+
+## Configuration
+
+No authentication required — the Airport Web API is public.
+
+```bash
+airportweb config list
+```
+
+## Usage
+
+### Airports
+
+```bash
+# Search airports by name or city
+airportweb airports search "London"
+airportweb airports search "JFK"
+
+# Get airport by IATA code
+airportweb airports get JFK
+airportweb airports get LHR
+
+# List airports
+airportweb airports list
+airportweb airports list --limit 20
+
+# List airports by country
+airportweb airports by-country US
+airportweb airports by-country DE
+```
+
+### Airlines
+
+```bash
+# List airlines
+airportweb airlines list
+airportweb airlines list --limit 30
+
+# Get airline by IATA code
+airportweb airlines get AA
+airportweb airlines get BA
+
+# Search airlines
+airportweb airlines search "Delta"
+airportweb airlines search "Lufthansa"
+```
+
+### Routes
+
+```bash
+# Get routes from an airport
+airportweb routes get --from JFK
+
+# Get routes to an airport
+airportweb routes get --to LHR
+
+# Get routes between airports
+airportweb routes get --from JFK --to LHR
+
+# Search routes with filters
+airportweb routes search --from JFK --airline AA
+airportweb routes search --from LAX --to SFO
+```
+
+### JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+airportweb airports get JFK --json
+airportweb airports search "London" --json | jq '.[].iata_code'
+airportweb routes get --from JFK --json
+```
+
+## Examples
+
+```bash
+# Find all airports in Germany
+airportweb airports by-country DE
+
+# Search for Delta airlines
+airportweb airlines search "Delta" --json
+
+# Get all routes from LAX
+airportweb routes get --from LAX --json | jq '.[].arr_iata' | sort | uniq
+```
+
+## License
+
+MIT

package/bin/airportweb.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+import(join(__dirname, '..', 'src', 'index.js'));

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ktmcp-cli/airportweb",
+  "version": "1.0.0",
+  "description": "Production-ready CLI for Airport Web API - Kill The MCP",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "airportweb": "bin/airportweb.js"
+  },
+  "keywords": ["airportweb", "airports", "airlines", "routes", "cli", "api", "ktmcp"],
+  "author": "KTMCP",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "axios": "^1.6.7",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "conf": "^12.0.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktmcp-cli/airportweb.git"
+  },
+  "homepage": "https://killthemcp.com/airportweb-cli",
+  "bugs": { "url": "https://github.com/ktmcp-cli/airportweb/issues" }
+}

package/src/api.js

@@ -0,0 +1,140 @@
+import axios from 'axios';
+
+const BASE_URL = 'https://airport-web.appspot.com';
+
+const client = axios.create({
+  baseURL: BASE_URL,
+  headers: {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json'
+  },
+  timeout: 15000
+});
+
+function handleApiError(error) {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+    if (status === 404) {
+      throw new Error('Resource not found.');
+    } else if (status === 429) {
+      throw new Error('Rate limit exceeded. Please wait before retrying.');
+    } else {
+      const message = data?.message || data?.error || JSON.stringify(data);
+      throw new Error(`API Error (${status}): ${message}`);
+    }
+  } else if (error.request) {
+    throw new Error('No response from Airport Web API. Check your internet connection.');
+  } else {
+    throw error;
+  }
+}
+
+// ============================================================
+// AIRPORTS
+// ============================================================
+
+export async function listAirports({ search, limit = 50 } = {}) {
+  try {
+    const params = {};
+    if (search) params.q = search;
+    if (limit) params.limit = limit;
+    const response = await client.get('/api/airports', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getAirportByIata(iata) {
+  try {
+    const response = await client.get(`/api/airports/${iata.toUpperCase()}`);
+    return response.data || null;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function listAirportsByCountry(country) {
+  try {
+    const params = { country };
+    const response = await client.get('/api/airports', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function searchAirports(query) {
+  try {
+    const params = { q: query };
+    const response = await client.get('/api/airports', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// AIRLINES
+// ============================================================
+
+export async function listAirlines({ search, limit = 50 } = {}) {
+  try {
+    const params = {};
+    if (search) params.q = search;
+    if (limit) params.limit = limit;
+    const response = await client.get('/api/airlines', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getAirline(iata) {
+  try {
+    const response = await client.get(`/api/airlines/${iata.toUpperCase()}`);
+    return response.data || null;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function searchAirlines(query) {
+  try {
+    const params = { q: query };
+    const response = await client.get('/api/airlines', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// ROUTES
+// ============================================================
+
+export async function getRoutes({ from, to } = {}) {
+  try {
+    const params = {};
+    if (from) params.dep_iata = from.toUpperCase();
+    if (to) params.arr_iata = to.toUpperCase();
+    const response = await client.get('/api/routes', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function searchRoutes({ from, to, airline } = {}) {
+  try {
+    const params = {};
+    if (from) params.dep_iata = from.toUpperCase();
+    if (to) params.arr_iata = to.toUpperCase();
+    if (airline) params.airline_iata = airline.toUpperCase();
+    const response = await client.get('/api/routes', { params });
+    return response.data || [];
+  } catch (error) {
+    handleApiError(error);
+  }
+}

package/src/config.js

@@ -0,0 +1,22 @@
+import Conf from 'conf';
+
+const config = new Conf({ projectName: '@ktmcp-cli/airportweb' });
+
+export function getConfig(key) {
+  return config.get(key);
+}
+
+export function setConfig(key, value) {
+  config.set(key, value);
+}
+
+export function isConfigured() {
+  // Airport Web API is public — no auth required
+  return true;
+}
+
+export function getAllConfig() {
+  return config.store;
+}
+
+export default config;

package/src/index.js

@@ -0,0 +1,440 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getConfig, setConfig, getAllConfig } from './config.js';
+import {
+  listAirports,
+  getAirportByIata,
+  listAirportsByCountry,
+  searchAirports,
+  listAirlines,
+  getAirline,
+  searchAirlines,
+  getRoutes,
+  searchRoutes
+} from './api.js';
+
+const program = new Command();
+
+// ============================================================
+// Helpers
+// ============================================================
+
+function printSuccess(message) {
+  console.log(chalk.green('✓') + ' ' + message);
+}
+
+function printError(message) {
+  console.error(chalk.red('✗') + ' ' + message);
+}
+
+function printTable(data, columns) {
+  if (!data || data.length === 0) {
+    console.log(chalk.yellow('No results found.'));
+    return;
+  }
+
+  const widths = {};
+  columns.forEach(col => {
+    widths[col.key] = col.label.length;
+    data.forEach(row => {
+      const val = String(col.format ? col.format(row[col.key], row) : (row[col.key] ?? ''));
+      if (val.length > widths[col.key]) widths[col.key] = val.length;
+    });
+    widths[col.key] = Math.min(widths[col.key], 40);
+  });
+
+  const header = columns.map(col => col.label.padEnd(widths[col.key])).join('  ');
+  console.log(chalk.bold(chalk.cyan(header)));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  data.forEach(row => {
+    const line = columns.map(col => {
+      const val = String(col.format ? col.format(row[col.key], row) : (row[col.key] ?? ''));
+      return val.substring(0, widths[col.key]).padEnd(widths[col.key]);
+    }).join('  ');
+    console.log(line);
+  });
+
+  console.log(chalk.dim(`\n${data.length} result(s)`));
+}
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function withSpinner(message, fn) {
+  const spinner = ora(message).start();
+  try {
+    const result = await fn();
+    spinner.stop();
+    return result;
+  } catch (error) {
+    spinner.stop();
+    throw error;
+  }
+}
+
+// ============================================================
+// Program metadata
+// ============================================================
+
+program
+  .name('airportweb')
+  .description(chalk.bold('Airport Web CLI') + ' - Airports, airlines, and routes from your terminal')
+  .version('1.0.0');
+
+// ============================================================
+// CONFIG
+// ============================================================
+
+const configCmd = program.command('config').description('Manage CLI configuration');
+
+configCmd
+  .command('get <key>')
+  .description('Get a configuration value')
+  .action((key) => {
+    const value = getConfig(key);
+    if (value === undefined) {
+      printError(`Key '${key}' not found`);
+    } else {
+      console.log(value);
+    }
+  });
+
+configCmd
+  .command('set <key> <value>')
+  .description('Set a configuration value')
+  .action((key, value) => {
+    setConfig(key, value);
+    printSuccess(`Config '${key}' set`);
+  });
+
+configCmd
+  .command('list')
+  .description('List all configuration values')
+  .action(() => {
+    const all = getAllConfig();
+    if (Object.keys(all).length === 0) {
+      console.log(chalk.yellow('No configuration set. Airport Web API is public — no auth required.'));
+    } else {
+      console.log(chalk.bold('\nAirport Web CLI Configuration\n'));
+      Object.entries(all).forEach(([k, v]) => {
+        console.log(`${k}: ${chalk.cyan(String(v))}`);
+      });
+    }
+  });
+
+// ============================================================
+// AIRPORTS
+// ============================================================
+
+const airportsCmd = program.command('airports').description('Search and browse airports');
+
+airportsCmd
+  .command('search <query>')
+  .description('Search airports by name, city, or IATA code')
+  .option('--limit <n>', 'Maximum number of results', '50')
+  .option('--json', 'Output as JSON')
+  .action(async (query, options) => {
+    try {
+      const airports = await withSpinner(`Searching airports for "${query}"...`, () =>
+        searchAirports(query)
+      );
+
+      if (options.json) {
+        printJson(airports);
+        return;
+      }
+
+      const data = Array.isArray(airports) ? airports.slice(0, parseInt(options.limit)) : [];
+      printTable(data, [
+        { key: 'iata_code', label: 'IATA' },
+        { key: 'icao_code', label: 'ICAO' },
+        { key: 'name', label: 'Name' },
+        { key: 'city', label: 'City' },
+        { key: 'country', label: 'Country' },
+        { key: 'latitude', label: 'Lat', format: (v) => v ? String(parseFloat(v).toFixed(4)) : '' },
+        { key: 'longitude', label: 'Lon', format: (v) => v ? String(parseFloat(v).toFixed(4)) : '' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+airportsCmd
+  .command('get <iata>')
+  .description('Get airport details by IATA code')
+  .option('--json', 'Output as JSON')
+  .action(async (iata, options) => {
+    try {
+      const airport = await withSpinner(`Fetching airport ${iata.toUpperCase()}...`, () =>
+        getAirportByIata(iata)
+      );
+
+      if (!airport) {
+        printError('Airport not found');
+        process.exit(1);
+      }
+
+      if (options.json) {
+        printJson(airport);
+        return;
+      }
+
+      console.log(chalk.bold('\nAirport Details\n'));
+      console.log('IATA Code:     ', chalk.cyan(airport.iata_code || iata.toUpperCase()));
+      console.log('ICAO Code:     ', airport.icao_code || 'N/A');
+      console.log('Name:          ', chalk.bold(airport.name || 'N/A'));
+      console.log('City:          ', airport.city || 'N/A');
+      console.log('Country:       ', airport.country || 'N/A');
+      console.log('Latitude:      ', airport.latitude || 'N/A');
+      console.log('Longitude:     ', airport.longitude || 'N/A');
+      console.log('Timezone:      ', airport.timezone || 'N/A');
+      console.log('Elevation:     ', airport.altitude ? `${airport.altitude} ft` : 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+airportsCmd
+  .command('list')
+  .description('List airports')
+  .option('--limit <n>', 'Maximum number of results', '50')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      const airports = await withSpinner('Fetching airports...', () =>
+        listAirports({ limit: parseInt(options.limit) })
+      );
+
+      if (options.json) {
+        printJson(airports);
+        return;
+      }
+
+      const data = Array.isArray(airports) ? airports : [];
+      printTable(data, [
+        { key: 'iata_code', label: 'IATA' },
+        { key: 'icao_code', label: 'ICAO' },
+        { key: 'name', label: 'Name' },
+        { key: 'city', label: 'City' },
+        { key: 'country', label: 'Country' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+airportsCmd
+  .command('by-country <country>')
+  .description('List airports by country code (e.g. US, DE, GB)')
+  .option('--json', 'Output as JSON')
+  .action(async (country, options) => {
+    try {
+      const airports = await withSpinner(`Fetching airports in ${country}...`, () =>
+        listAirportsByCountry(country)
+      );
+
+      if (options.json) {
+        printJson(airports);
+        return;
+      }
+
+      const data = Array.isArray(airports) ? airports : [];
+      printTable(data, [
+        { key: 'iata_code', label: 'IATA' },
+        { key: 'icao_code', label: 'ICAO' },
+        { key: 'name', label: 'Name' },
+        { key: 'city', label: 'City' },
+        { key: 'country', label: 'Country' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// AIRLINES
+// ============================================================
+
+const airlinesCmd = program.command('airlines').description('Search and browse airlines');
+
+airlinesCmd
+  .command('list')
+  .description('List airlines')
+  .option('--limit <n>', 'Maximum number of results', '50')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      const airlines = await withSpinner('Fetching airlines...', () =>
+        listAirlines({ limit: parseInt(options.limit) })
+      );
+
+      if (options.json) {
+        printJson(airlines);
+        return;
+      }
+
+      const data = Array.isArray(airlines) ? airlines : [];
+      printTable(data, [
+        { key: 'iata_code', label: 'IATA' },
+        { key: 'icao_code', label: 'ICAO' },
+        { key: 'name', label: 'Name' },
+        { key: 'country', label: 'Country' },
+        { key: 'active', label: 'Active', format: (v) => v ? 'Yes' : 'No' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+airlinesCmd
+  .command('get <iata>')
+  .description('Get airline details by IATA code')
+  .option('--json', 'Output as JSON')
+  .action(async (iata, options) => {
+    try {
+      const airline = await withSpinner(`Fetching airline ${iata.toUpperCase()}...`, () =>
+        getAirline(iata)
+      );
+
+      if (!airline) {
+        printError('Airline not found');
+        process.exit(1);
+      }
+
+      if (options.json) {
+        printJson(airline);
+        return;
+      }
+
+      console.log(chalk.bold('\nAirline Details\n'));
+      console.log('IATA Code:     ', chalk.cyan(airline.iata_code || iata.toUpperCase()));
+      console.log('ICAO Code:     ', airline.icao_code || 'N/A');
+      console.log('Name:          ', chalk.bold(airline.name || 'N/A'));
+      console.log('Country:       ', airline.country || 'N/A');
+      console.log('Active:        ', airline.active ? chalk.green('Yes') : chalk.red('No'));
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+airlinesCmd
+  .command('search <query>')
+  .description('Search airlines by name or code')
+  .option('--json', 'Output as JSON')
+  .action(async (query, options) => {
+    try {
+      const airlines = await withSpinner(`Searching airlines for "${query}"...`, () =>
+        searchAirlines(query)
+      );
+
+      if (options.json) {
+        printJson(airlines);
+        return;
+      }
+
+      const data = Array.isArray(airlines) ? airlines : [];
+      printTable(data, [
+        { key: 'iata_code', label: 'IATA' },
+        { key: 'icao_code', label: 'ICAO' },
+        { key: 'name', label: 'Name' },
+        { key: 'country', label: 'Country' },
+        { key: 'active', label: 'Active', format: (v) => v ? 'Yes' : 'No' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// ROUTES
+// ============================================================
+
+const routesCmd = program.command('routes').description('Search and browse flight routes');
+
+routesCmd
+  .command('get')
+  .description('Get routes between airports')
+  .option('--from <iata>', 'Departure airport IATA code')
+  .option('--to <iata>', 'Arrival airport IATA code')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    if (!options.from && !options.to) {
+      printError('Please specify at least --from or --to');
+      process.exit(1);
+    }
+
+    try {
+      const routes = await withSpinner('Fetching routes...', () =>
+        getRoutes({ from: options.from, to: options.to })
+      );
+
+      if (options.json) {
+        printJson(routes);
+        return;
+      }
+
+      const data = Array.isArray(routes) ? routes : [];
+      printTable(data, [
+        { key: 'dep_iata', label: 'From' },
+        { key: 'arr_iata', label: 'To' },
+        { key: 'airline_iata', label: 'Airline' },
+        { key: 'codeshare', label: 'Codeshare', format: (v) => v ? 'Yes' : 'No' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+routesCmd
+  .command('search')
+  .description('Search routes with filters')
+  .option('--from <iata>', 'Departure airport IATA code')
+  .option('--to <iata>', 'Arrival airport IATA code')
+  .option('--airline <iata>', 'Filter by airline IATA code')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    try {
+      const routes = await withSpinner('Searching routes...', () =>
+        searchRoutes({ from: options.from, to: options.to, airline: options.airline })
+      );
+
+      if (options.json) {
+        printJson(routes);
+        return;
+      }
+
+      const data = Array.isArray(routes) ? routes : [];
+      printTable(data, [
+        { key: 'dep_iata', label: 'From' },
+        { key: 'arr_iata', label: 'To' },
+        { key: 'airline_iata', label: 'Airline' },
+        { key: 'codeshare', label: 'Codeshare', format: (v) => v ? 'Yes' : 'No' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Parse
+// ============================================================
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  program.help();
+}