teleq-mcp 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TeleQ contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# teleq-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let Claude (or any MCP client) put things on your TV through the [TeleQ](https://teleq.online) app:
+large text cards, slides, pictures, video and small HTML dashboards. It talks to the TV over your
+home Wi‑Fi; nothing goes through a cloud server.
+
+```
+Claude Code / Claude Desktop / Cursor / Gemini CLI ──stdio──▶ teleq-mcp ──HTTP POST /mcp──▶ TeleQ on the TV
+```
+
+`teleq-mcp` is a thin bridge: the TV itself is the MCP server and decides what an assistant may do.
+It has no dependencies besides Node.js.
+
+For Claude on the web or phone, and for ChatGPT, use the cloud connector
+`https://relay.teleq.online/mcp` instead (see <https://teleq.online/ai/>).
+
+## Requirements
+
+* TeleQ open on an Android TV.
+* A computer on the **same Wi‑Fi** as the TV, with Node.js 18.17 or newer.
+
+## Install and link
+
+1. On the TV: TeleQ → **Linked devices** → **Link an assistant**. A 9‑digit code appears (valid for 5 minutes).
+2. On the computer:
+
+   ```bash
+   npx teleq-mcp pair
+   ```
+
+   It looks for TeleQ on your network, asks for the code and stores a key for this TV in your user
+   folder (owner-only file). The TV keeps only a hash of the key. Options:
+
+   * `--host 192.168.1.20` — skip the search and use this address (`--host 192.168.1.20:8766` for another port);
+   * `--name "Claude on my laptop"` — how the assistant is listed on the TV.
+
+3. Add it to your client:
+
+   | Client | How |
+   |---|---|
+   | Claude Code | `claude mcp add teleq -- npx -y teleq-mcp` |
+   | Claude Desktop | `"teleq": { "command": "npx", "args": ["-y", "teleq-mcp"] }` under `mcpServers` in `claude_desktop_config.json`, then restart |
+   | Cursor | the same JSON in `~/.cursor/mcp.json` (`mcpServers`) |
+   | VS Code | `"teleq": { "type": "stdio", "command": "npx", "args": ["-y", "teleq-mcp"] }` under `servers` in `.vscode/mcp.json` |
+   | Gemini CLI | the same JSON in `~/.gemini/settings.json` (`mcpServers`) |
+
+Then ask: “show tonight's recipe on the TV”, “make a 5-slide presentation about the Moon and check that
+everything fits”, “play this stream on the TV, then pause it”.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npx teleq-mcp pair [--host <ip[:port]>] [--name <label>]` | Link this computer with the code shown on the TV. |
+| `npx teleq-mcp status` | Show the linked TV, whether it answers right now, and where the config lives. |
+| `npx teleq-mcp unlink` | Forget the TV on this computer. To also revoke the key, choose **Unlink** next to it on the TV. |
+| `npx teleq-mcp` (or `serve`) | Run as an MCP server over stdio. This is what the client starts; you don't run it by hand. |
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `TELEQ_CONFIG_DIR` | Where the key (`tv.json`) and the tool cache (`cache.json`) are kept. Default: `$XDG_CONFIG_HOME/teleq`, `%APPDATA%\teleq` on Windows, else `~/.config/teleq`. Handy for linking two TVs: run each server with its own directory. |
+| `XDG_CONFIG_HOME`, `APPDATA` | Used for the default above. |
+
+## How it behaves
+
+* **The TV moved to a new address** (DHCP): when a call fails, the bridge searches the local /24 again,
+  prefers a TV with the same name and saves the new address.
+* **The TV is off**: `initialize` and `tools/list` are answered from the last description the TV sent,
+  so the client starts normally; tool calls return a readable error ("Can't reach the TV…").
+* **Unlinked on the TV**: calls return "This TV no longer trusts this computer"; run `pair` again.
+* **Limits** are enforced on the TV: 30 calls a minute per assistant, public `https://` links only
+  (nothing on your home network, no YouTube), HTML pages run in a sandbox without network access.
+  While an assistant's content is up the TV shows who put it there, and **Back** on the remote stops it.
+
+## Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| `No TV found` during `pair` | TeleQ must be open on the TV and both devices on the same Wi‑Fi (not a guest network, no VPN on the computer). Pass the TV's address with `--host`; it is shown in TeleQ on the TV under the QR code. |
+| `Wrong code` / `Too many wrong codes` | Codes last 5 minutes; 5 wrong tries burn the code and pause entry for 30 s. Open **Link an assistant** again for a fresh one. |
+| The client lists no TeleQ tools | Run `npx teleq-mcp status`. If it says "Not linked", run `pair`. Check the client's MCP log for `teleq-mcp:` lines (they go to stderr). |
+| `Can't reach the TV` on every call | The TV is asleep or TeleQ is closed. TeleQ can't be woken from the computer. |
+| Corporate or mesh Wi‑Fi blocks device-to-device traffic | Use the cloud connector (`https://relay.teleq.online/mcp`) instead. |
+| Start over | `npx teleq-mcp unlink`, unlink it on the TV too, then `pair`. |
+
+## Development
+
+```bash
+npm test                 # node --test, no dependencies
+node bin/teleq-mcp.mjs pair --host 192.168.1.20
+claude mcp add teleq-dev -- node "$PWD/bin/teleq-mcp.mjs"
+```
+
+License: MIT.

package/bin/teleq-mcp.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import readline from 'node:readline/promises';
+import os from 'node:os';
+import { createAutoBridge, serve } from '../src/bridge.mjs';
+import { configDir, deleteConfig, loadConfig, saveConfig } from '../src/config.mjs';
+import { DEFAULT_PORT, discover, isPrivateIPv4, pairWithCode, probe } from '../src/tv.mjs';
+
+const clientName = () => (process.env.TELEQ_CLIENT_NAME || `Claude on ${os.hostname().replace(/\.local$/, '')}`).slice(0, 60);
+
+const HELP = `teleq-mcp: let Claude put things on your TV
+
+  npx teleq-mcp pair [--host <tv-ip>] [--name <label>]   link this computer with the code on the TV
+  npx teleq-mcp status                                   show the linked TV and whether it answers
+  npx teleq-mcp unlink                                   forget the TV on this computer
+  npx teleq-mcp                                          run as an MCP server over stdio (what Claude starts);
+                                                         without a linked TV it offers a link_tv tool
+
+On the TV: open TeleQ -> "AI assistants" -> "Link an assistant" to get a code.
+`;
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+async function pair() {
+  const log = (s) => process.stderr.write(s + '\n');
+  let target;
+  const host = arg('host');
+  if (host) {
+    if (!isPrivateIPv4(host)) throw new Error('--host must be the TV\'s address on your home network (like 192.168.1.20).');
+    const [h, p] = host.split(':');
+    target = { host: h, port: Number(p) || DEFAULT_PORT };
+    if (!(await probe(target.host, target.port))) throw new Error(`No TeleQ TV answered at ${host}.`);
+  } else {
+    log('Looking for TVs on your network…');
+    const found = await discover();
+    if (found.length === 0) {
+      throw new Error('No TV found. Open TeleQ on the TV (same Wi-Fi), or pass its address with --host 192.168.x.x');
+    }
+    if (found.length === 1) target = found[0];
+    else {
+      found.forEach((t, i) => log(`  ${i + 1}) ${t.tvName ?? 'TV'}  ${t.host}`));
+      const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+      const n = Number(await rl.question('Which one? '));
+      rl.close();
+      target = found[n - 1];
+      if (!target) throw new Error('No such TV.');
+    }
+  }
+  log(`Found ${target.tvName ?? 'a TV'} at ${target.host}.`);
+  log('On the TV: TeleQ -> AI assistants -> Link an assistant. Type the code it shows.');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const code = await rl.question('Code: ');
+  rl.close();
+  const name = arg('name') ?? clientName();
+  const { key, tvName } = await pairWithCode(target, code, name);
+  saveConfig({ host: target.host, port: target.port, key, tvName: tvName ?? target.tvName });
+  log(`Linked with ${tvName ?? 'the TV'} as "${name}". Claude can use it now.`);
+}
+
+async function status() {
+  const cfg = loadConfig();
+  if (!cfg) {
+    console.log('Not linked. Run: npx teleq-mcp pair');
+    return;
+  }
+  const info = await probe(cfg.host, cfg.port);
+  console.log(`${cfg.tvName ?? 'TV'} at ${cfg.host}:${cfg.port}: ${info ? 'reachable' : 'not reachable (switched off, or it moved: it is searched for again when Claude starts)'}`);
+  console.log(`config: ${configDir()}`);
+}
+
+async function run() {
+  // Works without a linked TV too: the assistant then offers link_tv (the Claude Desktop extension relies on it).
+  const bridge = createAutoBridge({
+    configDir: configDir(),
+    deps: { loadConfig, saveConfig, discover, probe, pairWithCode, name: clientName },
+  });
+  await serve(bridge);
+}
+
+const cmd = process.argv[2];
+try {
+  if (cmd === 'pair') await pair();
+  else if (cmd === 'status') await status();
+  else if (cmd === 'unlink') {
+    deleteConfig();
+    console.log('Forgot the TV on this computer. To also revoke the key, unlink it in TeleQ on the TV (AI assistants).');
+  } else if (cmd === '--help' || cmd === '-h' || cmd === 'help') process.stdout.write(HELP);
+  else if (cmd === undefined || cmd === 'serve') await run();
+  else {
+    process.stderr.write(HELP);
+    process.exitCode = 2;
+  }
+} catch (e) {
+  process.stderr.write(`teleq-mcp: ${e.message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "teleq-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Let Claude (or any MCP client) show text, slides, images, video and web pages on your TV through the TeleQ app, over your home network.",
+  "mcpName": "io.github.max4et/teleq",
+  "type": "module",
+  "bin": { "teleq-mcp": "bin/teleq-mcp.mjs" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.17" },
+  "scripts": { "test": "node --test test/*.test.mjs", "pack:mcpb": "node scripts/pack-mcpb.mjs" },
+  "repository": { "type": "git", "url": "git+https://github.com/max4et/teleq.git", "directory": "mcp" },
+  "homepage": "https://teleq.online/ai/",
+  "bugs": { "url": "https://github.com/max4et/teleq/issues", "email": "support@teleq.online" },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "tv", "android-tv", "claude", "chatgpt", "teleq", "presentation", "smart-tv"],
+  "license": "MIT"
+}

package/src/bridge.mjs

@@ -0,0 +1,268 @@
+// MCP stdio <-> TeleQ TV. Newline-delimited JSON-RPC in, the same out; every message is forwarded
+// to POST /mcp on the TV. The bridge holds no tool logic of its own: the TV is the MCP server.
+import fs from 'node:fs';
+import { DEFAULT_PORT, discover, isPrivateIPv4, probe } from './tv.mjs';
+import { loadCache, saveCache } from './config.mjs';
+
+/** What TeleQ offers (tools/ai/catalog.mjs), for clients that start before this computer ever reached the TV. */
+const CATALOG = JSON.parse(fs.readFileSync(new URL('./catalog.json', import.meta.url), 'utf8'));
+const CACHED = { initialize: 'initialize', 'tools/list': 'tools', 'prompts/list': 'prompts' };
+
+const UNREACHABLE =
+  "Can't reach the TV. Open the TeleQ app on it (same Wi-Fi as this computer) and try again.";
+const REVOKED =
+  'This TV no longer trusts this computer (it was unlinked). Run "npx teleq-mcp pair" to link it again.';
+
+function rpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+}
+
+/** An older TV answers a tool it doesn't have with a JSON-RPC "Unknown tool" error. */
+function olderTv(reply) {
+  return typeof reply?.error?.message === 'string' && reply.error.message.startsWith('Unknown tool:');
+}
+
+const updateTv = (tool) =>
+  `This TV runs an older version of TeleQ that doesn't have "${tool}". Ask the user to update TeleQ on the TV (Google Play), or use the tools listed by tv_status.`;
+
+function toolError(id, text) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }], isError: true } });
+}
+
+/**
+ * [config] is the saved { host, port, key, tvName }; [onConfig] is called when the TV moved to a new
+ * address so the caller can persist it. Returns an async function: one input line in, one output
+ * line (or null when nothing should be written) out.
+ */
+export function createBridge({ config, onConfig = () => {}, configDir, rediscover = discover, timeoutMs = 20000 }) {
+  let current = { ...config };
+
+  async function post(body) {
+    return fetch(`http://${current.host}:${current.port}/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${current.key}` },
+      body,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  }
+
+  /** The TV may have a new DHCP address: find it again, preferring the one with the same name. */
+  async function relocate() {
+    const found = await rediscover();
+    const match = found.find((t) => t.tvName && t.tvName === current.tvName) ?? (found.length === 1 ? found[0] : null);
+    if (!match) return false;
+    current = { ...current, host: match.host, port: match.port };
+    onConfig(current);
+    return true;
+  }
+
+  async function send(line, msg) {
+    try {
+      return await post(line);
+    } catch {
+      if (!(await relocate())) return null;
+      try {
+        return await post(line);
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  /** The TV's last answer to initialize / tools/list / prompts/list, else what TeleQ offers in general. */
+  function fromCache(msg) {
+    const key = CACHED[msg.method];
+    if (!key) return null;
+    const hit = loadCache(configDir)[key] ?? CATALOG[key];
+    if (!hit) return null;
+    const result = msg.method === 'initialize' && typeof msg.params?.protocolVersion === 'string'
+      ? { ...hit, protocolVersion: hit.protocolVersion ?? msg.params.protocolVersion }
+      : hit;
+    return JSON.stringify({ jsonrpc: '2.0', id: msg.id, result });
+  }
+
+  return async function handleLine(line) {
+    if (!line.trim()) return null;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return rpcError(null, -32700, 'Parse error');
+    }
+    const isRequest = msg && typeof msg === 'object' && msg.id !== undefined && msg.id !== null && typeof msg.method === 'string';
+
+    const res = await send(line, msg);
+    if (!res) {
+      if (!isRequest) return null;
+      return fromCache(msg) ?? (msg.method === 'tools/call' ? toolError(msg.id, UNREACHABLE) : rpcError(msg.id, -32000, UNREACHABLE));
+    }
+    if (res.status === 202) return null;
+    if (res.status === 401) {
+      if (!isRequest) return null;
+      return msg.method === 'tools/call' ? toolError(msg.id, REVOKED) : rpcError(msg.id, -32001, REVOKED);
+    }
+    if (res.status === 429) {
+      if (!isRequest) return null;
+      return msg.method === 'tools/call'
+        ? toolError(msg.id, 'The TV is rate limiting requests. Wait a few seconds and try again.')
+        : rpcError(msg.id, -32002, 'Rate limited by the TV');
+    }
+    const text = await res.text();
+    if (isRequest && res.ok) {
+      let reply;
+      try {
+        reply = JSON.parse(text);
+      } catch {
+        // Not JSON: pass it through untouched.
+      }
+      if (reply?.result && CACHED[msg.method]) {
+        const cache = loadCache(configDir);
+        cache[CACHED[msg.method]] = reply.result;
+        saveCache(cache, configDir);
+      }
+      if (msg.method === 'tools/call' && olderTv(reply)) return toolError(msg.id, updateTv(String(msg.params?.name ?? 'that tool').slice(0, 64)));
+      // A TV from before prompts: "Method not found" for prompts/list means none.
+      if (msg.method === 'prompts/list' && reply?.error?.code === -32601) {
+        return JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { prompts: [] } });
+      }
+    }
+    return res.ok ? text : isRequest ? rpcError(msg.id, -32003, `The TV answered HTTP ${res.status}`) : null;
+  };
+}
+
+/** Wires [handleLine] to a pair of streams. Resolves when stdin ends. */
+export async function serve(handleLine, input = process.stdin, output = process.stdout) {
+  let buffer = '';
+  const pending = new Set();
+  const write = (s) => s && output.write(s + '\n');
+  const run = (line) => {
+    const p = handleLine(line).then(write, (e) => write(rpcError(null, -32603, String(e?.message ?? e))));
+    pending.add(p);
+    p.finally(() => pending.delete(p));
+  };
+  input.setEncoding('utf8');
+  for await (const chunk of input) {
+    buffer += chunk;
+    let i;
+    while ((i = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, i);
+      buffer = buffer.slice(i + 1);
+      run(line);
+    }
+  }
+  if (buffer.trim()) run(buffer);
+  await Promise.allSettled([...pending]);
+}
+
+export { probe };
+
+// ---- linking from inside the assistant (Claude Desktop extension, no terminal) ----
+
+export const LINK_TV_TOOL = {
+  name: 'link_tv',
+  title: 'Link a TV',
+  description:
+    'Link this computer with a TV running TeleQ on the same Wi-Fi. Ask the user to open TeleQ on the TV, choose Linked devices → Link an assistant, and read you the 9-digit code. Only needed once per TV (or after it was unlinked).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      code: { type: 'string', description: 'The 9-digit code shown on the TV.' },
+      tv_address: { type: 'string', description: "Optional: the TV's address on the home network (like 192.168.1.20), when several TVs are found." },
+    },
+    required: ['code'],
+    additionalProperties: false,
+  },
+  annotations: { title: 'Link a TV', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+};
+
+const NOT_LINKED =
+  'No TV is linked yet. Ask the user to open TeleQ on the TV → Linked devices → Link an assistant, then call link_tv with the 9-digit code.';
+
+const json = (id, result) => JSON.stringify({ jsonrpc: '2.0', id, result });
+const text = (id, t, isError = false) => json(id, { content: [{ type: 'text', text: t }], isError });
+
+/**
+ * The bridge as the client starts it: works whether or not a TV is linked, and offers link_tv either way.
+ * [deps] are injectable for tests: loadConfig/saveConfig, discover, probe, pairWithCode, name.
+ */
+export function createAutoBridge({ configDir, deps, defaultHost = process.env.TELEQ_TV_HOST }) {
+  let inner = null;
+  const config = () => deps.loadConfig(configDir);
+  const ensure = () => {
+    const cfg = config();
+    if (cfg && (!inner || inner.key !== cfg.key)) {
+      inner = { key: cfg.key, handle: createBridge({ config: cfg, configDir, onConfig: (c) => deps.saveConfig(c, configDir), rediscover: deps.discover }) };
+    }
+    return inner;
+  };
+
+  async function linkTv(id, args) {
+    const code = String(args?.code ?? '').replace(/\D/g, '');
+    if (code.length !== 9) return text(id, 'The code has 9 digits. Ask the user for the code shown on the TV.', true);
+    let target;
+    const address = String(args?.tv_address ?? defaultHost ?? '').trim();
+    if (address) {
+      const [host, p] = address.split(':');
+      if (!isPrivateIPv4(host)) return text(id, 'tv_address must be the TV\'s address on the home network, like 192.168.1.20.', true);
+      const port = Number(p) || DEFAULT_PORT;
+      const info = await deps.probe(host, port);
+      if (!info) return text(id, `No TeleQ TV answered at ${address}. Is TeleQ open on it?`, true);
+      target = { host, port, tvName: info.tvName };
+    } else {
+      const found = await deps.discover();
+      if (found.length === 0) return text(id, "No TV found on this network. TeleQ must be open on the TV, on the same Wi-Fi as this computer (not a guest network). You can also pass tv_address.", true);
+      if (found.length > 1) {
+        return text(id, `Several TVs found: ${found.map((t) => `${t.tvName ?? 'TV'} (${t.host})`).join(', ')}. Call link_tv again with tv_address set to the one showing the code.`, true);
+      }
+      target = found[0];
+    }
+    try {
+      const { key, tvName } = await deps.pairWithCode(target, code, deps.name());
+      deps.saveConfig({ host: target.host, port: target.port, key, tvName: tvName ?? target.tvName }, configDir);
+      inner = null;
+      return text(id, `Linked with ${tvName ?? target.tvName ?? 'the TV'}. You can use the TV tools now (start with tv_status).`);
+    } catch (e) {
+      return text(id, e.message, true);
+    }
+  }
+
+  return async function handleLine(line) {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return line.trim() ? rpcError(null, -32700, 'Parse error') : null;
+    }
+    const isRequest = msg && msg.id !== undefined && msg.id !== null && typeof msg.method === 'string';
+    if (isRequest && msg.method === 'tools/call' && msg.params?.name === 'link_tv') return linkTv(msg.id, msg.params.arguments);
+    const linked = ensure();
+    if (linked) {
+      const out = await linked.handle(line);
+      if (out && isRequest && msg.method === 'tools/list') {
+        try {
+          const reply = JSON.parse(out);
+          if (Array.isArray(reply.result?.tools) && !reply.result.tools.some((t) => t.name === 'link_tv')) reply.result.tools.push(LINK_TV_TOOL);
+          return JSON.stringify(reply);
+        } catch {
+          return out;
+        }
+      }
+      return out;
+    }
+    // Not linked: describe what TeleQ offers, and point every tool call at link_tv.
+    if (!isRequest) return null;
+    switch (msg.method) {
+      case 'initialize':
+        return json(msg.id, {
+          ...CATALOG.initialize,
+          protocolVersion: typeof msg.params?.protocolVersion === 'string' ? msg.params.protocolVersion : '2025-06-18',
+          instructions: `${CATALOG.initialize.instructions} ${NOT_LINKED}`,
+        });
+      case 'ping': return json(msg.id, {});
+      case 'tools/list': return json(msg.id, { tools: [...CATALOG.tools.tools, LINK_TV_TOOL] });
+      case 'prompts/list': return json(msg.id, CATALOG.prompts);
+      case 'tools/call': return text(msg.id, NOT_LINKED, true);
+      default: return rpcError(msg.id, -32601, `Method not found: ${msg.method}`);
+    }
+  };
+}

