@switchbot/openapi-cli 2.6.3 → 2.7.2

package/dist/commands/expand.js

@@ -1,5 +1,5 @@
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode, printJson, UsageError, emitJsonError } from '../utils/output.js';
+import { handleError, isJsonMode, printJson, UsageError, exitWithError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
@@ -92,20 +92,12 @@ Examples:
             }
             if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, 'command')) {
                 const reason = getDestructiveReason(deviceType, command, 'command');
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
-                        hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
-                    });
-                }
-                else {
-                    console.error(`Refusing to run destructive command "${command}" without --yes.`);
-                    if (reason)
-                        console.error(`Reason: ${reason}`);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'guard',
+                    message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
+                    hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
+                });
             }
             const body = await executeCommand(deviceId, command, parameter, 'command');
             const isIr = cached?.category === 'ir';

package/dist/commands/explain.js

@@ -43,12 +43,16 @@ Examples:
             }
             const caps = desc.capabilities;
             const commands = caps && 'commands' in caps
-                ? caps.commands.map((c) => ({
-                    command: c.command,
-                    parameter: c.parameter,
-                    idempotent: c.idempotent,
-                    destructive: c.destructive,
-                }))
+                ? caps.commands.map((c) => {
+                    const tier = c.safetyTier;
+                    return {
+                        command: c.command,
+                        parameter: c.parameter,
+                        idempotent: c.idempotent,
+                        ...(tier ? { safetyTier: tier } : {}),
+                        destructive: c.destructive,
+                    };
+                })
                 : [];
             const statusFields = caps && 'statusFields' in caps ? caps.statusFields : [];
             const liveStatus = caps && 'liveStatus' in caps ? caps.liveStatus : undefined;

