odelic 0.0.0-stage → 0.2.1

package/src/controller.ts

@@ -0,0 +1,267 @@
+/**
+ * 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) await this.mesh.connect();
+          try {
+            return await fn(this.mesh);
+          } catch (e) {
+            // retry once when the BLE link dropped under us; input / login errors are final
+            if (attempt || this.mesh.isConnected || e instanceof InputError || e instanceof LoginError) throw e;
+            log.info(`link lost (${(e as Error).message}), reconnecting`);
+            await this.mesh.disconnect();
+          }
+        }
+      } 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.ts

@@ -0,0 +1,100 @@
+/**
+ * Pairlink connected-mesh crypto.
+ *
+ * Reverse-engineered from libnative-lib.so in the ODELIC app (jp.co.odelic.smt.remote10):
+ *
+ * - key material = HomeID (4B, little endian) and password (4 ASCII bytes) interleaved
+ *                  -> h0 p0 h1 p1 h2 p2 h3 p3
+ * - login key    = material + "LOGINKEY"   (AES-128)
+ * - event key    = material + "EVENTKEY"   (AES-128)
+ * - login        : node sends 02 20 <AES_LK(homeid | session4 | pad)>,
+ *                  we answer 01 16 03 <AES_LK(homeid | pwd | session4 | pad)>
+ * - data packets : 03 <dst4> <ch> <payload>  ->  06 <dst4> <ch> XOR4(AES_EK(pkcs7(payload)), session4)
+ */
+import { createCipheriv, createDecipheriv } from 'node:crypto';
+
+import { InputError, LoginError } from './errors.ts';
+
+/** AES-128-ECB without padding; `data` must be a multiple of 16 bytes. */
+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: Uint8Array): Buffer {
+  const n = 16 - (data.length % 16);
+  return Buffer.concat([data, Buffer.alloc(n, n)]);
+}
+
+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');
+  }
+  return data.subarray(0, data.length - n);
+}
+
+/** Keys for one mesh (HomeID + password) and the per-connection session value. */
+export class MeshCrypto {
+  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})`);
+    }
+    if (typeof password !== 'string' || !/^[\x00-\x7f]{4}$/.test(password)) {
+      throw new InputError('password must be 4 ASCII characters');
+    }
+    this.homeid = Buffer.alloc(4);
+    this.homeid.writeUInt32LE(homeid);
+    this.password = Buffer.from(password, 'ascii');
+    const mat = Buffer.alloc(8);
+    for (let i = 0; i < 4; i++) {
+      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')]);
+  }
+
+  /** `challenge` = the 16 encrypted bytes following `02 20`. Returns the login packet. */
+  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])));
+    return Buffer.concat([Buffer.from([0x01, 0x16, 0x03]), body]);
+  }
+
+  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(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, this.session)]);
+  }
+
+  /** `06 <src/dst4> <ch> <cipher>`  ->  `03 <...> <payload>`; other packet types pass through. */
+  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), this.session);
+    body = body.subarray(0, body.length - (body.length % 16));
+    const plain = pkcs7Unpad(aes128(this.eventKey, body, { decrypt: true }));
+    return Buffer.concat([Buffer.from([0x03]), packet.subarray(1, 6), plain]);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,17 @@
+/** Error types. `InputError` = bad user input (HTTP 400); the others come from the mesh / BLE side. */
+
+export class OdelicError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+}
+
+/** Invalid argument: unknown light name, malformed vaddr / ID, out-of-range number, ... */
+export class InputError extends OdelicError {}
+
+/** The node rejected the login (wrong HomeID / password, or another controller is connected). */
+export class LoginError extends OdelicError {}
+
+/** No mesh node found, or the BLE link could not be established. */
+export class ConnectionError extends OdelicError {}

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.ts

@@ -0,0 +1,100 @@
+/**
+ * MCP server exposing ODELIC lights to AI assistants (stdio).
+ *
+ *     npm install odelic @modelcontextprotocol/sdk zod
+ *     odelic-mcp       # reads the ID from ODELIC_ID or the config file (`odelic setup --id ...`)
+ *
+ * The BLE link is opened on the first command. By default it is released after 60 s without
+ * commands so the official phone app can still connect; set ODELIC_IDLE_TIMEOUT (seconds, 0 = stay
+ * connected) or `odelic setup --keep-connected` to change that.
+ */
+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.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.`;
+
+/** 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: unknown): CallToolResult => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+
+/**
+ * Build the MCP server.
+ * @param getController called lazily on the first tool call
+ */
+export function createMcpServer(getController: () => McpController = lazyController()): McpServer {
+  const server = new McpServer({ name: 'odelic', version: VERSION }, { instructions: INSTRUCTIONS });
+  const ctl = () => getController();
+
+  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) {
+        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());
+  tool('light_status', 'Current state of a light: on/off, colour (0 warm..100 cool) and brightness (%).',
+    READ_ONLY, { target }, async (a) => {
+      const res = await ctl().status(a.target);
+      return Array.isArray(res) ? { lights: res } : res;
+    });
+  tool('turn_on', 'Turn a light (or "all") on with its previous colour and brightness.',
+    ACTION, { target }, (a) => ctl().on(a.target));
+  tool('turn_off', 'Turn a light (or "all") off.', ACTION, { target }, (a) => ctl().off(a.target));
+  tool('set_light', 'Turn on with a given colour and brightness.',
+    ACTION, { target, color, brightness }, (a) => ctl().setLight(a.target, a.color, a.brightness));
+  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: 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: 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: 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));
+  tool('forget_light_name', 'Remove a light name from the config.',
+    DESTRUCTIVE, { name: z.string() }, (a) => ctl().forgetName(a.name));
+  return server;
+}
+
+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(): Promise<void> {
+  const server = createMcpServer(lazyController());
+  await server.connect(new StdioServerTransport());
+}