miragea-mcp 0.1.0__tar.gz

miragea_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragea team
+
+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.

miragea_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: miragea-mcp
+Version: 0.1.0
+Summary: MCP server for AI voiceover, voice cloning and captions: text of any length to speech with exact durations, SRT/VTT from local files, per-scene narration for Remotion. Works with Claude, Cursor, Codex.
+Author: HeadVox
+License: MIT
+Project-URL: Homepage, https://github.com/yyert123/miragea-mcp
+Project-URL: Repository, https://github.com/yyert123/miragea-mcp
+Project-URL: Demo, https://huggingface.co/spaces/headvox/miragea-mcp
+Project-URL: Voice engine, https://miragea.ai
+Keywords: mcp,mcp-server,model-context-protocol,text-to-speech,tts,voiceover,voice-cloning,captions,subtitles,srt,remotion,claude,cursor,elevenlabs-alternative,miragea
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2
+Dynamic: license-file
+
+# Miragea MCP: voiceover, voice cloning and captions for Claude, Cursor and Codex
+
+<!-- mcp-name: io.github.yyert123/miragea-mcp -->
+
+An MCP server that gives your AI agent a real voice toolkit: **text of any length to speech** in your saved
+or cloned voice, **exact durations** for every file, **readable SRT/VTT captions** from any local audio or
+video, and **per-scene narration** with `durationInFrames` and word-level captions for Remotion and other
+video timelines. Local stdio server, one line of config, no GPU. Voice and speech recognition by
+[Miragea](https://miragea.ai).
+
+```json
+{
+  "mcpServers": {
+    "miragea": {
+      "command": "uvx",
+      "args": ["miragea-mcp"],
+      "env": { "MIRAGEA_API_KEY": "your_key", "MIRAGEA_VOICE_ID": "optional_default_voice" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add miragea -e MIRAGEA_API_KEY=your_key -- uvx miragea-mcp`.
+No uv? `pip install miragea-mcp` and use `"command": "miragea-mcp"`. Check everything with
+`uvx miragea-mcp --check`.
+
+Then just ask:
+
+- *"Read this changelog aloud in my voice and save it as release-notes.mp3."*
+- *"Make captions for ~/Videos/talk.mp4."* / *"TikTok-style captions for clip.mov."*
+- *"Narrate these 5 scenes for my Remotion video and set each scene's durationInFrames."*
+
+## Tools
+
+| Tool | What it does | Returns |
+|---|---|---|
+| `check_setup` | Checks key, ffmpeg, saved voices, output folder; gives a fix for each problem | status + problems |
+| `list_voices` | Voices saved in your Miragea account | `voice_id`, `name` |
+| `speak` | Any length of text to speech (split at sentence ends under the 2,000-char API limit, joined back seamlessly). Saved voice, or clone from a public clip | file path, **exact seconds**, chunks |
+| `transcribe` | Local audio/video to SRT + VTT: whole words (no mid-word splits), 2 x 42-char lines, min/max cue time; `style="shorts"` for 1-3 word uppercase captions | srt/vtt paths, text, language |
+| `narrate_scenes` | One audio file per scene, `seconds`, `durationInFrames` (rounded up, never cut off), `startFrame`, a `narration.json` manifest; `captions=true` adds word-level `captions.json` in Remotion's `Caption` shape | manifest |
+
+## What it does for you automatically
+
+- **Long text**: chunked at sentence boundaries and stitched with a natural 120 ms pause. You never see
+  the 2,000-character limit.
+- **Durations**: measured from the audio itself, so video timelines line up to the frame.
+- **Captions**: speech-recognition segments are rebuilt into whole words and re-flowed with broadcast rules.
+- **Uploads**: video files are reduced to a 16 kHz mono track before upload (fast, small).
+- **Caching**: the same text, voice and model is never billed twice; the same file is never transcribed twice.
+- **Safety**: existing files are never overwritten (`name-2.mp3`), the key is only read from the environment
+  and never logged, failed audio tasks are refunded by Miragea, and network retries reuse the same
+  idempotency key so a retry cannot double-charge.
+- **Clear errors**: every error comes back as `{"error", "how_to_fix"}` for the agent to act on.
+
+## Compared with other voice MCP servers
+
+| | **miragea-mcp** | ElevenLabs MCP | Thin TTS wrappers (Edge, Kokoro, Azure...) |
+|---|---|---|---|
+| Local stdio server, maintained | Yes | Local server deprecated; hosted OAuth server instead | Varies |
+| Reads/writes files anywhere you point it | Yes (default `~/Miragea`) | Local version restricted inputs to one base folder | Usually output folder only |
+| Returns exact audio duration | Yes, every call | No (callers had to measure it) | Rarely |
+| Text longer than one API request | Automatic split and join | Manual | Varies |
+| Captions (SRT/VTT) from local files | Yes, reflowed whole words | Separate speech-to-text tool | No |
+| Scene durations in frames + Remotion captions | Yes (`narrate_scenes`) | No | No |
+| Your own cloned voice | Saved voice id or reference clip | Yes (paid plans) | Stock voices only |
+| Billing | Pay-as-you-go Miragea points | Subscription credits | Free / cloud account |
+
+Sources: ElevenLabs MCP [README](https://github.com/elevenlabs/elevenlabs-mcp) (deprecation notice) and the
+[remotion-superpowers changelog](https://github.com/DojoCodingLabs/remotion-superpowers/blob/main/CHANGELOG.md)
+(base-folder restriction, no duration returned).
+
+## Configuration
+
+| Env var | Required | Meaning |
+|---|---|---|
+| `MIRAGEA_API_KEY` | yes | Your key from [miragea.ai](https://miragea.ai) |
+| `MIRAGEA_VOICE_ID` | no | Default saved voice, so the agent never has to ask |
+| `MIRAGEA_REF_URL`, `MIRAGEA_REF_TEXT` | no | Default reference clip (public URL) and its exact words |
+| `MIRAGEA_OUTPUT_DIR` | no | Where files go when no path is given (default `~/Miragea`) |
+
+Requirements: Python 3.10+. ffmpeg is optional (without it audio is saved as WAV and videos are uploaded whole).
+
+## FAQ
+
+**Which MCP clients work?** Any stdio MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
+(Copilot agent mode), Codex CLI, Gemini CLI, Cline, Zed.
+
+**How do I use my own voice?** Save your voice once in your Miragea account and set `MIRAGEA_VOICE_ID`, or
+pass `reference_audio_url` (a public link to a clean 5-20 s clip) with `reference_text` (its exact words,
+which uses the cheaper 1x rate). A direct upload of local reference clips is planned by Miragea; until then
+the reference must be a public URL.
+
+**What does it cost?** Speech is billed per character, captions at 3 points per audio second (live rates:
+`GET https://miragea.ai/v1/capabilities`). Cached repeats are free.
+
+**Is my key safe?** It is read from the server's environment only, never written to disk, logged or returned.
+
+**Can I clone anyone's voice?** No. Only clone your own voice or one you have permission to use.
+
+**Where are files saved?** Where you ask, or in `MIRAGEA_OUTPUT_DIR` (default `~/Miragea`). The cache lives in
+`~/Miragea/.cache` and can be deleted at any time.
+
+## Related
+
+- [miragea-skills](https://github.com/yyert123/miragea-skills): Agent Skills for screen-recording voiceover, Shorts, captions and Remotion narration.
+- [Retake](https://github.com/yyert123/retake): fix a flubbed voiceover line in your own voice (CLI + MCP).
+- [HeadVox](https://github.com/yyert123/headvox): script to voiceover with word-aligned captions.
+
+MIT License.

miragea_mcp-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Miragea MCP: voiceover, voice cloning and captions for Claude, Cursor and Codex
+
+<!-- mcp-name: io.github.yyert123/miragea-mcp -->
+
+An MCP server that gives your AI agent a real voice toolkit: **text of any length to speech** in your saved
+or cloned voice, **exact durations** for every file, **readable SRT/VTT captions** from any local audio or
+video, and **per-scene narration** with `durationInFrames` and word-level captions for Remotion and other
+video timelines. Local stdio server, one line of config, no GPU. Voice and speech recognition by
+[Miragea](https://miragea.ai).
+
+```json
+{
+  "mcpServers": {
+    "miragea": {
+      "command": "uvx",
+      "args": ["miragea-mcp"],
+      "env": { "MIRAGEA_API_KEY": "your_key", "MIRAGEA_VOICE_ID": "optional_default_voice" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add miragea -e MIRAGEA_API_KEY=your_key -- uvx miragea-mcp`.
+No uv? `pip install miragea-mcp` and use `"command": "miragea-mcp"`. Check everything with
+`uvx miragea-mcp --check`.
+
+Then just ask:
+
+- *"Read this changelog aloud in my voice and save it as release-notes.mp3."*
+- *"Make captions for ~/Videos/talk.mp4."* / *"TikTok-style captions for clip.mov."*
+- *"Narrate these 5 scenes for my Remotion video and set each scene's durationInFrames."*
+
+## Tools
+
+| Tool | What it does | Returns |
+|---|---|---|
+| `check_setup` | Checks key, ffmpeg, saved voices, output folder; gives a fix for each problem | status + problems |
+| `list_voices` | Voices saved in your Miragea account | `voice_id`, `name` |
+| `speak` | Any length of text to speech (split at sentence ends under the 2,000-char API limit, joined back seamlessly). Saved voice, or clone from a public clip | file path, **exact seconds**, chunks |
+| `transcribe` | Local audio/video to SRT + VTT: whole words (no mid-word splits), 2 x 42-char lines, min/max cue time; `style="shorts"` for 1-3 word uppercase captions | srt/vtt paths, text, language |
+| `narrate_scenes` | One audio file per scene, `seconds`, `durationInFrames` (rounded up, never cut off), `startFrame`, a `narration.json` manifest; `captions=true` adds word-level `captions.json` in Remotion's `Caption` shape | manifest |
+
+## What it does for you automatically
+
+- **Long text**: chunked at sentence boundaries and stitched with a natural 120 ms pause. You never see
+  the 2,000-character limit.
+- **Durations**: measured from the audio itself, so video timelines line up to the frame.
+- **Captions**: speech-recognition segments are rebuilt into whole words and re-flowed with broadcast rules.
+- **Uploads**: video files are reduced to a 16 kHz mono track before upload (fast, small).
+- **Caching**: the same text, voice and model is never billed twice; the same file is never transcribed twice.
+- **Safety**: existing files are never overwritten (`name-2.mp3`), the key is only read from the environment
+  and never logged, failed audio tasks are refunded by Miragea, and network retries reuse the same
+  idempotency key so a retry cannot double-charge.
+- **Clear errors**: every error comes back as `{"error", "how_to_fix"}` for the agent to act on.
+
+## Compared with other voice MCP servers
+
+| | **miragea-mcp** | ElevenLabs MCP | Thin TTS wrappers (Edge, Kokoro, Azure...) |
+|---|---|---|---|
+| Local stdio server, maintained | Yes | Local server deprecated; hosted OAuth server instead | Varies |
+| Reads/writes files anywhere you point it | Yes (default `~/Miragea`) | Local version restricted inputs to one base folder | Usually output folder only |
+| Returns exact audio duration | Yes, every call | No (callers had to measure it) | Rarely |
+| Text longer than one API request | Automatic split and join | Manual | Varies |
+| Captions (SRT/VTT) from local files | Yes, reflowed whole words | Separate speech-to-text tool | No |
+| Scene durations in frames + Remotion captions | Yes (`narrate_scenes`) | No | No |
+| Your own cloned voice | Saved voice id or reference clip | Yes (paid plans) | Stock voices only |
+| Billing | Pay-as-you-go Miragea points | Subscription credits | Free / cloud account |
+
+Sources: ElevenLabs MCP [README](https://github.com/elevenlabs/elevenlabs-mcp) (deprecation notice) and the
+[remotion-superpowers changelog](https://github.com/DojoCodingLabs/remotion-superpowers/blob/main/CHANGELOG.md)
+(base-folder restriction, no duration returned).
+
+## Configuration
+
+| Env var | Required | Meaning |
+|---|---|---|
+| `MIRAGEA_API_KEY` | yes | Your key from [miragea.ai](https://miragea.ai) |
+| `MIRAGEA_VOICE_ID` | no | Default saved voice, so the agent never has to ask |
+| `MIRAGEA_REF_URL`, `MIRAGEA_REF_TEXT` | no | Default reference clip (public URL) and its exact words |
+| `MIRAGEA_OUTPUT_DIR` | no | Where files go when no path is given (default `~/Miragea`) |
+
+Requirements: Python 3.10+. ffmpeg is optional (without it audio is saved as WAV and videos are uploaded whole).
+
+## FAQ
+
+**Which MCP clients work?** Any stdio MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
+(Copilot agent mode), Codex CLI, Gemini CLI, Cline, Zed.
+
+**How do I use my own voice?** Save your voice once in your Miragea account and set `MIRAGEA_VOICE_ID`, or
+pass `reference_audio_url` (a public link to a clean 5-20 s clip) with `reference_text` (its exact words,
+which uses the cheaper 1x rate). A direct upload of local reference clips is planned by Miragea; until then
+the reference must be a public URL.
+
+**What does it cost?** Speech is billed per character, captions at 3 points per audio second (live rates:
+`GET https://miragea.ai/v1/capabilities`). Cached repeats are free.
+
+**Is my key safe?** It is read from the server's environment only, never written to disk, logged or returned.
+
+**Can I clone anyone's voice?** No. Only clone your own voice or one you have permission to use.
+
+**Where are files saved?** Where you ask, or in `MIRAGEA_OUTPUT_DIR` (default `~/Miragea`). The cache lives in
+`~/Miragea/.cache` and can be deleted at any time.
+
+## Related
+
+- [miragea-skills](https://github.com/yyert123/miragea-skills): Agent Skills for screen-recording voiceover, Shorts, captions and Remotion narration.
+- [Retake](https://github.com/yyert123/retake): fix a flubbed voiceover line in your own voice (CLI + MCP).
+- [HeadVox](https://github.com/yyert123/headvox): script to voiceover with word-aligned captions.
+
+MIT License.

miragea_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "miragea-mcp"
+version = "0.1.0"
+description = "MCP server for AI voiceover, voice cloning and captions: text of any length to speech with exact durations, SRT/VTT from local files, per-scene narration for Remotion. Works with Claude, Cursor, Codex."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "HeadVox" }]
+keywords = ["mcp", "mcp-server", "model-context-protocol", "text-to-speech", "tts", "voiceover", "voice-cloning", "captions", "subtitles", "srt", "remotion", "claude", "cursor", "elevenlabs-alternative", "miragea"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Multimedia :: Video",
+  "Intended Audience :: Developers",
+]
+dependencies = ["mcp>=1.2"]
+
+[project.urls]
+Homepage = "https://github.com/yyert123/miragea-mcp"
+Repository = "https://github.com/yyert123/miragea-mcp"
+Demo = "https://huggingface.co/spaces/headvox/miragea-mcp"
+"Voice engine" = "https://miragea.ai"
+
+[project.scripts]
+miragea-mcp = "miragea_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

miragea_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

miragea_mcp-0.1.0/src/miragea_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Miragea MCP: voiceover, voice cloning and captions for AI agents (https://miragea.ai)."""
+__version__ = "0.1.0"

miragea_mcp-0.1.0/src/miragea_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+raise SystemExit(main())

miragea_mcp-0.1.0/src/miragea_mcp/captions.py

@@ -0,0 +1,136 @@
+"""Turn Miragea's segment transcript into readable caption cues (stdlib only).
+
+Miragea segments are timed by audio, not by words, and can split mid-word
+("cen" | "ts"). We place every character of the full transcript in time, rebuild
+whole words, then group words into cues that follow subtitle conventions.
+"""
+from __future__ import annotations
+
+import re
+
+PRESETS = {
+    # Netflix-style limits: 42 chars/line, 2 lines, 1-7 s, ~17 chars/s.
+    "standard": {"max_chars": 42, "max_lines": 2, "max_dur": 7.0, "min_dur": 1.0, "max_words": 99},
+    # Short-form vertical video: punchy 1-3 word cues, one line.
+    "shorts": {"max_chars": 16, "max_lines": 1, "max_dur": 2.0, "min_dur": 0.35, "max_words": 3},
+}
+
+
+def char_times(text: str, segments: list) -> list:
+    alnum_pos = [i for i, c in enumerate(text) if c.isalnum()]
+    alnum = "".join(text[i].lower() for i in alnum_pos)
+    times = [None] * len(text)
+    cursor = 0
+    for seg in segments:
+        s = "".join(c.lower() for c in seg.get("text", "") if c.isalnum())
+        if not s:
+            continue
+        at = alnum.find(s, cursor)
+        if at < 0:
+            at = alnum.find(s[:4], cursor)
+            if at < 0:
+                continue
+        end = min(at + len(s), len(alnum_pos)) - 1
+        n = max(1, end - at)
+        for k in range(at, end + 1):
+            times[alnum_pos[k]] = seg["start"] + (k - at) / n * (seg["end"] - seg["start"])
+        cursor = end + 1
+    known = [i for i, t in enumerate(times) if t is not None]
+    if not known:
+        return times
+    j = 0
+    for i in range(len(times)):
+        if times[i] is None:
+            while j + 1 < len(known) and known[j + 1] < i:
+                j += 1
+            left = known[j] if known[j] < i else None
+            right = next((k for k in known[j:] if k > i), None)
+            if left is None:
+                times[i] = times[right]
+            elif right is None:
+                times[i] = times[left]
+            else:
+                times[i] = times[left] + (i - left) / (right - left) * (times[right] - times[left])
+    return times
+
+
+def words(transcript: dict) -> list:
+    """Return [{'text', 'start', 'end'}] for every whole word."""
+    text = transcript.get("text") or " ".join(s.get("text", "") for s in transcript.get("segments", []))
+    times = char_times(text, transcript.get("segments", []))
+    out = []
+    for m in re.finditer(r"\S+", text):
+        idx = [i for i in range(m.start(), m.end()) if text[i].isalnum()] or [m.start()]
+        if times[idx[0]] is None:
+            continue
+        out.append({"text": m.group(), "start": times[idx[0]], "end": times[idx[-1]]})
+    # A word ends where the next begins at the latest; give the last word its segment end.
+    segs = transcript.get("segments") or []
+    if out and segs:
+        out[-1]["end"] = max(out[-1]["end"], segs[-1]["end"])
+    for a, b in zip(out, out[1:]):
+        a["end"] = max(a["end"], min(b["start"], a["start"] + 0.08))
+    return out
+
+
+def _wrap(text: str, max_chars: int, max_lines: int) -> str:
+    if len(text) <= max_chars or max_lines == 1:
+        return text
+    ws = text.split()
+    best, best_cost = text, 1e9
+    for k in range(1, len(ws)):  # most balanced 2-line split
+        a, b = " ".join(ws[:k]), " ".join(ws[k:])
+        cost = abs(len(a) - len(b)) + (100 if max(len(a), len(b)) > max_chars else 0)
+        if cost < best_cost:
+            best, best_cost = a + "\n" + b, cost
+    return best
+
+
+def build_cues(ws: list, preset: str = "standard", upper: bool = False) -> list:
+    p = PRESETS[preset]
+    limit = p["max_chars"] * p["max_lines"]
+    cues, cur = [], []
+
+    def flush():
+        if cur:
+            txt = " ".join(w["text"] for w in cur)
+            if preset == "shorts":
+                txt = txt.strip(",;:")
+            cues.append({"start": cur[0]["start"], "end": cur[-1]["end"], "text": txt.upper() if upper else txt})
+            cur.clear()
+
+    for w in ws:
+        if cur:
+            joined = len(" ".join(x["text"] for x in cur)) + 1 + len(w["text"])
+            gap = w["start"] - cur[-1]["end"]
+            if (joined > limit or len(cur) >= p["max_words"] or gap > 0.6
+                    or w["end"] - cur[0]["start"] > p["max_dur"]):
+                flush()
+        cur.append(w)
+        if re.search(r"[.!?…]['\")\]]*$", w["text"]) and not re.fullmatch(r"[A-Z]\.", w["text"]) and (preset == "shorts" or len(cur) >= 3):
+            flush()
+        elif preset == "standard" and re.search(r"[,;:—]$", w["text"]) and len(" ".join(x["text"] for x in cur)) > limit * 0.6:
+            flush()
+    flush()
+    # Minimum on-screen time without overlapping the next cue.
+    for a, b in zip(cues, cues[1:] + [None]):
+        want = a["start"] + p["min_dur"]
+        nxt = b["start"] - 0.04 if b else want
+        a["end"] = max(a["end"], min(want, nxt))
+    for c in cues:
+        c["text"] = _wrap(c["text"], p["max_chars"], p["max_lines"])
+    return cues
+
+
+def _ts(t: float, sep: str) -> str:
+    ms = int(round(max(t, 0) * 1000))
+    return f"{ms // 3600000:02d}:{ms // 60000 % 60:02d}:{ms // 1000 % 60:02d}{sep}{ms % 1000:03d}"
+
+
+def to_srt(cues: list) -> str:
+    return "\n".join(f"{i}\n{_ts(c['start'], ',')} --> {_ts(c['end'], ',')}\n{c['text']}\n"
+                     for i, c in enumerate(cues, 1))
+
+
+def to_vtt(cues: list) -> str:
+    return "WEBVTT\n\n" + "\n".join(f"{_ts(c['start'], '.')} --> {_ts(c['end'], '.')}\n{c['text']}\n" for c in cues)

miragea_mcp-0.1.0/src/miragea_mcp/client.py

@@ -0,0 +1,144 @@
+"""Minimal Miragea API client (https://miragea.ai/v1), standard library only.
+
+The API key is read from the MIRAGEA_API_KEY environment variable and is never
+logged, cached or written to disk.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+
+from . import __version__
+
+DEFAULT_BASE = "https://miragea.ai/v1"
+# Miragea sits behind Cloudflare, which rejects default library user agents.
+USER_AGENT = f"miragea-mcp/{__version__} (+https://github.com/yyert123/miragea-mcp)"
+
+
+class MirageaError(RuntimeError):
+    """An API or network error with a human-readable fix hint."""
+
+    def __init__(self, message: str, hint: str = "", status: int | None = None, code: str = ""):
+        self.hint = hint
+        self.status = status
+        self.code = code
+        super().__init__(message + (f"\n  How to fix: {hint}" if hint else ""))
+
+
+_HINTS = {
+    401: "Your MIRAGEA_API_KEY was rejected. Create a key at https://miragea.ai and export MIRAGEA_API_KEY=...",
+    402: "Your Miragea balance is too low for this job. Top up at https://miragea.ai.",
+    403: "This key has no API access. API access is enabled per account at https://miragea.ai.",
+    413: "The file is too large for one request (limit: 1024 MB / 90 min). Trim it first.",
+    429: "Rate limited or out of quota. Wait a minute and run the same command again (cached steps are not re-billed).",
+}
+
+
+class Client:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 60):
+        self.key = api_key or os.environ.get("MIRAGEA_API_KEY", "")
+        if not self.key:
+            raise MirageaError(
+                "MIRAGEA_API_KEY is not set.",
+                "Get a key at https://miragea.ai (API section), then run: export MIRAGEA_API_KEY=your_key",
+                code="missing_api_key",
+            )
+        self.base = (base_url or os.environ.get("MIRAGEA_BASE_URL") or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+
+    # -- low level -------------------------------------------------------
+    def _request(self, method: str, path: str, body: bytes | None = None, content_type: str | None = None,
+                 idem_key: str | None = None) -> dict:
+        headers = {"Authorization": "Bearer " + self.key, "Accept": "application/json", "User-Agent": USER_AGENT}
+        if content_type:
+            headers["Content-Type"] = content_type
+        if idem_key:
+            headers["Idempotency-Key"] = idem_key
+        req = urllib.request.Request(self.base + path, data=body, headers=headers, method=method)
+        last: Exception | None = None
+        for attempt in range(4):
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return json.load(resp)
+            except urllib.error.HTTPError as exc:
+                try:
+                    err = json.load(exc).get("error", {})
+                except Exception:  # noqa: BLE001
+                    err = {}
+                retryable = err.get("retryable") or exc.code in (502, 503, 504)
+                if retryable and attempt < 3:
+                    time.sleep(2 * (attempt + 1))
+                    continue
+                msg = err.get("message") or f"Miragea API returned HTTP {exc.code}"
+                raise MirageaError(msg, _HINTS.get(exc.code, ""), exc.code, err.get("code", "")) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as exc:
+                last = exc
+                if attempt < 3:
+                    time.sleep(2 * (attempt + 1))
+                    continue
+        raise MirageaError(f"Could not reach {self.base}: {last}",
+                           "Check your internet connection or MIRAGEA_BASE_URL, then re-run; the same request is retried safely.")
+
+    def wait(self, task: dict, timeout: float = 900) -> dict:
+        deadline = time.time() + timeout
+        while task.get("status") not in ("succeeded", "failed"):
+            if time.time() > deadline:
+                raise MirageaError(f"Task {task.get('task_id')} still {task.get('status')} after {timeout:.0f}s.",
+                                   "Re-run the same command later; finished results are cached.")
+            time.sleep(max(1.0, float(task.get("poll_after_seconds") or 3)))
+            task = self._request("GET", "/tasks/" + urllib.parse.quote(task["task_id"], safe=""))
+        if task["status"] == "failed":
+            err = task.get("error") or {}
+            raise MirageaError(f"Miragea task {task.get('task_id')} failed: {err.get('message', 'unknown error')}",
+                               "Points are refunded automatically for failed audio tasks. Check the input and retry.")
+        return task
+
+    # -- endpoints -------------------------------------------------------
+    def capabilities(self) -> dict:
+        return self._request("GET", "/capabilities")
+
+    def voices(self, limit: int = 50, offset: int = 0) -> dict:
+        return self._request("GET", f"/actors?limit={int(limit)}&offset={int(offset)}")
+
+    def transcribe(self, path: str | Path) -> dict:
+        """Upload a local audio/video file; returns {text, language, segments[{start,end,text}], srt}."""
+        path = Path(path)
+        rate = self.capabilities().get("subtitles", {}).get("points_per_second", 3)
+        boundary = "mskill-" + uuid.uuid4().hex
+        head = (f"--{boundary}\r\nContent-Disposition: form-data; name=\"expected_rate\"\r\n\r\n{rate}\r\n"
+                f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{path.name}\"\r\n"
+                f"Content-Type: application/octet-stream\r\n\r\n").encode()
+        body = head + path.read_bytes() + f"\r\n--{boundary}--\r\n".encode()
+        task = self._request("POST", "/subtitles/recognitions", body, "multipart/form-data; boundary=" + boundary,
+                             str(uuid.uuid4()))
+        return self.wait(task)["result"]
+
+    def speak(self, text: str, out_path: str | Path, *, actor_id: str | None = None,
+              reference_audio_url: str | None = None, reference_text: str | None = None,
+              model: str = "expressive", fmt: str = "wav", speed: float | None = None) -> Path:
+        """Generate speech in a saved voice (actor_id) or a cloned reference voice; saves to out_path."""
+        if not (actor_id or reference_audio_url):
+            raise MirageaError("No voice given.", "Pass voice_id (a voice saved in your Miragea account, see list_voices) or reference_audio_url (a public clip), or set MIRAGEA_VOICE_ID.")
+        payload: dict = {"text": text, "model": model, "format": fmt}
+        if actor_id:
+            payload["actor_id"] = actor_id
+        else:
+            payload["reference_audio_url"] = reference_audio_url
+            if reference_text:
+                payload["reference_text"] = reference_text
+        if speed:
+            payload["speed"] = speed
+        task = self._request("POST", "/audio/generations", json.dumps(payload).encode(), "application/json",
+                             str(uuid.uuid4()))
+        url = self.wait(task)["result"]["audio_url"]
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        out_path = Path(out_path)
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            out_path.write_bytes(resp.read())
+        return out_path

miragea_mcp-0.1.0/src/miragea_mcp/core.py

@@ -0,0 +1,287 @@
+"""Voice, captions and scene narration on top of the Miragea API. No MCP imports here (easy to test)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import wave
+from pathlib import Path
+
+from .captions import build_cues, to_srt, to_vtt, words
+from .client import Client, MirageaError
+
+MAX_CHARS = 1900  # API limit is 2000 per request; keep a margin
+FORMATS = ("mp3", "wav", "flac", "opus", "aac")
+
+
+# ---------------------------------------------------------------- helpers
+def output_dir() -> Path:
+    d = Path(os.environ.get("MIRAGEA_OUTPUT_DIR") or Path.home() / "Miragea").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def slug(text: str, n: int = 40) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return (s[:n].rstrip("-") or "speech")
+
+
+def unique(path: Path) -> Path:
+    """Never overwrite the user's files: add -2, -3, ... when the name is taken."""
+    if not path.exists():
+        return path
+    i = 2
+    while True:
+        cand = path.with_name(f"{path.stem}-{i}{path.suffix}")
+        if not cand.exists():
+            return cand
+        i += 1
+
+
+def resolve_out(output_path: str | None, text: str, fmt: str) -> Path:
+    if output_path:
+        p = Path(output_path).expanduser()
+        if not p.is_absolute():
+            p = output_dir() / p
+        if p.suffix.lower().lstrip(".") not in FORMATS:
+            p = p.with_name(p.name + "." + fmt)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return unique(p)
+    return unique(output_dir() / f"{slug(text)}.{fmt}")
+
+
+def chunk_text(text: str, limit: int = MAX_CHARS) -> list[str]:
+    """Split at sentence ends (then commas, then spaces) so every piece is under the API limit."""
+    text = re.sub(r"\s+", " ", text).strip()
+    if len(text) <= limit:
+        return [text] if text else []
+    parts, cur = [], ""
+    for sent in re.split(r"(?<=[.!?…])\s+", text):
+        while len(sent) > limit:  # a monster sentence: cut at the last comma/space before the limit
+            cut = max(sent.rfind(", ", 0, limit), sent.rfind(" ", 0, limit))
+            cut = cut if cut > limit // 3 else limit
+            head, sent = sent[:cut + 1].strip(), sent[cut + 1:].strip()
+            if cur:
+                parts.append(cur)
+                cur = ""
+            parts.append(head)
+        if cur and len(cur) + 1 + len(sent) > limit:
+            parts.append(cur)
+            cur = sent
+        else:
+            cur = f"{cur} {sent}".strip()
+    if cur:
+        parts.append(cur)
+    return parts
+
+
+def wav_duration(path: Path) -> float:
+    with wave.open(str(path)) as w:
+        return w.getnframes() / float(w.getframerate())
+
+
+def join_wavs(paths: list[Path], out: Path, gap: float = 0.12) -> None:
+    with wave.open(str(paths[0])) as w0:
+        params = w0.getparams()
+    silence = b"\x00" * int(params.framerate * gap) * params.sampwidth * params.nchannels
+    with wave.open(str(out), "wb") as o:
+        o.setparams(params)
+        for i, p in enumerate(paths):
+            with wave.open(str(p)) as w:
+                if (w.getframerate(), w.getsampwidth(), w.getnchannels()) != (params.framerate, params.sampwidth, params.nchannels):
+                    raise MirageaError("Audio chunks came back in different formats.", "Re-run; this is unexpected.")
+                if i:
+                    o.writeframes(silence)
+                o.writeframes(w.readframes(w.getnframes()))
+
+
+def has_ffmpeg() -> bool:
+    return bool(shutil.which("ffmpeg"))
+
+
+def encode(wav: Path, out: Path) -> None:
+    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", str(wav), str(out)], check=True)
+
+
+def voice_from(voice_id: str | None, reference_audio_url: str | None, reference_text: str | None) -> dict:
+    voice_id = voice_id or (None if reference_audio_url else os.environ.get("MIRAGEA_VOICE_ID"))
+    ref = reference_audio_url or (None if voice_id else os.environ.get("MIRAGEA_REF_URL"))
+    if voice_id:
+        return {"actor_id": voice_id}
+    if ref:
+        return {"reference_audio_url": ref, "reference_text": reference_text or os.environ.get("MIRAGEA_REF_TEXT")}
+    raise MirageaError("No voice chosen.",
+                       "Pass voice_id (call list_voices to see the voices saved in your Miragea account) or "
+                       "reference_audio_url (a public URL of a clip you may clone) plus reference_text. "
+                       "Set MIRAGEA_VOICE_ID in the server's env to make it the default.")
+
+
+def cache_dir() -> Path:
+    d = output_dir() / ".cache"
+    d.mkdir(exist_ok=True)
+    return d
+
+
+def _speak_chunk(client: Client, text: str, voice: dict, model: str, speed: float | None) -> Path:
+    key = hashlib.sha256(json.dumps([text, voice, model, speed], sort_keys=True).encode()).hexdigest()[:24]
+    path = cache_dir() / f"{key}.wav"
+    if not (path.exists() and path.stat().st_size > 100):
+        tmp = path.with_name(path.stem + ".part.wav")
+        client.speak(text, tmp, model=model, fmt="wav", speed=speed, **voice)
+        tmp.replace(path)
+    return path
+
+
+# ---------------------------------------------------------------- tools
+def speak(text: str, output_path: str | None = None, voice_id: str | None = None,
+          reference_audio_url: str | None = None, reference_text: str | None = None, model: str = "expressive",
+          speed: float | None = None, format: str = "mp3", client: Client | None = None) -> dict:
+    if not text or not text.strip():
+        raise MirageaError("Nothing to say.", "Pass the text to speak.")
+    fmt = format.lower().lstrip(".")
+    if fmt not in FORMATS:
+        raise MirageaError(f"Unsupported format '{format}'.", f"Use one of: {', '.join(FORMATS)}.")
+    voice = voice_from(voice_id, reference_audio_url, reference_text)
+    client = client or Client()
+    pieces = [_speak_chunk(client, c, voice, model, speed) for c in chunk_text(text)]
+    note = None
+    if fmt != "wav" and not has_ffmpeg():
+        fmt, note = "wav", "Saved as WAV because ffmpeg is not installed (install ffmpeg for mp3/flac/opus/aac)."
+    out = resolve_out(output_path, text, fmt)
+    with tempfile.TemporaryDirectory() as td:
+        joined = Path(td) / "joined.wav"
+        join_wavs(pieces, joined) if len(pieces) > 1 else shutil.copy(pieces[0], joined)
+        seconds = wav_duration(joined)
+        shutil.copy(joined, out) if fmt == "wav" else encode(joined, out)
+    res = {"path": str(out), "seconds": round(seconds, 3), "characters": len(text), "chunks": len(pieces),
+           "voice": voice.get("actor_id") or "reference clip", "model": model}
+    if note:
+        res["note"] = note
+    return res
+
+
+def _sha(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for b in iter(lambda: f.read(1 << 20), b""):
+            h.update(b)
+    return h.hexdigest()[:16]
+
+
+def transcript_of(path: Path, client: Client | None = None) -> dict:
+    cache = cache_dir() / f"transcript-{_sha(path)}.json"
+    if cache.exists():
+        return json.loads(cache.read_text())
+    client = client or Client()
+    with tempfile.TemporaryDirectory() as td:
+        src = path
+        if has_ffmpeg():  # upload a small 16 kHz mono track instead of a whole video
+            src = Path(td) / "audio.flac"
+            subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", str(path), "-vn", "-ac", "1", "-ar", "16000", str(src)],
+                           check=True)
+        r = client.transcribe(src)
+    data = {k: r.get(k) for k in ("text", "language", "segments")}
+    cache.write_text(json.dumps(data, ensure_ascii=False))
+    return data
+
+
+def transcribe(path: str, style: str = "standard", output_dir_: str | None = None,
+               client: Client | None = None) -> dict:
+    src = Path(path).expanduser()
+    if not src.exists():
+        raise MirageaError(f"File not found: {src}", "Pass an absolute path to an audio or video file.")
+    if style not in ("standard", "shorts"):
+        raise MirageaError(f"Unknown style '{style}'.", "Use 'standard' (2 lines x 42 chars) or 'shorts' (1-3 words).")
+    tr = transcript_of(src, client)
+    cues = build_cues(words(tr), style, upper=(style == "shorts"))
+    dest = Path(output_dir_).expanduser() if output_dir_ else src.parent
+    if not os.access(dest, os.W_OK):
+        dest = output_dir()
+    stem = src.stem + (".shorts" if style == "shorts" else "")
+    srt, vtt = unique(dest / f"{stem}.srt"), unique(dest / f"{stem}.vtt")
+    srt.write_text(to_srt(cues), encoding="utf-8")
+    vtt.write_text(to_vtt(cues), encoding="utf-8")
+    return {"text": tr.get("text"), "language": tr.get("language"), "srt": str(srt), "vtt": str(vtt),
+            "cues": len(cues), "seconds": round(cues[-1]["end"], 3) if cues else 0}
+
+
+def remotion_captions(tr: dict, offset: float = 0.0) -> list[dict]:
+    """Word-level captions in Remotion's Caption shape (@remotion/captions)."""
+    return [{"text": (" " if i else "") + w["text"], "startMs": round((w["start"] + offset) * 1000),
+             "endMs": round((w["end"] + offset) * 1000), "timestampMs": round(((w["start"] + w["end"]) / 2 + offset) * 1000),
+             "confidence": None} for i, w in enumerate(words(tr))]
+
+
+def narrate_scenes(scenes: list, output_dir_: str | None = None, fps: int = 30, voice_id: str | None = None,
+                   reference_audio_url: str | None = None, reference_text: str | None = None,
+                   model: str = "expressive", captions: bool = False, client: Client | None = None) -> dict:
+    if not scenes:
+        raise MirageaError("No scenes given.", "Pass a list of scene texts, or objects like {id, text}.")
+    items = []
+    for i, s in enumerate(scenes, 1):
+        sid, text = (s.get("id") or f"scene-{i:02d}", s.get("text", "")) if isinstance(s, dict) else (f"scene-{i:02d}", str(s))
+        if not text.strip():
+            raise MirageaError(f"Scene {i} has no text.", "Give every scene some narration text.")
+        items.append((slug(sid, 30), text))
+    dest = Path(output_dir_).expanduser() if output_dir_ else output_dir() / "narration"
+    dest.mkdir(parents=True, exist_ok=True)
+    voice = voice_from(voice_id, reference_audio_url, reference_text)
+    client = client or Client()
+    out, t = [], 0.0
+    fmt = "mp3" if has_ffmpeg() else "wav"
+    all_caps: list[dict] = []
+    for sid, text in items:
+        pieces = [_speak_chunk(client, c, voice, model, None) for c in chunk_text(text)]
+        f = dest / f"{sid}.{fmt}"  # stable names so a video project can reference them; regenerated in place
+        with tempfile.TemporaryDirectory() as td:
+            j = Path(td) / "j.wav"
+            join_wavs(pieces, j) if len(pieces) > 1 else shutil.copy(pieces[0], j)
+            secs = wav_duration(j)
+            shutil.copy(j, f) if fmt == "wav" else encode(j, f)
+            if captions:
+                all_caps += remotion_captions(transcript_of(j, client), offset=t)
+        frames = int(-(-secs * fps // 1))  # ceil, so audio is never cut off
+        out.append({"id": sid, "file": str(f), "seconds": round(secs, 3), "durationInFrames": frames,
+                    "startFrame": int(round(t * fps)), "text": text})
+        t += frames / fps
+    manifest = {"fps": fps, "totalSeconds": round(t, 3), "totalFrames": sum(s["durationInFrames"] for s in out),
+                "scenes": out}
+    if captions:
+        cap = dest / "captions.json"
+        cap.write_text(json.dumps(all_caps, indent=1))
+        manifest["captions"] = str(cap)
+    (dest / "narration.json").write_text(json.dumps(manifest, indent=2))
+    manifest["manifest"] = str(dest / "narration.json")
+    return manifest
+
+
+def check_setup(client_factory=Client) -> dict:
+    report: dict = {"api_key": bool(os.environ.get("MIRAGEA_API_KEY")), "ffmpeg": has_ffmpeg(),
+                    "output_dir": str(output_dir()), "default_voice": os.environ.get("MIRAGEA_VOICE_ID") or
+                    ("reference clip" if os.environ.get("MIRAGEA_REF_URL") else None), "problems": []}
+    if not report["ffmpeg"]:
+        report["problems"].append("ffmpeg not found: audio is saved as WAV and video files are uploaded whole. "
+                                  "Install: brew install ffmpeg / sudo apt install ffmpeg / winget install ffmpeg.")
+    if not report["api_key"]:
+        report["problems"].append("MIRAGEA_API_KEY is not set. Create a key at https://miragea.ai and add it to this "
+                                  "server's env in your MCP client config.")
+        return report
+    try:
+        c = client_factory()
+        caps = c.capabilities()
+        report["models"] = [m.get("id") for m in caps.get("audio", {}).get("models", [])]
+        report["max_chars_per_request"] = caps.get("audio", {}).get("max_text_length")
+        report["caption_points_per_second"] = caps.get("subtitles", {}).get("points_per_second")
+        v = c.voices(limit=50)
+        report["saved_voices"] = len(v.get("items", []))
+        if not v.get("items") and not report["default_voice"]:
+            report["problems"].append("No saved voices in this Miragea account yet. Create one at https://miragea.ai, "
+                                      "or pass reference_audio_url (a public clip) when speaking.")
+    except MirageaError as exc:
+        report["problems"].append(str(exc))
+    report["ok"] = not report["problems"]
+    return report

miragea_mcp-0.1.0/src/miragea_mcp/server.py

@@ -0,0 +1,98 @@
+"""MCP server (stdio) exposing Miragea voice and captions to Claude, Cursor, Codex and other MCP clients."""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Optional, Union
+
+from . import __version__, core
+from .client import Client, MirageaError
+
+INSTRUCTIONS = (
+    "Voiceover, voice cloning and captions via the Miragea API. Start with check_setup if unsure. "
+    "Use list_voices to find the user's saved voices; speak for any text (long text is split and joined "
+    "automatically); transcribe for SRT/VTT captions of a local audio/video file; narrate_scenes for "
+    "per-scene audio with exact durations (Remotion/HyperFrames/video timelines). Files are written to "
+    "MIRAGEA_OUTPUT_DIR (default ~/Miragea) unless a path is given, and existing files are never overwritten. "
+    "Only clone voices the user owns or has permission to use."
+)
+
+
+def _safe(fn, *a, **kw) -> dict:
+    try:
+        return fn(*a, **kw)
+    except MirageaError as exc:  # return a readable error with the fix instead of a stack trace
+        return {"error": str(exc).split("\n")[0], "how_to_fix": exc.hint or None}
+    except Exception as exc:  # noqa: BLE001
+        return {"error": f"{type(exc).__name__}: {exc}", "how_to_fix": "Check the input paths and try again."}
+
+
+def build_server():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:  # MCP SDK 2.x
+        from mcp.server.mcpserver import MCPServer as FastMCP  # type: ignore
+    mcp = FastMCP("miragea", instructions=INSTRUCTIONS)
+
+    @mcp.tool()
+    def check_setup() -> dict:
+        """Check the API key, ffmpeg, saved voices and output folder, with a fix for every problem found."""
+        return _safe(core.check_setup)
+
+    @mcp.tool()
+    def list_voices(limit: int = 50, offset: int = 0) -> dict:
+        """List voices saved in the user's Miragea account (ids to pass as voice_id)."""
+        def run():
+            r = Client().voices(limit, offset)
+            return {"voices": [{"voice_id": v.get("actor_id") or v.get("id"), "name": v.get("name")}
+                               for v in r.get("items", [])], "has_more": r.get("has_more", False)}
+        return _safe(run)
+
+    @mcp.tool()
+    def speak(text: str, output_path: Optional[str] = None, voice_id: Optional[str] = None,
+              reference_audio_url: Optional[str] = None, reference_text: Optional[str] = None,
+              model: str = "expressive", speed: Optional[float] = None, format: str = "mp3") -> dict:
+        """Turn text of any length into speech in a saved voice (voice_id) or a voice cloned from a public
+        clip (reference_audio_url + its exact words in reference_text, billed at the cheaper 1x rate).
+        Returns the saved file path and its exact duration in seconds. format: mp3, wav, flac, opus, aac.
+        model: 'expressive' (default) or 'standard'. speed: 0.25-4."""
+        return _safe(core.speak, text, output_path, voice_id, reference_audio_url, reference_text, model, speed, format)
+
+    @mcp.tool()
+    def transcribe(path: str, style: str = "standard", output_dir: Optional[str] = None) -> dict:
+        """Transcribe a local audio or video file into readable SRT and VTT captions (whole words, line-length
+        and timing rules applied). style: 'standard' (2 lines x 42 chars) or 'shorts' (1-3 words, uppercase).
+        Results are cached, so asking again for the same file is free."""
+        return _safe(core.transcribe, path, style, output_dir)
+
+    @mcp.tool()
+    def narrate_scenes(scenes: list[Union[str, dict[str, Any]]], output_dir: Optional[str] = None, fps: int = 30,
+                       voice_id: Optional[str] = None, reference_audio_url: Optional[str] = None,
+                       reference_text: Optional[str] = None, model: str = "expressive",
+                       captions: bool = False) -> dict:
+        """Voice a list of scenes (strings or {id, text}) as one audio file per scene and return each scene's
+        exact seconds, durationInFrames and startFrame at the given fps, plus a narration.json manifest.
+        captions=true also writes word-level captions.json in Remotion's Caption format. Unchanged scenes are
+        cached and cost nothing on re-runs."""
+        return _safe(core.narrate_scenes, scenes, output_dir, fps, voice_id, reference_audio_url, reference_text,
+                     model, captions)
+
+    return mcp
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] in ("-V", "--version"):
+        print(f"miragea-mcp {__version__}")
+        return 0
+    if argv and argv[0] in ("--check", "check"):
+        print(json.dumps(core.check_setup(), indent=2))
+        return 0
+    if argv and argv[0] in ("-h", "--help"):
+        print("miragea-mcp: MCP server (stdio) for Miragea voiceover and captions.\n"
+              "  miragea-mcp            run the server (configure it in your MCP client)\n"
+              "  miragea-mcp --check    check key, ffmpeg and voices\n"
+              "Env: MIRAGEA_API_KEY (required), MIRAGEA_VOICE_ID, MIRAGEA_REF_URL, MIRAGEA_REF_TEXT, MIRAGEA_OUTPUT_DIR")
+        return 0
+    build_server().run()
+    return 0

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: miragea-mcp
+Version: 0.1.0
+Summary: MCP server for AI voiceover, voice cloning and captions: text of any length to speech with exact durations, SRT/VTT from local files, per-scene narration for Remotion. Works with Claude, Cursor, Codex.
+Author: HeadVox
+License: MIT
+Project-URL: Homepage, https://github.com/yyert123/miragea-mcp
+Project-URL: Repository, https://github.com/yyert123/miragea-mcp
+Project-URL: Demo, https://huggingface.co/spaces/headvox/miragea-mcp
+Project-URL: Voice engine, https://miragea.ai
+Keywords: mcp,mcp-server,model-context-protocol,text-to-speech,tts,voiceover,voice-cloning,captions,subtitles,srt,remotion,claude,cursor,elevenlabs-alternative,miragea
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2
+Dynamic: license-file
+
+# Miragea MCP: voiceover, voice cloning and captions for Claude, Cursor and Codex
+
+<!-- mcp-name: io.github.yyert123/miragea-mcp -->
+
+An MCP server that gives your AI agent a real voice toolkit: **text of any length to speech** in your saved
+or cloned voice, **exact durations** for every file, **readable SRT/VTT captions** from any local audio or
+video, and **per-scene narration** with `durationInFrames` and word-level captions for Remotion and other
+video timelines. Local stdio server, one line of config, no GPU. Voice and speech recognition by
+[Miragea](https://miragea.ai).
+
+```json
+{
+  "mcpServers": {
+    "miragea": {
+      "command": "uvx",
+      "args": ["miragea-mcp"],
+      "env": { "MIRAGEA_API_KEY": "your_key", "MIRAGEA_VOICE_ID": "optional_default_voice" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add miragea -e MIRAGEA_API_KEY=your_key -- uvx miragea-mcp`.
+No uv? `pip install miragea-mcp` and use `"command": "miragea-mcp"`. Check everything with
+`uvx miragea-mcp --check`.
+
+Then just ask:
+
+- *"Read this changelog aloud in my voice and save it as release-notes.mp3."*
+- *"Make captions for ~/Videos/talk.mp4."* / *"TikTok-style captions for clip.mov."*
+- *"Narrate these 5 scenes for my Remotion video and set each scene's durationInFrames."*
+
+## Tools
+
+| Tool | What it does | Returns |
+|---|---|---|
+| `check_setup` | Checks key, ffmpeg, saved voices, output folder; gives a fix for each problem | status + problems |
+| `list_voices` | Voices saved in your Miragea account | `voice_id`, `name` |
+| `speak` | Any length of text to speech (split at sentence ends under the 2,000-char API limit, joined back seamlessly). Saved voice, or clone from a public clip | file path, **exact seconds**, chunks |
+| `transcribe` | Local audio/video to SRT + VTT: whole words (no mid-word splits), 2 x 42-char lines, min/max cue time; `style="shorts"` for 1-3 word uppercase captions | srt/vtt paths, text, language |
+| `narrate_scenes` | One audio file per scene, `seconds`, `durationInFrames` (rounded up, never cut off), `startFrame`, a `narration.json` manifest; `captions=true` adds word-level `captions.json` in Remotion's `Caption` shape | manifest |
+
+## What it does for you automatically
+
+- **Long text**: chunked at sentence boundaries and stitched with a natural 120 ms pause. You never see
+  the 2,000-character limit.
+- **Durations**: measured from the audio itself, so video timelines line up to the frame.
+- **Captions**: speech-recognition segments are rebuilt into whole words and re-flowed with broadcast rules.
+- **Uploads**: video files are reduced to a 16 kHz mono track before upload (fast, small).
+- **Caching**: the same text, voice and model is never billed twice; the same file is never transcribed twice.
+- **Safety**: existing files are never overwritten (`name-2.mp3`), the key is only read from the environment
+  and never logged, failed audio tasks are refunded by Miragea, and network retries reuse the same
+  idempotency key so a retry cannot double-charge.
+- **Clear errors**: every error comes back as `{"error", "how_to_fix"}` for the agent to act on.
+
+## Compared with other voice MCP servers
+
+| | **miragea-mcp** | ElevenLabs MCP | Thin TTS wrappers (Edge, Kokoro, Azure...) |
+|---|---|---|---|
+| Local stdio server, maintained | Yes | Local server deprecated; hosted OAuth server instead | Varies |
+| Reads/writes files anywhere you point it | Yes (default `~/Miragea`) | Local version restricted inputs to one base folder | Usually output folder only |
+| Returns exact audio duration | Yes, every call | No (callers had to measure it) | Rarely |
+| Text longer than one API request | Automatic split and join | Manual | Varies |
+| Captions (SRT/VTT) from local files | Yes, reflowed whole words | Separate speech-to-text tool | No |
+| Scene durations in frames + Remotion captions | Yes (`narrate_scenes`) | No | No |
+| Your own cloned voice | Saved voice id or reference clip | Yes (paid plans) | Stock voices only |
+| Billing | Pay-as-you-go Miragea points | Subscription credits | Free / cloud account |
+
+Sources: ElevenLabs MCP [README](https://github.com/elevenlabs/elevenlabs-mcp) (deprecation notice) and the
+[remotion-superpowers changelog](https://github.com/DojoCodingLabs/remotion-superpowers/blob/main/CHANGELOG.md)
+(base-folder restriction, no duration returned).
+
+## Configuration
+
+| Env var | Required | Meaning |
+|---|---|---|
+| `MIRAGEA_API_KEY` | yes | Your key from [miragea.ai](https://miragea.ai) |
+| `MIRAGEA_VOICE_ID` | no | Default saved voice, so the agent never has to ask |
+| `MIRAGEA_REF_URL`, `MIRAGEA_REF_TEXT` | no | Default reference clip (public URL) and its exact words |
+| `MIRAGEA_OUTPUT_DIR` | no | Where files go when no path is given (default `~/Miragea`) |
+
+Requirements: Python 3.10+. ffmpeg is optional (without it audio is saved as WAV and videos are uploaded whole).
+
+## FAQ
+
+**Which MCP clients work?** Any stdio MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code
+(Copilot agent mode), Codex CLI, Gemini CLI, Cline, Zed.
+
+**How do I use my own voice?** Save your voice once in your Miragea account and set `MIRAGEA_VOICE_ID`, or
+pass `reference_audio_url` (a public link to a clean 5-20 s clip) with `reference_text` (its exact words,
+which uses the cheaper 1x rate). A direct upload of local reference clips is planned by Miragea; until then
+the reference must be a public URL.
+
+**What does it cost?** Speech is billed per character, captions at 3 points per audio second (live rates:
+`GET https://miragea.ai/v1/capabilities`). Cached repeats are free.
+
+**Is my key safe?** It is read from the server's environment only, never written to disk, logged or returned.
+
+**Can I clone anyone's voice?** No. Only clone your own voice or one you have permission to use.
+
+**Where are files saved?** Where you ask, or in `MIRAGEA_OUTPUT_DIR` (default `~/Miragea`). The cache lives in
+`~/Miragea/.cache` and can be deleted at any time.
+
+## Related
+
+- [miragea-skills](https://github.com/yyert123/miragea-skills): Agent Skills for screen-recording voiceover, Shorts, captions and Remotion narration.
+- [Retake](https://github.com/yyert123/retake): fix a flubbed voiceover line in your own voice (CLI + MCP).
+- [HeadVox](https://github.com/yyert123/headvox): script to voiceover with word-aligned captions.
+
+MIT License.

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/miragea_mcp/__init__.py
+src/miragea_mcp/__main__.py
+src/miragea_mcp/captions.py
+src/miragea_mcp/client.py
+src/miragea_mcp/core.py
+src/miragea_mcp/server.py
+src/miragea_mcp.egg-info/PKG-INFO
+src/miragea_mcp.egg-info/SOURCES.txt
+src/miragea_mcp.egg-info/dependency_links.txt
+src/miragea_mcp.egg-info/entry_points.txt
+src/miragea_mcp.egg-info/requires.txt
+src/miragea_mcp.egg-info/top_level.txt
+tests/test_core.py

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+miragea-mcp = miragea_mcp.server:main

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp>=1.2

miragea_mcp-0.1.0/src/miragea_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+miragea_mcp

miragea_mcp-0.1.0/tests/test_core.py

@@ -0,0 +1,108 @@
+"""Offline tests: a fake Miragea client writes real WAV files, so the whole pipeline runs without a key."""
+import json
+import wave
+from pathlib import Path
+
+import pytest
+
+from miragea_mcp import core
+from miragea_mcp.client import MirageaError
+
+
+class FakeClient:
+    def __init__(self):
+        self.calls = []
+
+    def speak(self, text, out_path, **kw):
+        self.calls.append((text, kw))
+        n = int(16000 * (0.05 * len(text.split())))  # 50 ms per word
+        with wave.open(str(out_path), "wb") as w:
+            w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000)
+            w.writeframes(b"\x01\x00" * n)
+        return Path(out_path)
+
+    def transcribe(self, path):
+        return {"text": "Hello world.", "language": "English",
+                "segments": [{"start": 0.0, "end": 1.0, "text": "Hello wor"}, {"start": 1.0, "end": 1.5, "text": "ld."}]}
+
+
+@pytest.fixture(autouse=True)
+def env(tmp_path, monkeypatch):
+    monkeypatch.setenv("MIRAGEA_OUTPUT_DIR", str(tmp_path / "out"))
+    monkeypatch.setenv("MIRAGEA_API_KEY", "test")
+    for k in ("MIRAGEA_VOICE_ID", "MIRAGEA_REF_URL", "MIRAGEA_REF_TEXT"):
+        monkeypatch.delenv(k, raising=False)
+    monkeypatch.setattr(core, "has_ffmpeg", lambda: False)  # pure-Python path
+    return tmp_path
+
+
+def test_chunking_respects_limit_and_keeps_all_text():
+    text = " ".join(["A normal sentence, with a comma, for testing."] * 120)
+    parts = core.chunk_text(text)
+    assert len(parts) > 1 and all(len(p) <= core.MAX_CHARS for p in parts)
+    assert " ".join(parts) == text
+    giant = "word " * 1000  # no sentence end at all
+    assert all(len(p) <= core.MAX_CHARS for p in core.chunk_text(giant))
+
+
+def test_speak_long_text_joins_chunks_and_reports_exact_duration():
+    fc = FakeClient()
+    text = " ".join(["This is sentence number one of many."] * 80)
+    r = core.speak(text, voice_id="v1", client=fc)
+    assert r["chunks"] == len(fc.calls) > 1
+    assert r["path"].endswith(".wav") and "note" in r  # no ffmpeg -> WAV with an explanation
+    words = len(text.split())
+    assert abs(r["seconds"] - (words * 0.05 + 0.12 * (r["chunks"] - 1))) < 0.02
+
+
+def test_speak_never_overwrites_and_caches():
+    fc = FakeClient()
+    a = core.speak("Hello there.", voice_id="v1", format="wav", client=fc)
+    b = core.speak("Hello there.", voice_id="v1", format="wav", client=fc)
+    assert a["path"] != b["path"] and len(fc.calls) == 1  # second call served from cache, new file name
+
+
+def test_voice_resolution_and_errors(monkeypatch):
+    with pytest.raises(MirageaError, match="No voice"):
+        core.speak("Hi.", client=FakeClient())
+    monkeypatch.setenv("MIRAGEA_VOICE_ID", "env-voice")
+    assert core.voice_from(None, None, None) == {"actor_id": "env-voice"}
+    assert core.voice_from(None, "https://x/y.wav", "words")["reference_audio_url"] == "https://x/y.wav"
+    with pytest.raises(MirageaError, match="Unsupported format"):
+        core.speak("Hi.", format="midi", client=FakeClient())
+
+
+def test_narrate_scenes_frames_and_captions(tmp_path):
+    fc = FakeClient()
+    m = core.narrate_scenes(["One two three four.", {"id": "Outro!", "text": "Bye now."}], str(tmp_path / "n"),
+                            fps=30, voice_id="v", captions=True, client=fc)
+    s1, s2 = m["scenes"]
+    assert s1["durationInFrames"] == 6 and s2["startFrame"] == 6 and s2["id"] == "outro"
+    assert m["totalFrames"] == s1["durationInFrames"] + s2["durationInFrames"]
+    caps = json.loads(Path(m["captions"]).read_text())
+    assert caps[0]["text"] == "Hello" and caps[1]["text"] == " world."  # whole words even when segments split
+    assert caps[2]["startMs"] >= s2["startFrame"] / 30 * 1000 - 1  # second scene offset applied
+
+
+def test_transcribe_writes_srt_vtt(tmp_path):
+    f = tmp_path / "a.wav"
+    FakeClient().speak("x y", f)
+    r = core.transcribe(str(f), client=FakeClient())
+    assert Path(r["srt"]).read_text().startswith("1\n00:00:00,000")
+    assert Path(r["vtt"]).read_text().startswith("WEBVTT")
+    with pytest.raises(MirageaError, match="not found"):
+        core.transcribe(str(tmp_path / "missing.mp4"), client=FakeClient())
+
+
+def test_check_setup_without_key(monkeypatch):
+    monkeypatch.delenv("MIRAGEA_API_KEY")
+    r = core.check_setup()
+    assert r["api_key"] is False and any("MIRAGEA_API_KEY" in p for p in r["problems"])
+
+
+def test_server_registers_tools():
+    from miragea_mcp.server import build_server
+    srv = build_server()
+    import asyncio
+    names = {t.name for t in asyncio.run(srv.list_tools())}
+    assert names == {"check_setup", "list_voices", "speak", "transcribe", "narrate_scenes"}