odelic 0.2.0 → 0.2.2

package/src/controller.ts

@@ -0,0 +1,294 @@
+/**
+ * High-level controller shared by the CLI, the HTTP API and the MCP server.
+ *
+ * - connects lazily, serialises operations and reconnects once if the link dropped
+ * - disconnects after `idleTimeout` seconds without commands, so the phone app can use the mesh again
+ *   (0 = keep the link open)
+ * - accepts light names from the config file ("living"), "all", or a raw vaddr ("00000000")
+ */
+import { InputError, LoginError } from './errors.ts';
+import { log } from './log.ts';
+import * as P from './protocol.ts';
+import { OdelicMesh } from './client.ts';
+import { Config } from './config.ts';
+
+/** Where a command goes: a light name from the config, "all", or a vaddr. */
+export type Target = P.VaddrLike;
+
+export interface ActionResult {
+  ok: true;
+  action: string;
+  target?: string;
+  color?: number;
+  brightness?: number;
+  level?: number;
+  group?: number;
+  index?: number;
+}
+
+export interface LightInfo {
+  name: string | null;
+  vaddr: string;
+  online: boolean;
+  mac?: string;
+  product?: number;
+  version?: string;
+}
+
+export type LightStatus =
+  | ({ name: string | null; online: true } & P.LightStateJSON)
+  | { name: string | null; vaddr: string; online: false };
+
+export interface ControllerInfo {
+  connected: boolean;
+  node: string | null;
+  mode: 'keep' | 'idle';
+  idle_timeout: number;
+}
+
+export interface ControllerOptions {
+  /** BLE name / address of the node to connect through (default: config, else strongest node) */
+  node?: string | null;
+  config?: Config | null;
+  /** seconds before an idle link is released; 0 = stay connected; null = $ODELIC_IDLE_TIMEOUT / config / 60 s */
+  idleTimeout?: number | string | null;
+  /** use this mesh connection instead of creating one (mainly for tests) */
+  mesh?: OdelicMesh | null;
+}
+
+/** Integer from a number or numeric string (like Python's int()); throws InputError otherwise. */
+export function toInt(v: unknown, what = 'value'): number {
+  const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v;
+  if (typeof n !== 'number' || !Number.isFinite(n)) throw new InputError(`${what} must be a number (got ${JSON.stringify(v)})`);
+  return Math.trunc(n);
+}
+
+const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
+const byVaddr = (a: P.Device, b: P.Device) => Buffer.compare(a.vaddr, b.vaddr);
+
+export class Controller {
+  readonly config: Config;
+  readonly mesh: OdelicMesh;
+  /** seconds; 0 = keep the link open */
+  readonly idleTimeout: number;
+  private queue: Promise<unknown> = Promise.resolve();
+  private idle: NodeJS.Timeout | null = null;
+
+  /** @param appId default: $ODELIC_ID / config file */
+  constructor(appId: string | null = null, { node = null, config = null, idleTimeout = null, mesh = null }: ControllerOptions = {}) {
+    this.config = config ?? Config.load();
+    const aid = this.config.appId(appId);
+    if (!aid && !mesh) throw new InputError('no app ID: pass --id, set ODELIC_ID, or run `odelic setup --id <ID>`');
+    this.mesh = mesh ?? new OdelicMesh(aid, { device: node ?? this.config.node });
+    this.idleTimeout = this.config.idle(idleTimeout);
+  }
+
+  // ------------------------------------------------------------ connection handling
+  /** Run `fn` after every previously queued operation (a simple mutex). */
+  private locked<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.queue.then(fn);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  private run<T>(fn: (mesh: OdelicMesh) => Promise<T>): Promise<T> {
+    return this.locked(async () => {
+      this.cancelIdle();
+      try {
+        for (let attempt = 0; ; attempt++) {
+          if (!this.mesh.isConnected) {
+            log.info(`connecting via ${this.mesh.device ?? 'strongest node'}`);
+            await this.mesh.connect();
+          } else if (this.mesh.suspect) {
+            log.info('session looks stale, resynchronising');
+            try {
+              await this.mesh.resync();
+            } catch (e) {
+              log.warning(`resync failed (${(e as Error).message}), reconnecting`);
+              await this.mesh.disconnect();
+              continue;
+            }
+          }
+          let res: T;
+          try {
+            res = await fn(this.mesh);
+          } catch (e) {
+            // input / login errors are final; anything else may be a dropped link
+            if (attempt || e instanceof InputError || e instanceof LoginError) throw e;
+            log.warning(`request failed (${(e as Error).message}), reconnecting`);
+            await this.mesh.disconnect();
+            continue;
+          }
+          // status() resolves to null on timeout: the session may have
+          // switched under us (another controller logged in), so make sure
+          // the link is live and retry once
+          if (res === null && !attempt) {
+            log.info('no reply, ensuring the session is live and retrying');
+            try {
+              await this.mesh.ensureLive();
+            } catch (e) {
+              log.warning(`ensureLive failed (${(e as Error).message})`);
+            }
+            continue;
+          }
+          return res;
+        }
+      } finally {
+        this.armIdle();
+      }
+    });
+  }
+
+  private cancelIdle(): void {
+    if (this.idle) clearTimeout(this.idle);
+    this.idle = null;
+  }
+
+  private armIdle(): void {
+    if (!this.idleTimeout || !this.mesh.isConnected) return;
+    this.idle = setTimeout(() => {
+      this.locked(async () => {
+        this.idle = null;
+        if (this.mesh.isConnected) {
+          log.info('idle, disconnecting');
+          await this.mesh.disconnect();
+        }
+      }).catch((e: Error) => log.warning(`idle disconnect failed: ${e.message}`));
+    }, this.idleTimeout * 1000);
+    this.idle.unref();
+  }
+
+  /** Connect now (otherwise the first command connects). */
+  async connect(): Promise<void> {
+    await this.run(async () => {});
+  }
+
+  async close(): Promise<void> {
+    this.cancelIdle();
+    await this.locked(() => this.mesh.disconnect());
+  }
+
+  get connected(): boolean {
+    return this.mesh.isConnected;
+  }
+
+  get keepConnected(): boolean {
+    return !this.idleTimeout;
+  }
+
+  info(): ControllerInfo {
+    return { connected: this.connected, node: this.mesh.nodeName, mode: this.keepConnected ? 'keep' : 'idle', idle_timeout: this.idleTimeout };
+  }
+
+  // ------------------------------------------------------------ helpers
+  private label(v: Buffer): string {
+    return v.equals(P.BROADCAST) ? 'all' : (this.config.nameOf(v) ?? v.toString('hex'));
+  }
+
+  private done(action: string, v: Buffer, extra: Partial<ActionResult> = {}): ActionResult {
+    return { ok: true, action, target: this.label(v), ...extra };
+  }
+
+  // ------------------------------------------------------------ actions
+  async on(target: Target = 'all'): Promise<ActionResult> {
+    const v = this.config.resolve(target);
+    await this.run((m) => m.on(v));
+    return this.done('on', v);
+  }
+
+  async off(target: Target = 'all'): Promise<ActionResult> {
+    const v = this.config.resolve(target);
+    await this.run((m) => m.off(v));
+    return this.done('off', v);
+  }
+
+  /** color 0 (warm) .. 100 (cool), brightness 1..100 % */
+  async setLight(target: Target = 'all', color: number | string = 50, brightness: number | string = 100): Promise<ActionResult> {
+    const v = this.config.resolve(target);
+    const c = clamp(toInt(color, 'color'), 0, 100);
+    const b = clamp(toInt(brightness, 'brightness'), 1, 100);
+    await this.run((m) => m.setLight({ color: c, brightness: b, target: v }));
+    return this.done('light', v, { color: c, brightness: b });
+  }
+
+  async nightLight(target: Target = 'all', level: number | string = 0): Promise<ActionResult> {
+    const v = this.config.resolve(target);
+    const l = clamp(toInt(level, 'level'), 0, 2);
+    await this.run((m) => m.nightLight(l, v));
+    return this.done('night', v, { level: l });
+  }
+
+  /** action: "on", "off" or "light" (uses color / brightness) */
+  async group(groupId: number | string, action = 'on', color: number | string = 50, brightness: number | string = 100): Promise<ActionResult> {
+    const id = toInt(groupId, 'group id');
+    if (action === 'light') {
+      const c = clamp(toInt(color, 'color'), 0, 100);
+      const b = clamp(toInt(brightness, 'brightness'), 1, 100);
+      await this.run((m) => m.setGroup(id, { color: c, brightness: b }));
+    } else if (action === 'on' || action === 'off') {
+      await this.run((m) => m.setGroup(id, { on: action === 'on' }));
+    } else {
+      throw new InputError('action must be on, off or light');
+    }
+    return { ok: true, action: `group_${action}`, group: id };
+  }
+
+  async scene(index: number | string, save = false): Promise<ActionResult> {
+    const i = toInt(index, 'scene index');
+    await this.run((m) => (save ? m.saveScene(i) : m.playScene(i)));
+    return { ok: true, action: save ? 'scene_save' : 'scene_play', index: i };
+  }
+
+  async changeColor(target: Target): Promise<ActionResult> {
+    const v = this.config.resolve(target);
+    await this.run((m) => m.changeColor(v));
+    return this.done('change_color', v);
+  }
+
+  /** Lights answering a mesh ping, plus named lights that did not answer (online: false). */
+  async lights(timeout = 3): Promise<LightInfo[]> {
+    const devs = await this.run((m) => m.devices(timeout));
+    const out: LightInfo[] = [];
+    const seen = new Set<string>();
+    for (const d of [...devs].sort(byVaddr)) {
+      const hex = d.vaddr.toString('hex');
+      seen.add(hex);
+      out.push({ name: this.config.nameOf(d.vaddr), vaddr: hex, online: true, mac: d.mac, product: d.product, version: d.version });
+    }
+    for (const [name, v] of Object.entries(this.config.lights)) {
+      if (!seen.has(v)) out.push({ name, vaddr: v, online: false });
+    }
+    return out;
+  }
+
+  /** State of one light, or of every responding light for "all". */
+  async status(target: Target = 'all'): Promise<LightStatus | LightStatus[]> {
+    const v = this.config.resolve(target);
+    if (v.equals(P.BROADCAST)) {
+      const devs = await this.run((m) => m.devices());
+      const out: LightStatus[] = [];
+      for (const d of [...devs].sort(byVaddr)) out.push(await this.statusOf(d.vaddr));
+      return out;
+    }
+    return this.statusOf(v);
+  }
+
+  private async statusOf(v: Buffer): Promise<LightStatus> {
+    const st = await this.run((m) => m.status(v));
+    if (st === null) return { name: this.config.nameOf(v), vaddr: v.toString('hex'), online: false };
+    return { name: this.config.nameOf(v), online: true, ...st.toJSON() };
+  }
+
+  // ------------------------------------------------------------ names (no BLE needed)
+  nameLight(name: string, target: Target): { ok: true; name: string; vaddr: string } {
+    this.config.setName(name, target);
+    this.config.save();
+    return { ok: true, name, vaddr: this.config.lights[name] };
+  }
+
+  forgetName(name: string): { ok: true; removed: string } {
+    this.config.removeName(name);
+    this.config.save();
+    return { ok: true, removed: name };
+  }
+}

