@cliptude/cli 0.1.21 → 0.1.32
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 +444 -0
- package/cliptude_mcp/cli.py +166 -23
- package/cliptude_mcp/client.py +297 -66
- package/cliptude_mcp/creation.py +207 -0
- package/cliptude_mcp/credentials.py +31 -5
- package/cliptude_mcp/picks.py +226 -0
- package/cliptude_mcp/server.py +323 -77
- package/cliptude_mcp/widgets/avatars.html +287 -0
- package/cliptude_mcp/widgets/base.css +173 -0
- package/cliptude_mcp/widgets/bridge.js +378 -0
- package/cliptude_mcp/widgets/characters.html +108 -0
- package/cliptude_mcp/widgets/choices.html +230 -0
- package/cliptude_mcp/widgets/job.html +32 -0
- package/cliptude_mcp/widgets/player.html +126 -0
- package/cliptude_mcp/widgets/publish-kit.html +41 -0
- package/cliptude_mcp/widgets/review.html +31 -0
- package/cliptude_mcp/widgets/template.html +152 -0
- package/cliptude_mcp/widgets/templates.html +93 -0
- package/cliptude_mcp/widgets/views.js +547 -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
|
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
"""Browser fallback for the widgets, for MCP clients that cannot show MCP Apps.
|
|
2
|
+
|
|
3
|
+
Claude Code and Codex in a terminal, Cursor and other clients without MCP Apps cannot draw the avatar, voice,
|
|
4
|
+
music or review widgets. For them the widget-bound tools add `browser_picker_url` and `pick_id` to their
|
|
5
|
+
result: a cliptude.com/pick/... link (signed, 15 minutes, only for the signed-in owner) that opens the same
|
|
6
|
+
widget in the user's browser. Their pick, or their click on Confirm in a review, is stored on Cliptude;
|
|
7
|
+
`get_pick(pick_id)` reads it. The server builds what the page shows (POST /api/v1/picks with where to read it
|
|
8
|
+
from, never the content), and a review is only approved there: the agent then resends the call with the
|
|
9
|
+
review_token from get_pick. Clients that negotiated MCP Apps get exactly the old results.
|
|
10
|
+
|
|
11
|
+
How support is detected: the client's `initialize` capabilities (or the per-request capabilities on
|
|
12
|
+
2026-07-28) carry `extensions["io.modelcontextprotocol/ui"]` with the `text/html;profile=mcp-app` MIME type
|
|
13
|
+
(`mcp.server.apps.client_supports_apps`). The SDK parses `initialize` with the latest schema, so a client on
|
|
14
|
+
protocol 2025-11-25 that sends `capabilities.extensions` is seen too, although the server cannot advertise the
|
|
15
|
+
extension back at that version. Hosts that put it under `experimental`, and the hosts known to render widgets
|
|
16
|
+
(claude.ai / Claude Desktop, ChatGPT) by client name, count as supporting it as well.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import functools
|
|
22
|
+
import os
|
|
23
|
+
from collections.abc import Callable
|
|
24
|
+
from typing import Annotated, Any
|
|
25
|
+
|
|
26
|
+
from pydantic import Field
|
|
27
|
+
|
|
28
|
+
EXTENSION_ID = "io.modelcontextprotocol/ui"
|
|
29
|
+
APP_MIME_TYPE = "text/html;profile=mcp-app"
|
|
30
|
+
# Client names (initialize clientInfo.name) of hosts that render MCP Apps widgets even if they do not say so.
|
|
31
|
+
WIDGET_HOST_CLIENTS = frozenset({"claude-ai", "openai-mcp", "chatgpt"})
|
|
32
|
+
CTX_KWARG = "_cliptude_ctx"
|
|
33
|
+
|
|
34
|
+
PICKER_NOTE = (
|
|
35
|
+
"This client shows no widgets, so the choice opens in the user's browser: give the user browser_picker_url "
|
|
36
|
+
"(in a terminal agent, offer to open it), wait until they say they are done, then call get_pick with "
|
|
37
|
+
"pick_id. Only status \"done\" carries their pick; a review counts as approved only when get_pick shows "
|
|
38
|
+
"confirmed: true (or the user says OK in this chat). The link works for 15 minutes, once, for the signed-in "
|
|
39
|
+
"owner only."
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
# Tools whose results get a browser picker, and the pick kind.
|
|
43
|
+
LIST_KINDS: dict[str, str] = {
|
|
44
|
+
"list_avatars": "avatars",
|
|
45
|
+
"list_voices": "voices",
|
|
46
|
+
"list_vector_characters": "characters",
|
|
47
|
+
"show_choices": "choices",
|
|
48
|
+
"list_templates": "templates",
|
|
49
|
+
"get_template": "template",
|
|
50
|
+
"create_template": "template",
|
|
51
|
+
"get_job": "job",
|
|
52
|
+
"get_product_video_status": "job",
|
|
53
|
+
"get_render": "video",
|
|
54
|
+
"show_video": "video",
|
|
55
|
+
"show_publish_kit": "publish_kit",
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def enabled() -> bool:
|
|
60
|
+
"""CLIPTUDE_BROWSER_PICKER=0 turns the fallback off (an operator switch, and the tests' default)."""
|
|
61
|
+
return (os.environ.get("CLIPTUDE_BROWSER_PICKER") or "1").strip().lower() not in ("0", "false", "no", "off")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def client_renders_apps(ctx: Any) -> bool:
|
|
65
|
+
"""Whether the connected client shows MCP Apps widgets. Unknown (no context) counts as yes: no fallback."""
|
|
66
|
+
if ctx is None:
|
|
67
|
+
return True
|
|
68
|
+
try:
|
|
69
|
+
from mcp.server.apps import client_supports_apps
|
|
70
|
+
except ImportError: # pragma: no cover - an SDK without Apps serves no widgets at all
|
|
71
|
+
client_supports_apps = None
|
|
72
|
+
try:
|
|
73
|
+
if client_supports_apps is not None and client_supports_apps(ctx):
|
|
74
|
+
return True
|
|
75
|
+
capabilities = ctx.client_capabilities
|
|
76
|
+
except Exception:
|
|
77
|
+
return True
|
|
78
|
+
experimental = getattr(capabilities, "experimental", None) or {}
|
|
79
|
+
if isinstance(experimental, dict) and EXTENSION_ID in experimental:
|
|
80
|
+
return True
|
|
81
|
+
try:
|
|
82
|
+
params = ctx.request_context.session.client_params
|
|
83
|
+
name = str(getattr(getattr(params, "client_info", None), "name", "") or "").strip().lower()
|
|
84
|
+
except Exception:
|
|
85
|
+
name = ""
|
|
86
|
+
return name in WIDGET_HOST_CLIENTS
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _review_arguments(args: dict[str, Any]) -> dict[str, Any]:
|
|
90
|
+
"""The reviewed call's arguments, for the pick to hand back; file contents stay with the agent."""
|
|
91
|
+
out = {}
|
|
92
|
+
for key, value in args.items():
|
|
93
|
+
if key in ("review_token", "acknowledge") or value is None:
|
|
94
|
+
continue
|
|
95
|
+
if key.endswith("_base64"):
|
|
96
|
+
out[key] = "<the same file as before>"
|
|
97
|
+
continue
|
|
98
|
+
out[key] = value
|
|
99
|
+
return out
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _is_script(data: dict[str, Any]) -> bool:
|
|
103
|
+
"""views.js isScript: a written script waiting for the user's approval."""
|
|
104
|
+
if not isinstance(data.get("script"), str) or not data["script"].strip():
|
|
105
|
+
return False
|
|
106
|
+
if data.get("stage"):
|
|
107
|
+
return data["stage"] == "script_ready"
|
|
108
|
+
return data.get("output_kind") == "script" and data.get("status") == "completed"
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def _is_ready(data: dict[str, Any]) -> bool:
|
|
112
|
+
stage = data.get("stage") or ""
|
|
113
|
+
if stage:
|
|
114
|
+
return stage in ("ready_for_review", "rendered")
|
|
115
|
+
kind = data.get("output_kind") or "video"
|
|
116
|
+
return data.get("status") in ("ready_for_edit", "completed") and kind in ("video", "plan")
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def pick_source(name: str, args: dict[str, Any], result: Any) -> tuple[str, dict[str, Any]] | None:
|
|
120
|
+
"""(kind, payload_source) of the browser picker for one tool result, or None when there is nothing to pick."""
|
|
121
|
+
from cliptude_mcp.apps import REVIEW_TOOLS
|
|
122
|
+
|
|
123
|
+
if not isinstance(result, dict):
|
|
124
|
+
return None
|
|
125
|
+
if name in REVIEW_TOOLS:
|
|
126
|
+
detail = result.get("detail") if isinstance(result.get("detail"), dict) else {}
|
|
127
|
+
if result.get("status") == 428 and detail.get("review") and detail.get("review_token"):
|
|
128
|
+
return "review", {"tool": name, "arguments": _review_arguments(args),
|
|
129
|
+
"review_token": detail["review_token"]}
|
|
130
|
+
return None
|
|
131
|
+
if result.get("error"):
|
|
132
|
+
return None
|
|
133
|
+
kind = LIST_KINDS.get(name)
|
|
134
|
+
if kind is None:
|
|
135
|
+
return None
|
|
136
|
+
if name == "list_avatars":
|
|
137
|
+
return kind, {k: args.get(k) for k in ("section", "search", "gender", "limit", "offset") if args.get(k) is not None}
|
|
138
|
+
if name == "list_voices":
|
|
139
|
+
return kind, {k: args.get(k) for k in ("provider", "language") if args.get(k)}
|
|
140
|
+
if name == "show_choices":
|
|
141
|
+
return kind, {"format": args.get("format"), "field": args.get("field")}
|
|
142
|
+
if name == "get_template":
|
|
143
|
+
return kind, {"template_id": args.get("template_id")}
|
|
144
|
+
if name == "create_template":
|
|
145
|
+
template_id = result.get("id") or (result.get("template") or {}).get("id")
|
|
146
|
+
return (kind, {"template_id": template_id}) if template_id else None
|
|
147
|
+
if name in ("get_job", "get_product_video_status"):
|
|
148
|
+
source = {"job_id": args.get("job_id"), "product": name == "get_product_video_status"}
|
|
149
|
+
if _is_script(result):
|
|
150
|
+
return "script", source
|
|
151
|
+
return (kind, source) if _is_ready(result) else None # progress alone: nothing to pick
|
|
152
|
+
if name == "get_render":
|
|
153
|
+
render = result.get("render") if isinstance(result.get("render"), dict) else {}
|
|
154
|
+
return (kind, {"render_id": args.get("render_id")}) if render.get("output_url") else None
|
|
155
|
+
if name == "show_video":
|
|
156
|
+
return (kind, {"job_id": args.get("job_id")}) if result.get("url") else None
|
|
157
|
+
if name == "show_publish_kit":
|
|
158
|
+
return kind, {"job_id": args.get("job_id")}
|
|
159
|
+
return kind, {}
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _with_picker(result: dict[str, Any], pick: Any) -> dict[str, Any]:
|
|
163
|
+
if not isinstance(pick, dict) or not pick.get("url") or not pick.get("pick_id"):
|
|
164
|
+
return result
|
|
165
|
+
return {**result, "browser_picker_url": pick["url"], "pick_id": pick["pick_id"],
|
|
166
|
+
"browser_picker": PICKER_NOTE}
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _wrap(tool: Any, name: str, client: Callable[[], Any]) -> None:
|
|
170
|
+
original = tool.fn
|
|
171
|
+
if getattr(original, "_cliptude_picker", False) or getattr(tool, "is_async", False):
|
|
172
|
+
return
|
|
173
|
+
if tool.context_kwarg not in (None, CTX_KWARG):
|
|
174
|
+
return # the tool takes the context itself; leave it alone
|
|
175
|
+
|
|
176
|
+
@functools.wraps(original)
|
|
177
|
+
def with_picker(*args: Any, **kwargs: Any) -> Any:
|
|
178
|
+
ctx = kwargs.pop(CTX_KWARG, None)
|
|
179
|
+
result = original(*args, **kwargs)
|
|
180
|
+
if not enabled() or client_renders_apps(ctx):
|
|
181
|
+
return result
|
|
182
|
+
source = pick_source(name, kwargs, result)
|
|
183
|
+
if source is None:
|
|
184
|
+
return result
|
|
185
|
+
try:
|
|
186
|
+
pick = client().create_pick(source[0], source[1])
|
|
187
|
+
except Exception:
|
|
188
|
+
return result # the tool's own answer matters more than the link
|
|
189
|
+
return _with_picker(result, pick)
|
|
190
|
+
|
|
191
|
+
with_picker._cliptude_picker = True # type: ignore[attr-defined]
|
|
192
|
+
tool.fn = with_picker
|
|
193
|
+
tool.context_kwarg = CTX_KWARG
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def add_browser_fallback(mcp: Any, client: Callable[[], Any]) -> list[str]:
|
|
197
|
+
"""Give the widget-bound tools a browser picker for clients without MCP Apps; returns the names wrapped."""
|
|
198
|
+
from cliptude_mcp.apps import REVIEW_TOOLS
|
|
199
|
+
|
|
200
|
+
manager = getattr(mcp, "_tool_manager", None)
|
|
201
|
+
wrapped = []
|
|
202
|
+
for name in (*LIST_KINDS, *REVIEW_TOOLS):
|
|
203
|
+
tool = manager.get_tool(name) if manager is not None else None
|
|
204
|
+
if tool is None:
|
|
205
|
+
continue
|
|
206
|
+
_wrap(tool, name, client)
|
|
207
|
+
if getattr(tool.fn, "_cliptude_picker", False):
|
|
208
|
+
wrapped.append(name)
|
|
209
|
+
return wrapped
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def register_pick_tools(mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]]) -> None:
|
|
213
|
+
from mcp.types import ToolAnnotations
|
|
214
|
+
|
|
215
|
+
@mcp.tool(
|
|
216
|
+
title="Get pick",
|
|
217
|
+
annotations=ToolAnnotations(title="Get pick", read_only_hint=True, open_world_hint=False),
|
|
218
|
+
)
|
|
219
|
+
def get_pick(
|
|
220
|
+
pick_id: Annotated[str, Field(min_length=8, description="pick_id from a result's browser picker")],
|
|
221
|
+
) -> dict[str, Any]:
|
|
222
|
+
"""What the user picked or confirmed on a browser picker page (browser_picker_url, for clients that show no widgets). Returns {status: open|done|expired, result}. Only status done carries their pick: result.message and result.choice (the exact ids), or for a review result.confirmed with tool, arguments, review_token and acknowledge to resend that call once. Call it after the user says they are done; while open, ask them to finish on the page."""
|
|
223
|
+
try:
|
|
224
|
+
return client().get_pick(pick_id)
|
|
225
|
+
except Exception as exc:
|
|
226
|
+
return err(exc)
|