@drakulavich/kesha-voice-kit 1.19.0 → 1.21.0-beta.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
 </p>
 
 <h1 align="center">Kesha Voice Kit</h1>
@@ -21,7 +21,7 @@
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
 
 <p align="center">
-  <img src="./demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+  <img src="https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
 </p>
 
 ## Quick Start
@@ -104,6 +104,16 @@ kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav     # auto-routes (Milena on darwin, ru-vosk-m02 elsewhere)
 ```
 
+**Output formats** (`--format`, or inferred from `--out` extension):
+
+```bash
+kesha say "Hello" --out hi.wav                       # WAV (default, uncompressed)
+kesha say "Hello" --format ogg-opus --out hi.ogg     # OGG/Opus — messenger voice notes (Telegram/WhatsApp/Signal)
+kesha say "Hello" --format flac --out hi.flac        # FLAC — lossless, royalty-free, plays in every browser incl. Safari/iOS
+```
+
+FLAC is the format for web-embeddable samples: it plays natively in all modern browsers (including Safari/iOS, where OGG/Opus does not), stays royalty-free like Opus, and keeps the engine's native sample rate (no resample). `--bitrate` / `--sample-rate` apply only to `--format ogg-opus`.
+
 **Russian abbreviations** (`ru-vosk-*`): all-uppercase Cyrillic 2-5-char tokens auto-expand letter-by-letter when not pronounceable as a Russian syllable (ФСБ → "эф-эс-бэ", ВОЗ → "воз"). Disable with `--no-expand-abbrev`. See [docs/tts.md#russian-abbreviation-auto-expansion](docs/tts.md#russian-abbreviation-auto-expansion).
 
 **English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev`. See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
@@ -136,6 +146,33 @@ Honored when `<prosody rate>` wraps the whole utterance. Mid-utterance prosody w
 
 macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tts.md](docs/tts.md).
 
+### Examples
+
+```bash
+# Auto-detect language and pick a male default (en-am_michael / ru-vosk-m02)
+kesha say "Hello, world" --out hello.wav
+kesha say "Привет, мир"  --out privet.wav
+
+# Choose a specific voice
+kesha say --voice en-am_michael "Voice in, text out." --out en.wav
+kesha say --voice ru-vosk-m02   "Голос в текст." --out ru.wav
+
+# List installed voices
+kesha say --list-voices
+
+# Output formats — inferred from the --out extension, or set with --format
+kesha say "Lossless, plays in Safari/iOS"   --out demo.flac        # FLAC (v1.20.0+)
+kesha say "Telegram-ready voice note" --format ogg-opus --out vn.ogg
+kesha say "Stream raw WAV to stdout"  > out.wav                    # default: WAV
+
+# Speaking rate, 0.5×–2.0× (Vosk honors it on every platform)
+kesha say --voice ru-vosk-m02 --rate 0.75 "Помедленнее." --out slow.flac
+kesha say --voice ru-vosk-m02 --rate 1.5  "Побыстрее."   --out fast.flac
+
+# macOS system voice — zero model download
+kesha say --voice macos-com.apple.voice.compact.ru-RU.Milena "Привет" --out milena.wav
+```
+
 ## Homebrew Install
 
 Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
@@ -232,7 +269,7 @@ mandb ~/.local/share/man 2>/dev/null || true
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](docs/assets/benchmark.svg)
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://raw.githubusercontent.com/drakulavich/kesha-voice-kit/main/docs/assets/benchmark.svg)
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
@@ -280,6 +317,10 @@ Cache boundary: `kesha install` and opt-in feature installs populate the local
 cache; ordinary transcription and speech commands fail fast if required assets
 are missing.
 
+Contributors: see [`docs/architecture.md`](docs/architecture.md) for the
+code-level map (repo layout, CLI↔engine boundary, backends, model pinning,
+tests, and a "where to change X" table).
+
 ## What's Inside
 
 | Model | Task | Size | Source |