package/src/catalog.json

@@ -0,0 +1,626 @@
+{
+  "initialize": {
+    "capabilities": {
+      "tools": {
+        "listChanged": false
+      },
+      "prompts": {
+        "listChanged": false
+      }
+    },
+    "serverInfo": {
+      "name": "teleq-tv",
+      "title": "TeleQ TV",
+      "version": "catalog"
+    },
+    "instructions": "This server controls one TV in the user's home through the TeleQ app. Put content up with show_text, show_slides, show_html, show_image, show_queue and play_video; every show_* call returns an id that update_text / update_html / slides_control use. Design for a 10-foot screen: 16:9, dark background, light text, at least 28 px body text and 48 px headings at 1080p, at most about 6 lines or bullets per screen, no scrolling, nothing interactive, keep 5% margins (TV overscan) and leave the top-right corner free for the TeleQ badge. After showing something important, call screen_snapshot to see what the TV really shows and fix overflow or tiny text with update_html or by showing it again. Video frames may appear black in snapshots. For presentations use show_slides (one idea per slide, speaker notes in notes) and slides_control to move; the viewer can also use ←/→ on the remote. For live boards (scores, timers, progress) show_html once and push new values with update_html data; the page receives them as window \"message\" events with {type:\"teleq:update\", data}. Pages have no network access: inline everything. Use notify for a short heads-up without interrupting what is playing; it is limited to one every 10 s. Call tv_status first if unsure what is on screen; its capabilities list says which tools this TV supports (older TVs may lack some: ask the user to update TeleQ). The user sees on the TV which assistant put content up and can stop it with Back on the remote. Don't show anything the user didn't ask for."
+  },
+  "tools": {
+    "tools": [
+      {
+        "name": "tv_status",
+        "title": "TV status",
+        "description": "Check what the TV is showing right now (and its id, slide or queue position), whether a phone is also connected, the screen size and safe area, and which tools this TV supports (capabilities). Call this before changing the screen if you are unsure what is on it.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Checking the TV…",
+          "openai/toolInvocation/invoked": "Checked the TV"
+        },
+        "annotations": {
+          "title": "TV status",
+          "readOnlyHint": true,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "show_text",
+        "title": "Show text on the TV",
+        "description": "Show a large, readable text card on the TV: a recipe, a list, a summary, an answer. Keep it short; people read it from the couch. Markdown subset: # headings, **bold**, - bullet lists, 1. numbered lists, blank lines between paragraphs. Returns an id for update_text.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "markdown": {
+              "type": "string",
+              "description": "The text to show (Markdown subset). Up to 20000 characters."
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional heading shown above the text (up to 120 characters)."
+            },
+            "duration_s": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3600,
+              "description": "Optional: clear the screen after this many seconds (1-3600). Without it the content stays until replaced or stopped."
+            }
+          },
+          "required": [
+            "markdown"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Putting the text on the TV…",
+          "openai/toolInvocation/invoked": "Text is on the TV"
+        },
+        "annotations": {
+          "title": "Show text on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "show_slides",
+        "title": "Present slides on the TV",
+        "description": "Show a presentation: a list of slides, each either Markdown (rendered as a big, centred TV slide) or a complete self-contained HTML page (sandboxed, no network). The viewer moves with ←/→ on the remote; you move with slides_control. Put what you would say in notes (not shown on the TV; returned by slides_control). Up to 50 slides and 1024 KB in total. Returns an id.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "slides": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 50,
+              "description": "The slides in order. Each needs markdown or html (not both).",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "markdown": {
+                    "type": "string",
+                    "description": "Slide content in the Markdown subset (# heading, - bullets, **bold**). Aim for a heading and at most 5 short bullets."
+                  },
+                  "html": {
+                    "type": "string",
+                    "description": "A complete HTML document for this slide, designed for 1920x1080, dark background, no scrolling."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Optional slide title, used in status and the slide counter."
+                  },
+                  "notes": {
+                    "type": "string",
+                    "description": "Optional speaker notes (up to 4000 characters), never shown on the TV."
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional presentation title (up to 120 characters)."
+            },
+            "start_slide": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50,
+              "description": "Optional slide to open first (1-based). Default 1."
+            }
+          },
+          "required": [
+            "slides"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Putting the slides on the TV…",
+          "openai/toolInvocation/invoked": "Slides are on the TV"
+        },
+        "annotations": {
+          "title": "Present slides on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "slides_control",
+        "title": "Move through the slides",
+        "description": "Go to the next, previous, first, last or a given slide of the presentation on screen. Returns the slide number, the count and that slide's notes.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "action": {
+              "type": "string",
+              "enum": [
+                "next",
+                "prev",
+                "first",
+                "last",
+                "goto"
+              ],
+              "description": "Where to go."
+            },
+            "slide": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50,
+              "description": "Slide number (1-based). Required for \"goto\"."
+            },
+            "id": {
+              "type": "string",
+              "description": "Optional: the id from show_slides, to make sure the right presentation is still on screen."
+            }
+          },
+          "required": [
+            "action"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Changing the slide…",
+          "openai/toolInvocation/invoked": "Slide changed"
+        },
+        "annotations": {
+          "title": "Move through the slides",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "show_html",
+        "title": "Show an HTML page on the TV",
+        "description": "Show a self-contained HTML page (a dashboard, a chart, a scoreboard, a timer, a visual) full screen on the TV. It runs in a locked-down sandbox: scripts and CSS work, but there is no network access, so inline everything; images may be data: URIs or https:// URLs. Design for 1920x1080, large type, dark background, no scrolling, no input. To change values later without reloading, listen for window \"message\" events whose data is {type:\"teleq:update\", data} and call update_html. Returns an id.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "html": {
+              "type": "string",
+              "description": "A complete HTML document. Up to 262144 characters."
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional title (not drawn; used in the status) (up to 120 characters)."
+            },
+            "duration_s": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3600,
+              "description": "Optional: clear the screen after this many seconds (1-3600). Without it the content stays until replaced or stopped."
+            }
+          },
+          "required": [
+            "html"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Putting the page on the TV…",
+          "openai/toolInvocation/invoked": "Page is on the TV"
+        },
+        "annotations": {
+          "title": "Show an HTML page on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "update_text",
+        "title": "Update the text on the TV",
+        "description": "Replace the text of a card shown with show_text, in place and without flicker. Only works while that card is still on screen.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The id returned by the show_* call that put the content up."
+            },
+            "markdown": {
+              "type": "string",
+              "description": "The new text (Markdown subset). Up to 20000 characters."
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional new heading (up to 120 characters)."
+            }
+          },
+          "required": [
+            "id",
+            "markdown"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Updating the TV…",
+          "openai/toolInvocation/invoked": "TV updated"
+        },
+        "annotations": {
+          "title": "Update the text on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "update_html",
+        "title": "Update the page on the TV",
+        "description": "Update a page shown with show_html. With data, the page stays and receives a window \"message\" event {type:\"teleq:update\", data} (no reload, no flicker; up to 64 KB of JSON). With html, the page is replaced (a short reload). Only works while that page is still on screen.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The id returned by the show_* call that put the content up."
+            },
+            "data": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "New values for the page, delivered as message event data."
+            },
+            "html": {
+              "type": "string",
+              "description": "Optional replacement HTML document (up to 262144 characters)."
+            }
+          },
+          "required": [
+            "id"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Updating the TV…",
+          "openai/toolInvocation/invoked": "TV updated"
+        },
+        "annotations": {
+          "title": "Update the page on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "show_image",
+        "title": "Show an image on the TV",
+        "description": "Show a picture on the TV, letterboxed on a black background. The image must be reachable on the public internet over https://.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "Public https:// URL of a JPEG, PNG, WebP or GIF image."
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional caption (up to 120 characters)."
+            }
+          },
+          "required": [
+            "url"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Showing the picture on the TV…",
+          "openai/toolInvocation/invoked": "Picture sent to the TV"
+        },
+        "annotations": {
+          "title": "Show an image on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": true
+        }
+      },
+      {
+        "name": "show_queue",
+        "title": "Show several photos and videos",
+        "description": "Show up to 50 photos and videos one after another: each photo stays for its duration_s (default 8 s), each video plays to the end. The viewer can skip with ←/→ on the remote. Public https:// links only. Returns an id.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 50,
+              "description": "The photos and videos in order.",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "description": "Public https:// URL of an image or a video (file, HLS or DASH)."
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "image",
+                      "video"
+                    ],
+                    "description": "Optional; guessed from the link when missing."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Optional caption."
+                  },
+                  "duration_s": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 3600,
+                    "description": "Photos only: seconds on screen (default 8)."
+                  }
+                },
+                "required": [
+                  "url"
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": [
+            "items"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Showing the pictures on the TV…",
+          "openai/toolInvocation/invoked": "Pictures sent to the TV"
+        },
+        "annotations": {
+          "title": "Show several photos and videos",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": true
+        }
+      },
+      {
+        "name": "play_video",
+        "title": "Play a video on the TV",
+        "description": "Play a video on the TV in full screen. Works with direct video files (.mp4, .webm, .mkv) and HLS (.m3u8) or DASH (.mpd) streams over public https://. YouTube and DRM-protected services are not supported. Use `playback` afterwards to pause, resume or seek.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "Public https:// URL of the video file or stream."
+            },
+            "title": {
+              "type": "string",
+              "description": "Optional title shown on the TV (up to 120 characters)."
+            }
+          },
+          "required": [
+            "url"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Starting the video on the TV…",
+          "openai/toolInvocation/invoked": "Video sent to the TV"
+        },
+        "annotations": {
+          "title": "Play a video on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": true
+        }
+      },
+      {
+        "name": "notify",
+        "title": "Show a short notice on the TV",
+        "description": "Show a short notice for a few seconds on top of whatever is on screen, without interrupting a video. Up to 200 characters, at most one every 10 seconds.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "text": {
+              "type": "string",
+              "description": "The notice (up to 200 characters)."
+            }
+          },
+          "required": [
+            "text"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Sending a notice to the TV…",
+          "openai/toolInvocation/invoked": "Notice shown"
+        },
+        "annotations": {
+          "title": "Show a short notice on the TV",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "screen_snapshot",
+        "title": "See the TV screen",
+        "description": "Get a picture (at most 1280 px wide) of what TeleQ is showing right now, to check that your content fits and looks right. Only TeleQ's own content an assistant put up is captured, never other apps or the user's own photos; video frames may come out black.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Looking at the TV screen…",
+          "openai/toolInvocation/invoked": "Looked at the TV"
+        },
+        "annotations": {
+          "title": "See the TV screen",
+          "readOnlyHint": true,
+          "idempotentHint": true,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "playback",
+        "title": "Control video playback",
+        "description": "Control the video that is playing on the TV: play, pause, seek to a position, or stop.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "action": {
+              "type": "string",
+              "enum": [
+                "play",
+                "pause",
+                "seek",
+                "stop"
+              ],
+              "description": "What to do."
+            },
+            "position_s": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 86400,
+              "description": "Seconds from the start. Required when action is \"seek\"."
+            }
+          },
+          "required": [
+            "action"
+          ],
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Controlling the video…",
+          "openai/toolInvocation/invoked": "Done"
+        },
+        "annotations": {
+          "title": "Control video playback",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      },
+      {
+        "name": "clear_screen",
+        "title": "Clear the TV screen",
+        "description": "Stop whatever is being shown and return the TV to its idle screen.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "_meta": {
+          "openai/toolInvocation/invoking": "Clearing the TV…",
+          "openai/toolInvocation/invoked": "TV cleared"
+        },
+        "annotations": {
+          "title": "Clear the TV screen",
+          "readOnlyHint": false,
+          "destructiveHint": false,
+          "idempotentHint": false,
+          "openWorldHint": false
+        }
+      }
+    ]
+  },
+  "prompts": {
+    "prompts": [
+      {
+        "name": "present_topic",
+        "title": "Present a topic on the TV",
+        "description": "Prepare a short slide presentation about a topic and present it on the TV.",
+        "arguments": [
+          {
+            "name": "topic",
+            "description": "What the presentation is about.",
+            "required": true
+          },
+          {
+            "name": "slides",
+            "description": "How many slides (default 6).",
+            "required": false
+          },
+          {
+            "name": "audience",
+            "description": "Who is watching (default: a general audience).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "name": "daily_brief",
+        "title": "Daily brief on the TV",
+        "description": "A one-screen morning brief (date, weather, agenda, one fun fact) as a TV dashboard.",
+        "arguments": [
+          {
+            "name": "city",
+            "description": "City for the weather (default: ask me).",
+            "required": false
+          },
+          {
+            "name": "agenda",
+            "description": "Things on my plate today, if you don't know them already.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "name": "show_recipe_steps",
+        "title": "Recipe step by step",
+        "description": "Show a recipe on the TV as slides: ingredients first, then one step per slide.",
+        "arguments": [
+          {
+            "name": "dish",
+            "description": "What to cook.",
+            "required": true
+          },
+          {
+            "name": "servings",
+            "description": "How many people (default 4).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "name": "kids_quiz",
+        "title": "Quiz for kids on the TV",
+        "description": "A friendly quiz on the TV with a live scoreboard.",
+        "arguments": [
+          {
+            "name": "topic",
+            "description": "Quiz topic.",
+            "required": true
+          },
+          {
+            "name": "age",
+            "description": "Age of the players (default 8).",
+            "required": false
+          },
+          {
+            "name": "questions",
+            "description": "Number of questions (default 8).",
+            "required": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/config.mjs

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function configDir(env = process.env) {
+  if (env.TELEQ_CONFIG_DIR) return env.TELEQ_CONFIG_DIR;
+  const base = env.XDG_CONFIG_HOME || (process.platform === 'win32' && env.APPDATA) || path.join(os.homedir(), '.config');
+  return path.join(base, 'teleq');
+}
+
+export function loadConfig(dir = configDir()) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(dir, 'tv.json'), 'utf8'));
+    return cfg && typeof cfg.key === 'string' && typeof cfg.host === 'string' ? cfg : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The key is a credential for the TV: owner-only file, owner-only directory. */
+export function saveConfig(cfg, dir = configDir()) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, 'tv.json');
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
+export function deleteConfig(dir = configDir()) {
+  fs.rmSync(path.join(dir, 'tv.json'), { force: true });
+  fs.rmSync(path.join(dir, 'cache.json'), { force: true });
+}
+
+/** Last `initialize` / `tools/list` results, so Claude can start while the TV is switched off. */
+export function loadCache(dir = configDir()) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'cache.json'), 'utf8')) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveCache(cache, dir = configDir()) {
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(dir, 'cache.json'), JSON.stringify(cache), { mode: 0o600 });
+  } catch {
+    // The cache is a convenience only.
+  }
+}

package/src/tv.mjs

@@ -0,0 +1,90 @@
+// Finding and talking to the TV. No dependencies: Node's own fetch and os.
+import os from 'node:os';
+
+export const DEFAULT_PORT = 8765;
+const PORT_FALLBACKS = Array.from({ length: 10 }, (_, i) => DEFAULT_PORT + 1 + i);
+
+/** True when [host] is an RFC 1918 / link-local IPv4 literal: the only addresses we ever talk to. */
+export function isPrivateIPv4(host) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+}
+
+/** GET /health; resolves to { tvName } when [host]:[port] is a TeleQ TV, else null. */
+export async function probe(host, port, timeoutMs = 1500) {
+  try {
+    const res = await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (body?.status !== 'ok' || typeof body.protocolVersion !== 'number') return null;
+    return { tvName: typeof body.tvName === 'string' ? body.tvName : null };
+  } catch {
+    return null;
+  }
+}
+
+/** Every other address of each local /24 (the home network), without our own. */
+export function localCandidates(interfaces = os.networkInterfaces()) {
+  const out = new Set();
+  for (const addrs of Object.values(interfaces)) {
+    for (const a of addrs ?? []) {
+      if (a.family !== 'IPv4' || a.internal || !isPrivateIPv4(a.address)) continue;
+      const base = a.address.split('.').slice(0, 3).join('.');
+      for (let i = 1; i <= 254; i++) {
+        const host = `${base}.${i}`;
+        if (host !== a.address) out.add(host);
+      }
+    }
+  }
+  return [...out];
+}
+
+async function sweep(hosts, ports, concurrency, timeoutMs) {
+  const jobs = hosts.flatMap((host) => ports.map((port) => ({ host, port })));
+  const found = [];
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, jobs.length) }, async () => {
+      while (next < jobs.length) {
+        const { host, port } = jobs[next++];
+        const info = await probe(host, port, timeoutMs);
+        if (info) found.push({ host, port, tvName: info.tvName });
+      }
+    }),
+  );
+  return found;
+}
+
+/**
+ * Looks for TVs on the local network: the default port everywhere first (a few seconds), the
+ * fallback ports only when nothing answered.
+ */
+export async function discover({ hosts = localCandidates(), ports, concurrency = 64, timeoutMs = 800 } = {}) {
+  if (ports) return sweep(hosts, ports, concurrency, timeoutMs);
+  const first = await sweep(hosts, [DEFAULT_PORT], concurrency, timeoutMs);
+  return first.length ? first : sweep(hosts, PORT_FALLBACKS, concurrency, timeoutMs);
+}
+
+/** Links this computer with the code shown on the TV. Throws Error with a user-facing message. */
+export async function pairWithCode({ host, port }, code, name) {
+  let res;
+  try {
+    res = await fetch(`http://${host}:${port}/agent/pair`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ protocolVersion: 1, code: String(code).replace(/\D/g, ''), name }),
+      signal: AbortSignal.timeout(8000),
+    });
+  } catch {
+    throw new Error(`Can't reach the TV at ${host}:${port}. Is TeleQ open on it, on the same Wi-Fi?`);
+  }
+  const body = await res.json().catch(() => ({}));
+  if (res.ok && body.success && body.key) return { key: body.key, tvName: body.tvName ?? null };
+  if (res.status === 429) throw new Error('Too many wrong codes. Wait half a minute and try again.');
+  if (res.status === 401) {
+    throw new Error(`${body.message ?? 'Wrong code'}. On the TV, open "AI assistants" and choose "Link an assistant" for a fresh code.`);
+  }
+  throw new Error(body.message ?? `The TV refused the request (HTTP ${res.status}).`);
+}