@ciphore/radiocli 0.2.2 → 0.2.4

package/dist/agent/mcp-install.js

@@ -0,0 +1,467 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { applyEdits, modify, parse } from 'jsonc-parser';
+import { JsonLibraryStore } from '../storage/store.js';
+import { defaultAgentControlSettings } from '../types.js';
+import { resolveCommandDetails } from '../platform/executables.js';
+const formatting = { insertSpaces: true, tabSize: 2, eol: '\n' };
+export async function configureMcpIntegrations(enabled, runtime, output = process.stdout) {
+    const store = new JsonLibraryStore();
+    const current = store.snapshot().settings;
+    if (!enabled)
+        store.updateSettings({ agentControl: { ...(current.agentControl ?? defaultAgentControlSettings), enabled: false } });
+    const results = [];
+    const command = mcpServerCommand(runtime);
+    if (enabled) {
+        const probe = await probeMcpServer(command);
+        results.push({ client: 'RadioCLI MCP server', status: probe.ok ? 'configured' : 'failed', detail: probe.detail });
+        if (!probe.ok) {
+            output?.write('\nAgent integration could not be enabled\n');
+            output?.write(`  RadioCLI MCP server: failed · ${probe.detail}\n`);
+            return results;
+        }
+    }
+    const codex = resolveCodexExecutable();
+    if (codex) {
+        results.push(await configureCliClient('Codex', codex, enabled
+            ? ['mcp', 'add', 'radiocli', '--', ...command]
+            : ['mcp', 'remove', 'radiocli'], ['mcp', 'remove', 'radiocli']));
+    }
+    else
+        results.push(notFound('Codex'));
+    const claude = resolveCommandDetails('claude', { env: process.env }).path;
+    if (claude) {
+        results.push(await configureCliClient('Claude Code', claude, enabled
+            ? ['mcp', 'add', '--scope', 'user', 'radiocli', '--', ...command]
+            : ['mcp', 'remove', '--scope', 'user', 'radiocli'], ['mcp', 'remove', '--scope', 'user', 'radiocli']));
+    }
+    else
+        results.push(notFound('Claude Code'));
+    const openCodePath = openCodeConfigPath();
+    if (resolveCommandDetails('opencode', { env: process.env }).path || existsSync(openCodePath)) {
+        try {
+            updateOpenCodeConfig(openCodePath, enabled, command);
+            results.push({ client: 'OpenCode', status: enabled ? 'configured' : 'removed', detail: openCodePath });
+        }
+        catch (error) {
+            results.push({ client: 'OpenCode', status: 'failed', detail: message(error) });
+        }
+    }
+    else
+        results.push(notFound('OpenCode'));
+    configureJsonClient(results, 'Cursor', cursorDetected(), join(homedir(), '.cursor', 'mcp.json'), ['mcpServers', 'radiocli'], enabled, {
+        command: command[0], args: command.slice(1)
+    });
+    configureJsonClient(results, 'Gemini CLI', Boolean(resolveCommandDetails('gemini', { env: process.env }).path), join(homedir(), '.gemini', 'settings.json'), ['mcpServers', 'radiocli'], enabled, {
+        command: command[0], args: command.slice(1)
+    });
+    configureJsonClient(results, 'VS Code / Copilot Agent Host', vsCodeDetected(), join(homedir(), '.copilot', 'mcp-config.json'), ['servers', 'radiocli'], enabled, {
+        type: 'stdio', command: command[0], args: command.slice(1)
+    });
+    if (resolveCommandDetails('orca', { env: process.env }).path) {
+        results.push({ client: 'Orca', status: 'inherited', detail: 'Orca exposes MCP integrations through its configured Codex/Claude agent runtimes.' });
+    }
+    else
+        results.push(notFound('Orca'));
+    const portablePath = writePortableConfig(command, enabled);
+    results.push({ client: 'Other MCP clients', status: enabled ? 'configured' : 'removed', detail: portablePath });
+    if (enabled) {
+        const latest = store.snapshot().settings;
+        store.updateSettings({ agentControl: { ...(latest.agentControl ?? defaultAgentControlSettings), enabled: true } });
+    }
+    output?.write(`\nAgent integration ${enabled ? 'enabled' : 'disabled'}\n`);
+    for (const result of results)
+        output?.write(`  ${result.client}: ${result.status} · ${result.detail}\n`);
+    if (enabled) {
+        output?.write('\nIMPORTANT: Fully quit and reopen every running agent client before testing RadioCLI. New tasks opened before that restart will not have the RadioCLI tools and may incorrectly fall back to a browser.\n');
+    }
+    return results;
+}
+export function portableMcpConfig(runtime) {
+    const command = mcpServerCommand(runtime);
+    return { mcpServers: { radiocli: { type: 'stdio', command: command[0], args: command.slice(1) } } };
+}
+export async function mcpIntegrationReport(runtime) {
+    const settings = new JsonLibraryStore().snapshot().settings.agentControl ?? defaultAgentControlSettings;
+    const command = mcpServerCommand(runtime);
+    const shimLauncher = command.length === 3;
+    const server = await probeMcpServer(command);
+    const clients = await mcpClientStates(command);
+    const needsRepair = Object.entries(clients)
+        .filter(([, client]) => client.detected && (client.state === 'missing' || client.state === 'stale'))
+        .map(([client]) => client);
+    const launcherExists = Boolean(command[0] && existsSync(command[0]) && (shimLauncher || (command[1] && existsSync(command[1]))));
+    return {
+        enabled: settings.enabled,
+        health: !settings.enabled ? 'disabled' : launcherExists && server.ok && needsRepair.length === 0 ? 'ready' : 'needs-repair',
+        nextStep: !settings.enabled
+            ? 'Enable Agent control & MCP in the TUI, or run radiocli mcp enable.'
+            : !server.ok
+                ? `The configured MCP server cannot start: ${server.detail} Run radiocli mcp repair after reinstalling or rebuilding RadioCLI.`
+                : needsRepair.length > 0
+                    ? `Run radiocli mcp repair, then restart open agent clients. Needs repair: ${needsRepair.join(', ')}.`
+                    : 'RadioCLI is ready for local agents and Codex Voice.',
+        command,
+        server,
+        launcher: {
+            mode: shimLauncher ? 'radiocli-shim' : 'node-fallback',
+            path: command[0],
+            target: shimLauncher ? command[0] : command[1],
+            exists: launcherExists,
+            upgradeSafe: shimLauncher
+        },
+        clients,
+        portableConfigPath: portableConfigPath()
+    };
+}
+/** Prefer the package-manager-owned shim because it survives package/Cellar version changes. */
+export function mcpServerCommand(runtime, radioCliPath, platform = process.platform) {
+    const candidate = radioCliPath === undefined ? matchingRadioCliShim(runtime, platform) : radioCliPath;
+    const launcher = candidate && usableDirectLauncher(candidate, platform) ? candidate : undefined;
+    return launcher
+        ? [launcher, 'mcp', 'serve']
+        : [runtime.nodePath, runtime.cliPath, 'mcp', 'serve'];
+}
+export function probeMcpServer(command, timeoutMs = 5_000) {
+    return new Promise(resolve => {
+        const [program, ...args] = command;
+        if (!program) {
+            resolve({ ok: false, detail: 'No MCP server command was resolved.' });
+            return;
+        }
+        const child = spawn(program, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.kill();
+            resolve(result);
+        };
+        const timer = setTimeout(() => finish({ ok: false, detail: `Handshake timed out after ${timeoutMs} ms.${stderr ? ` ${stderr.trim()}` : ''}` }), timeoutMs);
+        timer.unref();
+        child.stderr.on('data', value => { stderr += String(value); });
+        child.stdout.on('data', value => {
+            stdout += String(value);
+            let newline = stdout.indexOf('\n');
+            while (newline >= 0) {
+                const line = stdout.slice(0, newline).trim();
+                stdout = stdout.slice(newline + 1);
+                if (line) {
+                    try {
+                        const response = JSON.parse(line);
+                        if (response.id === 1 && response.result?.serverInfo?.name === 'radiocli') {
+                            finish({ ok: true, detail: 'stdio handshake succeeded' });
+                            return;
+                        }
+                        if (response.id === 1 && response.error) {
+                            finish({ ok: false, detail: `Handshake rejected: ${String(response.error.message ?? 'unknown MCP error')}` });
+                            return;
+                        }
+                    }
+                    catch {
+                        // Keep reading: a client may emit a non-protocol diagnostic line before startup.
+                    }
+                }
+                newline = stdout.indexOf('\n');
+            }
+        });
+        child.once('error', error => finish({ ok: false, detail: error.message }));
+        child.once('close', code => finish({ ok: false, detail: `${stderr.trim() || stdout.trim() || `server exited with code ${code ?? 1}`}` }));
+        child.stdin.end(`${JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'radiocli-setup', version: '1.0.0' } }
+        })}\n`);
+    });
+}
+function matchingRadioCliShim(runtime, platform) {
+    const candidate = resolveCommandDetails('radiocli', { env: process.env, platform }).path;
+    if (!candidate)
+        return undefined;
+    if (!usableDirectLauncher(candidate, platform))
+        return undefined;
+    try {
+        return realpathSync(candidate) === realpathSync(runtime.cliPath) ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function usableDirectLauncher(path, platform) {
+    return platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(path);
+}
+async function mcpClientStates(command) {
+    const openCodePath = openCodeConfigPath();
+    const cursorPath = join(homedir(), '.cursor', 'mcp.json');
+    const geminiPath = join(homedir(), '.gemini', 'settings.json');
+    const vscodePath = join(homedir(), '.copilot', 'mcp-config.json');
+    return {
+        codex: await codexClientState(resolveCodexExecutable(), command),
+        claude: await claudeClientState(resolveCommandDetails('claude', { env: process.env }).path, command),
+        opencode: jsonClientState(Boolean(resolveCommandDetails('opencode', { env: process.env }).path || existsSync(openCodePath)), openCodePath, [
+            ['mcp', 'servers', 'radiocli'], ['mcp', 'radiocli']
+        ], command),
+        cursor: jsonClientState(cursorDetected(), cursorPath, [['mcpServers', 'radiocli']], command),
+        gemini: jsonClientState(Boolean(resolveCommandDetails('gemini', { env: process.env }).path), geminiPath, [['mcpServers', 'radiocli']], command),
+        vscode: jsonClientState(vsCodeDetected(), vscodePath, [['servers', 'radiocli']], command),
+        orca: {
+            detected: Boolean(resolveCommandDetails('orca', { env: process.env }).path),
+            state: resolveCommandDetails('orca', { env: process.env }).path ? 'managed-by-client' : 'not-found',
+            detail: 'inherits MCP configuration from its Codex or Claude runtime'
+        },
+        portable: jsonClientState(true, portableConfigPath(), [['mcpServers', 'radiocli']], command)
+    };
+}
+function managedClientState(detected) {
+    return { detected, state: detected ? 'managed-by-client' : 'not-found', detail: detected ? 'inspect with the client MCP command' : 'client is not installed' };
+}
+export function resolveCodexExecutable(env = process.env, platform = process.platform, home = homedir()) {
+    const configured = env.CODEX_CLI_PATH;
+    if (configured && existsSync(configured))
+        return configured;
+    const pathExecutable = resolveCommandDetails('codex', { env, platform, home }).path;
+    if (pathExecutable)
+        return pathExecutable;
+    const candidates = platform === 'darwin'
+        ? [
+            '/Applications/ChatGPT.app/Contents/Resources/codex',
+            join(home, 'Applications', 'ChatGPT.app', 'Contents', 'Resources', 'codex')
+        ]
+        : platform === 'win32'
+            ? [
+                join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'Programs', 'ChatGPT', 'resources', 'codex.exe'),
+                join(env.ProgramFiles ?? 'C:\\Program Files', 'ChatGPT', 'resources', 'codex.exe')
+            ]
+            : [];
+    return candidates.find(candidate => existsSync(candidate));
+}
+function cursorDetected() {
+    return Boolean(resolveCommandDetails('cursor', { env: process.env }).path ||
+        resolveCommandDetails('cursor-agent', { env: process.env }).path ||
+        existsSync(join(homedir(), '.cursor')) ||
+        (process.platform === 'darwin' && existsSync('/Applications/Cursor.app')) ||
+        (process.platform === 'win32' && existsSync(join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Programs', 'cursor', 'Cursor.exe'))));
+}
+function vsCodeDetected() {
+    return Boolean(resolveCommandDetails('code', { env: process.env }).path ||
+        (process.platform === 'darwin' && existsSync('/Applications/Visual Studio Code.app')) ||
+        (process.platform === 'win32' && existsSync(join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Programs', 'Microsoft VS Code', 'Code.exe'))));
+}
+async function codexClientState(executable, expected) {
+    if (!executable)
+        return managedClientState(false);
+    const result = await run(executable, ['mcp', 'get', 'radiocli', '--json']);
+    if (result.code !== 0) {
+        const detail = `${result.stderr}\n${result.stdout}`.trim();
+        return missingRegistration(detail)
+            ? { detected: true, state: 'missing', detail: 'RadioCLI is not registered' }
+            : { detected: true, state: 'stale', detail: detail || `Codex MCP inspection exited with code ${result.code}` };
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const actual = parsed.transport?.type === 'stdio' && typeof parsed.transport.command === 'string' && Array.isArray(parsed.transport.args)
+            ? [parsed.transport.command, ...parsed.transport.args.filter((value) => typeof value === 'string')]
+            : [];
+        if (parsed.enabled === false)
+            return { detected: true, state: 'stale', detail: 'RadioCLI is registered but disabled in Codex' };
+        return arraysEqual(actual, expected)
+            ? { detected: true, state: 'configured', detail: 'shared ChatGPT desktop, Codex CLI, and IDE configuration' }
+            : { detected: true, state: 'stale', detail: `registered command: ${actual.join(' ') || 'unrecognized transport'}` };
+    }
+    catch {
+        return { detected: true, state: 'stale', detail: 'Codex returned an invalid MCP status response' };
+    }
+}
+async function claudeClientState(executable, expected) {
+    if (!executable)
+        return managedClientState(false);
+    const result = await run(executable, ['mcp', 'get', 'radiocli']);
+    const detail = `${result.stdout}\n${result.stderr}`.trim();
+    if (result.code !== 0) {
+        return missingRegistration(detail)
+            ? { detected: true, state: 'missing', detail: 'RadioCLI is not registered' }
+            : { detected: true, state: 'stale', detail: detail || `Claude MCP inspection exited with code ${result.code}` };
+    }
+    const commandMatches = expected.every(value => detail.includes(value));
+    return commandMatches
+        ? { detected: true, state: 'configured', detail: 'user-level MCP configuration' }
+        : { detected: true, state: 'stale', detail: 'RadioCLI is registered with a different command' };
+}
+function jsonClientState(detected, path, candidates, expected) {
+    if (!detected && !existsSync(path))
+        return { detected: false, state: 'not-found', detail: path };
+    if (!existsSync(path))
+        return { detected, state: 'missing', detail: path };
+    try {
+        const parsed = parse(readFileSync(path, 'utf8'));
+        const value = candidates.map(segments => valueAt(parsed, segments)).find(candidate => candidate !== undefined);
+        if (value === undefined)
+            return { detected, state: 'missing', detail: path };
+        const actual = commandFromConfig(value);
+        return { detected, state: arraysEqual(actual, expected) ? 'configured' : 'stale', detail: path };
+    }
+    catch {
+        return { detected, state: 'stale', detail: `${path} (invalid configuration)` };
+    }
+}
+function valueAt(value, segments) {
+    let current = value;
+    for (const segment of segments) {
+        if (!current || typeof current !== 'object' || !(segment in current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function commandFromConfig(value) {
+    if (!value || typeof value !== 'object')
+        return [];
+    const object = value;
+    if (Array.isArray(object.command) && object.command.every(item => typeof item === 'string'))
+        return object.command;
+    if (typeof object.command === 'string' && Array.isArray(object.args) && object.args.every(item => typeof item === 'string')) {
+        return [object.command, ...object.args];
+    }
+    return [];
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function missingRegistration(detail) {
+    return /not found|does not exist|not configured|no mcp server(?:s)?.*found|no mcp servers are configured/i.test(detail);
+}
+async function configureCliClient(client, program, args, removeArgs) {
+    try {
+        let result = await run(program, args);
+        if (result.code !== 0 && args.includes('add') && /already exists|already configured|duplicate/i.test(`${result.stderr}\n${result.stdout}`)) {
+            const removed = await run(program, removeArgs);
+            if (removed.code !== 0)
+                throw new Error((removed.stderr || removed.stdout || `exit ${removed.code}`).trim());
+            result = await run(program, args);
+        }
+        if (result.code !== 0)
+            throw new Error((result.stderr || result.stdout || `exit ${result.code}`).trim());
+        return { client, status: args.includes('add') ? 'configured' : 'removed', detail: 'user-level MCP configuration' };
+    }
+    catch (error) {
+        if (!args.includes('add') && /not found|does not exist|No MCP server/i.test(message(error)))
+            return { client, status: 'removed', detail: 'already absent' };
+        return { client, status: 'failed', detail: message(error) };
+    }
+}
+export function updateOpenCodeConfig(path, enabled, command) {
+    const source = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const parsed = source ? parse(source) : {};
+    const legacy = Boolean(parsed.mcp && !('servers' in parsed.mcp) && Object.values(parsed.mcp).some(isLegacyOpenCodeServer));
+    const value = enabled
+        ? legacy ? { type: 'local', command, enabled: true } : { type: 'local', command, disabled: false }
+        : undefined;
+    updateJsoncValue(path, legacy ? ['mcp', 'radiocli'] : ['mcp', 'servers', 'radiocli'], value, '{\n  "$schema": "https://opencode.ai/config.json"\n}\n', 'OpenCode');
+}
+function isLegacyOpenCodeServer(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (candidate.type === 'local' && Array.isArray(candidate.command)) || (candidate.type === 'remote' && typeof candidate.url === 'string');
+}
+function configureJsonClient(results, client, detected, path, segments, enabled, value) {
+    if (!detected && !existsSync(path)) {
+        results.push(notFound(client));
+        return;
+    }
+    try {
+        updateJsoncValue(path, segments, enabled ? value : undefined, '{}\n', client);
+        results.push({ client, status: enabled ? 'configured' : 'removed', detail: path });
+    }
+    catch (error) {
+        results.push({ client, status: 'failed', detail: message(error) });
+    }
+}
+function updateJsoncValue(path, segments, value, initial, client) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const source = existsSync(path) ? readFileSync(path, 'utf8') : initial;
+    const errors = [];
+    parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length)
+        throw new Error(`Cannot safely update invalid ${client} config: ${path}`);
+    const updated = applyEdits(source, modify(source, segments, value, { formattingOptions: formatting }));
+    writeFileSync(path, updated.endsWith('\n') ? updated : `${updated}\n`, { mode: 0o600 });
+}
+function writePortableConfig(command, enabled) {
+    const path = portableConfigPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const config = enabled ? { mcpServers: { radiocli: { type: 'stdio', command: command[0], args: command.slice(1) } } } : { mcpServers: {} };
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    return path;
+}
+function portableConfigPath() {
+    if (process.env.RADIOCLI_HOME)
+        return join(process.env.RADIOCLI_HOME, 'mcp.json');
+    const base = process.platform === 'win32'
+        ? process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming')
+        : process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+    return join(base, 'radiocli', 'mcp.json');
+}
+function openCodeConfigPath() {
+    const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+    const directory = join(base, 'opencode');
+    const jsonc = join(directory, 'opencode.jsonc');
+    const json = join(directory, 'opencode.json');
+    return existsSync(jsonc) ? jsonc : json;
+}
+function run(program, args, timeoutMs = 15_000) {
+    return new Promise((resolve, reject) => {
+        const invocation = cliInvocation(program, args);
+        const child = spawn(invocation.program, invocation.args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish({ code: 1, stdout, stderr: `${stderr}${stderr ? '\n' : ''}Timed out after ${timeoutMs} ms.` });
+        }, timeoutMs);
+        timer.unref();
+        child.stdout.on('data', value => { stdout += String(value); });
+        child.stderr.on('data', value => { stderr += String(value); });
+        child.once('error', error => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('close', code => finish({ code: code ?? 1, stdout, stderr }));
+    });
+}
+export function cliInvocation(program, args, platform = process.platform, env = process.env) {
+    if (platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(program))
+        return { program, args };
+    const command = [program, ...args].map(value => `"${escapeCmdArgument(value)}"`).join(' ');
+    return { program: env.ComSpec || env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/v:off', '/c', command] };
+}
+function escapeCmdArgument(value) {
+    return value
+        .replaceAll('%', '%%')
+        .replaceAll('"', '""')
+        .replaceAll('^', '^^')
+        .replaceAll('&', '^&')
+        .replaceAll('|', '^|')
+        .replaceAll('<', '^<')
+        .replaceAll('>', '^>');
+}
+function notFound(client) { return { client, status: 'not-found', detail: 'client is not installed on this computer' }; }
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/agent/mcp-server.js

@@ -0,0 +1,139 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod';
+import { appVersion } from '../version.js';
+import { receiverStyleNames, themeNames } from '../types.js';
+import { AgentRadioService, stationForAgent } from './service.js';
+export const radioCliMcpInstructions = `RadioCLI is the authoritative handler for requests about RadioCLI, “the radio”, “my radio”, recent stations, favorites, or stations from a place. Never substitute a web browser, web search, Computer Use, or another radio/music service. “Play my most recent radio station” means call radio_play with source="recent" and index=0. “Play a station from New York” means call radio_search with query="New York", then radio_play with one returned opaque station ID. Call these tools directly; do not delegate a radio-only operation or create a goal merely to monitor it.
+
+RadioCLI controls internet radio, alarms, and macOS AirPlay locally. Discover unidentified stations with radio_search or radio_browse, then use only returned opaque IDs; never invent IDs or stream URLs. Ordinary stop never dismisses an alarm: list active alarms and use alarm controls, with an exact ID when several ring. Never remove an alarm without explicit user confirmation. List AirPlay receivers before selecting one. Never install an update without explicit approval.
+
+For “this station”, omit station_id when favoriting. A request such as “do X, then play or stop the radio” is a normal completion action in the current task: perform X, then call radio_run_completion_preset once X is genuinely complete. Do not create or set a goal, scheduled task, automation, reminder, task record, or separate monitoring task merely to defer or track that radio action. Use one of those mechanisms only when the user explicitly requests it for a separate reason. AirPlay is macOS-only. Submit a receiver code only when the user provides it; codes are never saved. Use radio_update_status for version or upgrade questions, and tell the user to restart their MCP client after an update.`;
+const alarmScheduleSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('once'), at: z.string().min(1).describe('Absolute ISO-8601 minute including an offset or Z, with zero seconds.') }),
+    z.object({
+        type: z.literal('recurring'),
+        time: z.string().regex(/^\d{2}:\d{2}$/).describe('24-hour local civil time, HH:mm.'),
+        weekdays: z.array(z.number().int().min(1).max(7)).min(1).describe('ISO weekdays, Monday=1 through Sunday=7.'),
+        timezone: z.string().min(1).describe('IANA timezone such as America/Los_Angeles.')
+    })
+]);
+const alarmOptionsSchema = {
+    label: z.string().min(1).max(120).optional(),
+    enabled: z.boolean().optional(),
+    volume: z.number().int().min(0).max(100).optional(),
+    fade_seconds: z.number().int().min(0).max(3600).optional(),
+    stop_after_minutes: z.number().int().min(1).max(10080).optional(),
+    fallback_station_id: z.string().min(1).optional(),
+    missed_run_grace_minutes: z.number().int().min(0).max(10080).optional(),
+    wake_if_supported: z.boolean().optional(),
+    keep_awake_until_alarm: z.boolean().optional()
+};
+export async function runMcpServer(runtime) {
+    const service = new AgentRadioService(runtime);
+    serveStdio(() => createMcpServer(service), { onerror: error => console.error(`RadioCLI MCP: ${error.message}`) });
+}
+function createMcpServer(service) {
+    const server = new McpServer({ name: 'radiocli', version: appVersion() }, { instructions: radioCliMcpInstructions });
+    const tool = (name, description, schema, handler) => {
+        const config = schema ? { description, inputSchema: schema } : { description };
+        server.registerTool(name, config, async (raw) => {
+            try {
+                const value = await handler(raw);
+                return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+            }
+            catch (error) {
+                return { content: [{ type: 'text', text: error instanceof Error ? error.message : 'RadioCLI request failed.' }], isError: true };
+            }
+        });
+    };
+    tool('radio_status', 'Get current playback, active station, queue, agent preferences, and whether alarm playback is active.', undefined, () => service.status());
+    tool('radio_update_status', 'Check the installed and latest RadioCLI versions and return the appropriate update command. This is read-only and never installs an update.', undefined, () => service.updateStatus());
+    tool('radio_search', 'Search RadioCLI’s public station directory by name, genre, language, city, region, or country. Use this—not web search or a browser—for requests such as “play a station from New York”, then pass a returned opaque id to radio_play.', z.object({
+        query: z.string().min(1).max(200),
+        limit: z.number().int().min(1).max(30).default(10),
+        country_code: z.string().length(2).optional()
+    }), async ({ query, limit, country_code }) => (await service.search(query, limit, country_code)).map(stationForAgent));
+    tool('radio_browse', 'List saved favorites, recent stations, popular stations, nearby stations, countries, or recent track titles.', z.object({
+        kind: z.enum(['favorites', 'recent', 'popular', 'nearby', 'countries', 'track-history']),
+        limit: z.number().int().min(1).max(50).default(20)
+    }), async ({ kind, limit }) => {
+        const values = await service.browse(kind, limit);
+        return kind === 'favorites' || kind === 'recent' || kind === 'popular' || kind === 'nearby'
+            ? values.map(stationForAgent)
+            : values;
+    });
+    tool('radio_play', 'Play through RadioCLI using a searched/saved station id, or choose from recent, favorites, popular, or a country. For “play my most recent radio station”, call this directly with source="recent" and index=0. By default this opens the normal RadioCLI TUI in a terminal window; set open_ui=false only when the user requests headless playback.', z.object({
+        station_id: z.string().min(1).optional(),
+        source: z.enum(['recent', 'favorite', 'popular', 'country']).default('recent'),
+        country_code: z.string().length(2).optional(),
+        index: z.number().int().min(0).optional(),
+        random: z.boolean().default(false),
+        open_ui: z.boolean().optional(),
+        if_playing: z.enum(['keep', 'replace']).default('replace')
+    }), ({ station_id, source, country_code, index, random, open_ui, if_playing }) => service.play({ stationId: station_id, source, countryCode: country_code, index, random, openUi: open_ui, ifPlaying: if_playing }));
+    tool('radio_pause', 'Pause playback. Safe to call repeatedly.', undefined, () => service.control({ type: 'pause' }));
+    tool('radio_resume', 'Resume paused playback without changing stations.', undefined, () => service.control({ type: 'resume' }));
+    tool('radio_stop', 'Stop ordinary interactive/headless playback. This never dismisses or modifies an alarm.', undefined, () => service.control({ type: 'stop' }));
+    tool('radio_next', 'Play the next station in the queue created by the last radio_play request.', undefined, () => service.control({ type: 'next' }));
+    tool('radio_previous', 'Play the previous station in the current queue.', undefined, () => service.control({ type: 'previous' }));
+    tool('radio_set_volume', 'Set playback volume from 0 through 100 and save it as the RadioCLI preference.', z.object({ volume: z.number().min(0).max(100) }), ({ volume }) => service.control({ type: 'set-volume', volume }));
+    tool('radio_set_muted', 'Explicitly mute or unmute playback; this is not a toggle.', z.object({ muted: z.boolean() }), ({ muted }) => service.control({ type: 'set-muted', muted }));
+    tool('radio_set_favorite', 'Explicitly add or remove a favorite. Omit station_id to act on the current station, as in “favorite this”.', z.object({ favorite: z.boolean().default(true), station_id: z.string().min(1).optional() }), ({ favorite, station_id }) => service.setFavorite(favorite, station_id));
+    tool('radio_stats', 'Get local listening time, stations heard, active days, and streak statistics.', undefined, () => service.stats());
+    tool('radio_get_appearance', 'List available display themes and receiver styles and show the current selections.', undefined, () => service.appearance());
+    tool('radio_set_appearance', 'Change the RadioCLI display color theme or visual receiver style. An open TUI updates immediately.', z.object({ theme: z.enum(themeNames).optional(), receiver_style: z.enum(receiverStyleNames).optional() }), ({ theme, receiver_style }) => service.updateAppearance({ theme, receiverStyle: receiver_style }));
+    tool('radio_set_agent_preferences', 'Choose whether agent-started playback opens the normal TUI and whether it switches an open TUI to Now Playing.', z.object({ open_ui_on_play: z.boolean().optional(), focus_now_playing: z.boolean().optional() }), ({ open_ui_on_play, focus_now_playing }) => service.updateAgentPreferences({ openUiOnPlay: open_ui_on_play, focusNowPlaying: focus_now_playing }));
+    tool('radio_run_completion_preset', 'Run the user-configured completion action immediately after the current task completes. This is a one-shot radio action, not a reason to create a goal, automation, reminder, task record, or monitoring task.', undefined, () => service.runCompletionPreset());
+    tool('radio_configure_completion_preset', 'Configure what radio_run_completion_preset does: play/stop/pause/resume, station source, conflict behavior, and optional UI override.', z.object({
+        action: z.enum(['play', 'pause', 'resume', 'stop']).optional(),
+        source: z.enum(['recent', 'favorite', 'popular', 'country']).optional(),
+        country_code: z.string().length(2).optional(),
+        if_playing: z.enum(['keep', 'replace']).optional(),
+        open_ui: z.boolean().optional()
+    }), ({ action, source, country_code, if_playing, open_ui }) => service.configureCompletionPreset({ action, source, countryCode: country_code, ifPlaying: if_playing, openUi: open_ui }));
+    tool('radio_alarm_list', 'List saved alarms with exact IDs, schedules, stations, next occurrences, playback settings, and last outcomes.', undefined, () => service.alarmList());
+    tool('radio_alarm_status', 'Get saved alarms, native scheduler health, and every currently ringing alarm occurrence.', undefined, () => service.alarmStatus());
+    tool('radio_alarm_create', 'Create and natively schedule a one-time or recurring radio alarm. Resolve the station with radio_search or radio_browse first.', z.object({
+        station_id: z.string().min(1),
+        schedule: alarmScheduleSchema,
+        ...alarmOptionsSchema
+    }), ({ station_id, schedule, label, enabled, volume, fade_seconds, stop_after_minutes, fallback_station_id, missed_run_grace_minutes, wake_if_supported, keep_awake_until_alarm }) => service.alarmCreate({
+        stationId: station_id, schedule: schedule, label, enabled, volume,
+        fadeSeconds: fade_seconds, stopAfterMinutes: stop_after_minutes, fallbackStationId: fallback_station_id,
+        missedRunGraceMinutes: missed_run_grace_minutes, wakeIfSupported: wake_if_supported, keepAwakeUntilAlarm: keep_awake_until_alarm
+    }));
+    tool('radio_alarm_update', 'Edit an existing alarm by exact ID. Omitted fields remain unchanged; pass the complete replacement schedule when changing time or recurrence.', z.object({
+        alarm_id: z.string().min(1),
+        station_id: z.string().min(1).optional(),
+        schedule: alarmScheduleSchema.optional(),
+        clear_fallback: z.boolean().optional(),
+        ...alarmOptionsSchema
+    }).refine(value => !(value.clear_fallback && value.fallback_station_id), { message: 'Choose either clear_fallback or fallback_station_id.' }), ({ alarm_id, station_id, schedule, clear_fallback, label, enabled, volume, fade_seconds, stop_after_minutes, fallback_station_id, missed_run_grace_minutes, wake_if_supported, keep_awake_until_alarm }) => service.alarmUpdate(alarm_id, {
+        stationId: station_id, schedule: schedule, clearFallback: clear_fallback,
+        label, enabled, volume, fadeSeconds: fade_seconds, stopAfterMinutes: stop_after_minutes, fallbackStationId: fallback_station_id,
+        missedRunGraceMinutes: missed_run_grace_minutes, wakeIfSupported: wake_if_supported, keepAwakeUntilAlarm: keep_awake_until_alarm
+    }));
+    tool('radio_alarm_set_enabled', 'Explicitly enable or disable an alarm by exact ID and reconcile its native scheduler job.', z.object({ alarm_id: z.string().min(1), enabled: z.boolean() }), ({ alarm_id, enabled }) => service.alarmSetEnabled(alarm_id, enabled));
+    tool('radio_alarm_remove', 'Permanently remove an alarm and its native scheduler job. First list alarms and obtain explicit user confirmation for the exact ID, then pass confirm=true.', z.object({ alarm_id: z.string().min(1), confirm: z.boolean() }), ({ alarm_id, confirm }) => service.alarmRemove(alarm_id, confirm));
+    tool('radio_alarm_sync', 'Reconcile every saved alarm with the operating system scheduler after setup, upgrades, timezone changes, or repair.', undefined, () => service.alarmSync());
+    tool('radio_alarm_control', 'Control one currently ringing alarm: dismiss it, snooze it, keep playing past its automatic stop, or hand it off to normal interactive playback. If multiple alarms ring, supply an exact alarm_id and optionally occurrence_at from radio_alarm_status.', z.object({
+        action: z.enum(['dismiss', 'snooze', 'keep-playing', 'handoff']),
+        alarm_id: z.string().min(1).optional(),
+        occurrence_at: z.string().min(1).optional(),
+        snooze_minutes: z.number().int().min(1).max(1440).optional()
+    }).refine(value => value.action === 'snooze' || value.snooze_minutes === undefined, { message: 'snooze_minutes is only valid for the snooze action.' }), ({ action, alarm_id, occurrence_at, snooze_minutes }) => service.alarmControl({ action, alarmId: alarm_id, occurrenceAt: occurrence_at, snoozeMinutes: snooze_minutes }));
+    tool('radio_airplay_list', 'Discover AirPlay receivers visible to this Mac. Returns opaque receiver IDs; always call this before selecting a receiver.', undefined, async () => (await service.listAirPlayDevices()).map(device => ({
+        id: device.id,
+        name: device.name,
+        host: device.host,
+        port: device.port,
+        requiresPassword: device.requiresPassword,
+        airplay2: device.airplay2,
+        local: device.local ?? false
+    })));
+    tool('radio_airplay_select', 'Switch current or future interactive playback to an exact AirPlay receiver ID returned by radio_airplay_list. Opens RadioCLI when needed unless open_ui=false.', z.object({ device_id: z.string().min(1), open_ui: z.boolean().optional() }), ({ device_id, open_ui }) => service.selectAirPlayDevice(device_id, open_ui));
+    tool('radio_airplay_use_local', 'Switch interactive playback from AirPlay back to this Mac using the best available local backend.', z.object({ open_ui: z.boolean().optional() }).optional(), args => service.useLocalOutput(args?.open_ui));
+    tool('radio_airplay_submit_code', 'Submit a receiver-displayed AirPlay code to the active AirPlay session. Use only a code the user explicitly provides; RadioCLI never saves it.', z.object({ code: z.string().min(1).max(64) }), ({ code }) => service.submitAirPlayPasscode(code));
+    return server;
+}