@@ -305,6 +346,26 @@ Audio decoding via [symphonia](https://github.com/pdeljanov/Symphonia) — WAV,
 - **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
 - **Raycast** (macOS) — transcribe selected audio & speak clipboard from the launcher. Source + install: [`raycast/`](raycast/).
 
+## MCP server
+
+`kesha mcp` runs a local Model Context Protocol server over stdio, exposing
+`transcribe_audio`, `synthesize_speech`, `list_voices`, and `list_languages` to
+any MCP client. Models are never auto-downloaded — tools fail with a
+`kesha install` / `kesha install --tts` hint when missing.
+
+Add to your client config:
+
+```json
+{ "mcpServers": { "kesha": { "command": "kesha", "args": ["mcp"] } } }
+```
+
+- **Claude Desktop:** `claude_desktop_config.json`
+- **Claude Code:** `claude mcp add kesha -- kesha mcp`
+- **Cursor:** `.cursor/mcp.json`
+
+If a tool returns "models not installed", run `kesha install` (ASR) or
+`kesha install --tts` (TTS) once, then retry.
+
 ## Programmatic API
 
 ```typescript
@@ -374,7 +435,13 @@ state and retention.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). Project docs:
+
+- [Architecture](docs/architecture.md) — TS CLI ↔ Rust engine ↔ ASR/TTS backends, model cache, where tests live
+- [Use cases](docs/use-cases.md) — copy-paste recipes (transcribe a meeting, speak from OpenClaw, run offline, move the cache)
+- [Roadmap](ROADMAP.md) — Now / Next / Later
+- [Decision log](docs/decision-log.md) — why the platform/model choices were made (and reversed)
+- Dev setup: `make dev-setup` (Bun, Rust, nextest, platform libs)
 
 ## License
 

package/SKILL.md

@@ -168,6 +168,12 @@ kesha say --list-voices                            # Kokoro + Vosk-TTS + ~180 ma
 
 Output: WAV mono float32 by default. `--out <path>` writes to a file instead of stdout. For Telegram/OpenClaw replies, prefer `--format ogg-opus --out reply.ogg` or the OpenClaw-provided `{{OutputPath}}`.
 
+**Output formats** (`--format`, or inferred from the `--out` extension): `wav` (default, uncompressed), `ogg-opus` (messenger voice notes), `flac` (lossless, royalty-free, plays in every browser incl. Safari/iOS — the format for web-embeddable samples). FLAC keeps the engine's native rate; `--bitrate` / `--sample-rate` apply only to `ogg-opus`.
+
+```bash
+kesha say --format flac --out sample.flac "Hello"   # web-embeddable, Safari-safe
+```
+
 **Voice notes (Telegram / WhatsApp / Signal / Discord):** add `--format ogg-opus` to emit OGG/Opus directly — the format messenger APIs render as a native voice message:
 
 ```bash

package/completions/kesha.bash

@@ -6,7 +6,7 @@ _kesha_completion() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   command="${COMP_WORDS[1]}"
-  commands="completions doctor init install logs manpage record say stats status support-bundle"
+  commands="completions doctor init install logs manpage mcp record say stats status support-bundle"
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
@@ -24,6 +24,7 @@ _kesha_completion() {
     install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
     logs) opts="--help -h --json" ;;
     manpage) opts="--help -h" ;;
+    mcp) opts="--help -h" ;;
     record) opts="--help -h --out --max-seconds --debug" ;;
     say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
     stats) opts="--help -h --format" ;;

package/completions/kesha.fish

@@ -6,6 +6,7 @@ complete -c kesha -n '__fish_use_subcommand' -a 'init' -d 'Interactive setup gui
 complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
 complete -c kesha -n '__fish_use_subcommand' -a 'logs' -d 'Manage local privacy-safe diagnostic logs'
 complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
+complete -c kesha -n '__fish_use_subcommand' -a 'mcp' -d 'Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: \'kesha\', args: [\'mcp\'] }.'
 complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
 complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
 complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
