@ktmcp-cli/aiception 1.0.0

package/AGENT.md

@@ -0,0 +1,44 @@
+# AIception CLI - AI Agent Guide
+
+This CLI provides programmatic access to the AIception Image Recognition API.
+
+## Quick Start for AI Agents
+
+```bash
+aiception config set --username YOUR_USER --password YOUR_PASS
+aiception images analyze https://example.com/image.jpg
+aiception tasks get TASK_ID
+```
+
+## Available Commands
+
+### config
+- `aiception config set --username <user> --password <pass>` - Set credentials
+- `aiception config get <key>` - Get config value
+- `aiception config list` - Show all config
+
+### images
+- `aiception images analyze <url>` - Analyze image content
+- `aiception images classify <url>` - Classify image into categories
+- `aiception images detect-objects <url>` - Detect objects in image
+
+### tasks
+- `aiception tasks get <task-id>` - Get async task result
+- `aiception tasks list` - List recent tasks
+
+### nudity
+- `aiception nudity detect <url>` - Detect nudity in image
+
+## Async Processing Workflow
+
+AIception uses async processing. The typical workflow:
+
+1. Submit image: `aiception images analyze <url> --json | jq -r '.task_id'`
+2. Wait for processing
+3. Get result: `aiception tasks get <task-id> --json`
+
+## Tips for Agents
+
+- All commands support `--json` for machine-readable output
+- Image commands return a task_id for async polling
+- Use `--json` and `jq` to extract task IDs automatically

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,128 @@
+> "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/)
+
+# AIception CLI
+
+Production-ready CLI for the [AIception](https://aiception.com) Image Recognition API. Analyze images, detect objects, classify content, and detect nudity directly from your terminal.
+
+> **Disclaimer**: This is an unofficial CLI tool and is not affiliated with, endorsed by, or supported by AIception.
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/aiception
+```
+
+## Configuration
+
+```bash
+aiception config set --username YOUR_USERNAME --password YOUR_PASSWORD
+```
+
+Get your credentials at [aiception.com](https://aiception.com).
+
+## Usage
+
+### Configuration
+
+```bash
+# Set credentials
+aiception config set --username YOUR_USERNAME --password YOUR_PASSWORD
+
+# Show configuration
+aiception config list
+
+# Get a specific config value
+aiception config get username
+```
+
+### Image Analysis
+
+```bash
+# Analyze an image and get a description
+aiception images analyze https://example.com/image.jpg
+
+# Classify an image into categories
+aiception images classify https://example.com/photo.png
+
+# Detect objects in an image
+aiception images detect-objects https://example.com/scene.jpg
+```
+
+### Task Management
+
+AIception processes images asynchronously. Use task commands to retrieve results:
+
+```bash
+# Get the result of a processing task
+aiception tasks get TASK_ID
+
+# List all recent tasks
+aiception tasks list
+```
+
+### Nudity Detection
+
+```bash
+# Detect nudity in an image
+aiception nudity detect https://example.com/image.jpg
+```
+
+### JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+# Analyze image and get task ID as JSON
+aiception images analyze https://example.com/image.jpg --json
+
+# Get task result as JSON
+aiception tasks get TASK_ID --json | jq '.result'
+
+# Check nudity detection result
+aiception nudity detect https://example.com/image.jpg --json | jq '{nude: .nude, confidence: .confidence}'
+```
+
+## Workflow Example
+
+AIception uses asynchronous processing. Here's a typical workflow:
+
+```bash
+# 1. Submit an image for analysis
+aiception images analyze https://example.com/photo.jpg
+# Note the Task ID from the output
+
+# 2. Poll for the result
+aiception tasks get TASK_ID
+
+# 3. Or get it as JSON for scripting
+aiception tasks get TASK_ID --json | jq '.result'
+```
+
+## Examples
+
+```bash
+# Classify a product image
+aiception images classify https://shop.example.com/product.jpg
+
+# Detect objects in a scene
+aiception images detect-objects https://example.com/street.jpg --json | jq '.objects'
+
+# Moderate user-uploaded content
+aiception nudity detect https://upload.example.com/user123/photo.jpg
+
+# Batch analyze images
+for url in url1 url2 url3; do
+  aiception images analyze $url --json | jq -r '.task_id'
+done
+```
+
+## License
+
+MIT
+
+---
+
+Part of the [KTMCP CLI](https://killthemcp.com) project — replacing MCPs with simple, composable CLIs.

package/bin/aiception.js

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

package/package.json

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

package/src/api.js

@@ -0,0 +1,90 @@
+import axios from 'axios';
+import { getConfig } from './config.js';
+
+const BASE_URL = 'https://aiception.com/api/v2.1';
+
+function getAuth() {
+  const username = getConfig('username');
+  const password = getConfig('password');
+  if (!username || !password) {
+    throw new Error('Credentials not configured. Run: aiception config set username YOUR_USER and aiception config set password YOUR_PASS');
+  }
+  return { username, password };
+}
+
+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 username/password credentials.');
+    } 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 || data?.message || JSON.stringify(data);
+      throw new Error(`API Error (${status}): ${message}`);
+    }
+  } else if (error.request) {
+    throw new Error('No response from AIception API. Check your internet connection.');
+  } else {
+    throw error;
+  }
+}
+
+async function apiGet(path) {
+  const auth = getAuth();
+  try {
+    const response = await axios.get(`${BASE_URL}${path}`, { auth });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+async function apiPost(path, data = {}) {
+  const auth = getAuth();
+  try {
+    const response = await axios.post(`${BASE_URL}${path}`, data, { auth });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// IMAGES
+// ============================================================
+
+export async function analyzeImage(imageUrl) {
+  return await apiPost('/image_understanding', { image_url: imageUrl });
+}
+
+export async function classifyImage(imageUrl) {
+  return await apiPost('/classify', { image_url: imageUrl });
+}
+
+export async function detectObjects(imageUrl) {
+  return await apiPost('/detect_objects', { image_url: imageUrl });
+}
+
+// ============================================================
+// NUDITY DETECTION
+// ============================================================
+
+export async function detectNudity(imageUrl) {
+  return await apiPost('/detect_nudity', { image_url: imageUrl });
+}
+
+// ============================================================
+// TASKS
+// ============================================================
+
+export async function getTask(taskId) {
+  return await apiGet(`/task/${taskId}`);
+}
+
+export async function listTasks() {
+  return await apiGet('/tasks');
+}

package/src/config.js

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

package/src/index.js

@@ -0,0 +1,333 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getConfig, setConfig, isConfigured, getAllConfig } from './config.js';
+import {
+  analyzeImage,
+  classifyImage,
+  detectObjects,
+  detectNudity,
+  getTask,
+  listTasks
+} 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;
+  }
+}
+
+function requireAuth() {
+  if (!isConfigured()) {
+    printError('AIception credentials not configured.');
+    console.log('\nRun the following to configure:');
+    console.log(chalk.cyan('  aiception config set --username YOUR_USERNAME --password YOUR_PASSWORD'));
+    process.exit(1);
+  }
+}
+
+// ============================================================
+// Program metadata
+// ============================================================
+
+program
+  .name('aiception')
+  .description(chalk.bold('AIception CLI') + ' - AI image recognition 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('--username <user>', 'AIception API username')
+  .option('--password <pass>', 'AIception API password')
+  .action((options) => {
+    let changed = false;
+    if (options.username) {
+      setConfig('username', options.username);
+      printSuccess('Username set');
+      changed = true;
+    }
+    if (options.password) {
+      setConfig('password', options.password);
+      printSuccess('Password set');
+      changed = true;
+    }
+    if (!changed) {
+      printError('No options provided. Use --username and/or --password');
+    }
+  });
+
+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('pass') ? '*'.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('\nAIception CLI Configuration\n'));
+    console.log('Username:', all.username ? chalk.green(all.username) : chalk.red('not set'));
+    console.log('Password:', all.password ? chalk.green('*'.repeat(8)) : chalk.red('not set'));
+    console.log('');
+  });
+
+// ============================================================
+// IMAGES
+// ============================================================
+
+const imagesCmd = program.command('images').description('Image analysis and recognition');
+
+imagesCmd
+  .command('analyze <url>')
+  .description('Analyze an image and get a description of its content')
+  .option('--json', 'Output as JSON')
+  .action(async (url, options) => {
+    requireAuth();
+    try {
+      const result = await withSpinner('Analyzing image...', () => analyzeImage(url));
+      if (options.json) { printJson(result); return; }
+      console.log(chalk.bold('\nImage Analysis\n'));
+      console.log('Image URL:', chalk.cyan(url));
+      if (result.task_id || result.id) {
+        console.log('Task ID:  ', chalk.yellow(result.task_id || result.id));
+        console.log('Status:   ', result.status || 'processing');
+        console.log('\nNote: Use', chalk.cyan(`aiception tasks get ${result.task_id || result.id}`), 'to retrieve results');
+      } else if (result.result || result.description) {
+        console.log('Result:   ', result.result || result.description);
+      } else {
+        printJson(result);
+      }
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+imagesCmd
+  .command('classify <url>')
+  .description('Classify an image into categories')
+  .option('--json', 'Output as JSON')
+  .action(async (url, options) => {
+    requireAuth();
+    try {
+      const result = await withSpinner('Classifying image...', () => classifyImage(url));
+      if (options.json) { printJson(result); return; }
+      console.log(chalk.bold('\nImage Classification\n'));
+      console.log('Image URL:', chalk.cyan(url));
+      if (result.task_id || result.id) {
+        console.log('Task ID:  ', chalk.yellow(result.task_id || result.id));
+        console.log('Status:   ', result.status || 'processing');
+        console.log('\nNote: Use', chalk.cyan(`aiception tasks get ${result.task_id || result.id}`), 'to retrieve results');
+      } else if (result.predictions || result.classes) {
+        const preds = result.predictions || result.classes || [];
+        const rows = Array.isArray(preds) ? preds : Object.entries(preds).map(([k, v]) => ({ label: k, confidence: v }));
+        printTable(rows, [
+          { key: 'label', label: 'Class' },
+          { key: 'confidence', label: 'Confidence', format: (v) => v !== undefined ? `${(parseFloat(v) * 100).toFixed(1)}%` : 'N/A' }
+        ]);
+      } else {
+        printJson(result);
+      }
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+imagesCmd
+  .command('detect-objects <url>')
+  .description('Detect and locate objects within an image')
+  .option('--json', 'Output as JSON')
+  .action(async (url, options) => {
+    requireAuth();
+    try {
+      const result = await withSpinner('Detecting objects...', () => detectObjects(url));
+      if (options.json) { printJson(result); return; }
+      console.log(chalk.bold('\nObject Detection\n'));
+      console.log('Image URL:', chalk.cyan(url));
+      if (result.task_id || result.id) {
+        console.log('Task ID:  ', chalk.yellow(result.task_id || result.id));
+        console.log('Status:   ', result.status || 'processing');
+        console.log('\nNote: Use', chalk.cyan(`aiception tasks get ${result.task_id || result.id}`), 'to retrieve results');
+      } else if (result.objects || result.detections) {
+        const objects = result.objects || result.detections || [];
+        printTable(objects, [
+          { key: 'label', label: 'Object' },
+          { key: 'confidence', label: 'Confidence', format: (v) => v !== undefined ? `${(parseFloat(v) * 100).toFixed(1)}%` : 'N/A' },
+          { key: 'bbox', label: 'Bounding Box', format: (v) => v ? JSON.stringify(v) : 'N/A' }
+        ]);
+      } else {
+        printJson(result);
+      }
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// TASKS
+// ============================================================
+
+const tasksCmd = program.command('tasks').description('Manage async processing tasks');
+
+tasksCmd
+  .command('get <task-id>')
+  .description('Get the result of an async processing task')
+  .option('--json', 'Output as JSON')
+  .action(async (taskId, options) => {
+    requireAuth();
+    try {
+      const task = await withSpinner(`Fetching task ${taskId}...`, () => getTask(taskId));
+      if (options.json) { printJson(task); return; }
+      console.log(chalk.bold('\nTask Details\n'));
+      console.log('Task ID:   ', chalk.cyan(taskId));
+      console.log('Status:    ', task.status === 'completed' ? chalk.green(task.status) : chalk.yellow(task.status || 'unknown'));
+      if (task.result) {
+        console.log('Result:    ', JSON.stringify(task.result, null, 2));
+      }
+      if (task.created_at) console.log('Created:   ', task.created_at);
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+tasksCmd
+  .command('list')
+  .description('List recent processing tasks')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const tasks = await withSpinner('Fetching tasks...', () => listTasks());
+      if (options.json) { printJson(tasks); return; }
+      const list = Array.isArray(tasks) ? tasks : (tasks?.tasks || tasks?.data || []);
+      printTable(list, [
+        { key: 'id', label: 'Task ID' },
+        { key: 'status', label: 'Status' },
+        { key: 'type', label: 'Type' },
+        { key: 'created_at', label: 'Created' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// NUDITY
+// ============================================================
+
+const nudityCmd = program.command('nudity').description('Nudity detection in images');
+
+nudityCmd
+  .command('detect <url>')
+  .description('Detect nudity content in an image')
+  .option('--json', 'Output as JSON')
+  .action(async (url, options) => {
+    requireAuth();
+    try {
+      const result = await withSpinner('Analyzing image for nudity...', () => detectNudity(url));
+      if (options.json) { printJson(result); return; }
+      console.log(chalk.bold('\nNudity Detection Result\n'));
+      console.log('Image URL:', chalk.cyan(url));
+      if (result.task_id || result.id) {
+        console.log('Task ID:  ', chalk.yellow(result.task_id || result.id));
+        console.log('Status:   ', result.status || 'processing');
+        console.log('\nNote: Use', chalk.cyan(`aiception tasks get ${result.task_id || result.id}`), 'to retrieve results');
+      } else {
+        const hasNudity = result.nude ?? result.has_nudity ?? false;
+        const confidence = result.confidence ?? result.score ?? 'N/A';
+        console.log('Contains Nudity:', hasNudity ? chalk.red('Yes') : chalk.green('No'));
+        console.log('Confidence:     ', confidence !== 'N/A' ? `${(parseFloat(confidence) * 100).toFixed(1)}%` : 'N/A');
+        if (result.raw) console.log('Raw Score:      ', result.raw);
+      }
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Parse
+// ============================================================
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  program.help();
+}