@ktmcp-cli/adafruit 1.0.0

package/AGENT.md

@@ -0,0 +1,46 @@
+# Adafruit IO CLI - AI Agent Guide
+
+This CLI provides programmatic access to the Adafruit IO IoT Platform API.
+
+## Quick Start for AI Agents
+
+```bash
+adafruit config set --api-key YOUR_AIO_KEY
+adafruit config set --username YOUR_USERNAME
+adafruit feeds list
+```
+
+## Available Commands
+
+### config
+- `adafruit config set --api-key <key>` - Set Adafruit IO API key
+- `adafruit config set --username <user>` - Set Adafruit IO username
+- `adafruit config get <key>` - Get a config value
+- `adafruit config list` - List all config values
+
+### feeds
+- `adafruit feeds list` - List all feeds
+- `adafruit feeds get <feed-key>` - Get feed details
+- `adafruit feeds create --name <name>` - Create a new feed
+
+### data
+- `adafruit data send <feed-key> <value>` - Send data to a feed
+- `adafruit data send <feed-key> <value> --lat <lat> --lon <lon>` - Send with GPS
+- `adafruit data get <feed-key> <data-id>` - Get a specific data point
+- `adafruit data list <feed-key>` - List recent data points
+- `adafruit data list <feed-key> --limit <n>` - List with limit
+- `adafruit data list <feed-key> --start <iso> --end <iso>` - List by date range
+
+### dashboards
+- `adafruit dashboards list` - List all dashboards
+- `adafruit dashboards get <dashboard-key>` - Get dashboard details
+- `adafruit dashboards create --name <name>` - Create a new dashboard
+
+## Output Format
+
+All commands output formatted tables by default. Use `--json` flag for machine-readable JSON output.
+
+## Authentication
+
+This CLI uses your Adafruit IO AIO Key for authentication. Get your key at https://io.adafruit.com/api/docs/
+Rate limit: 30 data points/minute on free plan.

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,96 @@
+> "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/)
+
+# Adafruit IO CLI
+
+Production-ready CLI for Adafruit IO IoT Platform API.
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/adafruit
+```
+
+## Configuration
+
+```bash
+adafruit config set --api-key YOUR_AIO_KEY
+adafruit config set --username YOUR_USERNAME
+```
+
+Get your AIO key from: https://io.adafruit.com/api/docs/
+
+## Usage
+
+### Feeds
+
+```bash
+# List all feeds
+adafruit feeds list
+
+# Get feed details
+adafruit feeds get temperature-sensor
+
+# Create a new feed
+adafruit feeds create --name "Temperature" --description "Indoor temp" --visibility private
+adafruit feeds create --name "GPS Location" --visibility public
+```
+
+### Data
+
+```bash
+# Send a data point to a feed
+adafruit data send temperature-sensor 72.5
+
+# Send with GPS location
+adafruit data send gps-tracker 1 --lat 40.7128 --lon -74.0060
+
+# Get a specific data point
+adafruit data get temperature-sensor <data-id>
+
+# List recent data points
+adafruit data list temperature-sensor --limit 50
+adafruit data list temperature-sensor --start 2024-01-01T00:00:00Z --end 2024-01-31T23:59:59Z
+```
+
+### Dashboards
+
+```bash
+# List all dashboards
+adafruit dashboards list
+
+# Get dashboard details
+adafruit dashboards get my-home-dashboard
+
+# Create a dashboard
+adafruit dashboards create --name "Home Monitoring" --description "Temperature and humidity"
+```
+
+### Configuration
+
+```bash
+adafruit config set --api-key YOUR_KEY
+adafruit config set --username YOUR_USERNAME
+adafruit config get username
+adafruit config list
+```
+
+## JSON Output
+
+All commands support `--json` flag for machine-readable output:
+
+```bash
+adafruit feeds list --json
+adafruit data list temperature-sensor --json
+```
+
+## Rate Limits
+
+- Free plan: 30 data points per minute
+- Plus plan: 60 data points per minute
+
+## License
+
+MIT

package/bin/adafruit.js

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ktmcp-cli/adafruit",
+  "version": "1.0.0",
+  "description": "Production-ready CLI for Adafruit IO IoT Platform API - Kill The MCP",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "adafruit": "bin/adafruit.js"
+  },
+  "keywords": ["adafruit", "iot", "cli", "api", "ktmcp", "feeds", "dashboards", "hardware"],
+  "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/adafruit.git"
+  },
+  "homepage": "https://killthemcp.com/adafruit-cli",
+  "bugs": { "url": "https://github.com/ktmcp-cli/adafruit/issues" }
+}

package/src/api.js

@@ -0,0 +1,169 @@
+import axios from 'axios';
+import { getConfig } from './config.js';
+
+const BASE_URL = 'https://io.adafruit.com/api/v2';
+
+function getClient() {
+  const apiKey = getConfig('apiKey');
+  const username = getConfig('username');
+
+  if (!apiKey || !username) {
+    throw new Error('Adafruit IO credentials not configured. Run: adafruit config set --api-key YOUR_KEY --username YOUR_USERNAME');
+  }
+
+  return axios.create({
+    baseURL: BASE_URL,
+    headers: {
+      'X-AIO-Key': apiKey,
+      'Content-Type': 'application/json',
+      'Accept': 'application/json'
+    }
+  });
+}
+
+function getUsername() {
+  return getConfig('username');
+}
+
+function handleApiError(error) {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+    if (status === 401) throw new Error('Authentication failed. Check your Adafruit IO API key.');
+    if (status === 403) throw new Error('Access forbidden. Check your API key permissions.');
+    if (status === 404) throw new Error('Resource not found on Adafruit IO.');
+    if (status === 429) throw new Error('Rate limit exceeded. Free plan allows 30 data points/minute.');
+    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 Adafruit IO API. Check your internet connection.');
+  } else {
+    throw error;
+  }
+}
+
+// ============================================================
+// FEEDS
+// ============================================================
+
+export async function listFeeds() {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.get(`/${username}/feeds`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getFeed(feedKey) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.get(`/${username}/feeds/${feedKey}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function createFeed({ name, description, visibility = 'private' }) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.post(`/${username}/feeds`, {
+      feed: { name, description, visibility }
+    });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// DATA
+// ============================================================
+
+export async function sendData(feedKey, value, { lat, lon, ele, createdAt } = {}) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const body = { value: String(value) };
+    if (lat !== undefined) body.lat = lat;
+    if (lon !== undefined) body.lon = lon;
+    if (ele !== undefined) body.ele = ele;
+    if (createdAt) body.created_at = createdAt;
+
+    const response = await client.post(`/${username}/feeds/${feedKey}/data`, body);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getData(feedKey, dataId) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.get(`/${username}/feeds/${feedKey}/data/${dataId}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function listData(feedKey, { limit = 100, startTime, endTime } = {}) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const params = { limit };
+    if (startTime) params.start_time = startTime;
+    if (endTime) params.end_time = endTime;
+
+    const response = await client.get(`/${username}/feeds/${feedKey}/data`, { params });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// DASHBOARDS
+// ============================================================
+
+export async function listDashboards() {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.get(`/${username}/dashboards`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getDashboard(dashboardKey) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.get(`/${username}/dashboards/${dashboardKey}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function createDashboard({ name, description }) {
+  try {
+    const client = getClient();
+    const username = getUsername();
+    const response = await client.post(`/${username}/dashboards`, {
+      name,
+      description
+    });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}

package/src/config.js

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

package/src/index.js

@@ -0,0 +1,373 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getConfig, setConfig, isConfigured, getAllConfig } from './config.js';
+import {
+  listFeeds, getFeed, createFeed,
+  sendData, getData, listData,
+  listDashboards, getDashboard, createDashboard
+} 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('Adafruit IO credentials not configured.');
+    console.log('\nRun the following to configure:');
+    console.log(chalk.cyan('  adafruit config set --api-key YOUR_AIO_KEY --username YOUR_USERNAME'));
+    process.exit(1);
+  }
+}
+
+// ============================================================
+// Program metadata
+// ============================================================
+
+program
+  .name('adafruit')
+  .description(chalk.bold('Adafruit IO CLI') + ' - IoT feeds and dashboards 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>', 'Adafruit IO API key (AIO Key)')
+  .option('--username <user>', 'Adafruit IO username')
+  .action((options) => {
+    if (options.apiKey) { setConfig('apiKey', options.apiKey); printSuccess('API key set'); }
+    if (options.username) { setConfig('username', options.username); printSuccess(`Username set: ${options.username}`); }
+    if (!options.apiKey && !options.username) {
+      printError('No options provided. Use --api-key or --username');
+    }
+  });
+
+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('list')
+  .description('List all configuration values')
+  .action(() => {
+    const all = getAllConfig();
+    console.log(chalk.bold('\nAdafruit IO CLI Configuration\n'));
+    console.log('API Key:  ', all.apiKey ? chalk.green('aio_' + '*'.repeat(20)) : chalk.red('not set'));
+    console.log('Username: ', all.username ? chalk.green(all.username) : chalk.red('not set'));
+    console.log('');
+  });
+
+// ============================================================
+// FEEDS
+// ============================================================
+
+const feedsCmd = program.command('feeds').description('Manage Adafruit IO feeds');
+
+feedsCmd
+  .command('list')
+  .description('List all feeds')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const feeds = await withSpinner('Fetching feeds...', () => listFeeds());
+      if (options.json) { printJson(feeds); return; }
+      printTable(feeds, [
+        { key: 'id', label: 'ID' },
+        { key: 'name', label: 'Name' },
+        { key: 'key', label: 'Key' },
+        { key: 'visibility', label: 'Visibility' },
+        { key: 'last_value', label: 'Last Value' },
+        { key: 'status', label: 'Status' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+feedsCmd
+  .command('get <feed-key>')
+  .description('Get details of a specific feed')
+  .option('--json', 'Output as JSON')
+  .action(async (feedKey, options) => {
+    requireAuth();
+    try {
+      const feed = await withSpinner('Fetching feed...', () => getFeed(feedKey));
+      if (options.json) { printJson(feed); return; }
+      console.log(chalk.bold('\nFeed Details\n'));
+      console.log('ID:          ', chalk.cyan(feed.id));
+      console.log('Name:        ', chalk.bold(feed.name));
+      console.log('Key:         ', feed.key);
+      console.log('Visibility:  ', feed.visibility);
+      console.log('Last Value:  ', feed.last_value !== null ? chalk.green(feed.last_value) : chalk.dim('no data'));
+      console.log('Unit Symbol: ', feed.unit_symbol || 'N/A');
+      console.log('Unit Type:   ', feed.unit_type || 'N/A');
+      console.log('Status:      ', feed.status || 'N/A');
+      console.log('Created:     ', feed.created_at || 'N/A');
+      console.log('Updated:     ', feed.updated_at || 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+feedsCmd
+  .command('create')
+  .description('Create a new feed')
+  .requiredOption('--name <name>', 'Feed name')
+  .option('--description <desc>', 'Feed description')
+  .option('--visibility <vis>', 'Feed visibility (public|private)', 'private')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const feed = await withSpinner('Creating feed...', () =>
+        createFeed({ name: options.name, description: options.description, visibility: options.visibility })
+      );
+      if (options.json) { printJson(feed); return; }
+      printSuccess(`Feed created: ${chalk.bold(feed.name)}`);
+      console.log('Key:        ', feed.key);
+      console.log('Visibility: ', feed.visibility);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// DATA
+// ============================================================
+
+const dataCmd = program.command('data').description('Send and retrieve feed data');
+
+dataCmd
+  .command('send <feed-key> <value>')
+  .description('Send a data point to a feed')
+  .option('--lat <lat>', 'Latitude for location data')
+  .option('--lon <lon>', 'Longitude for location data')
+  .option('--ele <ele>', 'Elevation for location data')
+  .option('--json', 'Output as JSON')
+  .action(async (feedKey, value, options) => {
+    requireAuth();
+    try {
+      const dataPoint = await withSpinner(`Sending value "${value}" to feed "${feedKey}"...`, () =>
+        sendData(feedKey, value, {
+          lat: options.lat,
+          lon: options.lon,
+          ele: options.ele
+        })
+      );
+      if (options.json) { printJson(dataPoint); return; }
+      printSuccess(`Data sent to ${chalk.bold(feedKey)}`);
+      console.log('ID:         ', dataPoint.id);
+      console.log('Value:      ', chalk.green(dataPoint.value));
+      console.log('Created At: ', dataPoint.created_at);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+dataCmd
+  .command('get <feed-key> <data-id>')
+  .description('Get a specific data point from a feed')
+  .option('--json', 'Output as JSON')
+  .action(async (feedKey, dataId, options) => {
+    requireAuth();
+    try {
+      const dataPoint = await withSpinner('Fetching data point...', () => getData(feedKey, dataId));
+      if (options.json) { printJson(dataPoint); return; }
+      console.log(chalk.bold('\nData Point\n'));
+      console.log('ID:         ', chalk.cyan(dataPoint.id));
+      console.log('Value:      ', chalk.green(dataPoint.value));
+      console.log('Created At: ', dataPoint.created_at);
+      if (dataPoint.lat) console.log('Location:   ', `${dataPoint.lat}, ${dataPoint.lon}`);
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+dataCmd
+  .command('list <feed-key>')
+  .description('List data points from a feed')
+  .option('--limit <n>', 'Maximum number of points', '100')
+  .option('--start <time>', 'Start time (ISO 8601)')
+  .option('--end <time>', 'End time (ISO 8601)')
+  .option('--json', 'Output as JSON')
+  .action(async (feedKey, options) => {
+    requireAuth();
+    try {
+      const data = await withSpinner('Fetching data...', () =>
+        listData(feedKey, {
+          limit: parseInt(options.limit),
+          startTime: options.start,
+          endTime: options.end
+        })
+      );
+      if (options.json) { printJson(data); return; }
+      printTable(data, [
+        { key: 'id', label: 'ID' },
+        { key: 'value', label: 'Value' },
+        { key: 'created_at', label: 'Created At' },
+        { key: 'lat', label: 'Lat', format: (v) => v || 'N/A' },
+        { key: 'lon', label: 'Lon', format: (v) => v || 'N/A' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// DASHBOARDS
+// ============================================================
+
+const dashboardsCmd = program.command('dashboards').description('Manage Adafruit IO dashboards');
+
+dashboardsCmd
+  .command('list')
+  .description('List all dashboards')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const dashboards = await withSpinner('Fetching dashboards...', () => listDashboards());
+      if (options.json) { printJson(dashboards); return; }
+      printTable(dashboards, [
+        { key: 'id', label: 'ID' },
+        { key: 'name', label: 'Name' },
+        { key: 'key', label: 'Key' },
+        { key: 'description', label: 'Description' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+dashboardsCmd
+  .command('get <dashboard-key>')
+  .description('Get details of a specific dashboard')
+  .option('--json', 'Output as JSON')
+  .action(async (dashboardKey, options) => {
+    requireAuth();
+    try {
+      const dashboard = await withSpinner('Fetching dashboard...', () => getDashboard(dashboardKey));
+      if (options.json) { printJson(dashboard); return; }
+      console.log(chalk.bold('\nDashboard Details\n'));
+      console.log('ID:          ', chalk.cyan(dashboard.id));
+      console.log('Name:        ', chalk.bold(dashboard.name));
+      console.log('Key:         ', dashboard.key);
+      console.log('Description: ', dashboard.description || 'N/A');
+      console.log('Created:     ', dashboard.created_at || 'N/A');
+      console.log('Updated:     ', dashboard.updated_at || 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+dashboardsCmd
+  .command('create')
+  .description('Create a new dashboard')
+  .requiredOption('--name <name>', 'Dashboard name')
+  .option('--description <desc>', 'Dashboard description')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const dashboard = await withSpinner('Creating dashboard...', () =>
+        createDashboard({ name: options.name, description: options.description })
+      );
+      if (options.json) { printJson(dashboard); return; }
+      printSuccess(`Dashboard created: ${chalk.bold(dashboard.name)}`);
+      console.log('ID:  ', dashboard.id);
+      console.log('Key: ', dashboard.key);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Parse
+// ============================================================
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  program.help();
+}