@@ -56,6 +57,8 @@ complete -c kesha -n '__fish_seen_subcommand_from logs' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from logs' -l json -d 'Output status as JSON'
 complete -c kesha -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from mcp' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from mcp' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l out -r -d 'Write recorded WAV audio to this path'
@@ -69,7 +72,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio
 complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'

package/completions/kesha.zsh

@@ -10,6 +10,7 @@ _kesha() {
     'install:Download inference engine and models'
     'logs:Manage local privacy-safe diagnostic logs'
     'manpage:Print the kesha(1) manpage'
+    'mcp:Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: '\''kesha'\'', args: \['\''mcp'\''\] }.'
     'record:Record microphone audio to a WAV file'
     'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
     'stats:Manage local anonymous Kesha Stats'
@@ -83,6 +84,10 @@ _kesha() {
       _arguments '--help[Show help]' \
         '-h[Show help]'
       ;;
+    mcp)
+      _arguments '--help[Show help]' \
+        '-h[Show help]'
+      ;;
     record)
       _arguments '--help[Show help]' \
         '-h[Show help]' \
@@ -99,7 +104,7 @@ _kesha() {
         '--rate=[Speaking rate 0.5–2.0]:rate:' \
         '--list-voices[List installed voices and exit]' \
         '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
-        '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
+        '--format=[Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.]:format:' \
         '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
         '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
         '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \

package/man/kesha.1

@@ -1,4 +1,4 @@
-.TH KESHA 1 "May 2026" "kesha 1.19.0" "User Commands"
+.TH KESHA 1 "May 2026" "kesha 1.21.0-beta.1" "User Commands"
 .SH NAME
 kesha \- open-source local voice toolkit
 .SH SYNOPSIS
@@ -29,6 +29,9 @@ Manage local privacy\-safe diagnostic logs
 .B manpage
 Print the kesha(1) manpage
 .TP
+.B mcp
+Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: 'kesha', args: ['mcp'] }.
+.TP
 .B record
 Record microphone audio to a WAV file
 .TP
@@ -167,7 +170,7 @@ List installed voices and exit
 Parse input as SSML (supports <speak>, <break>; strips unknown tags)
 .TP
 .B \-\-format
-Output format: wav (default) or ogg\-opus (Telegram\-ready voice note). Inferred from \-\-out extension when omitted.
+Output format: wav (default), ogg\-opus (Telegram\-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from \-\-out extension when omitted.
 .TP
 .B \-\-bitrate
 Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.19.0",
+  "version": "1.21.0-beta.1",
   "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.19.0"
+    "version": "1.21.0-beta.1"
   },
   "scripts": {
     "test": "bun test",
@@ -79,15 +79,17 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260423.1",
-    "fast-xml-parser": "^5.5.10",
+    "fast-xml-parser": "^5.8.0",
     "typescript": "^6.0.2",
     "yaml": "^2.9.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@toon-format/toon": "^2.1.0",
     "citty": "^0.2.2",
     "fastest-levenshtein": "^1.0.16",
     "picocolors": "^1.1.1",
-    "tinyld": "^1.3.4"
+    "tinyld": "^1.3.4",
+    "zod": "^4.4.3"
   }
 }

package/src/cli/dispatch.ts

@@ -14,6 +14,7 @@ import { statsCommand } from "./stats";
 import { statusCommand } from "./status";
 import { supportBundleCommand } from "./support-bundle";
 import { mainCommand } from "./main";
+import { mcpCommand } from "./mcp";
 
 // Single source of truth: keyed lookup also feeds the `did you mean` suggester.
 // `CommandDef<any>` is intentional — citty's generic is invariant in the args
