@cliptude/cli 0.1.21 → 0.1.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -2
- package/cliptude_mcp/apps.py +311 -0
- package/cliptude_mcp/cli.py +103 -21
- package/cliptude_mcp/client.py +288 -66
- package/cliptude_mcp/creation.py +207 -0
- package/cliptude_mcp/credentials.py +31 -5
- package/cliptude_mcp/server.py +284 -76
- package/cliptude_mcp/widgets/avatars.html +287 -0
- package/cliptude_mcp/widgets/base.css +123 -0
- package/cliptude_mcp/widgets/bridge.js +314 -0
- package/cliptude_mcp/widgets/characters.html +108 -0
- package/cliptude_mcp/widgets/choices.html +230 -0
- package/cliptude_mcp/widgets/player.html +126 -0
- package/cliptude_mcp/widgets/publish-kit.html +170 -0
- package/cliptude_mcp/widgets/voices.html +436 -0
- package/package.json +1 -1
- package/pyproject.toml +4 -4
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
"""MCP tools that make the user's own avatar and voices: create_avatar, design_voice_previews, save_designed_voice,
|
|
2
|
+
clone_voice. The avatar and voice picker widgets call them with `tools/call`; the model can call them too.
|
|
3
|
+
|
|
4
|
+
Files travel as base64 in the tool call (the widget reads the file the user picked, or a recording), never as a
|
|
5
|
+
path on the hosted server: a local path is accepted only by the stdio server, which runs on the user's computer.
|
|
6
|
+
The server-side rules are the website's (videos/creation_api.py): paid plans, the 55-credit avatar goes through a
|
|
7
|
+
428 price review first, clones need the same consent as the Clone a voice page, every voice and avatar is private.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import base64
|
|
13
|
+
import binascii
|
|
14
|
+
import json
|
|
15
|
+
import mimetypes
|
|
16
|
+
from collections.abc import Callable
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Annotated, Any
|
|
19
|
+
|
|
20
|
+
import httpx
|
|
21
|
+
from mcp.types import CallToolResult, TextContent, ToolAnnotations
|
|
22
|
+
from pydantic import Field
|
|
23
|
+
|
|
24
|
+
from cliptude_mcp.client import CliptudeApiError
|
|
25
|
+
|
|
26
|
+
MAX_UPLOAD_BYTES = 10 * 1024 * 1024
|
|
27
|
+
CLONE_CONSENT_TEXT = (
|
|
28
|
+
"I confirm this is my own voice, or I have the voice owner's explicit consent and the rights to clone it. "
|
|
29
|
+
"I will not use cloned voices to impersonate or deceive others, as required by the Terms of Service."
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _file_arg(
|
|
34
|
+
*, data_base64: str | None, file_name: str | None, path: str | None, local: bool, what: str
|
|
35
|
+
) -> tuple[str, bytes, str] | None:
|
|
36
|
+
"""(name, bytes, mime) from base64 or (stdio only) a local path; None when neither was given."""
|
|
37
|
+
if path:
|
|
38
|
+
if not local:
|
|
39
|
+
raise CliptudeApiError(f"This server cannot read files on your computer: send the {what} as base64.")
|
|
40
|
+
p = Path(path).expanduser()
|
|
41
|
+
if not p.is_file():
|
|
42
|
+
raise CliptudeApiError(f"{what.capitalize()} not found: {p}")
|
|
43
|
+
raw = p.read_bytes()
|
|
44
|
+
name = p.name
|
|
45
|
+
elif data_base64:
|
|
46
|
+
text = data_base64.split(",", 1)[1] if data_base64.startswith("data:") else data_base64
|
|
47
|
+
try:
|
|
48
|
+
raw = base64.b64decode(text, validate=False)
|
|
49
|
+
except (binascii.Error, ValueError) as exc:
|
|
50
|
+
raise CliptudeApiError(f"The {what} is not valid base64.") from exc
|
|
51
|
+
name = (file_name or "").strip() or what.replace(" ", "_")
|
|
52
|
+
else:
|
|
53
|
+
return None
|
|
54
|
+
if len(raw) > MAX_UPLOAD_BYTES:
|
|
55
|
+
raise CliptudeApiError(f"The {what} is over {MAX_UPLOAD_BYTES // (1024 * 1024)} MB.")
|
|
56
|
+
if not raw:
|
|
57
|
+
raise CliptudeApiError(f"The {what} is empty.")
|
|
58
|
+
mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
|
|
59
|
+
return name, raw, mime
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
CLONE_PROVIDERS = frozenset({"elevenlabs", "minimax", "cartesia", "inworld", "voicetory"})
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _path_refused(local: bool, name: str, value: Any) -> dict[str, Any] | None:
|
|
66
|
+
"""A hosted server never reads its own disk for a caller (same code as the server's other tools)."""
|
|
67
|
+
if local or value is None or not str(value).strip():
|
|
68
|
+
return None
|
|
69
|
+
from cliptude_mcp.server import LOCAL_FILES_REFUSED
|
|
70
|
+
|
|
71
|
+
return {"error": LOCAL_FILES_REFUSED.format(param=name), "code": "local_path_not_allowed"}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def post_form(client: Any, path: str, data: dict[str, Any], files: dict[str, tuple[str, bytes, str]] | None = None,
|
|
75
|
+
*, _retried: bool = False) -> Any:
|
|
76
|
+
"""Multipart/form POST to the Cliptude API with the client's auth (client.request only sends JSON)."""
|
|
77
|
+
try:
|
|
78
|
+
resp = httpx.post(
|
|
79
|
+
f"{client.base_url}{path}",
|
|
80
|
+
headers=client._headers(json_content=False),
|
|
81
|
+
data={k: v for k, v in data.items() if v not in (None, "")},
|
|
82
|
+
files=files or None,
|
|
83
|
+
timeout=max(float(client.timeout or 0), 180.0),
|
|
84
|
+
)
|
|
85
|
+
except httpx.HTTPError as exc:
|
|
86
|
+
raise CliptudeApiError(str(exc)) from exc
|
|
87
|
+
if resp.status_code == 401 and not _retried and client._maybe_refresh():
|
|
88
|
+
return post_form(client, path, data, files, _retried=True)
|
|
89
|
+
try:
|
|
90
|
+
payload = resp.json()
|
|
91
|
+
except ValueError:
|
|
92
|
+
payload = {"error": resp.text}
|
|
93
|
+
if resp.status_code >= 400:
|
|
94
|
+
client._raise_http(resp, payload=payload)
|
|
95
|
+
return payload
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def register_creation_tools(
|
|
99
|
+
mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]], *, local: bool
|
|
100
|
+
) -> None:
|
|
101
|
+
@mcp.tool(
|
|
102
|
+
title="Create avatar",
|
|
103
|
+
annotations=ToolAnnotations(title="Create avatar", read_only_hint=False, destructive_hint=False,
|
|
104
|
+
open_world_hint=True),
|
|
105
|
+
)
|
|
106
|
+
def create_avatar(
|
|
107
|
+
display_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the new avatar")],
|
|
108
|
+
gender: Annotated[str | None, Field(description='"male" or "female" (needed for a description; a photo is detected)')] = None,
|
|
109
|
+
appearance: Annotated[str | None, Field(description="Describe the presenter, when there is no photo")] = None,
|
|
110
|
+
photo_base64: Annotated[str | None, Field(description="A landscape 16:9 JPG/PNG/WEBP photo, base64 (max 10 MB)")] = None,
|
|
111
|
+
photo_file_name: Annotated[str | None, Field(description="The photo's file name, e.g. me.jpg")] = None,
|
|
112
|
+
photo_path: Annotated[str | None, Field(description="Local photo path (only when Cliptude runs on this computer)")] = None,
|
|
113
|
+
review_token: Annotated[str | None, Field(description="From the 428 review, after the user approved the price")] = None,
|
|
114
|
+
) -> dict[str, Any]:
|
|
115
|
+
"""Create the user's own private photo avatar for Avatar Video, from a 16:9 photo of them (or someone who agreed) or a description. It costs 55 credits: the first call returns a review (status 428, detail.review with the price) and creates nothing; show it to the user and call again with the same arguments and review_token once they approve. HeyGen finishes it in a few minutes; list_avatars(section="mine") shows it then."""
|
|
116
|
+
refused = _path_refused(local, "photo_path", photo_path)
|
|
117
|
+
if refused:
|
|
118
|
+
return refused
|
|
119
|
+
try:
|
|
120
|
+
photo = _file_arg(data_base64=photo_base64, file_name=photo_file_name, path=photo_path, local=local,
|
|
121
|
+
what="photo")
|
|
122
|
+
data = {"display_name": display_name, "gender": gender, "appearance": appearance,
|
|
123
|
+
"review_token": review_token}
|
|
124
|
+
return post_form(client(), "/api/v1/avatars/new", data,
|
|
125
|
+
{"photo_file": photo} if photo else None)
|
|
126
|
+
except Exception as exc:
|
|
127
|
+
return err(exc)
|
|
128
|
+
|
|
129
|
+
@mcp.tool(
|
|
130
|
+
title="Design voice previews",
|
|
131
|
+
annotations=ToolAnnotations(title="Design voice previews", read_only_hint=False, destructive_hint=False,
|
|
132
|
+
open_world_hint=True),
|
|
133
|
+
)
|
|
134
|
+
def design_voice_previews(
|
|
135
|
+
provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
|
|
136
|
+
description: Annotated[str, Field(min_length=10, max_length=1000, description="The voice to design: age, gender, accent, tone, pace")],
|
|
137
|
+
language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
|
|
138
|
+
) -> CallToolResult:
|
|
139
|
+
"""Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. The audio goes to the voice picker widget only; the text result lists the preview ids."""
|
|
140
|
+
try:
|
|
141
|
+
payload = post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}/previews",
|
|
142
|
+
{"description": description, "language": language})
|
|
143
|
+
except Exception as exc:
|
|
144
|
+
failure = err(exc)
|
|
145
|
+
return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
|
|
146
|
+
structured_content=failure)
|
|
147
|
+
previews = payload.get("previews") or [] if isinstance(payload, dict) else []
|
|
148
|
+
summary = {
|
|
149
|
+
"provider": provider,
|
|
150
|
+
"previews": [{"preview_id": p.get("preview_id")} for p in previews],
|
|
151
|
+
"rounds_left_today": payload.get("rounds_left_today") if isinstance(payload, dict) else None,
|
|
152
|
+
"next": "Let the user listen in the voice picker (or describe the previews), then save_designed_voice "
|
|
153
|
+
"with the preview_id they pick and a voice_name.",
|
|
154
|
+
}
|
|
155
|
+
return CallToolResult(
|
|
156
|
+
content=[TextContent(type="text", text=json.dumps(summary))],
|
|
157
|
+
structured_content={"provider": provider, **(payload if isinstance(payload, dict) else {})},
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
@mcp.tool(
|
|
161
|
+
title="Save designed voice",
|
|
162
|
+
annotations=ToolAnnotations(title="Save designed voice", read_only_hint=False, destructive_hint=False,
|
|
163
|
+
open_world_hint=True),
|
|
164
|
+
)
|
|
165
|
+
def save_designed_voice(
|
|
166
|
+
provider: Annotated[str, Field(description="Same provider as the previews")],
|
|
167
|
+
preview_id: Annotated[str, Field(min_length=1, description="The preview the user picked")],
|
|
168
|
+
voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the voice")],
|
|
169
|
+
) -> dict[str, Any]:
|
|
170
|
+
"""Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices and can be used as voice_id (with voice_provider) in create_template."""
|
|
171
|
+
try:
|
|
172
|
+
return post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}",
|
|
173
|
+
{"preview_id": preview_id, "voice_name": voice_name})
|
|
174
|
+
except Exception as exc:
|
|
175
|
+
return err(exc)
|
|
176
|
+
|
|
177
|
+
@mcp.tool(
|
|
178
|
+
title="Clone voice",
|
|
179
|
+
annotations=ToolAnnotations(title="Clone voice", read_only_hint=False, destructive_hint=False,
|
|
180
|
+
open_world_hint=True),
|
|
181
|
+
)
|
|
182
|
+
def clone_voice(
|
|
183
|
+
provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")],
|
|
184
|
+
voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the clone")],
|
|
185
|
+
consent: Annotated[bool, Field(description="True only after the user confirmed: " + CLONE_CONSENT_TEXT)],
|
|
186
|
+
audio_base64: Annotated[str | None, Field(description="30 s to 3 min of clear speech (MP3, M4A or WAV), base64, max 10 MB")] = None,
|
|
187
|
+
audio_file_name: Annotated[str | None, Field(description="The recording's file name, e.g. me.mp3")] = None,
|
|
188
|
+
audio_path: Annotated[str | None, Field(description="Local recording path (only when Cliptude runs on this computer)")] = None,
|
|
189
|
+
) -> dict[str, Any]:
|
|
190
|
+
"""Clone the user's own voice from a recording, private to their account; it then appears in list_voices under my_voices. Paid plans. Ask the user to confirm the consent statement first and pass consent=true only after they do."""
|
|
191
|
+
refused = _path_refused(local, "audio_path", audio_path)
|
|
192
|
+
if refused:
|
|
193
|
+
return refused
|
|
194
|
+
provider = (provider or "").strip().lower()
|
|
195
|
+
if provider not in CLONE_PROVIDERS:
|
|
196
|
+
return {"error": f"provider must be one of: {', '.join(sorted(CLONE_PROVIDERS))}."}
|
|
197
|
+
if not consent:
|
|
198
|
+
return {"error": "The user must confirm: " + CLONE_CONSENT_TEXT}
|
|
199
|
+
try:
|
|
200
|
+
audio = _file_arg(data_base64=audio_base64, file_name=audio_file_name, path=audio_path, local=local,
|
|
201
|
+
what="recording")
|
|
202
|
+
if audio is None:
|
|
203
|
+
return {"error": "Send the recording as audio_base64."}
|
|
204
|
+
return post_form(client(), f"/api/v1/voice-clones/{provider}",
|
|
205
|
+
{"voice_name": voice_name, "voice_consent": "true"}, {"clone_audio": audio})
|
|
206
|
+
except Exception as exc:
|
|
207
|
+
return err(exc)
|
|
@@ -4,6 +4,7 @@ from __future__ import annotations
|
|
|
4
4
|
|
|
5
5
|
import json
|
|
6
6
|
import os
|
|
7
|
+
import secrets
|
|
7
8
|
from pathlib import Path
|
|
8
9
|
from typing import Any
|
|
9
10
|
|
|
@@ -27,13 +28,38 @@ def load_credentials() -> dict[str, Any] | None:
|
|
|
27
28
|
|
|
28
29
|
|
|
29
30
|
def save_credentials(data: dict[str, Any]) -> Path:
|
|
31
|
+
"""Write the login atomically, owner-only (0600) from the moment the file exists (folder 0700)."""
|
|
30
32
|
path = credentials_path()
|
|
31
|
-
path.parent
|
|
32
|
-
|
|
33
|
+
folder = path.parent
|
|
34
|
+
if not folder.exists():
|
|
35
|
+
folder.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
36
|
+
try:
|
|
37
|
+
os.chmod(folder, 0o700) # mkdir's mode is masked by the umask
|
|
38
|
+
except OSError:
|
|
39
|
+
pass
|
|
40
|
+
payload = (json.dumps(data, indent=2) + "\n").encode("utf-8")
|
|
41
|
+
tmp = folder / f".{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp"
|
|
42
|
+
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
|
|
43
|
+
fd = os.open(tmp, flags, 0o600)
|
|
33
44
|
try:
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
45
|
+
try:
|
|
46
|
+
os.fchmod(fd, 0o600) # in case the umask kept bits back; never wider than 0600
|
|
47
|
+
except (AttributeError, OSError):
|
|
48
|
+
pass
|
|
49
|
+
with os.fdopen(fd, "wb") as fh:
|
|
50
|
+
fd = -1
|
|
51
|
+
fh.write(payload)
|
|
52
|
+
fh.flush()
|
|
53
|
+
os.fsync(fh.fileno())
|
|
54
|
+
os.replace(tmp, path)
|
|
55
|
+
except BaseException:
|
|
56
|
+
if fd >= 0:
|
|
57
|
+
os.close(fd)
|
|
58
|
+
try:
|
|
59
|
+
tmp.unlink()
|
|
60
|
+
except OSError:
|
|
61
|
+
pass
|
|
62
|
+
raise
|
|
37
63
|
return path
|
|
38
64
|
|
|
39
65
|
|