package/dist/commands/history.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, UsageError, emitJsonError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, exitWithError } from '../utils/output.js';
 import { readAudit, verifyAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
 import { queryDeviceHistory, queryDeviceHistoryStats, } from '../devices/history-query.js';
@@ -10,7 +10,7 @@ const DEFAULT_AUDIT = path.join(os.homedir(), '.switchbot', 'audit.log');
 export function registerHistoryCommand(program) {
     const history = program
         .command('history')
-        .description('View and replay commands recorded via --audit-log')
+        .description('View and replay SwitchBot commands recorded via --audit-log')
         .addHelpText('after', `
 Every 'devices command' run with --audit-log is appended as JSONL to the
 audit file (default ~/.switchbot/audit.log). 'history show' prints the file,
@@ -70,25 +70,19 @@ Examples:
         const entries = readAudit(file);
         const idx = Number(indexArg);
         if (!Number.isInteger(idx) || idx < 1 || idx > entries.length) {
-            const msg = `Invalid index ${indexArg}. Log has ${entries.length} entries.`;
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `Invalid index ${indexArg}. Log has ${entries.length} entries.`,
+            });
         }
         const entry = entries[idx - 1];
         if (entry.kind !== 'command') {
-            const msg = `Entry ${idx} is not a command (kind=${entry.kind}).`;
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `Entry ${idx} is not a command (kind=${entry.kind}).`,
+            });
         }
         try {
             const result = await executeCommand(entry.deviceId, entry.command, entry.parameter, entry.commandType);

package/dist/commands/identity.js

@@ -0,0 +1,59 @@
+/**
+ * Single source of truth for SwitchBot product identity.
+ *
+ * Consumed by:
+ *   - `program.description()` / `--help`   (via PRODUCT_TAGLINE in src/index.ts)
+ *   - `--help --json` root                  (via src/utils/help-json.ts)
+ *   - `switchbot capabilities` / `--json`   (identity block)
+ *   - `switchbot agent-bootstrap --json`    (identity block)
+ *
+ * Keeping this in one file prevents drift between those four surfaces.
+ *
+ * IMPORTANT: the SwitchBot CLI only talks to the SwitchBot Cloud API over
+ * HTTPS. It does NOT drive BLE radios directly — BLE-only devices are
+ * reached by going through a SwitchBot Hub, which the Cloud API already
+ * handles transparently. Please do not reintroduce the word "BLE" into the
+ * tagline / README: it is misleading for AI agents reading `--help`.
+ */
+export const IDENTITY = {
+    product: 'SwitchBot',
+    domain: 'IoT smart home device control',
+    vendor: 'Wonderlabs, Inc.',
+    apiVersion: 'v1.1',
+    apiDocs: 'https://github.com/OpenWonderLabs/SwitchBotAPI',
+    // Product category keywords. AI agents scan these to judge scope
+    // ("does SwitchBot control door locks? air conditioners?") without
+    // parsing the full device catalog.
+    productCategories: [
+        'lights (bulbs / strips / color)',
+        'locks / keypads',
+        'curtains / blinds / shades',
+        'sensors (motion / contact / climate / water-leak)',
+        'plugs / strips',
+        'bots / mechanical pushers',
+        'robot vacuums',
+        'IR appliances via Hub (TV / AC / fan / projector)',
+    ],
+    deviceCategories: {
+        physical: 'Wi-Fi-connected and Hub-mediated devices — controlled via Cloud API (CLI does not drive BLE directly)',
+        ir: 'IR remote devices learned by a SwitchBot Hub (TV, AC, fan, etc.)',
+    },
+    constraints: {
+        quotaPerDay: 10000,
+        hubRequiredForBle: true,
+        transport: 'Cloud API v1.1 (HTTPS)',
+        authMethod: 'HMAC-SHA256 token+secret',
+    },
+    agentGuide: 'docs/agent-guide.md',
+};
+/**
+ * One-line product description used for `program.description()` (the first
+ * line an AI agent sees when running `switchbot --help`).
+ *
+ * Structure: "SwitchBot smart home CLI — <product categories> via <transport>;
+ *             <verbs: scenes, events, MCP>." Keep categories in sync with
+ * IDENTITY.productCategories above.
+ */
+export const PRODUCT_TAGLINE = 'SwitchBot smart home CLI — control lights, locks, curtains, sensors, plugs, ' +
+    'and IR appliances (TV/AC/fan) via Cloud API v1.1; run scenes, stream real-time ' +
+    'events, and integrate AI agents via MCP.';

package/dist/commands/mcp.js

@@ -3,11 +3,11 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode, buildErrorPayload, emitJsonError } from '../utils/output.js';
+import { handleError, buildErrorPayload, exitWithError } from '../utils/output.js';
 import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
-import { findCatalogEntry } from '../devices/catalog.js';
+import { findCatalogEntry, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { validateParameter } from '../devices/param-validator.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
@@ -274,6 +274,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        let effectiveCommand = command;
         let effectiveParameter = parameter;
         // stringifiedParam mirrors the CLI form that validateCommand /
         // validateParameter expect — B-1 runs on the string representation.
@@ -291,52 +292,37 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
+            const dryValidation = validateCommand(deviceId, effectiveCommand, stringifiedParam, effectiveType);
+            if (!dryValidation.ok) {
+                return mcpError('usage', 2, dryValidation.error.message, {
+                    hint: dryValidation.error.hint,
+                    context: {
+                        validationKind: dryValidation.error.kind,
+                        deviceType: cached.type,
+                        command: effectiveCommand,
+                    },
+                });
+            }
+            if (dryValidation.normalized) {
+                effectiveCommand = dryValidation.normalized;
+            }
             // R-2: run B-1 param validation in dry-run too, so dry-run doesn't
             // falsely accept inputs the live API would reject.
             if (effectiveType !== 'customize') {
-                const pv = validateParameter(cached.type, command, stringifiedParam);
+                const pv = validateParameter(cached.type, effectiveCommand, stringifiedParam);
                 if (!pv.ok) {
                     return mcpError('usage', 2, pv.error, {
                         hint: 'Dry-run rejected the parameter client-side; the API would reject it too.',
-                        context: { deviceType: cached.type, command, parameter: stringifiedParam },
+                        context: { deviceType: cached.type, command: effectiveCommand, parameter: stringifiedParam },
                     });
                 }
                 if (pv.normalized !== undefined) {
                     effectiveParameter = pv.normalized;
                 }
             }
-            // Bug #55: validateCommand is lenient by design (passes unknown device
-            // types, ambiguous catalog matches). For dry-run we need stricter
-            // checking — query the catalog directly and reject unknown commands
-            // when the catalog has a definitive match.
-            if (effectiveType !== 'customize') {
-                const catalogMatch = findCatalogEntry(cached.type);
-                if (catalogMatch && !Array.isArray(catalogMatch)) {
-                    const builtinCmds = catalogMatch.commands.filter((c) => c.commandType !== 'customize');
-                    if (builtinCmds.length > 0) {
-                        const exactMatch = builtinCmds.find((c) => c.command === command);
-                        const caseMatch = !exactMatch
-                            ? builtinCmds.find((c) => c.command.toLowerCase() === command.toLowerCase())
-                            : null;
-                        if (!exactMatch && !caseMatch) {
-                            const supported = [...new Set(builtinCmds.map((c) => c.command))].join(', ');
-                            return mcpError('usage', 2, `"${command}" is not a supported command for ${cached.name} (${cached.type}).`, {
-                                hint: `Supported commands: ${supported}`,
-                                context: { validationKind: 'unknown-command', deviceType: cached.type, command },
-                            });
-                        }
-                    }
-                    else if (catalogMatch.readOnly) {
-                        return mcpError('usage', 2, `${cached.name} (${cached.type}) is a read-only sensor — it has no control commands.`, {
-                            hint: "Use 'get_device_status' to read this device instead.",
-                            context: { validationKind: 'read-only-device', deviceType: cached.type, command },
-                        });
-                    }
-                }
-            }
             const wouldSend = {
                 deviceId,
-                command,
+                command: effectiveCommand,
                 parameter: effectiveParameter ?? 'default',
                 commandType: effectiveType,
             };
@@ -361,40 +347,46 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             }
             typeName = physical ? physical.deviceType : ir.remoteType;
         }
-        if (isDestructiveCommand(typeName, command, effectiveType) && !confirm) {
-            const reason = getDestructiveReason(typeName, command, effectiveType);
+        if (isDestructiveCommand(typeName, effectiveCommand, effectiveType) && !confirm) {
+            const reason = getDestructiveReason(typeName, effectiveCommand, effectiveType);
             const entry = typeName ? findCatalogEntry(typeName) : null;
             const spec = entry && !Array.isArray(entry)
-                ? entry.commands.find((c) => c.command === command)
+                ? entry.commands.find((c) => c.command === effectiveCommand)
                 : undefined;
             const hint = reason
                 ? `Re-issue with confirm:true after confirming with the user. Reason: ${reason}`
                 : 'Re-issue the call with confirm:true to proceed.';
-            return mcpError('guard', 3, `Command "${command}" on device type "${typeName}" is destructive and requires confirm:true.`, {
+            return mcpError('guard', 3, `Command "${effectiveCommand}" on device type "${typeName}" is destructive and requires confirm:true.`, {
                 hint,
                 context: {
-                    command,
+                    command: effectiveCommand,
                     deviceType: typeName,
                     description: spec?.description ?? null,
-                    ...(reason ? { destructiveReason: reason } : {}),
+                    ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}),
                 },
             });
         }
         // validateCommand covers command existence + required/unexpected-parameter.
         // stringifiedParam was computed once at the top of the handler so dry-run
         // and live paths share the same shape.
-        const validation = validateCommand(deviceId, command, stringifiedParam, effectiveType);
+        const validation = validateCommand(deviceId, effectiveCommand, stringifiedParam, effectiveType);
         if (!validation.ok) {
-            return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
+            return mcpError('usage', 2, validation.error.message, {
+                hint: validation.error.hint,
+                context: { validationKind: validation.error.kind, deviceType: typeName, command: effectiveCommand },
+            });
+        }
+        if (validation.normalized) {
+            effectiveCommand = validation.normalized;
         }
         // R-2: run B-1 client-side parameter validator (range/format checks).
         // Customize commands (user-defined IR buttons) opt out — the catalog
         // cannot know their expected shape.
         if (effectiveType !== 'customize') {
-            const pv = validateParameter(typeName, command, stringifiedParam);
+            const pv = validateParameter(typeName, effectiveCommand, stringifiedParam);
             if (!pv.ok) {
                 return mcpError('usage', 2, pv.error, {
-                    context: { deviceType: typeName, command, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
+                    context: { deviceType: typeName, command: effectiveCommand, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
                 });
             }
             if (pv.normalized !== undefined) {
@@ -403,7 +395,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         }
         let result;
         try {
-            result = await executeCommand(deviceId, command, effectiveParameter, effectiveType, undefined, {
+            result = await executeCommand(deviceId, effectiveCommand, effectiveParameter, effectiveType, undefined, {
                 idempotencyKey,
             });
         }
@@ -420,7 +412,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             return apiErrorToMcpError(err);
         }
         const isIr = getCachedDevice(deviceId)?.category === 'ir';
-        const structured = { ok: true, command, deviceId, result };
+        const structured = { ok: true, command: effectiveCommand, deviceId, result };
         if (isIr) {
             structured.verification = {
                 verifiable: false,
@@ -524,6 +516,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     description: z.string(),
                     commandType: z.enum(['command', 'customize']).optional(),
                     idempotent: z.boolean().optional(),
+                    safetyTier: z.enum(['read', 'mutation', 'ir-fire-forget', 'destructive', 'maintenance']).optional(),
+                    safetyReason: z.string().optional(),
                     destructive: z.boolean().optional(),
                 }).passthrough()),
                 aliases: z.array(z.string()).optional(),
@@ -540,9 +534,22 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             });
         }
         const hits = searchCatalog(query, limit);
-        const structured = { results: hits, total: hits.length };
+        const normalised = hits.map((e) => ({
+            ...e,
+            commands: e.commands.map((c) => {
+                const tier = deriveSafetyTier(c, e);
+                const reason = getCommandSafetyReason(c);
+                return {
+                    ...c,
+                    safetyTier: tier,
+                    destructive: tier === 'destructive',
+                    ...(reason ? { safetyReason: reason } : {}),
+                };
+            }),
+        }));
+        const structured = { results: normalised, total: normalised.length };
         return {
-            content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(normalised, null, 2) }],
             structuredContent: structured,
         };
     });
@@ -599,16 +606,64 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         _meta: { agentSafetyTier: 'read' },
         inputSchema: z
             .object({
-            deviceId: z.string().min(1),
-            since: z.string().optional(),
-            from: z.string().optional(),
-            to: z.string().optional(),
-            metrics: z.array(z.string().min(1)).min(1),
-            aggs: z.array(z.enum(ALL_AGG_FNS)).optional(),
-            bucket: z.string().optional(),
-            maxBucketSamples: z.number().int().positive().max(MAX_SAMPLE_CAP).optional(),
+            deviceId: z.string().min(1).describe('Device ID to aggregate over (must exist in ~/.switchbot/device-history/).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Relative window ending now, e.g. "30s", "15m", "1h", "7d". Mutually exclusive with from/to.'),
+            from: z.string().optional().describe('Range start (ISO-8601). Requires `to`.'),
+            to: z.string().optional().describe('Range end (ISO-8601). Requires `from`.'),
+            metrics: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe('One or more numeric payload field names to aggregate (e.g. ["temperature","humidity"]).'),
+            aggs: z
+                .array(z.enum(ALL_AGG_FNS))
+                .optional()
+                .describe('Aggregation functions to apply per metric (default: ["count","avg"]).'),
+            bucket: z
+                .string()
+                .optional()
+                .describe('Bucket width like "5m", "1h", "1d". Omit for a single bucket spanning the full range.'),
+            maxBucketSamples: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_SAMPLE_CAP)
+                .optional()
+                .describe(`Sample cap per bucket to bound memory (default ${10_000}, max ${MAX_SAMPLE_CAP}). partial=true in the result when any bucket was capped.`),
         })
             .strict(),
+        outputSchema: {
+            deviceId: z.string(),
+            bucket: z.string().optional().describe('Bucket width echoed back when specified; omitted for single-bucket results.'),
+            from: z.string().describe('Effective range start (ISO-8601).'),
+            to: z.string().describe('Effective range end (ISO-8601).'),
+            metrics: z.array(z.string()).describe('Metrics that were requested.'),
+            aggs: z
+                .array(z.enum(ALL_AGG_FNS))
+                .describe('Aggregation functions that were applied.'),
+            buckets: z
+                .array(z.object({
+                t: z.string().describe('Bucket start timestamp (ISO-8601).'),
+                metrics: z
+                    .record(z.string(), z
+                    .object({
+                    count: z.number().optional(),
+                    min: z.number().optional(),
+                    max: z.number().optional(),
+                    avg: z.number().optional(),
+                    sum: z.number().optional(),
+                    p50: z.number().optional(),
+                    p95: z.number().optional(),
+                })
+                    .describe('Per-aggregate function result for this metric in this bucket.'))
+                    .describe('Per-metric result keyed by metric name.'),
+            }))
+                .describe('Time-ordered buckets; empty when no records match.'),
+            partial: z.boolean().describe('True if any bucket was sample-capped; retry with a higher maxBucketSamples or a narrower range for exact values.'),
+            notes: z.array(z.string()).describe('Human-readable notes about the aggregation (e.g. "metric X is non-numeric").'),
+        },
     }, async (args) => {
         const opts = {
             since: args.since,
@@ -620,9 +675,21 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             maxBucketSamples: args.maxBucketSamples,
         };
         const res = await aggregateDeviceHistory(args.deviceId, opts);
+        const structured = {
+            deviceId: res.deviceId,
+            from: res.from,
+            to: res.to,
+            metrics: res.metrics,
+            aggs: res.aggs,
+            buckets: res.buckets,
+            partial: res.partial,
+            notes: res.notes,
+        };
+        if (res.bucket !== undefined)
+            structured.bucket = res.bucket;
         return {
             content: [{ type: 'text', text: JSON.stringify(res, null, 2) }],
-            structuredContent: res,
+            structuredContent: structured,
         };
     });
     // ---- account_overview ---------------------------------------------------
@@ -737,6 +804,18 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     }
     return server;
 }
+/**
+ * P10: list the tool names registered on an McpServer instance. Used by
+ * `doctor`'s dry-run check. The MCP SDK keeps `_registeredTools` private,
+ * so we reach through a narrow cast — safe because this only runs in
+ * diagnostic code and the shape is stable across SDK versions.
+ */
+export function listRegisteredTools(server) {
+    const internal = server;
+    if (!internal._registeredTools)
+        return [];
+    return Object.keys(internal._registeredTools).sort();
+}
 export function registerMcpCommand(program) {
     const mcp = program
         .command('mcp')
@@ -786,19 +865,19 @@ Inspect locally:
         .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)', stringArg('--auth-token'))
         .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)', stringArg('--cors-origin'))
         .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', intArg('--rate-limit', { min: 1 }), '60')
+        .addHelpText('after', `
+Examples:
+  $ switchbot mcp serve
+  $ switchbot mcp serve --port 8787
+  $ switchbot mcp serve --port 8787 --bind 127.0.0.1 --auth-token your-token
+  $ switchbot mcp serve --port 8787 --bind 0.0.0.0 --auth-token your-token
+`)
         .action(async (options) => {
         try {
             if (options.port) {
                 const port = Number(options.port);
                 if (!Number.isFinite(port) || port < 1 || port > 65535) {
-                    const msg = `Invalid --port "${options.port}". Must be 1-65535.`;
-                    if (isJsonMode()) {
-                        emitJsonError({ code: 2, kind: 'usage', message: msg });
-                    }
-                    else {
-                        console.error(msg);
-                    }
-                    process.exit(2);
+                    exitWithError(`Invalid --port "${options.port}". Must be 1-65535.`);
                 }
                 const bind = options.bind ?? '127.0.0.1';
                 const authToken = options.authToken ?? process.env.SWITCHBOT_MCP_TOKEN;
@@ -807,14 +886,7 @@ Inspect locally:
                 // Guard: refuse to bind non-localhost without auth
                 const isLocalhost = bind === '127.0.0.1' || bind === 'localhost' || bind === '::1';
                 if (!isLocalhost && !authToken) {
-                    const msg = 'Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).';
-                    if (isJsonMode()) {
-                        emitJsonError({ code: 2, kind: 'usage', message: msg });
-                    }
-                    else {
-                        console.error(msg);
-                    }
-                    process.exit(2);
+                    exitWithError('Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).');
                 }
                 const { createServer } = await import('node:http');
                 const rateLimitMap = new Map();
@@ -1033,6 +1105,29 @@ process_uptime_seconds ${Math.floor(process.uptime())}
             const server = createSwitchBotMcpServer({ eventManager });
             const transport = new StdioServerTransport();
             await server.connect(transport);
+            let isShuttingDown = false;
+            const gracefulShutdown = async () => {
+                if (isShuttingDown)
+                    return;
+                isShuttingDown = true;
+                console.error('Shutting down...');
+                // Force exit after 30s if shutdown hangs (e.g. stuck MQTT disconnect).
+                const forceExit = setTimeout(() => {
+                    console.error('Force exiting after 30s timeout');
+                    process.exit(1);
+                }, 30000);
+                forceExit.unref();
+                try {
+                    await eventManager.shutdown();
+                }
+                catch (err) {
+                    console.error('Error during shutdown:', err instanceof Error ? err.message : String(err));
+                }
+                process.exit(0);
+            };
+            process.on('SIGTERM', gracefulShutdown);
+            process.on('SIGINT', gracefulShutdown);
+            process.stdin.on('end', gracefulShutdown);
         }
         catch (error) {
             handleError(error);

package/dist/commands/plan.js

@@ -160,7 +160,7 @@ function readStdin() {
 export function registerPlanCommand(program) {
     const plan = program
         .command('plan')
-        .description('Agent-authored batch plans: schema, validate, run')
+        .description('Author, validate, and run SwitchBot batch plans (JSON schema for AI agents)')
         .addHelpText('after', `
 A "plan" is a JSON document describing a sequence of commands/scenes/waits.
 The schema is fixed — agents emit plans, the CLI executes them. No LLM inside.

package/dist/commands/schema.js

@@ -1,6 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
+import { RESOURCE_CATALOG } from '../devices/resources.js';
 import { loadCache } from '../devices/cache.js';
 function toSchemaEntry(e) {
     return {
@@ -10,18 +11,22 @@ function toSchemaEntry(e) {
         aliases: e.aliases ?? [],
         role: e.role ?? null,
         readOnly: e.readOnly ?? false,
-        commands: e.commands.map(toSchemaCommand),
+        commands: e.commands.map((c) => toSchemaCommand(c, e)),
         statusFields: e.statusFields ?? [],
     };
 }
-function toSchemaCommand(c) {
+function toSchemaCommand(c, entry) {
+    const tier = deriveSafetyTier(c, entry);
+    const reason = getCommandSafetyReason(c);
     return {
         command: c.command,
         parameter: c.parameter,
         description: c.description,
         commandType: (c.commandType ?? 'command'),
         idempotent: Boolean(c.idempotent),
-        destructive: Boolean(c.destructive),
+        safetyTier: tier,
+        destructive: tier === 'destructive',
+        ...(reason ? { safetyReason: reason } : {}),
         ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
     };
 }
@@ -31,13 +36,17 @@ function toCompactEntry(e) {
         category: e.category,
         role: e.role ?? null,
         readOnly: e.readOnly ?? false,
-        commands: e.commands.map((c) => ({
-            command: c.command,
-            parameter: c.parameter,
-            commandType: (c.commandType ?? 'command'),
-            idempotent: Boolean(c.idempotent),
-            destructive: Boolean(c.destructive),
-        })),
+        commands: e.commands.map((c) => {
+            const tier = deriveSafetyTier(c, e);
+            return {
+                command: c.command,
+                parameter: c.parameter,
+                commandType: (c.commandType ?? 'command'),
+                idempotent: Boolean(c.idempotent),
+                safetyTier: tier,
+                destructive: tier === 'destructive',
+            };
+        }),
         statusFields: e.statusFields ?? [],
     };
 }
@@ -54,7 +63,7 @@ export function registerSchemaCommand(program) {
     const CATEGORIES = ['physical', 'ir'];
     const schema = program
         .command('schema')
-        .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
+        .description('Export the SwitchBot device catalog as structured JSON (for AI agent prompts / tooling)');
     schema
         .command('export')
         .description('Print the catalog as structured JSON (one object per type)')
@@ -137,6 +146,7 @@ Examples:
         };
         if (!options.compact) {
             payload.generatedAt = new Date().toISOString();
+            payload.resources = RESOURCE_CATALOG;
             payload.cliAddedFields = [
                 {
                     field: '_fetchedAt',