package/src/{crypto.js → crypto.ts}

@@ -13,21 +13,21 @@
  */
 import { createCipheriv, createDecipheriv } from 'node:crypto';
 
-import { InputError, LoginError } from './errors.js';
+import { InputError, LoginError } from './errors.ts';
 
 /** AES-128-ECB without padding; `data` must be a multiple of 16 bytes. */
-export function aes128(key, data, { decrypt = false } = {}) {
-  const c = (decrypt ? createDecipheriv : createCipheriv)('aes-128-ecb', key, null);
+export function aes128(key: Uint8Array, data: Uint8Array, { decrypt = false }: { decrypt?: boolean } = {}): Buffer {
+  const c = decrypt ? createDecipheriv('aes-128-ecb', key, null) : createCipheriv('aes-128-ecb', key, null);
   c.setAutoPadding(false);
   return Buffer.concat([c.update(data), c.final()]);
 }
 
-export function pkcs7Pad(data) {
+export function pkcs7Pad(data: Uint8Array): Buffer {
   const n = 16 - (data.length % 16);
   return Buffer.concat([data, Buffer.alloc(n, n)]);
 }
 
-export function pkcs7Unpad(data) {
+export function pkcs7Unpad(data: Buffer): Buffer {
   const n = data.length ? data[data.length - 1] : 0;
   if (n < 1 || n > 16 || n > data.length || !data.subarray(-n).every((b) => b === n)) {
     throw new InputError('bad padding');
@@ -37,11 +37,15 @@ export function pkcs7Unpad(data) {
 
 /** Keys for one mesh (HomeID + password) and the per-connection session value. */
 export class MeshCrypto {
-  /**
-   * @param {number} homeid
-   * @param {string} password 4 ASCII characters
-   */
-  constructor(homeid, password) {
+  readonly homeid: Buffer;
+  readonly password: Buffer;
+  /** Per-connection value from the login challenge; null until logged in. */
+  session: Buffer | null = null;
+  private readonly loginKey: Buffer;
+  private readonly eventKey: Buffer;
+
+  /** @param password 4 ASCII characters */
+  constructor(homeid: number, password: string) {
     if (!Number.isInteger(homeid) || homeid < 0 || homeid > 0xffffffff) {
       throw new InputError(`HomeID must be a 32-bit unsigned integer (got ${homeid})`);
     }
@@ -56,44 +60,58 @@ export class MeshCrypto {
       mat[2 * i] = this.homeid[i];
       mat[2 * i + 1] = this.password[i];
     }
-    this._loginKey = Buffer.concat([mat, Buffer.from('LOGINKEY')]);
-    this._eventKey = Buffer.concat([mat, Buffer.from('EVENTKEY')]);
-    /** @type {Buffer|null} */
-    this.session = null;
+    this.loginKey = Buffer.concat([mat, Buffer.from('LOGINKEY')]);
+    this.eventKey = Buffer.concat([mat, Buffer.from('EVENTKEY')]);
   }
 
   /** `challenge` = the 16 encrypted bytes following `02 20`. Returns the login packet. */
-  answerChallenge(challenge) {
-    const plain = aes128(this._loginKey, Buffer.from(challenge).subarray(0, 16), { decrypt: true });
+  answerChallenge(challenge: Uint8Array): Buffer {
+    const plain = aes128(this.loginKey, Buffer.from(challenge).subarray(0, 16), { decrypt: true });
     if (!plain.subarray(0, 4).equals(this.homeid)) {
       throw new LoginError(`node belongs to another HomeID (${plain.readUInt32LE(0)})`);
     }
     this.session = Buffer.from(plain.subarray(4, 8));
-    const body = aes128(this._loginKey, pkcs7Pad(Buffer.concat([this.homeid, this.password, this.session])));
+    const body = aes128(this.loginKey, pkcs7Pad(Buffer.concat([this.homeid, this.password, this.session])));
     return Buffer.concat([Buffer.from([0x01, 0x16, 0x03]), body]);
   }
 
-  _xor(data) {
-    const k = this.session;
-    return Buffer.from(data.map((b, i) => b ^ k[i % 4]));
+  /**
+   * Follow a login challenge we did not ask for.
+   *
+   * The node switches to the session value of every new challenge, even when that login is
+   * later refused with status 08. On macOS all processes share one BLE link per peripheral,
+   * so another program logging in through the same link silently invalidates our session
+   * unless we switch too. Returns true if the session changed.
+   */
+  adoptChallenge(challenge: Uint8Array): boolean {
+    const plain = aes128(this.loginKey, Buffer.from(challenge).subarray(0, 16), { decrypt: true });
+    if (!plain.subarray(0, 4).equals(this.homeid)) return false;
+    const next = Buffer.from(plain.subarray(4, 8));
+    const changed = this.session === null || !next.equals(this.session);
+    this.session = next;
+    return changed;
+  }
+
+  private xor(data: Buffer, key: Buffer): Buffer {
+    return Buffer.from(data.map((b, i) => b ^ key[i % 4]));
   }
 
   /** `03 <dst4> <ch> <payload>`  ->  `06 <dst4> <ch> <cipher>` */
-  encrypt(plain) {
-    plain = Buffer.from(plain);
+  encrypt(packet: Uint8Array): Buffer {
+    const plain = Buffer.from(packet);
     if (this.session === null) throw new LoginError('not logged in');
     if (plain.length < 7 || plain[0] !== 0x03) throw new InputError('expected a data-event packet (type 3)');
-    const cipher = aes128(this._eventKey, pkcs7Pad(plain.subarray(6)));
-    return Buffer.concat([Buffer.from([0x06]), plain.subarray(1, 6), this._xor(cipher)]);
+    const cipher = aes128(this.eventKey, pkcs7Pad(plain.subarray(6)));
+    return Buffer.concat([Buffer.from([0x06]), plain.subarray(1, 6), this.xor(cipher, this.session)]);
   }
 
   /** `06 <src/dst4> <ch> <cipher>`  ->  `03 <...> <payload>`; other packet types pass through. */
-  decrypt(packet) {
-    packet = Buffer.from(packet);
+  decrypt(data: Uint8Array): Buffer {
+    const packet = Buffer.from(data);
     if (!packet.length || packet[0] !== 0x06 || this.session === null) return packet;
-    let body = this._xor(packet.subarray(6));
+    let body = this.xor(packet.subarray(6), this.session);
     body = body.subarray(0, body.length - (body.length % 16));
-    const plain = pkcs7Unpad(aes128(this._eventKey, body, { decrypt: true }));
+    const plain = pkcs7Unpad(aes128(this.eventKey, body, { decrypt: true }));
     return Buffer.concat([Buffer.from([0x03]), packet.subarray(1, 6), plain]);
   }
 }

package/src/{errors.js → errors.ts}

@@ -1,9 +1,9 @@
 /** Error types. `InputError` = bad user input (HTTP 400); the others come from the mesh / BLE side. */
 
 export class OdelicError extends Error {
-  constructor(message, options) {
+  constructor(message?: string, options?: ErrorOptions) {
     super(message, options);
-    this.name = this.constructor.name;
+    this.name = new.target.name;
   }
 }
 

package/src/index.ts

@@ -0,0 +1,17 @@
+/** Unofficial Node.js library for ODELIC Bluetooth lights (Pairlink connected-mesh). */
+export { OdelicMesh, findNodes } from './client.ts';
+export type { MeshNode, OdelicMeshOptions, PacketListener, SetGroupOptions, SetLightOptions } from './client.ts';
+export { Config, configPath, parseIdle } from './config.ts';
+export type { ConfigData } from './config.ts';
+export { Controller } from './controller.ts';
+export type { ActionResult, ControllerInfo, ControllerOptions, LightInfo, LightStatus, Target } from './controller.ts';
+export { MeshCrypto } from './crypto.ts';
+export { ConnectionError, InputError, LoginError, OdelicError } from './errors.ts';
+export { setLogLevel } from './log.ts';
+export type { LogLevel } from './log.ts';
+export { BROADCAST, Device, LightState, parseAppId } from './protocol.ts';
+export type { LightStateJSON, VaddrLike } from './protocol.ts';
+export * as protocol from './protocol.ts';
+export { serve } from './server.ts';
+export type { ServeOptions } from './server.ts';
+export { VERSION } from './version.ts';

package/src/log.ts

@@ -0,0 +1,24 @@
+/** Minimal leveled logger writing to stderr (stdout stays clean for the CLI output and MCP stdio). */
+
+const LEVELS = { debug: 10, info: 20, warning: 30, error: 40, silent: 100 } as const;
+export type LogLevel = keyof typeof LEVELS;
+
+const isLevel = (v: string): v is LogLevel => Object.hasOwn(LEVELS, v);
+const fromEnv = String(process.env.ODELIC_LOG ?? '').toLowerCase();
+let current: number = isLevel(fromEnv) ? LEVELS[fromEnv] : LEVELS.warning;
+
+export function setLogLevel(level: LogLevel): void {
+  if (!isLevel(level)) throw new RangeError(`unknown log level ${level}`);
+  current = LEVELS[level];
+}
+
+function emit(level: LogLevel, args: unknown[]): void {
+  if (LEVELS[level] >= current) console.error('odelic:', ...args);
+}
+
+export const log = {
+  debug: (...a: unknown[]) => emit('debug', a),
+  info: (...a: unknown[]) => emit('info', a),
+  warning: (...a: unknown[]) => emit('warning', a),
+  error: (...a: unknown[]) => emit('error', a),
+};

package/src/{mcp.js → mcp.ts}

@@ -10,41 +10,53 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 
-import { Controller } from './controller.js';
-import { VERSION } from './version.js';
+import { Controller } from './controller.ts';
+import { VERSION } from './version.ts';
 
 export const INSTRUCTIONS = `Controls ODELIC Bluetooth ceiling/room lights in the user's home.
 Targets: a light name (see list_lights), or "all" for every light.
 Colour is 0 = warm/電球色 (orange) ... 100 = cool/昼光色 (bluish white); brightness is 1..100 %.
 Commands are fire-and-forget; use light_status to confirm the result if needed.`;
 
-const READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
-const ACTION = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+/** The part of Controller the MCP tools use. */
+export type McpController = Pick<Controller,
+  'lights' | 'status' | 'on' | 'off' | 'setLight' | 'nightLight' | 'group' | 'scene' | 'nameLight' | 'forgetName'>;
+
+const READ_ONLY: ToolAnnotations = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+const ACTION: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const DESTRUCTIVE: ToolAnnotations = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
 
 const target = z.string().default('all').describe('light name, vaddr, or "all"');
 const color = z.number().int().min(0).max(100).default(50).describe('0 = warm/電球色 .. 50 = neutral .. 100 = cool/昼光色');
 const brightness = z.number().int().min(1).max(100).default(100).describe('1..100 (%)');
+const byte = z.number().int().min(0).max(255);
 
-const result = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const result = (value: unknown): CallToolResult => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
 
 /**
  * Build the MCP server.
- * @param {() => Controller} getController called lazily on the first tool call
+ * @param getController called lazily on the first tool call
  */
-export function createMcpServer(getController = lazyController()) {
+export function createMcpServer(getController: () => McpController = lazyController()): McpServer {
   const server = new McpServer({ name: 'odelic', version: VERSION }, { instructions: INSTRUCTIONS });
   const ctl = () => getController();
-  const tool = (name, description, annotations, inputSchema, fn) =>
-    server.registerTool(name, { description, annotations, inputSchema }, async (args) => {
+
+  function tool<S extends z.ZodRawShape>(name: string, description: string, annotations: ToolAnnotations, inputSchema: S,
+    fn: (args: z.infer<z.ZodObject<S>>) => unknown): void {
+    const handler = async (args: z.infer<z.ZodObject<S>>): Promise<CallToolResult> => {
       try {
         return result(await fn(args));
       } catch (e) {
-        return { ...result({ ok: false, error: `${e.name}: ${e.message}` }), isError: true };
+        const err = e as Error;
+        return { ...result({ ok: false, error: `${err.name}: ${err.message}` }), isError: true };
       }
-    });
+    };
+    // the SDK's registerTool generics do not narrow well through this helper
+    (server.registerTool as (n: string, c: object, h: typeof handler) => unknown)(name, { description, annotations, inputSchema }, handler);
+  }
 
   tool('list_lights', 'List the lights in the mesh (name, vaddr, online, product). Takes a few seconds.',
     READ_ONLY, {}, () => ctl().lights());
@@ -61,12 +73,12 @@ export function createMcpServer(getController = lazyController()) {
   tool('night_light', 'Very dim warm night light. level 0..2.',
     ACTION, { target, level: z.number().int().min(0).max(2).default(0) }, (a) => ctl().nightLight(a.target, a.level));
   tool('control_group', 'Control a group configured in the ODELIC app. action: "on", "off" or "light" (uses color/brightness).',
-    ACTION, { group_id: z.number().int().min(0).max(255), action: z.enum(['on', 'off', 'light']).default('on'), color, brightness },
+    ACTION, { group_id: byte, action: z.enum(['on', 'off', 'light']).default('on'), color, brightness },
     (a) => ctl().group(a.group_id, a.action, a.color, a.brightness));
   tool('play_scene', 'Recall a scene saved in the lights (index as in the app).',
-    ACTION, { index: z.number().int().min(0).max(255) }, (a) => ctl().scene(a.index, false));
+    ACTION, { index: byte }, (a) => ctl().scene(a.index, false));
   tool('save_scene', 'Store the current state of all lights as scene `index` (overwrites that scene).',
-    DESTRUCTIVE, { index: z.number().int().min(0).max(255) }, (a) => ctl().scene(a.index, true));
+    DESTRUCTIVE, { index: byte }, (a) => ctl().scene(a.index, true));
   tool('name_light', 'Give a light (vaddr from list_lights) a friendly name such as "living" or "リビング".',
     { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, { name: z.string().min(1), vaddr: z.string() },
     (a) => ctl().nameLight(a.name, a.vaddr));
@@ -75,15 +87,14 @@ export function createMcpServer(getController = lazyController()) {
   return server;
 }
 
-function lazyController() {
-  let c = null;
+function lazyController(): () => Controller {
+  let c: Controller | null = null;
   // idle timeout from $ODELIC_IDLE_TIMEOUT / config (0 = stay connected)
   return () => (c ??= new Controller());
 }
 
 /** Run the MCP server on stdio (logs go to stderr). */
-export async function main() {
-  const getController = lazyController();
-  const server = createMcpServer(getController);
+export async function main(): Promise<void> {
+  const server = createMcpServer(lazyController());
   await server.connect(new StdioServerTransport());
 }