@cliptude/cli 0.1.30 → 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/cliptude_mcp/apps.py +162 -29
- package/cliptude_mcp/cli.py +63 -2
- package/cliptude_mcp/client.py +9 -0
- package/cliptude_mcp/picks.py +226 -0
- package/cliptude_mcp/server.py +44 -6
- package/cliptude_mcp/widgets/base.css +50 -0
- package/cliptude_mcp/widgets/bridge.js +68 -4
- package/cliptude_mcp/widgets/job.html +32 -0
- package/cliptude_mcp/widgets/publish-kit.html +4 -133
- 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/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/apps.py
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai.
|
|
1
|
+
"""MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai, ChatGPT.
|
|
2
2
|
|
|
3
3
|
Spec: https://modelcontextprotocol.io/specification/draft/extensions/apps (SEP-1865, `io.modelcontextprotocol/ui`).
|
|
4
4
|
|
|
@@ -8,23 +8,30 @@ sandboxed iframe next to a tool's result:
|
|
|
8
8
|
- list_avatars -> ui://cliptude/avatars.html avatar thumbnails, pick one
|
|
9
9
|
- list_voices -> ui://cliptude/voices.html play voice previews, pick one
|
|
10
10
|
- list_vector_characters -> ui://cliptude/characters.html Vector Explainer cast and uploads, pick one
|
|
11
|
-
- get_render,
|
|
12
|
-
-> ui://cliptude/player.html watch the MP4, or "not rendered yet"
|
|
11
|
+
- get_render, show_video -> ui://cliptude/player.html watch the MP4, or "not rendered yet"
|
|
13
12
|
- show_choices -> ui://cliptude/choices.html music (play), backgrounds, style packs, themes, captions
|
|
14
13
|
- show_publish_kit -> ui://cliptude/publish-kit.html thumbnails, title ideas, description, chapters, tags
|
|
14
|
+
- list_templates -> ui://cliptude/templates.html template gallery, "Use this template"
|
|
15
|
+
- create_template, get_template
|
|
16
|
+
-> ui://cliptude/template.html one template's card: voice, presenter, music, look, switches
|
|
17
|
+
- create_job, create_plan_job, create_script, create_voiceover, continue_job, render_product_video,
|
|
18
|
+
draft_product_script, run_agent, render_project, create_avatar
|
|
19
|
+
-> ui://cliptude/review.html the 428 review to confirm (or the result card)
|
|
20
|
+
- get_job, get_product_video_status, get_narration
|
|
21
|
+
-> ui://cliptude/job.html progress card, the script to approve, or the publish kit
|
|
15
22
|
|
|
16
23
|
The existing tools keep their names, parameters and JSON (the text content stays the same for clients without
|
|
17
|
-
Apps);
|
|
18
|
-
|
|
19
|
-
tools would draw a widget on every one of their (frequent, polling) calls.
|
|
24
|
+
Apps); `bind_existing_tools` adds `_meta.ui.resourceUri` (plus ChatGPT's `openai/outputTemplate` alias) and tags a
|
|
25
|
+
428 review with the tool that returned it (`tool`), so the review widget knows what to call again.
|
|
20
26
|
|
|
21
27
|
A widget picks by posting a `ui/message` into the chat ("Use the voice ... (voice_id ...)"), so the model gets the
|
|
22
|
-
id without the user typing it.
|
|
23
|
-
|
|
28
|
+
id without the user typing it. Calls a widget makes itself (`tools/call`) happen only on the user's click: the
|
|
29
|
+
review widget's Confirm resends the reviewed call with its review_token, never on its own.
|
|
24
30
|
"""
|
|
25
31
|
|
|
26
32
|
from __future__ import annotations
|
|
27
33
|
|
|
34
|
+
import functools
|
|
28
35
|
from collections.abc import Callable
|
|
29
36
|
from importlib import resources
|
|
30
37
|
from typing import Annotated, Any
|
|
@@ -44,6 +51,10 @@ CHARACTERS_URI = "ui://cliptude/characters.html"
|
|
|
44
51
|
PLAYER_URI = "ui://cliptude/player.html"
|
|
45
52
|
CHOICES_URI = "ui://cliptude/choices.html"
|
|
46
53
|
PUBLISH_KIT_URI = "ui://cliptude/publish-kit.html"
|
|
54
|
+
TEMPLATES_URI = "ui://cliptude/templates.html"
|
|
55
|
+
TEMPLATE_URI = "ui://cliptude/template.html"
|
|
56
|
+
REVIEW_URI = "ui://cliptude/review.html"
|
|
57
|
+
JOB_URI = "ui://cliptude/job.html"
|
|
47
58
|
|
|
48
59
|
# uri -> (file, name, description)
|
|
49
60
|
WIDGETS: dict[str, tuple[str, str, str]] = {
|
|
@@ -53,15 +64,58 @@ WIDGETS: dict[str, tuple[str, str, str]] = {
|
|
|
53
64
|
PLAYER_URI: ("player.html", "Video player", "Plays a finished Cliptude MP4, or shows that it is not rendered yet."),
|
|
54
65
|
CHOICES_URI: ("choices.html", "Setting picker", "Previews of music, backgrounds and styles to pick a template setting."),
|
|
55
66
|
PUBLISH_KIT_URI: ("publish-kit.html", "Publish kit", "Thumbnails, title ideas, description, chapters and tags."),
|
|
67
|
+
TEMPLATES_URI: ("templates.html", "Templates", "The user's saved templates, to pick one for a video."),
|
|
68
|
+
TEMPLATE_URI: ("template.html", "Template", "One template: voice, presenter, music, background, style and switches."),
|
|
69
|
+
REVIEW_URI: ("review.html", "Review and confirm", "What a job or spend does and costs, for the user to confirm."),
|
|
70
|
+
JOB_URI: ("job.html", "Job", "A job's progress, its script to approve, or its publish kit when ready."),
|
|
56
71
|
}
|
|
57
72
|
|
|
73
|
+
# Tools whose first call answers with a 428 review (detail.review + review_token) before they spend credits.
|
|
74
|
+
REVIEW_TOOLS: tuple[str, ...] = (
|
|
75
|
+
"create_job", "create_plan_job", "create_script", "create_voiceover", "continue_job", "render_product_video",
|
|
76
|
+
"draft_product_script", "run_agent", "render_project", "create_avatar",
|
|
77
|
+
)
|
|
78
|
+
# Of those, the ones that take acknowledge ids (the job review's acknowledgements_required).
|
|
79
|
+
ACKNOWLEDGE_TOOLS: frozenset[str] = frozenset({
|
|
80
|
+
"create_job", "create_plan_job", "create_script", "create_voiceover", "draft_product_script",
|
|
81
|
+
})
|
|
82
|
+
|
|
58
83
|
# Existing tools that get a widget, by name.
|
|
59
84
|
BOUND_TOOLS: dict[str, str] = {
|
|
60
85
|
"list_avatars": AVATARS_URI,
|
|
61
86
|
"list_voices": VOICES_URI,
|
|
62
87
|
"list_vector_characters": CHARACTERS_URI,
|
|
63
88
|
"get_render": PLAYER_URI,
|
|
64
|
-
"
|
|
89
|
+
"list_templates": TEMPLATES_URI,
|
|
90
|
+
"create_template": TEMPLATE_URI,
|
|
91
|
+
"get_template": TEMPLATE_URI,
|
|
92
|
+
"get_job": JOB_URI,
|
|
93
|
+
"get_product_video_status": JOB_URI,
|
|
94
|
+
"get_narration": JOB_URI,
|
|
95
|
+
**{name: REVIEW_URI for name in REVIEW_TOOLS},
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
# Tools a widget calls itself (tools/call). ChatGPT wants openai/widgetAccessible on them.
|
|
99
|
+
WIDGET_CALLED_TOOLS: frozenset[str] = frozenset({
|
|
100
|
+
*REVIEW_TOOLS, "list_avatars", "design_voice_previews", "save_designed_voice", "clone_voice", "show_publish_kit",
|
|
101
|
+
})
|
|
102
|
+
|
|
103
|
+
# ChatGPT's short status lines while a widget tool runs and after (openai/toolInvocation/*, at most 64 chars).
|
|
104
|
+
INVOCATION_TEXT: dict[str, tuple[str, str]] = {
|
|
105
|
+
"list_avatars": ("Loading avatars…", "Avatars ready"),
|
|
106
|
+
"list_voices": ("Loading voices…", "Voices ready"),
|
|
107
|
+
"list_vector_characters": ("Loading characters…", "Characters ready"),
|
|
108
|
+
"get_render": ("Checking the export…", "Export checked"),
|
|
109
|
+
"show_video": ("Loading the video…", "Video ready"),
|
|
110
|
+
"show_choices": ("Loading choices…", "Choices ready"),
|
|
111
|
+
"show_publish_kit": ("Opening the publish kit…", "Publish kit ready"),
|
|
112
|
+
"list_templates": ("Loading templates…", "Templates ready"),
|
|
113
|
+
"create_template": ("Saving the template…", "Template saved"),
|
|
114
|
+
"get_template": ("Loading the template…", "Template ready"),
|
|
115
|
+
"get_job": ("Checking the job…", "Job checked"),
|
|
116
|
+
"get_product_video_status": ("Checking the product video…", "Product video checked"),
|
|
117
|
+
"get_narration": ("Loading the narration…", "Narration ready"),
|
|
118
|
+
**{name: ("Preparing the review…", "Review ready") for name in REVIEW_TOOLS},
|
|
65
119
|
}
|
|
66
120
|
|
|
67
121
|
# Where the widgets' pictures, audio and video come from (CSP img-src/media-src via resourceDomains).
|
|
@@ -124,17 +178,48 @@ def widget_html(file_name: str) -> str:
|
|
|
124
178
|
html = (pkg / file_name).read_text(encoding="utf-8")
|
|
125
179
|
bridge = (pkg / "bridge.js").read_text(encoding="utf-8")
|
|
126
180
|
css = (pkg / "base.css").read_text(encoding="utf-8")
|
|
127
|
-
|
|
181
|
+
views = (pkg / "views.js").read_text(encoding="utf-8")
|
|
182
|
+
html = html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
|
|
183
|
+
return html.replace("/*@VIEWS_JS@*/", views)
|
|
128
184
|
|
|
129
185
|
|
|
130
186
|
def media_domains(*, local: bool) -> list[str]:
|
|
131
187
|
return list(MEDIA_DOMAINS) + (list(LOCAL_MEDIA_DOMAINS) if local else [])
|
|
132
188
|
|
|
133
189
|
|
|
134
|
-
def
|
|
190
|
+
def _openai_meta(name: str, uri: str) -> dict[str, Any]:
|
|
191
|
+
"""ChatGPT's aliases (Apps SDK reference): it reads `_meta.ui.resourceUri` too, and documents these."""
|
|
192
|
+
meta: dict[str, Any] = {"openai/outputTemplate": uri}
|
|
193
|
+
invoking, invoked = INVOCATION_TEXT.get(name, ("", ""))
|
|
194
|
+
if invoking:
|
|
195
|
+
meta["openai/toolInvocation/invoking"] = invoking[:64]
|
|
196
|
+
meta["openai/toolInvocation/invoked"] = invoked[:64]
|
|
197
|
+
if name in WIDGET_CALLED_TOOLS:
|
|
198
|
+
meta["openai/widgetAccessible"] = True
|
|
199
|
+
return meta
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def _ui_meta(uri: str, name: str = "") -> dict[str, Any]:
|
|
135
203
|
# `ui.resourceUri` is the spec's key; the flat `ui/resourceUri` is its deprecated form, kept for hosts that
|
|
136
204
|
# shipped before the rename.
|
|
137
|
-
return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri}
|
|
205
|
+
return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri, **_openai_meta(name, uri)}
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def _resource_meta(uri: str, description: str, *, local: bool) -> dict[str, Any]:
|
|
209
|
+
"""`_meta` of a widget resource: the spec's `ui` block plus ChatGPT's openai/widget* aliases."""
|
|
210
|
+
domains = media_domains(local=local)
|
|
211
|
+
ui: dict[str, Any] = {"csp": ResourceCsp(resource_domains=domains).model_dump(by_alias=True, exclude_none=True)}
|
|
212
|
+
permissions = _PERMISSIONS.get(uri)
|
|
213
|
+
if permissions is not None:
|
|
214
|
+
ui["permissions"] = permissions.model_dump(by_alias=True, exclude_none=True)
|
|
215
|
+
ui["prefersBorder"] = True
|
|
216
|
+
return {
|
|
217
|
+
"ui": ui,
|
|
218
|
+
# The widgets fetch nothing themselves (no connect_domains); pictures, audio and video come from these.
|
|
219
|
+
"openai/widgetCSP": {"connect_domains": [], "resource_domains": domains},
|
|
220
|
+
"openai/widgetDescription": description,
|
|
221
|
+
"openai/widgetPrefersBorder": True,
|
|
222
|
+
}
|
|
138
223
|
|
|
139
224
|
|
|
140
225
|
def build_apps(
|
|
@@ -148,23 +233,25 @@ def build_apps(
|
|
|
148
233
|
return None
|
|
149
234
|
from mcp.types import ToolAnnotations
|
|
150
235
|
|
|
236
|
+
from mcp.server.mcpserver.resources import TextResource
|
|
237
|
+
|
|
151
238
|
apps = Apps()
|
|
152
|
-
csp = ResourceCsp(resource_domains=media_domains(local=local))
|
|
153
239
|
for uri, (file_name, name, description) in WIDGETS.items():
|
|
154
|
-
apps.
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
240
|
+
apps.add_resource(
|
|
241
|
+
TextResource(
|
|
242
|
+
uri=uri,
|
|
243
|
+
name=name,
|
|
244
|
+
title=name,
|
|
245
|
+
description=description,
|
|
246
|
+
mime_type=APP_MIME_TYPE,
|
|
247
|
+
meta=_resource_meta(uri, description, local=local),
|
|
248
|
+
text=widget_html(file_name),
|
|
249
|
+
)
|
|
163
250
|
)
|
|
164
251
|
|
|
165
252
|
@apps.tool(
|
|
166
253
|
resource_uri=CHOICES_URI,
|
|
167
|
-
meta={"ui/resourceUri": CHOICES_URI},
|
|
254
|
+
meta={"ui/resourceUri": CHOICES_URI, **_openai_meta("show_choices", CHOICES_URI)},
|
|
168
255
|
name="show_choices",
|
|
169
256
|
title="Show setting choices",
|
|
170
257
|
annotations=ToolAnnotations(title="Show setting choices", read_only_hint=True, open_world_hint=False),
|
|
@@ -188,7 +275,7 @@ def build_apps(
|
|
|
188
275
|
|
|
189
276
|
@apps.tool(
|
|
190
277
|
resource_uri=PLAYER_URI,
|
|
191
|
-
meta={"ui/resourceUri": PLAYER_URI},
|
|
278
|
+
meta={"ui/resourceUri": PLAYER_URI, **_openai_meta("show_video", PLAYER_URI)},
|
|
192
279
|
name="show_video",
|
|
193
280
|
title="Show video",
|
|
194
281
|
annotations=ToolAnnotations(title="Show video", read_only_hint=True, open_world_hint=False),
|
|
@@ -205,7 +292,7 @@ def build_apps(
|
|
|
205
292
|
|
|
206
293
|
@apps.tool(
|
|
207
294
|
resource_uri=PUBLISH_KIT_URI,
|
|
208
|
-
meta={"ui/resourceUri": PUBLISH_KIT_URI},
|
|
295
|
+
meta={"ui/resourceUri": PUBLISH_KIT_URI, **_openai_meta("show_publish_kit", PUBLISH_KIT_URI)},
|
|
209
296
|
name="show_publish_kit",
|
|
210
297
|
title="Show publish kit",
|
|
211
298
|
annotations=ToolAnnotations(title="Show publish kit", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
@@ -213,20 +300,47 @@ def build_apps(
|
|
|
213
300
|
def show_publish_kit(
|
|
214
301
|
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
215
302
|
) -> dict[str, Any]:
|
|
216
|
-
"""The generated thumbnails, title ideas, YouTube description, chapters and tags
|
|
303
|
+
"""The finished video in a player, then its generated thumbnails, title ideas, YouTube description, chapters and tags with copy buttons (hosts that show apps). Call it as soon as a video is ready (rendered, or built and waiting for review): it is the one place the user watches the video and gets everything to publish it. Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, video, thumbnails, publish_metadata}; video.url is the latest export, else the job's own MP4, empty until one exists."""
|
|
217
304
|
try:
|
|
218
305
|
data = client().open_editor_project(job_id)
|
|
219
306
|
except Exception as exc:
|
|
220
307
|
return err(exc)
|
|
221
|
-
|
|
308
|
+
payload = publish_kit_payload(data, job_id)
|
|
309
|
+
if not payload.get("error") and not (payload.get("video") or {}).get("url"):
|
|
310
|
+
try:
|
|
311
|
+
job = client().get_job(job_id)
|
|
312
|
+
except Exception:
|
|
313
|
+
job = None
|
|
314
|
+
output = job.get("output") if isinstance(job, dict) and isinstance(job.get("output"), dict) else {}
|
|
315
|
+
if output.get("url"):
|
|
316
|
+
payload["video"] = {"url": output["url"], "source": "original", "note": ""}
|
|
317
|
+
return payload
|
|
222
318
|
|
|
223
319
|
return apps
|
|
224
320
|
|
|
225
321
|
|
|
322
|
+
def _tag_reviews(tool: Any, name: str) -> None:
|
|
323
|
+
"""A 428 review result also names the tool that returned it, so the review widget can call it again."""
|
|
324
|
+
original = tool.fn
|
|
325
|
+
if getattr(original, "_cliptude_tagged", False) or getattr(tool, "is_async", False):
|
|
326
|
+
return
|
|
327
|
+
|
|
328
|
+
@functools.wraps(original)
|
|
329
|
+
def tagged(*args: Any, **kwargs: Any) -> Any:
|
|
330
|
+
result = original(*args, **kwargs)
|
|
331
|
+
if isinstance(result, dict) and result.get("status") == 428 and "tool" not in result:
|
|
332
|
+
return {**result, "tool": name}
|
|
333
|
+
return result
|
|
334
|
+
|
|
335
|
+
tagged._cliptude_tagged = True # type: ignore[attr-defined]
|
|
336
|
+
tool.fn = tagged
|
|
337
|
+
|
|
338
|
+
|
|
226
339
|
def bind_existing_tools(mcp: Any) -> list[str]:
|
|
227
340
|
"""Stamp `_meta.ui.resourceUri` on the existing tools that have a widget; returns the names bound.
|
|
228
341
|
|
|
229
|
-
The tools are registered by server.py as before, so their names
|
|
342
|
+
The tools are registered by server.py (and creation.py) as before, so their names and parameters do not
|
|
343
|
+
change; a 428 review also says which tool returned it (`tool`).
|
|
230
344
|
"""
|
|
231
345
|
manager = getattr(mcp, "_tool_manager", None)
|
|
232
346
|
bound = []
|
|
@@ -234,8 +348,14 @@ def bind_existing_tools(mcp: Any) -> list[str]:
|
|
|
234
348
|
tool = manager.get_tool(name) if manager is not None else None
|
|
235
349
|
if tool is None:
|
|
236
350
|
continue
|
|
237
|
-
tool.meta = {**(tool.meta or {}), **_ui_meta(uri)}
|
|
351
|
+
tool.meta = {**(tool.meta or {}), **_ui_meta(uri, name)}
|
|
352
|
+
if name in REVIEW_TOOLS:
|
|
353
|
+
_tag_reviews(tool, name)
|
|
238
354
|
bound.append(name)
|
|
355
|
+
for name in sorted(WIDGET_CALLED_TOOLS - set(BOUND_TOOLS)):
|
|
356
|
+
tool = manager.get_tool(name) if manager is not None else None
|
|
357
|
+
if tool is not None:
|
|
358
|
+
tool.meta = {**(tool.meta or {}), "openai/widgetAccessible": True}
|
|
239
359
|
return bound
|
|
240
360
|
|
|
241
361
|
|
|
@@ -289,6 +409,18 @@ def video_payload(job: Any, job_id: str) -> dict[str, Any]:
|
|
|
289
409
|
}
|
|
290
410
|
|
|
291
411
|
|
|
412
|
+
def _project_video(project: dict[str, Any]) -> dict[str, Any]:
|
|
413
|
+
"""The newest finished export of the editor project, for the publish kit's player."""
|
|
414
|
+
render = project.get("latest_render") if isinstance(project.get("latest_render"), dict) else {}
|
|
415
|
+
url = ""
|
|
416
|
+
if str(render.get("status") or "completed").lower() == "completed":
|
|
417
|
+
url = str(render.get("output_url") or project.get("latest_render_url") or "")
|
|
418
|
+
if url:
|
|
419
|
+
return {"url": url, "source": "export", "note": ""}
|
|
420
|
+
note = "Not rendered yet: render_project makes the MP4." if render.get("status") not in (None, "", "completed") else ""
|
|
421
|
+
return {"url": "", "source": "", "note": note}
|
|
422
|
+
|
|
423
|
+
|
|
292
424
|
def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
|
|
293
425
|
if not isinstance(data, dict):
|
|
294
426
|
return {"error": "Cliptude returned no editor project."}
|
|
@@ -300,6 +432,7 @@ def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
|
|
|
300
432
|
"job_id": job_id,
|
|
301
433
|
"project_id": project.get("id"),
|
|
302
434
|
"title": project.get("title") or "",
|
|
435
|
+
"video": _project_video(project),
|
|
303
436
|
"thumbnails": project.get("thumbnails") or {"status": "", "items": []},
|
|
304
437
|
"publish_metadata": {
|
|
305
438
|
"title_variants": meta.get("title_variants") or [],
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
|
|
1
|
+
"""Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
@@ -175,6 +175,43 @@ def _wait(fetch, status_of, *, interval: float = 10.0, timeout: float = 3600.0):
|
|
|
175
175
|
time.sleep(interval)
|
|
176
176
|
|
|
177
177
|
|
|
178
|
+
def _run_pick(client: CliptudeClient, args) -> dict:
|
|
179
|
+
"""Open a browser picker (made here with --kind, or one an agent got as browser_picker_url) and wait for it.
|
|
180
|
+
|
|
181
|
+
The page is the same widget Claude Desktop shows (avatars, voices, music, a review to confirm, ...), on
|
|
182
|
+
cliptude.com for the signed-in owner, for 15 minutes. Returns the pick once the user is done.
|
|
183
|
+
"""
|
|
184
|
+
import time
|
|
185
|
+
import webbrowser
|
|
186
|
+
|
|
187
|
+
pick_id, url = (args.pick_id or "").strip(), (args.url or "").strip()
|
|
188
|
+
if args.kind:
|
|
189
|
+
try:
|
|
190
|
+
source = json.loads(args.source or "{}")
|
|
191
|
+
except ValueError as exc:
|
|
192
|
+
raise CliptudeApiError("--source must be a JSON object.") from exc
|
|
193
|
+
if not isinstance(source, dict):
|
|
194
|
+
raise CliptudeApiError("--source must be a JSON object.")
|
|
195
|
+
created = client.create_pick(args.kind, source)
|
|
196
|
+
pick_id, url = str(created.get("pick_id") or ""), str(created.get("url") or "")
|
|
197
|
+
if not pick_id:
|
|
198
|
+
raise CliptudeApiError("Give a pick_id (with --url to open it), or --kind to make a new picker.")
|
|
199
|
+
if url:
|
|
200
|
+
if not url.startswith(("https://", "http://127.0.0.1", "http://localhost")):
|
|
201
|
+
raise CliptudeApiError("--url must be the https link Cliptude gave (browser_picker_url).")
|
|
202
|
+
print(f"Pick in your browser: {url}", file=sys.stderr)
|
|
203
|
+
if not args.no_open:
|
|
204
|
+
webbrowser.open(url)
|
|
205
|
+
deadline = time.monotonic() + max(5.0, float(args.timeout))
|
|
206
|
+
while True:
|
|
207
|
+
payload = client.get_pick(pick_id)
|
|
208
|
+
status = str(payload.get("status") or "")
|
|
209
|
+
if status != "open" or time.monotonic() > deadline:
|
|
210
|
+
return payload
|
|
211
|
+
print("Waiting for your pick in the browser...", file=sys.stderr)
|
|
212
|
+
time.sleep(max(1.0, float(args.interval)))
|
|
213
|
+
|
|
214
|
+
|
|
178
215
|
def _run_auth(auth_cmd: str) -> None:
|
|
179
216
|
from cliptude_mcp.auth_login import AuthLoginError, login
|
|
180
217
|
from cliptude_mcp.credentials import clear_credentials, stored_access_token
|
|
@@ -261,6 +298,25 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
261
298
|
use.add_argument("target", nargs="?", choices=["desktop", "cloud", "auto"],
|
|
262
299
|
help="auto = the desktop app while it is running, else cliptude.com")
|
|
263
300
|
|
|
301
|
+
pk = sub.add_parser(
|
|
302
|
+
"pick",
|
|
303
|
+
help="Open a browser picker (avatars, voices, music, a review to confirm, ...) and wait for the pick",
|
|
304
|
+
description=(
|
|
305
|
+
"Clients without MCP Apps widgets get browser_picker_url and pick_id from the MCP tools. This opens the "
|
|
306
|
+
"link in your browser and waits until you pick (or confirm) there, then prints the result. With --kind "
|
|
307
|
+
"it makes a new picker first."
|
|
308
|
+
),
|
|
309
|
+
)
|
|
310
|
+
pk.add_argument("pick_id", nargs="?", default="", help="pick_id from the tool result")
|
|
311
|
+
pk.add_argument("--url", default="", help="browser_picker_url from the tool result")
|
|
312
|
+
pk.add_argument("--kind", default="", choices=["", "avatars", "voices", "characters", "choices", "templates",
|
|
313
|
+
"template", "job", "script", "publish_kit", "video"],
|
|
314
|
+
help="Make a new picker of this kind instead")
|
|
315
|
+
pk.add_argument("--source", default="{}", help='Where Cliptude reads it from, JSON, e.g. {"provider": "elevenlabs"}')
|
|
316
|
+
pk.add_argument("--no-open", action="store_true", help="Print the link instead of opening a browser")
|
|
317
|
+
pk.add_argument("--timeout", type=float, default=900.0, help="Seconds to wait (the link lasts 15 minutes)")
|
|
318
|
+
pk.add_argument("--interval", type=float, default=3.0, help="Seconds between checks")
|
|
319
|
+
|
|
264
320
|
t = sub.add_parser("templates", help="List saved templates")
|
|
265
321
|
t.add_argument("--limit", type=int, default=20)
|
|
266
322
|
t.add_argument("--offset", type=int, default=0)
|
|
@@ -662,7 +718,12 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
662
718
|
return
|
|
663
719
|
client = CliptudeClient(client_kind="cli")
|
|
664
720
|
try:
|
|
665
|
-
if args.cmd == "
|
|
721
|
+
if args.cmd == "pick":
|
|
722
|
+
payload = _run_pick(client, args)
|
|
723
|
+
_print(payload)
|
|
724
|
+
if payload.get("status") != "done":
|
|
725
|
+
raise SystemExit(1)
|
|
726
|
+
elif args.cmd == "templates":
|
|
666
727
|
_print(client.list_templates(limit=args.limit, offset=args.offset))
|
|
667
728
|
elif args.cmd == "template-create":
|
|
668
729
|
settings = {}
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -1163,6 +1163,15 @@ class CliptudeClient:
|
|
|
1163
1163
|
def get_account(self) -> Any:
|
|
1164
1164
|
return self.request("GET", "/api/v1/account")
|
|
1165
1165
|
|
|
1166
|
+
# Browser pickers (clients without MCP Apps widgets) ---------------------------------------------
|
|
1167
|
+
|
|
1168
|
+
def create_pick(self, kind: str, payload_source: dict[str, Any]) -> Any:
|
|
1169
|
+
"""A cliptude.com/pick link showing a widget in the browser; Cliptude builds what it shows."""
|
|
1170
|
+
return self.request("POST", "/api/v1/picks", json_body={"kind": kind, "payload_source": payload_source})
|
|
1171
|
+
|
|
1172
|
+
def get_pick(self, pick_id: str) -> Any:
|
|
1173
|
+
return self.request("GET", f"/api/v1/picks/{_uuid_seg(pick_id, 'pick_id')}")
|
|
1174
|
+
|
|
1166
1175
|
def estimate_credits(
|
|
1167
1176
|
self,
|
|
1168
1177
|
*,
|
|
@@ -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)
|