@cliptude/cli 0.1.19 → 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.
@@ -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.mkdir(parents=True, exist_ok=True)
32
- path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
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
- os.chmod(path, 0o600)
35
- except OSError:
36
- pass
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