@ktmcp-cli/abstractapi 1.0.0

package/AGENT.md

@@ -0,0 +1,36 @@
+# AbstractAPI CLI - AI Agent Guide
+
+This CLI provides programmatic access to the AbstractAPI Geolocation API.
+
+## Quick Start for AI Agents
+
+```bash
+abstractapi config set --api-key YOUR_KEY
+abstractapi geolocate current
+abstractapi geolocate lookup 8.8.8.8
+```
+
+## Available Commands
+
+### config
+- `abstractapi config set --api-key <key>` - Set API key
+- `abstractapi config get <key>` - Get config value
+- `abstractapi config list` - Show all config
+
+### geolocate
+- `abstractapi geolocate lookup <ip>` - Look up geolocation for an IP address
+- `abstractapi geolocate current` - Look up your own current IP's geolocation
+
+### vpn
+- `abstractapi vpn detect [ip]` - Detect if IP is using VPN/proxy (omit IP for your own)
+
+### timezone
+- `abstractapi timezone get [--ip <ip>] [--location <location>]` - Get timezone info
+- `abstractapi timezone current` - Get timezone for your current IP
+
+## Tips for Agents
+
+- All commands support `--json` for machine-readable output
+- Pipe to `jq`: `abstractapi geolocate lookup 8.8.8.8 --json | jq '{city, country, timezone}'`
+- Omit IP in vpn detect to check your own IP
+- Location strings work for timezone: "London", "New York", "51.5,-0.09"

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,116 @@
+> "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/)
+
+# AbstractAPI CLI
+
+Production-ready CLI for the [AbstractAPI](https://abstractapi.com) Geolocation API. Look up IP addresses, detect VPNs, and get timezone information directly from your terminal.
+
+> **Disclaimer**: This is an unofficial CLI tool and is not affiliated with, endorsed by, or supported by Abstract API.
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/abstractapi
+```
+
+## Configuration
+
+```bash
+abstractapi config set --api-key YOUR_API_KEY
+```
+
+Get your API key at [abstractapi.com](https://abstractapi.com).
+
+## Usage
+
+### Configuration
+
+```bash
+# Set API key
+abstractapi config set --api-key YOUR_API_KEY
+
+# Show configuration
+abstractapi config list
+
+# Get a specific config value
+abstractapi config get apiKey
+```
+
+### Geolocation
+
+```bash
+# Look up an IP address
+abstractapi geolocate lookup 8.8.8.8
+abstractapi geolocate lookup 1.1.1.1
+
+# Look up your own current IP
+abstractapi geolocate current
+```
+
+### VPN Detection
+
+```bash
+# Detect if an IP is using a VPN or proxy
+abstractapi vpn detect 8.8.8.8
+
+# Check your own IP
+abstractapi vpn detect
+```
+
+### Timezone
+
+```bash
+# Get timezone for an IP
+abstractapi timezone get --ip 8.8.8.8
+
+# Get timezone by location name
+abstractapi timezone get --location "London"
+abstractapi timezone get --location "New York"
+
+# Get timezone for your current IP
+abstractapi timezone current
+```
+
+### JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+# Look up IP as JSON
+abstractapi geolocate lookup 8.8.8.8 --json
+
+# Pipe to jq
+abstractapi geolocate lookup 1.1.1.1 --json | jq '{city, country, timezone}'
+
+# Get your timezone as JSON
+abstractapi timezone current --json | jq '.timezone'
+```
+
+## Examples
+
+```bash
+# Find where a suspicious IP is located
+abstractapi geolocate lookup 192.168.1.1
+
+# Check if your VPN is working
+abstractapi vpn detect
+
+# Find timezone for a remote meeting participant
+abstractapi timezone get --ip 123.456.789.0
+
+# Script: Get country code for multiple IPs
+for ip in 8.8.8.8 1.1.1.1 9.9.9.9; do
+  echo -n "$ip: "
+  abstractapi geolocate lookup $ip --json | jq -r '.country_code'
+done
+```
+
+## License
+
+MIT
+
+---
+
+Part of the [KTMCP CLI](https://killthemcp.com) project — replacing MCPs with simple, composable CLIs.

package/bin/abstractapi.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ktmcp-cli/abstractapi",
+  "version": "1.0.0",
+  "description": "Production-ready CLI for Abstract API Geolocation - Kill The MCP",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "abstractapi": "bin/abstractapi.js"
+  },
+  "keywords": ["abstractapi", "geolocation", "ip", "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/abstractapi.git"
+  },
+  "homepage": "https://killthemcp.com/abstractapi-cli",
+  "bugs": { "url": "https://github.com/ktmcp-cli/abstractapi/issues" }
+}

package/src/api.js