@@ -31,6 +32,7 @@ const SUBCOMMANDS: Record<string, CommandDef<any>> = {
   "support-bundle": supportBundleCommand,
   completions: completionsCommand,
   manpage: manpageCommand,
+  mcp: mcpCommand,
 };
 
 function isPathLike(arg: string): boolean {

package/src/cli/mcp.ts

@@ -0,0 +1,17 @@
+import { defineCommand } from "citty";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createKeshaMcpServer } from "../mcp/server";
+
+export const mcpCommand = defineCommand({
+  meta: {
+    name: "mcp",
+    description:
+      "Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). " +
+      "Configure an MCP client with: { command: 'kesha', args: ['mcp'] }.",
+  },
+  async run() {
+    const server = createKeshaMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  },
+});

package/src/cli/say.ts

@@ -100,7 +100,7 @@ export const sayCommand = defineCommand({
     format: {
       type: "string",
       description:
-        "Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.",
+        "Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.",
     },
     bitrate: {
       type: "string",
@@ -145,12 +145,12 @@ export const sayCommand = defineCommand({
     const fmtArg = typeof args.format === "string" ? args.format.toLowerCase() : undefined;
     let format: SayFormat | undefined;
     if (fmtArg) {
-      if (fmtArg === "wav" || fmtArg === "ogg-opus") {
+      if (fmtArg === "wav" || fmtArg === "ogg-opus" || fmtArg === "flac") {
         format = fmtArg;
       } else if (fmtArg === "opus" || fmtArg === "ogg") {
         format = "ogg-opus";
       } else {
-        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus`);
+        log.error(`unknown --format '${args.format}'. supported: wav, ogg-opus, flac`);
         process.exit(2);
       }
     }
@@ -166,7 +166,10 @@ export const sayCommand = defineCommand({
         ? args.out.split(".").pop()?.toLowerCase()
         : undefined;
       const impliesOpus = outExt && ["ogg", "opus", "oga"].includes(outExt);
-      if (format === "wav" || (format === undefined && !impliesOpus)) {
+      // --bitrate / --sample-rate are Opus-only. Reject for wav and flac
+      // (both lossless / no encoder knobs) and for any non-Opus extension.
+      const resolvesToOpus = format === "ogg-opus" || (format === undefined && impliesOpus);
+      if (!resolvesToOpus) {
         log.error("--bitrate and --sample-rate are only valid with --format ogg-opus");
         process.exit(2);
       }

package/src/mcp/audio-output.ts

@@ -0,0 +1,47 @@
+import { tmpdir } from "os";
+import { join } from "path";
+import { mkdirSync, readdirSync, statSync, unlinkSync } from "fs";
+import { randomUUID } from "crypto";
+import type { SayFormat } from "../synth";
+
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export function audioDir(): string {
+  return join(tmpdir(), "kesha-mcp");
+}
+
+function extFor(format: SayFormat): string {
+  switch (format) {
+    case "ogg-opus":
+      return "ogg";
+    case "flac":
+      return "flac";
+    case "wav":
+    default:
+      return "wav";
+  }
+}
+
+export function allocAudioPath(format: SayFormat): string {
+  mkdirSync(audioDir(), { recursive: true, mode: 0o700 });
+  return join(audioDir(), `${randomUUID()}.${extFor(format)}`);
+}
+
+export function sweepOldAudio(): void {
+  const dir = audioDir();
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - MAX_AGE_MS;
+  for (const name of entries) {
+    const p = join(dir, name);
+    try {
+      if (statSync(p).mtimeMs < cutoff) unlinkSync(p);
+    } catch {
+      // best-effort: race with another session or perms — ignore
+    }
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { packageVersion } from "../package-info";
+import { sweepOldAudio } from "./audio-output";
+import { registerTools } from "./tools";
+
+export function createKeshaMcpServer(): McpServer {
+  sweepOldAudio();
+  const server = new McpServer({ name: "kesha-voice-kit", version: packageVersion });
+  registerTools(server);
+  return server;
+}

package/src/mcp/tools.ts

@@ -0,0 +1,200 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { chmodSync, existsSync, readFileSync, statSync } from "fs";
+import { basename, join } from "path";
+import { transcribe, transcribeWithTimestamps } from "../lib";
+import { listVoices, aggregateLanguages } from "./voices";
+import { say, type SayFormat } from "../synth";
+import { allocAudioPath, audioDir } from "./audio-output";
+
+export function registerTools(server: McpServer): void {
+  function mimeForExt(file: string): string {
+    if (file.endsWith(".flac")) return "audio/flac";
+    if (file.endsWith(".ogg")) return "audio/ogg";
+    return "audio/wav";
+  }
+
+  server.registerResource(
+    "synthesized-audio",
+    new ResourceTemplate("kesha-audio://{file}", { list: undefined }),
+    { title: "Synthesized audio", description: "WAV/OGG/FLAC produced by synthesize_speech." },
+    async (uri, { file }) => {
+      const name = basename(String(file)); // sandbox: reject path traversal
+      const filePath = join(audioDir(), name);
+      let bytes: Buffer;
+      try {
+        bytes = readFileSync(filePath);
+      } catch {
+        throw new Error(`synthesized-audio: file not found or already swept: ${name}`);
+      }
+      return { contents: [{ uri: uri.href, mimeType: mimeForExt(name), blob: bytes.toString("base64") }] };
+    },
+  );
+
+  server.registerTool(
+    "synthesize_speech",
+    {
+      title: "Synthesize speech",
+      description:
+        "Synthesize speech from text into an audio file and return a resource link. " +
+        "Omit voice to auto-route by language (male defaults en-am_michael / ru-vosk-m02).",
+      inputSchema: {
+        text: z.string().min(1).describe("Text to speak"),
+        voice: z.string().optional().describe("Voice id, e.g. en-am_michael"),
+        rate: z.number().optional().describe("Speaking rate 0.5-2.0"),
+        format: z.enum(["wav", "ogg-opus", "flac"]).optional().describe("Output format (default wav)"),
+      },
+      outputSchema: {
+        uri: z.string(),
+        path: z.string(),
+        format: z.string(),
+        voice: z.string(),
+        bytes: z.number(),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+    async ({ text, voice, rate, format }, extra) => {
+      if (extra.signal?.aborted) {
+        return { isError: true, content: [{ type: "text" as const, text: "request cancelled" }] };
+      }
+      if (rate !== undefined && !(rate >= 0.5 && rate <= 2.0)) {
+        return { isError: true, content: [{ type: "text" as const, text: `rate ${rate} out of range (0.5-2.0)` }] };
+      }
+      const fmt: SayFormat = format ?? "wav";
+      const outPath = allocAudioPath(fmt);
+      try {
+        await say({ text, voice, rate, format: fmt, out: outPath });
+        chmodSync(outPath, 0o600);
+        const bytes = statSync(outPath).size;
+        const file = basename(outPath);
+        const uri = `kesha-audio://${file}`;
+        const mimeType = mimeForExt(file);
+        const resolvedVoice = voice ?? "(auto)";
+        return {
+          content: [
+            { type: "resource_link" as const, uri, name: file, mimeType },
+            { type: "text" as const, text: `Synthesized ${bytes} bytes (voice=${resolvedVoice}, format=${fmt}); read via resources/read ${uri}.` },
+          ],
+          structuredContent: { uri, path: outPath, format: fmt, voice: resolvedVoice, bytes },
+        };
+      } catch (err) {
+        return { isError: true, content: [{ type: "text" as const, text: toToolError(err) }] };
+      }
+    },
+  );
+
+  server.registerTool(
+    "transcribe_audio",
+    {
+      title: "Transcribe audio",
+      description: "Transcribe a local audio file to text. Set timestamps for segment timings.",
+      inputSchema: {
+        path: z.string().describe("Absolute or relative path to a local audio file"),
+        timestamps: z.boolean().optional().describe("Return per-segment start/end times"),
+      },
+      outputSchema: {
+        text: z.string(),
+        segments: z.array(
+          z.object({
+            text: z.string(),
+            start: z.number(),
+            end: z.number(),
+            speaker: z.number().optional(),
+          }),
+        ),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async ({ path, timestamps }, extra) => {
+      if (extra.signal?.aborted) {
+        return { isError: true, content: [{ type: "text" as const, text: "request cancelled" }] };
+      }
+      if (!existsSync(path)) {
+        return { isError: true, content: [{ type: "text" as const, text: `File not found: ${path}` }] };
+      }
+      try {
+        if (timestamps) {
+          const out = await transcribeWithTimestamps(path);
+          return {
+            content: [{ type: "text" as const, text: out.text }],
+            structuredContent: { text: out.text, segments: out.segments ?? [] },
+          };
+        }
+        const text = await transcribe(path);
+        return {
+          content: [{ type: "text" as const, text: text }],
+          structuredContent: { text, segments: [] },
+        };
+      } catch (err) {
+        return { isError: true, content: [{ type: "text" as const, text: toToolError(err) }] };
+      }
+    },
+  );
+
+  server.registerTool(
+    "list_voices",
+    {
+      title: "List voices",
+      description: "List installed TTS voices with their engine and language.",
+      inputSchema: {},
+      outputSchema: {
+        voices: z.array(
+          z.object({
+            voiceId: z.string(),
+            modelId: z.enum(["kokoro", "vosk", "avspeech", "unknown"]),
+            modelName: z.string(),
+            languageCode: z.string(),
+            languageName: z.string(),
+            gender: z.enum(["male", "female"]).nullable(),
+          }),
+        ),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async () => {
+      try {
+        const voices = await listVoices();
+        return {
+          content: [{ type: "text" as const, text: `${voices.length} voices installed.` }],
+          structuredContent: { voices },
+        };
+      } catch (err) {
+        return { isError: true, content: [{ type: "text" as const, text: `list_voices failed: ${toToolError(err)}` }] };
+      }
+    },
+  );
+
+  server.registerTool(
+    "list_languages",
+    {
+      title: "List languages",
+      description: "List languages available for synthesis, derived from installed voices.",
+      inputSchema: {},
+      outputSchema: {
+        languages: z.array(
+          z.object({
+            languageCode: z.string(),
+            languageName: z.string(),
+            voiceCount: z.number(),
+          }),
+        ),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    async () => {
+      try {
+        const languages = aggregateLanguages(await listVoices());
+        return {
+          content: [{ type: "text" as const, text: `${languages.length} languages available.` }],
+          structuredContent: { languages },
+        };
+      } catch (err) {
+        return { isError: true, content: [{ type: "text" as const, text: `list_languages failed: ${toToolError(err)}` }] };
+      }
+    },
+  );
+}
+
+function toToolError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/mcp/voices.ts

@@ -0,0 +1,118 @@
+import { getEngineBinPath } from "../engine";
+
+export interface VoiceInfo {
+  voiceId: string;
+  modelId: "kokoro" | "vosk" | "avspeech" | "unknown";
+  modelName: string;
+  languageCode: string;
+  languageName: string;
+  gender: "male" | "female" | null;
+}
+
+export interface LanguageInfo {
+  languageCode: string;
+  languageName: string;
+  voiceCount: number;
+}
+
+const langNames = new Intl.DisplayNames(["en"], { type: "language" });
+
+function langNameFor(code: string): string {
+  if (!code) return "Unknown";
+  try {
+    const name = langNames.of(code);
+    if (!name || name === code) return code;
+    return name;
+  } catch {
+    return code;
+  }
+}
+
+function parseVoiceInfo(id: string): VoiceInfo {
+  if (id.startsWith("ru-vosk-")) {
+    const suffix = id.slice("ru-vosk-".length); // e.g. "m02" or "f01"
+    const genderChar = suffix[0];
+    const gender: "male" | "female" | null =
+      genderChar === "m" ? "male" : genderChar === "f" ? "female" : null;
+    return {
+      voiceId: id,
+      modelId: "vosk",
+      modelName: "Vosk-TTS",
+      languageCode: "ru",
+      languageName: langNameFor("ru"),
+      gender,
+    };
+  }
+
+  if (id.startsWith("en-") && /^[ab][fm]_/.test(id.slice(3))) {
+    const suffix = id.slice("en-".length); // e.g. "am_michael" or "bf_emma"
+    const accent = suffix[0]; // 'a' = American, 'b' = British
+    const genderChar = suffix[1]; // 'f' = female, 'm' = male
+    const languageCode = accent === "a" ? "en-US" : "en-GB";
+    const gender: "male" | "female" = genderChar === "f" ? "female" : "male";
+    return {
+      voiceId: id,
+      modelId: "kokoro",
+      modelName: "Kokoro-82M",
+      languageCode,
+      languageName: langNameFor(languageCode),
+      gender,
+    };
+  }
+
+  if (id.startsWith("macos-")) {
+    const m = id.match(/[a-z]{2}-[A-Z]{2}/);
+    const languageCode = m ? m[0] : "";
+    return {
+      voiceId: id,
+      modelId: "avspeech",
+      modelName: "macOS AVSpeech",
+      languageCode,
+      languageName: langNameFor(languageCode),
+      gender: null,
+    };
+  }
+
+  return {
+    voiceId: id,
+    modelId: "unknown",
+    modelName: "Unknown",
+    languageCode: "",
+    languageName: "Unknown",
+    gender: null,
+  };
+}
+
+export function parseVoiceLines(text: string): VoiceInfo[] {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .map((id) => parseVoiceInfo(id));
+}
+
+export async function listVoices(): Promise<VoiceInfo[]> {
+  const proc = Bun.spawn([getEngineBinPath(), "say", "--list-voices"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) {
+    throw new Error(`engine list-voices failed (exit ${code}): ${err.trim()}`);
+  }
+  return parseVoiceLines(out);
+}
+
+export function aggregateLanguages(voices: VoiceInfo[]): LanguageInfo[] {
+  const map = new Map<string, LanguageInfo>();
+  for (const v of voices) {
+    const existing = map.get(v.languageCode);
+    if (existing) existing.voiceCount++;
+    else map.set(v.languageCode, { languageCode: v.languageCode, languageName: v.languageName, voiceCount: 1 });
+  }
+  return [...map.values()].sort((a, b) => a.languageCode.localeCompare(b.languageCode));
+}

package/src/shell-artifacts.ts

@@ -6,6 +6,7 @@ import { installCommand } from "./cli/install";
 import { logsCommand } from "./cli/logs";
 import { mainCommand } from "./cli/main";
 import { manpageCommand } from "./cli/manpage";
+import { mcpCommand } from "./cli/mcp";
 import { recordCommand } from "./cli/record";
 import { sayCommand } from "./cli/say";
 import { statsCommand } from "./cli/stats";
@@ -50,6 +51,7 @@ const CLI_COMMANDS: CliCommand[] = [
   { name: "install", command: installCommand },
   { name: "logs", command: logsCommand },
   { name: "manpage", command: manpageCommand },
+  { name: "mcp", command: mcpCommand },
   { name: "record", command: recordCommand },
   { name: "say", command: sayCommand },
   { name: "stats", command: statsCommand },

package/src/synth.ts

@@ -14,8 +14,10 @@ import { registerProcessTree } from "./process-tree";
  * - `wav` (default): RIFF WAV at the engine's native sample rate.
  * - `ogg-opus`: OGG-encapsulated Opus, mono. The format Telegram, WhatsApp,
  *   Signal, and Discord render as native voice messages. See #223.
+ * - `flac`: lossless, royalty-free, plays in every modern browser including
+ *   Safari/iOS. Keeps the engine's native rate; no bitrate knob.
  */
-export type SayFormat = "wav" | "ogg-opus";
+export type SayFormat = "wav" | "ogg-opus" | "flac";
 export const MAX_TEXT_CHARS = 5000;
 
 export interface SayOptions {