@switchbot/openapi-cli 2.0.1 → 2.1.0

package/README.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml)
 
 Command-line interface for the [SwitchBot API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI).
-List devices, query live status, send control commands, run scenes, and manage webhooks — all from your terminal or shell scripts.
+List devices, query live status, send control commands, run scenes, receive real-time events, and connect AI agents via the built-in MCP server — all from your terminal or shell scripts.
 
 - **npm package:** [`@switchbot/openapi-cli`](https://www.npmjs.com/package/@switchbot/openapi-cli)
 - **Source code:** [github.com/OpenWonderLabs/switchbot-openapi-cli](https://github.com/OpenWonderLabs/switchbot-openapi-cli)
@@ -41,11 +41,19 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - [Commands](#commands)
   - [`config`](#config--credential-management)
   - [`devices`](#devices--list-status-control)
+  - [`devices batch`](#devices-batch--bulk-commands)
+  - [`devices watch`](#devices-watch--poll-status)
   - [`scenes`](#scenes--run-manual-scenes)
   - [`webhook`](#webhook--receive-device-events-over-http)
-  - [`batch`](#batch--run-multiple-commands)
-  - [`watch`](#watch--poll-device-status)
+  - [`events`](#events--receive-device-events)
+  - [`plan`](#plan--declarative-batch-operations)
   - [`mcp`](#mcp--model-context-protocol-server)
+  - [`doctor`](#doctor--self-check)
+  - [`quota`](#quota--api-request-counter)
+  - [`history`](#history--audit-log)
+  - [`catalog`](#catalog--device-type-catalog)
+  - [`schema`](#schema--export-catalog-as-json)
+  - [`capabilities`](#capabilities--cli-manifest)
   - [`cache`](#cache--inspect-and-clear-local-cache)
   - [`completion`](#completion--shell-tab-completion)
 - [Output modes](#output-modes)
@@ -67,7 +75,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 592 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 692 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -187,6 +195,7 @@ switchbot devices command ABC123 turnOn --dry-run
 ```bash
 switchbot config set-token <token> <secret>   # Save to ~/.switchbot/config.json
 switchbot config show                          # Print current source + masked secret
+switchbot config list-profiles                 # List saved profiles
 ```
 
 ### `devices` — list, status, control
@@ -272,13 +281,48 @@ switchbot devices expand <relayId> setMode --channel 1 --mode edge
 
 Run `switchbot devices expand <id> <command> --help` to see the available flags for any device command.
 
-#### `devices explain` — plain-language command description
+#### `devices explain` — one-shot device summary
 
 ```bash
-switchbot devices explain <deviceId> <command>   # e.g. "explain ABC123 setAll"
+# Metadata + supported commands + live status in one call
+switchbot devices explain <deviceId>
+
+# Skip live status fetch (catalog-only output, no API call)
+switchbot devices explain <deviceId> --no-live
+```
+
+Returns a combined view: static catalog info (commands, parameters, status fields) merged with the current live status. For Hub devices, also lists connected child devices. Prefer this over separate `status` + `describe` calls.
+
+#### `devices meta` — local device metadata
+
+```bash
+switchbot devices meta set <deviceId> --alias "Office Light"
+switchbot devices meta set <deviceId> --hide          # hide from `devices list`
+switchbot devices meta get <deviceId>
+switchbot devices meta list                            # show all saved metadata
+switchbot devices meta clear <deviceId>
+```
+
+Stores local annotations (alias, hidden flag, notes) in `~/.switchbot/device-meta.json`. The alias is used as a display name; `--show-hidden` on `devices list` reveals hidden devices.
+
+#### `devices batch` — bulk commands
+
+```bash
+# Send the same command to every device matching a filter
+switchbot devices batch turnOff --filter 'type=Bot'
+switchbot devices batch setBrightness 50 --filter 'type~=Light,family=Living'
+
+# Explicit device IDs (comma-separated)
+switchbot devices batch turnOn --ids ID1,ID2,ID3
+
+# Pipe device IDs from `devices list`
+switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
+
+# Destructive commands require --yes
+switchbot devices batch unlock --filter 'type=Smart Lock' --yes
 ```
 
-Returns a human-readable description of what the command does and what each parameter means.
+Sends the same command to many devices in one run. Uses the same `--filter` expressions as `devices list`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
 
 ### `scenes` — run manual scenes
 
@@ -307,6 +351,67 @@ switchbot webhook delete https://your.host/hook
 
 The CLI validates that `<url>` is an absolute `http://` or `https://` URL before calling the API. `--enable` and `--disable` are mutually exclusive.
 
+### `events` — receive device events
+
+Two subcommands cover the two ways SwitchBot can push state changes to you.
+
+#### `events tail` — local webhook receiver
+
+```bash
+# Listen on port 3000 and print every incoming webhook POST
+switchbot events tail
+
+# Filter to one device
+switchbot events tail --filter deviceId=ABC123
+
+# Stop after 5 matching events
+switchbot events tail --filter 'type=WoMeter' --max 5
+
+# Custom port / path
+switchbot events tail --port 8080 --path /hook --json
+```
+
+Run `switchbot webhook setup https://your.host/hook` first to tell SwitchBot where to send events, then expose the local port via ngrok/cloudflared and point the webhook URL at it. `events tail` only runs the local receiver — tunnelling is up to you.
+
+Output (one JSON line per matched event):
+```
+{ "t": "2024-01-01T12:00:00.000Z", "remote": "1.2.3.4:54321", "path": "/", "body": {...}, "matched": true }
+```
+
+Filter keys: `deviceId=<id>`, `type=<deviceType>` (comma-separated for AND logic).
+
+#### `events mqtt-tail` — real-time MQTT stream
+
+```bash
+# Stream all shadow-update events (runs in foreground until Ctrl-C)
+switchbot events mqtt-tail
+
+# Filter to a topic subtree
+switchbot events mqtt-tail --topic 'switchbot/#'
+
+# Stop after 10 events
+switchbot events mqtt-tail --max 10 --json
+```
+
+Connects to the SwitchBot MQTT service automatically using the same credentials configured for the REST API (`SWITCHBOT_TOKEN` + `SWITCHBOT_SECRET`). No additional MQTT configuration is required — the client certificates are provisioned on first use.
+
+Output (one JSON line per message):
+```
+{ "t": "2024-01-01T12:00:00.000Z", "topic": "switchbot/abc123/status", "payload": {...} }
+```
+
+This command runs in the foreground and streams events until you press Ctrl-C. To run it persistently in the background, use a process manager:
+
+```bash
+# pm2
+pm2 start "switchbot events mqtt-tail --json" --name switchbot-events
+
+# nohup
+nohup switchbot events mqtt-tail --json >> ~/switchbot-events.log 2>&1 &
+```
+
+Run `switchbot doctor` to verify MQTT credentials are configured correctly before connecting.
+
 ### `completion` — shell tab-completion
 
 ```bash
@@ -325,28 +430,36 @@ switchbot completion powershell >> $PROFILE
 
 Supported shells: `bash`, `zsh`, `fish`, `powershell` (`pwsh` is accepted as an alias).
 
-### `batch` — run multiple commands
+### `plan` — declarative batch operations
 
 ```bash
-# Run a sequence of commands from a JSON/YAML file
-switchbot batch run commands.json
-switchbot batch run commands.yaml --dry-run
+# Print the plan JSON Schema (give to your agent framework)
+switchbot plan schema
 
-# Validate a plan file without executing it
-switchbot batch validate commands.json
+# Validate a plan file without running it
+switchbot plan validate plan.json
+
+# Preview — mutations skipped, GETs still execute
+switchbot --dry-run plan run plan.json
+
+# Run — pass --yes to allow destructive steps
+switchbot plan run plan.json --yes
+switchbot plan run plan.json --continue-on-error
 ```
 
-A batch file is a JSON array of `{ deviceId, command, parameter?, commandType? }` objects.
+A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
 
-### `watch` — poll device status
+### `devices watch` — poll status
 
 ```bash
 # Poll a device's status every 30 s until Ctrl-C
-switchbot watch <deviceId>
-switchbot watch <deviceId> --interval 10s --json
+switchbot devices watch <deviceId>
+
+# Custom interval; emit every tick even when nothing changed
+switchbot devices watch <deviceId> --interval 10s --include-unchanged --json
 ```
 
-Output is a stream of JSON status objects (with `--json`) or a refreshed table.
+Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks.
 
 ### `mcp` — Model Context Protocol server
 
@@ -358,6 +471,65 @@ switchbot mcp serve
 Exposes 8 MCP tools (`list_devices`, `describe_device`, `get_device_status`, `send_command`, `list_scenes`, `run_scene`, `search_catalog`, `account_overview`) plus a `switchbot://events` resource for real-time shadow updates.
 See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full tool reference and safety rules (destructive-command guard).
 
+### `doctor` — self-check
+
+```bash
+switchbot doctor
+switchbot doctor --json
+```
+
+Runs 8 local checks (Node version, credentials, profiles, catalog, cache, quota file, clock, MQTT) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). Use this to diagnose connectivity or config issues before running automation.
+
+### `quota` — API request counter
+
+```bash
+switchbot quota status     # today's usage + last 7 days
+switchbot quota reset      # delete the counter file
+```
+
+Tracks daily API calls against the 10,000/day account limit. The counter is stored in `~/.switchbot/quota.json` and incremented on every mutating request. Pass `--no-quota` to skip tracking for a single run.
+
+### `history` — audit log
+
+```bash
+switchbot history show              # recent entries (newest first)
+switchbot history show --limit 20   # last 20 entries
+switchbot history replay 7          # re-run entry #7
+switchbot --json history show --limit 50 | jq '.entries[] | select(.result=="error")'
+```
+
+Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `--audit-log`). Each entry records the timestamp, command, device ID, result, and dry-run flag. `replay` re-runs the original command with the original arguments.
+
+### `catalog` — device type catalog
+
+```bash
+switchbot catalog show              # all 42 built-in types
+switchbot catalog show Bot          # one type
+switchbot catalog diff              # what a local overlay changes vs built-in
+switchbot catalog path              # location of the local overlay file
+switchbot catalog refresh           # reload local overlay (clears in-process cache)
+```
+
+The built-in catalog ships with the package. Create `~/.switchbot/catalog-overlay.json` to add, extend, or override type definitions without modifying the package.
+
+### `schema` — export catalog as JSON
+
+```bash
+switchbot schema export                         # all types as structured JSON
+switchbot schema export --type 'Strip Light'    # one type
+switchbot schema export --role sensor           # filter by role
+```
+
+Exports the effective catalog in a machine-readable format. Pipe the output into an agent's system prompt or tool schema to give it a complete picture of controllable devices.
+
+### `capabilities` — CLI manifest
+
+```bash
+switchbot capabilities --json
+```
+
+Prints a versioned JSON manifest describing available surfaces (CLI, MCP, MQTT, plan runner), commands, and environment variables. Designed for agents and tooling that need to discover the CLI's capabilities programmatically.
+
 ### `cache` — inspect and clear local cache
 
 ```bash
@@ -457,11 +629,11 @@ Typical errors bubble up in the form `Error: <message>` on stderr. The SwitchBot
 
 ## Environment variables
 
-| Variable            | Description                                                        |
-| ------------------- | ------------------------------------------------------------------ |
-| `SWITCHBOT_TOKEN`   | API token — takes priority over the config file                    |
-| `SWITCHBOT_SECRET`  | API secret — takes priority over the config file                   |
-| `NO_COLOR`          | Disable ANSI colors in all output (automatically respected)        |
+| Variable                    | Description                                                        |
+| --------------------------- | ------------------------------------------------------------------ |
+| `SWITCHBOT_TOKEN`           | API token — takes priority over the config file                    |
+| `SWITCHBOT_SECRET`          | API secret — takes priority over the config file                   |
+| `NO_COLOR`                  | Disable ANSI colors in all output (automatically respected)        |
 
 ## Scripting examples
 
@@ -484,7 +656,7 @@ npm install
 
 npm run dev -- <args>       # Run from TypeScript sources via tsx
 npm run build               # Compile to dist/
-npm test                    # Run the Vitest suite (592 tests)
+npm test                    # Run the Vitest suite (692 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -506,21 +678,23 @@ src/
 ├── commands/
 │   ├── config.ts
 │   ├── devices.ts
+│   ├── expand.ts         # `devices expand` — semantic flag builder
+│   ├── explain.ts        # `devices explain` — one-shot device summary
+│   ├── device-meta.ts    # `devices meta` — local aliases / hide flags
 │   ├── scenes.ts
 │   ├── webhook.ts
-│   ├── batch.ts          # `switchbot batch run/validate`
-│   ├── watch.ts          # `switchbot watch <deviceId>`
-│   ├── mcp.ts            # `switchbot mcp serve` (MCP stdio server)
-│   ├── cache.ts          # `switchbot cache show/clear`
-│   ├── history.ts        # `switchbot history [replay]`
-│   ├── events.ts         # `switchbot events`
-│   ├── quota.ts          # `switchbot quota`
-│   ├── explain.ts        # `switchbot explain <deviceId>`
-│   ├── plan.ts           # `switchbot plan run <file>`
-│   ├── doctor.ts         # `switchbot doctor`
-│   ├── schema.ts         # `switchbot schema export`
-│   ├── catalog.ts        # `switchbot catalog search`
-│   └── completion.ts     # `switchbot completion bash|zsh|fish|powershell`
+│   ├── watch.ts          # `devices watch <deviceId>`
+│   ├── events.ts         # `events tail` / `events mqtt-tail`
+│   ├── mcp.ts            # `mcp serve` (MCP stdio/HTTP server)
+│   ├── plan.ts           # `plan run/validate`
+│   ├── cache.ts          # `cache show/clear`
+│   ├── history.ts        # `history show/replay`
+│   ├── quota.ts          # `quota status/reset`
+│   ├── catalog.ts        # `catalog show/diff/path`
+│   ├── schema.ts         # `schema export`
+│   ├── doctor.ts         # `doctor`
+│   ├── capabilities.ts   # `capabilities`
+│   └── completion.ts     # `completion bash|zsh|fish|powershell`
 └── utils/
     ├── flags.ts          # Global flag readers (isVerbose / isDryRun / getCacheMode / …)
     ├── output.ts         # printTable / printKeyValue / printJson / handleError / buildErrorPayload

package/dist/commands/capabilities.js

@@ -68,6 +68,13 @@ export function registerCapabilitiesCommand(program) {
                     tools: MCP_TOOLS,
                     resources: ['switchbot://events'],
                 },
+                mqtt: {
+                    mode: 'consumer',
+                    authSource: 'SWITCHBOT_TOKEN + SWITCHBOT_SECRET (auto-provisioned via POST /v1.1/iot/credential)',
+                    cliCmd: 'events mqtt-tail',
+                    mcpResource: 'switchbot://events',
+                    protocol: 'MQTTS with TLS client certificates (AWS IoT)',
+                },
                 plan: {
                     schemaCmd: 'plan schema',
                     validateCmd: 'plan validate -',

package/dist/commands/doctor.js

@@ -101,6 +101,38 @@ function checkNodeVersion() {
     }
     return { name: 'node', status: 'ok', detail: `Node ${process.versions.node}` };
 }
+function checkMqtt() {
+    // MQTT credentials are auto-provisioned from the SwitchBot API using the
+    // account's token+secret — no extra env vars needed. Report availability
+    // based on whether REST credentials are configured (no network call).
+    const hasEnvCreds = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
+    if (hasEnvCreds) {
+        return {
+            name: 'mqtt',
+            status: 'ok',
+            detail: "auto-provisioned from credentials — run 'switchbot events mqtt-tail' to test live connectivity",
+        };
+    }
+    const file = configFilePath();
+    if (fs.existsSync(file)) {
+        try {
+            const cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            if (cfg.token && cfg.secret) {
+                return {
+                    name: 'mqtt',
+                    status: 'ok',
+                    detail: "auto-provisioned from credentials — run 'switchbot events mqtt-tail' to test live connectivity",
+                };
+            }
+        }
+        catch { /* fall through */ }
+    }
+    return {
+        name: 'mqtt',
+        status: 'warn',
+        detail: "unavailable — configure credentials first (see credentials check above)",
+    };
+}
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
@@ -122,6 +154,7 @@ Examples:
             checkCache(),
             checkQuotaFile(),
             checkClockSkew(),
+            checkMqtt(),
         ];
         const summary = {
             ok: checks.filter((c) => c.status === 'ok').length,

package/dist/commands/events.js

@@ -1,5 +1,8 @@
 import http from 'node:http';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { SwitchBotMqttClient } from '../mqtt/client.js';
+import { fetchMqttCredential } from '../mqtt/credential.js';
+import { tryLoadConfig } from '../config.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
@@ -102,7 +105,7 @@ export function startReceiver(port, pathMatch, filter, onEvent) {
 export function registerEventsCommand(program) {
     const events = program
         .command('events')
-        .description('Subscribe to local webhook events forwarded by SwitchBot');
+        .description('Receive SwitchBot device events — webhook receiver (tail) or MQTT stream (mqtt-tail)');
     events
         .command('tail')
         .description('Run a local HTTP receiver and print incoming webhook events as JSONL')
@@ -184,4 +187,83 @@ Examples:
             handleError(error);
         }
     });
+    events
+        .command('mqtt-tail')
+        .description('Subscribe to SwitchBot MQTT shadow events and stream them as JSONL')
+        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)')
+        .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)')
+        .addHelpText('after', `
+Connects to the SwitchBot MQTT service using your existing credentials
+(SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
+No additional MQTT configuration required.
+
+Output (JSONL, one event per line):
+  { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+
+Examples:
+  $ switchbot events mqtt-tail
+  $ switchbot events mqtt-tail --topic 'switchbot/#'
+  $ switchbot events mqtt-tail --max 10 --json
+`)
+        .action(async (options) => {
+        try {
+            const maxEvents = options.max !== undefined ? Number(options.max) : null;
+            if (maxEvents !== null && (!Number.isInteger(maxEvents) || maxEvents < 1)) {
+                throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
+            }
+            let creds;
+            const loaded = tryLoadConfig();
+            if (!loaded) {
+                throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
+            }
+            creds = loaded;
+            if (!isJsonMode()) {
+                console.error('Fetching MQTT credentials from SwitchBot service…');
+            }
+            const credential = await fetchMqttCredential(creds.token, creds.secret);
+            const topic = options.topic ?? credential.topics.status;
+            let eventCount = 0;
+            const ac = new AbortController();
+            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(creds.token, creds.secret));
+            const unsub = client.onMessage((msgTopic, payload) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(payload.toString('utf-8'));
+                }
+                catch {
+                    parsed = payload.toString('utf-8');
+                }
+                const record = { t: new Date().toISOString(), topic: msgTopic, payload: parsed };
+                if (isJsonMode()) {
+                    printJson(record);
+                }
+                else {
+                    console.log(JSON.stringify(record));
+                }
+                eventCount++;
+                if (maxEvents !== null && eventCount >= maxEvents) {
+                    ac.abort();
+                }
+            });
+            await client.connect();
+            client.subscribe(topic);
+            if (!isJsonMode()) {
+                console.error(`Connected to ${credential.brokerUrl} (Ctrl-C to stop)`);
+            }
+            await new Promise((resolve) => {
+                const cleanup = () => {
+                    process.removeListener('SIGINT', cleanup);
+                    process.removeListener('SIGTERM', cleanup);
+                    unsub();
+                    client.disconnect().then(resolve).catch(resolve);
+                };
+                process.once('SIGINT', cleanup);
+                process.once('SIGTERM', cleanup);
+                ac.signal.addEventListener('abort', cleanup, { once: true });
+            });
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/mcp.js

@@ -11,8 +11,7 @@ import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
-import { profileFilePath } from '../config.js';
-import { getMqttConfig } from '../mqtt/credential.js';
+import { profileFilePath, tryLoadConfig } from '../config.js';
 import fs from 'node:fs';
 function mcpError(kind, code, message, options) {
     const obj = { code, kind, message };
@@ -350,7 +349,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             mqtt: z.object({
                 state: z.string(),
                 subscribers: z.number(),
-            }).optional().describe('MQTT connection state (HTTP mode only)'),
+            }).optional().describe('MQTT connection state (present when REST credentials are configured; auto-provisioned via POST /v1.1/iot/credential)'),
         },
     }, async () => {
         const deviceList = await fetchDeviceList();
@@ -398,7 +397,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         server.registerResource('events', 'switchbot://events', {
             title: 'SwitchBot real-time shadow events',
             description: 'Recent device shadow-update events received via MQTT. Returns a JSON snapshot of the ring buffer. ' +
-                'State is "disabled" when MQTT credentials are not configured (set SWITCHBOT_MQTT_HOST / USERNAME / PASSWORD).',
+                'State is "disabled" when REST credentials (SWITCHBOT_TOKEN + SWITCHBOT_SECRET) are not configured.',
             mimeType: 'application/json',
         }, (_uri) => {
             const state = eventManager.getState();
@@ -419,7 +418,7 @@ export function registerMcpCommand(program) {
         .command('mcp')
         .description('Run as a Model Context Protocol server so AI agents can call SwitchBot tools')
         .addHelpText('after', `
-The MCP server exposes seven tools over stdio:
+The MCP server exposes eight tools:
   - list_devices          fetch all physical + IR devices
   - get_device_status     live status for a physical device
   - send_command          control a device (destructive commands need confirm:true)
@@ -427,6 +426,12 @@ The MCP server exposes seven tools over stdio:
   - run_scene             execute a manual scene
   - search_catalog        offline catalog search by type/alias
   - describe_device       metadata + commands + (optionally) live status for one device
+  - account_overview      single cold-start snapshot: devices + scenes + quota + cache + MQTT state
+
+Resource (read-only):
+  - switchbot://events    snapshot of recent MQTT shadow events from the ring buffer
+    Auto-provisioned from SWITCHBOT_TOKEN + SWITCHBOT_SECRET;
+    returns {state:"disabled"} when credentials are not configured.
 
 Example Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
 
@@ -487,17 +492,17 @@ Inspect locally:
                 const { createServer } = await import('node:http');
                 const rateLimitMap = new Map();
                 // Initialize shared EventSubscriptionManager for event streaming.
-                // If MQTT creds are present, connect in the background so the HTTP server
-                // starts immediately; /ready reflects the real state.
+                // Credentials are auto-provisioned from the SwitchBot API using the
+                // account's token+secret — no extra MQTT env vars needed.
                 const eventManager = new EventSubscriptionManager();
-                const mqttConfig = getMqttConfig();
-                if (mqttConfig) {
-                    eventManager.initialize(mqttConfig).catch((err) => {
+                const mqttCreds = tryLoadConfig();
+                if (mqttCreds) {
+                    eventManager.initialize(mqttCreds.token, mqttCreds.secret).catch((err) => {
                         console.error('MQTT initialization failed:', err instanceof Error ? err.message : String(err));
                     });
                 }
                 else {
-                    console.error('MQTT disabled: set SWITCHBOT_MQTT_HOST, SWITCHBOT_MQTT_USERNAME, SWITCHBOT_MQTT_PASSWORD to enable real-time events.');
+                    console.error('MQTT disabled: credentials not configured.');
                 }
                 // Helper: constant-time token comparison
                 const tokenMatch = (provided) => {
@@ -691,7 +696,14 @@ process_uptime_seconds ${Math.floor(process.uptime())}
                 });
                 return;
             }
-            const server = createSwitchBotMcpServer();
+            const eventManager = new EventSubscriptionManager();
+            const mqttCreds = tryLoadConfig();
+            if (mqttCreds) {
+                eventManager.initialize(mqttCreds.token, mqttCreds.secret).catch((err) => {
+                    console.error('MQTT initialization failed:', err instanceof Error ? err.message : String(err));
+                });
+            }
+            const server = createSwitchBotMcpServer({ eventManager });
             const transport = new StdioServerTransport();
             await server.connect(transport);
         }

package/dist/config.js

@@ -62,6 +62,29 @@ export function loadConfig() {
         process.exit(1);
     }
 }
+/**
+ * Like loadConfig but returns null instead of exiting. Use this in code paths
+ * that want graceful degradation (e.g. optional MQTT init in `mcp serve`).
+ */
+export function tryLoadConfig() {
+    const envToken = process.env.SWITCHBOT_TOKEN;
+    const envSecret = process.env.SWITCHBOT_SECRET;
+    if (envToken && envSecret)
+        return { token: envToken, secret: envSecret };
+    const file = configFilePath();
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const cfg = JSON.parse(raw);
+        if (!cfg.token || !cfg.secret)
+            return null;
+        return cfg;
+    }
+    catch {
+        return null;
+    }
+}
 export function saveConfig(token, secret) {
     const file = configFilePath();
     const dir = path.dirname(file);

package/dist/index.js

@@ -68,9 +68,9 @@ Exit codes:
   2  usage error (bad flag, unknown subcommand, invalid argument, unknown device type)
 
 Environment:
-  SWITCHBOT_TOKEN   credential token (takes priority over config file)
-  SWITCHBOT_SECRET  credential secret (takes priority over config file)
-  NO_COLOR          disable ANSI colors (auto-respected via chalk)
+  SWITCHBOT_TOKEN          credential token (takes priority over config file)
+  SWITCHBOT_SECRET         credential secret (takes priority over config file)
+  NO_COLOR                 disable ANSI colors (auto-respected via chalk)
 
 Examples:
   $ switchbot config set-token <token> <secret>

package/dist/mcp/events-subscription.js

@@ -1,4 +1,5 @@
 import { SwitchBotMqttClient } from '../mqtt/client.js';
+import { fetchMqttCredential } from '../mqtt/credential.js';
 import { parseFilter, applyFilter } from '../utils/filter.js';
 import { fetchDeviceList } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
@@ -18,22 +19,17 @@ export class EventSubscriptionManager {
         this.mqttClient = mqttClient || null;
         this.getClient = getClient;
     }
-    async initialize(mqttConfig) {
+    async initialize(token, secret) {
         if (!this.mqttClient) {
-            const client = new SwitchBotMqttClient(mqttConfig, async () => {
-                // Auth refresh callback - would need credential resolution here
-                return {
-                    username: mqttConfig.username,
-                    password: mqttConfig.password,
-                };
-            });
+            const credential = await fetchMqttCredential(token, secret);
+            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(token, secret));
             client.onStateChange((state) => {
                 if (state === 'connected') {
                     this.emit({
                         kind: 'events.reconnected',
                         timestamp: Date.now(),
                     });
-                    client.subscribe('$aws/things/+/shadow/update/accepted');
+                    client.subscribe(credential.topics.status);
                 }
             });
             client.onMessage((topic, payload) => {

package/dist/mqtt/client.js

@@ -1,41 +1,45 @@
 import { connect } from 'mqtt';
 export class SwitchBotMqttClient {
     client = null;
-    config;
+    credential;
     state = 'connecting';
-    authRefreshNeeded = false;
+    credentialExpired = false;
     reconnectAttempts = 0;
     maxReconnectAttempts = 10;
+    disconnecting = false;
     handlers = new Set();
     messageHandlers = new Set();
-    authRefreshCallback;
-    stableTimer = null;
-    lastConnectionAttempt = 0;
-    constructor(config, onAuthRefreshNeeded) {
-        this.config = config;
-        this.authRefreshCallback = onAuthRefreshNeeded;
+    credentialRefreshCallback;
+    constructor(credential, onCredentialExpired) {
+        this.credential = credential;
+        this.credentialRefreshCallback = onCredentialExpired;
     }
     async connect() {
-        if (this.client && this.state === 'connected') {
+        if (this.client && this.state === 'connected')
             return;
-        }
         this.setState('connecting');
-        this.authRefreshNeeded = false;
+        this.credentialExpired = false;
         this.reconnectAttempts = 0;
         try {
+            const { tls, brokerUrl, clientId } = this.credential;
+            // tls.ca/cert/keyBase64 are PEM strings despite the misleading field name
             const options = {
-                username: this.config.username,
-                password: this.config.password,
+                clientId,
+                ca: tls.caBase64,
+                cert: tls.certBase64,
+                key: tls.keyBase64,
+                rejectUnauthorized: true,
                 clean: true,
-                reconnectPeriod: 0, // Manual reconnect control
-                connectTimeout: 10000,
-                rejectUnauthorized: this.config.rejectUnauthorized ?? true,
+                reconnectPeriod: 0,
+                connectTimeout: 30000,
+                keepalive: 60,
+                reschedulePings: true,
             };
-            this.client = connect(`mqtts://${this.config.host}:${this.config.port}`, options);
+            this.client = connect(brokerUrl, options);
             this.client.on('connect', () => {
                 this.reconnectAttempts = 0;
                 this.setState('connected');
-                this.authRefreshNeeded = false;
+                this.credentialExpired = false;
             });
             this.client.on('message', (topic, payload) => {
                 for (const handler of this.messageHandlers) {
@@ -43,18 +47,17 @@ export class SwitchBotMqttClient {
                 }
             });
             this.client.on('error', (err) => {
-                // Check for auth-related errors
-                if ((err instanceof Error &&
-                    (err.message.includes('401') ||
-                        err.message.includes('Unauthorized') ||
-                        err.message.includes('EACCES'))) ||
-                    err.code === 'EACCES') {
-                    this.authRefreshNeeded = true;
+                if (err instanceof Error &&
+                    (err.message.includes('certificate') ||
+                        err.message.includes('ECONNRESET') ||
+                        err.message.includes('handshake'))) {
+                    this.credentialExpired = true;
                 }
             });
             this.client.on('close', () => {
-                this.clearStableTimer();
-                if (this.authRefreshNeeded) {
+                if (this.disconnecting)
+                    return;
+                if (this.credentialExpired) {
                     this.setState('failed');
                 }
                 else if (this.reconnectAttempts < this.maxReconnectAttempts) {
@@ -64,7 +67,6 @@ export class SwitchBotMqttClient {
                     this.setState('failed');
                 }
             });
-            // Wait for connection with timeout
             await new Promise((resolve, reject) => {
                 const timeout = setTimeout(() => {
                     reject(new Error('MQTT connection timeout'));
@@ -97,26 +99,22 @@ export class SwitchBotMqttClient {
     async attemptReconnect() {
         this.reconnectAttempts++;
         this.setState('reconnecting');
-        if (this.authRefreshNeeded && this.authRefreshCallback) {
+        if (this.credentialExpired && this.credentialRefreshCallback) {
             try {
-                const refreshed = await this.authRefreshCallback();
-                this.config.username = refreshed.username;
-                this.config.password = refreshed.password;
-                this.authRefreshNeeded = false;
+                this.credential = await this.credentialRefreshCallback();
+                this.credentialExpired = false;
             }
-            catch (err) {
-                // Auth refresh failed, mark as failed
+            catch {
                 this.setState('failed');
                 return;
             }
         }
-        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 30s...
         const delay = Math.min(30000, 1000 * Math.pow(2, this.reconnectAttempts - 1));
         await new Promise((r) => setTimeout(r, delay));
         try {
             await this.connect();
         }
-        catch (err) {
+        catch {
             if (this.reconnectAttempts < this.maxReconnectAttempts) {
                 await this.attemptReconnect();
             }
@@ -133,12 +131,6 @@ export class SwitchBotMqttClient {
             }
         }
     }
-    clearStableTimer() {
-        if (this.stableTimer) {
-            clearTimeout(this.stableTimer);
-            this.stableTimer = null;
-        }
-    }
     subscribe(topic) {
         if (this.client && this.state === 'connected') {
             this.client.subscribe(topic, (err) => {
@@ -167,18 +159,14 @@ export class SwitchBotMqttClient {
         return this.state === 'connected' && this.client?.connected === true;
     }
     async disconnect() {
-        this.clearStableTimer();
+        this.disconnecting = true;
         if (this.client) {
             await new Promise((resolve) => {
-                this.client?.end(false, () => {
-                    resolve();
-                });
+                this.client?.end(false, () => resolve());
             });
             this.client = null;
-            this.setState('failed');
         }
-    }
-    setAuthRefreshCallback(callback) {
-        this.authRefreshCallback = callback;
+        this.disconnecting = false;
+        this.setState('failed');
     }
 }

package/dist/mqtt/credential.js

@@ -1,12 +1,29 @@
-export function getMqttConfig() {
-    const host = process.env.SWITCHBOT_MQTT_HOST;
-    const username = process.env.SWITCHBOT_MQTT_USERNAME;
-    const password = process.env.SWITCHBOT_MQTT_PASSWORD;
-    if (!host || !username || !password)
-        return null;
-    const rawPort = process.env.SWITCHBOT_MQTT_PORT;
-    const port = rawPort ? Number(rawPort) : 8883;
-    if (!Number.isFinite(port) || port <= 0 || port > 65535)
-        return null;
-    return { host, port, username, password };
+import crypto from 'node:crypto';
+import { buildAuthHeaders } from '../auth.js';
+const CREDENTIAL_ENDPOINT = 'https://api.switchbot.net/v1.1/iot/credential';
+export async function fetchMqttCredential(token, secret) {
+    // Derive a stable instance ID per token so the server can track this client.
+    const instanceId = crypto.createHash('sha256').update(token).digest('hex').slice(0, 16);
+    const headers = buildAuthHeaders(token, secret);
+    const res = await fetch(CREDENTIAL_ENDPOINT, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ instanceId }),
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) {
+        throw new Error(`MQTT credential request failed: HTTP ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    if (json.statusCode !== 100) {
+        throw new Error(`MQTT credential API error: statusCode ${json.statusCode}`);
+    }
+    // Response shape: { statusCode, body: { body: { channels: { mqtt: ... } } } }
+    const outer = json.body;
+    const inner = (outer.body ?? outer);
+    const channels = inner.channels;
+    if (!channels?.mqtt) {
+        throw new Error('Unexpected MQTT credential response — channels.mqtt missing');
+    }
+    return channels.mqtt;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.0.1",
-  "description": "Command-line interface for SwitchBot API v1.1",
+  "version": "2.1.0",
+  "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",
     "cli",