@@ -0,0 +1,81 @@
+import axios from 'axios';
+import { getConfig } from './config.js';
+
+const BASE_URL = 'https://ipgeolocation.abstractapi.com/v1';
+
+function getApiKey() {
+  const apiKey = getConfig('apiKey');
+  if (!apiKey) {
+    throw new Error('API key not configured. Run: abstractapi config set apiKey YOUR_API_KEY');
+  }
+  return apiKey;
+}
+
+function handleApiError(error) {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+    if (status === 401 || status === 403) {
+      throw new Error('Authentication failed. Check your API key: abstractapi config set apiKey YOUR_KEY');
+    } else if (status === 429) {
+      throw new Error('Rate limit exceeded. Please wait before retrying.');
+    } else if (status === 404) {
+      throw new Error('Resource not found.');
+    } else {
+      const message = data?.error?.message || data?.message || JSON.stringify(data);
+      throw new Error(`API Error (${status}): ${message}`);
+    }
+  } else if (error.request) {
+    throw new Error('No response from AbstractAPI. Check your internet connection.');
+  } else {
+    throw error;
+  }
+}
+
+async function apiGet(url, params = {}) {
+  const apiKey = getApiKey();
+  try {
+    const response = await axios.get(url, {
+      params: { api_key: apiKey, ...params }
+    });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// GEOLOCATE
+// ============================================================
+
+export async function lookupIp(ipAddress) {
+  return await apiGet(BASE_URL + '/', { ip_address: ipAddress });
+}
+
+export async function lookupCurrent() {
+  return await apiGet(BASE_URL + '/');
+}
+
+// ============================================================
+// VPN DETECTION
+// ============================================================
+
+export async function detectVpn(ipAddress) {
+  const params = ipAddress ? { ip_address: ipAddress } : {};
+  return await apiGet('https://vpndetection.abstractapi.com/v1/', params);
+}
+
+// ============================================================
+// TIMEZONE
+// ============================================================
+
+export async function getTimezone({ ipAddress, location }) {
+  const params = {};
+  if (ipAddress) params.ip_address = ipAddress;
+  if (location) params.location = location;
+  return await apiGet('https://timezone.abstractapi.com/v1/', params);
+}
+
+export async function getCurrentTimezone() {
+  return await apiGet('https://timezone.abstractapi.com/v1/');
+}

package/src/config.js

@@ -0,0 +1,19 @@
+import Conf from 'conf';
+
+const config = new Conf({ projectName: '@ktmcp-cli/abstractapi' });
+
+export function getConfig(key) {
+  return config.get(key);
+}
+
+export function setConfig(key, value) {
+  config.set(key, value);
+}
+
+export function isConfigured() {
+  return !!config.get('apiKey');
+}
+
+export function getAllConfig() {
+  return config.store;
+}

package/src/index.js

@@ -0,0 +1,251 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getConfig, setConfig, isConfigured, getAllConfig } from './config.js';
+import {
+  lookupIp,
+  lookupCurrent,
+  detectVpn,
+  getTimezone,
+  getCurrentTimezone
+} 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 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;
+  }
+}
+
+function requireAuth() {
+  if (!isConfigured()) {
+    printError('AbstractAPI key not configured.');
+    console.log('\nRun the following to configure:');
+    console.log(chalk.cyan('  abstractapi config set apiKey YOUR_API_KEY'));
+    process.exit(1);
+  }
+}
+
+function printGeoResult(data) {
+  console.log(chalk.bold('\nGeolocation Result\n'));
+  console.log('IP Address:  ', chalk.cyan(data.ip_address || 'N/A'));
+  console.log('City:        ', data.city || 'N/A');
+  console.log('Region:      ', data.region || 'N/A');
+  console.log('Country:     ', `${data.country || 'N/A'} (${data.country_code || '??'})`);
+  console.log('Continent:   ', data.continent || 'N/A');
+  console.log('Latitude:    ', data.latitude ?? 'N/A');
+  console.log('Longitude:   ', data.longitude ?? 'N/A');
+  console.log('Timezone:    ', data.timezone?.name || 'N/A');
+  console.log('Currency:    ', data.currency?.currency_name ? `${data.currency.currency_name} (${data.currency.currency_code})` : 'N/A');
+  console.log('ISP:         ', data.connection?.isp_name || data.connection?.autonomous_system_organization || 'N/A');
+  console.log('');
+}
+
+// ============================================================
+// Program metadata
+// ============================================================
+
+program
+  .name('abstractapi')
+  .description(chalk.bold('AbstractAPI CLI') + ' - IP geolocation & detection from your terminal')
+  .version('1.0.0');
+
+// ============================================================
+// CONFIG
+// ============================================================
+
+const configCmd = program.command('config').description('Manage CLI configuration');
+
+configCmd
+  .command('set')
+  .description('Set configuration values')
+  .option('--api-key <key>', 'AbstractAPI API key')
+  .action((options) => {
+    if (options.apiKey) {
+      setConfig('apiKey', options.apiKey);
+      printSuccess('API key set');
+    } else {
+      printError('No options provided. Use --api-key');
+    }
+  });
+
+configCmd
+  .command('get')
+  .description('Get a configuration value')
+  .argument('<key>', 'Config key to retrieve')
+  .action((key) => {
+    const value = getConfig(key);
+    if (value === undefined || value === null || value === '') {
+      console.log(chalk.yellow(`${key}: not set`));
+    } else {
+      const masked = key.toLowerCase().includes('key') ? '*'.repeat(8) : value;
+      console.log(`${key}: ${chalk.green(masked)}`);
+    }
+  });
+
+configCmd
+  .command('list')
+  .description('List all configuration values')
+  .action(() => {
+    const all = getAllConfig();
+    console.log(chalk.bold('\nAbstractAPI CLI Configuration\n'));
+    console.log('API Key:', all.apiKey ? chalk.green('*'.repeat(8)) : chalk.red('not set'));
+    console.log('');
+  });
+
+// ============================================================
+// GEOLOCATE
+// ============================================================
+
+const geoCmd = program.command('geolocate').description('IP geolocation lookup');
+
+geoCmd
+  .command('lookup <ip>')
+  .description('Look up geolocation data for an IP address')
+  .option('--json', 'Output as JSON')
+  .action(async (ip, options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner(`Looking up IP ${ip}...`, () => lookupIp(ip));
+      if (options.json) { printJson(data); return; }
+      printGeoResult(data);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+geoCmd
+  .command('current')
+  .description('Look up geolocation data for your current IP address')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner('Looking up your IP address...', () => lookupCurrent());
+      if (options.json) { printJson(data); return; }
+      printGeoResult(data);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// VPN DETECTION
+// ============================================================
+
+const vpnCmd = program.command('vpn').description('VPN and proxy detection');
+
+vpnCmd
+  .command('detect')
+  .description('Detect if an IP address is using a VPN or proxy')
+  .argument('[ip]', 'IP address to check (omit for your current IP)')
+  .option('--json', 'Output as JSON')
+  .action(async (ip, options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner(`Checking VPN status${ip ? ` for ${ip}` : ''}...`, () => detectVpn(ip));
+      if (options.json) { printJson(data); return; }
+      console.log(chalk.bold('\nVPN Detection Result\n'));
+      console.log('IP Address:   ', chalk.cyan(data.ip_address || ip || 'N/A'));
+      const isVpn = data.is_vpn ?? data.vpn ?? false;
+      const isProxy = data.is_proxy ?? data.proxy ?? false;
+      const isTor = data.is_tor ?? data.tor ?? false;
+      console.log('VPN:          ', isVpn ? chalk.red('Yes') : chalk.green('No'));
+      console.log('Proxy:        ', isProxy ? chalk.red('Yes') : chalk.green('No'));
+      console.log('Tor:          ', isTor ? chalk.red('Yes') : chalk.green('No'));
+      if (data.service) console.log('Service:      ', data.service);
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// TIMEZONE
+// ============================================================
+
+const tzCmd = program.command('timezone').description('Timezone lookup');
+
+tzCmd
+  .command('get')
+  .description('Get timezone information for an IP address or location')
+  .option('--ip <ip>', 'IP address to look up')
+  .option('--location <location>', 'Location name or coordinates (e.g. "London" or "51.5,-0.09")')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner('Fetching timezone data...', () =>
+        getTimezone({ ipAddress: options.ip, location: options.location })
+      );
+      if (options.json) { printJson(data); return; }
+      console.log(chalk.bold('\nTimezone Information\n'));
+      console.log('Timezone:     ', chalk.cyan(data.timezone || 'N/A'));
+      console.log('Abbreviation: ', data.abbreviation || data.timezone_abbreviation || 'N/A');
+      console.log('GMT Offset:   ', data.gmt_offset ?? 'N/A');
+      console.log('Current Time: ', data.datetime || data.current_time || 'N/A');
+      console.log('Is DST:       ', data.is_dst !== undefined ? (data.is_dst ? chalk.yellow('Yes') : 'No') : 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+tzCmd
+  .command('current')
+  .description('Get timezone information for your current IP address')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner('Fetching your timezone...', () => getCurrentTimezone());
+      if (options.json) { printJson(data); return; }
+      console.log(chalk.bold('\nYour Timezone Information\n'));
+      console.log('Timezone:     ', chalk.cyan(data.timezone || 'N/A'));
+      console.log('Abbreviation: ', data.abbreviation || data.timezone_abbreviation || 'N/A');
+      console.log('GMT Offset:   ', data.gmt_offset ?? 'N/A');
+      console.log('Current Time: ', data.datetime || data.current_time || 'N/A');
+      console.log('Is DST:       ', data.is_dst !== undefined ? (data.is_dst ? chalk.yellow('Yes') : 'No') : 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Parse
+// ============================================================
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  program.help();
+}