@cliptude/cli 0.1.3 → 0.1.7
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 +39 -7
- package/cliptude_mcp/auth.py +33 -1
- package/cliptude_mcp/cli.py +394 -16
- package/cliptude_mcp/client.py +529 -44
- package/cliptude_mcp/server.py +566 -30
- package/package.json +1 -1
- package/pyproject.toml +1 -1
- package/cliptude_mcp/__pycache__/__init__.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/auth_login.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/cli.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/client.cpython-313.pyc +0 -0
- package/cliptude_mcp/__pycache__/credentials.cpython-313.pyc +0 -0
package/cliptude_mcp/server.py
CHANGED
|
@@ -35,16 +35,84 @@ def _err(exc: Exception) -> dict[str, Any]:
|
|
|
35
35
|
return {"error": str(exc)}
|
|
36
36
|
|
|
37
37
|
|
|
38
|
+
def mcp_allowed_hosts(resource_url: str | None = None) -> list[str]:
|
|
39
|
+
"""Host header values the Streamable HTTP transport should accept.
|
|
40
|
+
|
|
41
|
+
The SDK auto-allowlists only localhost when streamable_http_app() is called
|
|
42
|
+
with the default host. Public MCP is reached as mcp.cliptude.com via nginx,
|
|
43
|
+
so authenticated POSTs otherwise return 421 Invalid Host header.
|
|
44
|
+
"""
|
|
45
|
+
hosts = ["127.0.0.1:*", "localhost:*", "[::1]:*"]
|
|
46
|
+
extra = (os.environ.get("MCP_ALLOWED_HOSTS") or "").strip()
|
|
47
|
+
if extra:
|
|
48
|
+
hosts.extend(h.strip() for h in extra.split(",") if h.strip())
|
|
49
|
+
return hosts
|
|
50
|
+
from urllib.parse import urlparse
|
|
51
|
+
|
|
52
|
+
parsed = urlparse(
|
|
53
|
+
resource_url
|
|
54
|
+
or os.environ.get("MCP_RESOURCE_URL")
|
|
55
|
+
or "https://mcp.cliptude.com/mcp"
|
|
56
|
+
)
|
|
57
|
+
hostname = (parsed.hostname or "").strip()
|
|
58
|
+
if hostname:
|
|
59
|
+
hosts.append(hostname)
|
|
60
|
+
hosts.append(f"{hostname}:*")
|
|
61
|
+
return hosts
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def mcp_allowed_origins(resource_url: str | None = None) -> list[str]:
|
|
65
|
+
origins = ["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"]
|
|
66
|
+
extra = (os.environ.get("MCP_ALLOWED_ORIGINS") or "").strip()
|
|
67
|
+
if extra:
|
|
68
|
+
origins.extend(o.strip() for o in extra.split(",") if o.strip())
|
|
69
|
+
return origins
|
|
70
|
+
from urllib.parse import urlparse
|
|
71
|
+
|
|
72
|
+
parsed = urlparse(
|
|
73
|
+
resource_url
|
|
74
|
+
or os.environ.get("MCP_RESOURCE_URL")
|
|
75
|
+
or "https://mcp.cliptude.com/mcp"
|
|
76
|
+
)
|
|
77
|
+
hostname = (parsed.hostname or "").strip()
|
|
78
|
+
scheme = (parsed.scheme or "https").strip() or "https"
|
|
79
|
+
if hostname:
|
|
80
|
+
origins.append(f"{scheme}://{hostname}")
|
|
81
|
+
origins.append(f"{scheme}://{hostname}:*")
|
|
82
|
+
return origins
|
|
83
|
+
|
|
84
|
+
|
|
38
85
|
def build_server(*, with_http_auth: bool = False):
|
|
39
86
|
from mcp.server import MCPServer
|
|
40
87
|
from mcp.types import ToolAnnotations
|
|
41
88
|
|
|
42
89
|
kwargs: dict[str, Any] = {
|
|
43
90
|
"instructions": (
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
91
|
+
"Generate Cliptude videos from a saved template. "
|
|
92
|
+
"Call list_templates, then create_job with template_id + title plus "
|
|
93
|
+
"(no suitable template? get_template_options + list_voices, then create_template) "
|
|
94
|
+
"To revise a finished video: open_editor_project, run_agent with timeline item ids, "
|
|
95
|
+
"poll get_agent_run, then render_project and get_render. "
|
|
96
|
+
"prompt, script, voiceover_path (uploaded audio, transcribed; skips TTS), "
|
|
97
|
+
"or talking_head_path (presenter video on a Talking Head template). "
|
|
98
|
+
"create_job returns immediately; poll get_job until completed or failed. "
|
|
99
|
+
"For a script only (no MP4), use create_script. For narration audio only, "
|
|
100
|
+
"use create_voiceover. To turn a completed script or voiceover job into an MP4 "
|
|
101
|
+
"on the same job id, use continue_job (do not create a second job). "
|
|
102
|
+
"Never set prompt to the video title. If the user only named a topic or title, "
|
|
103
|
+
"web-search current facts, write spoken narration, and pass it as script. "
|
|
104
|
+
"If the user pastes a full narration, pass it as script, not prompt. "
|
|
105
|
+
"If they provide a voiceover file, pass voiceover_path and omit prompt/script. "
|
|
106
|
+
"If they provide a talking-head recording, pass talking_head_path and omit "
|
|
107
|
+
"prompt/script/voiceover_path (template format must be talking_head). "
|
|
108
|
+
"Avatar Video templates may include avatar_intro_only "
|
|
109
|
+
"(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
|
|
110
|
+
"on create_job to override the template, or omit them to keep the template. "
|
|
111
|
+
"AGENT-PLANNED VIDEOS (Faceless Documentary, Top 10, Avatar Video): you plan every visual "
|
|
112
|
+
"and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
|
|
113
|
+
"plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
|
|
114
|
+
"plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
|
|
115
|
+
"cliptude-plan skill."
|
|
48
116
|
),
|
|
49
117
|
}
|
|
50
118
|
if with_http_auth:
|
|
@@ -63,7 +131,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
63
131
|
limit: Annotated[int, Field(ge=1, le=100, description="Page size")] = 20,
|
|
64
132
|
offset: Annotated[int, Field(ge=0, description="Offset")] = 0,
|
|
65
133
|
) -> dict[str, Any]:
|
|
66
|
-
"""List saved video templates (id, name, format). Empty list means the user has not saved a template in Cliptude yet."""
|
|
134
|
+
"""List saved video templates (id, name, format). Avatar Video rows include avatar_intro_only and avatar_ai_footage. Empty list means the user has not saved a template in Cliptude yet."""
|
|
67
135
|
try:
|
|
68
136
|
return _client().list_templates(limit=limit, offset=offset)
|
|
69
137
|
except Exception as exc:
|
|
@@ -76,74 +144,355 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
76
144
|
def get_template(
|
|
77
145
|
template_id: Annotated[str, Field(min_length=8, description="Template UUID")],
|
|
78
146
|
) -> dict[str, Any]:
|
|
79
|
-
"""Get one saved template summary (not internal JSON)."""
|
|
147
|
+
"""Get one saved template summary (not internal JSON). Avatar Video includes avatar_intro_only and avatar_ai_footage."""
|
|
80
148
|
try:
|
|
81
149
|
return _client().get_template(template_id)
|
|
82
150
|
except Exception as exc:
|
|
83
151
|
return _err(exc)
|
|
84
152
|
|
|
153
|
+
@mcp.tool(
|
|
154
|
+
title="Get template options",
|
|
155
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
156
|
+
)
|
|
157
|
+
def get_template_options(
|
|
158
|
+
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
|
|
159
|
+
) -> dict[str, Any]:
|
|
160
|
+
"""Fields, choices and defaults that create_template accepts for one format (styles, colours, backgrounds, music, models, durations)."""
|
|
161
|
+
try:
|
|
162
|
+
return _client().template_options(format)
|
|
163
|
+
except Exception as exc:
|
|
164
|
+
return _err(exc)
|
|
165
|
+
|
|
166
|
+
@mcp.tool(
|
|
167
|
+
title="List voices",
|
|
168
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=True),
|
|
169
|
+
)
|
|
170
|
+
def list_voices(
|
|
171
|
+
provider: Annotated[str, Field(description="elevenlabs, minimax, cartesia, inworld or voicetory")] = "elevenlabs",
|
|
172
|
+
language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
|
|
173
|
+
) -> dict[str, Any]:
|
|
174
|
+
"""Voice catalog for one TTS provider. Use a voice's voice_id (and name, provider) in create_template."""
|
|
175
|
+
try:
|
|
176
|
+
return _client().list_voices(provider=provider, language=language)
|
|
177
|
+
except Exception as exc:
|
|
178
|
+
return _err(exc)
|
|
179
|
+
|
|
180
|
+
@mcp.tool(title="Create template")
|
|
181
|
+
def create_template(
|
|
182
|
+
name: Annotated[str, Field(min_length=1, max_length=120, description="Template name")],
|
|
183
|
+
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary")],
|
|
184
|
+
settings: Annotated[
|
|
185
|
+
dict[str, Any],
|
|
186
|
+
Field(
|
|
187
|
+
description=(
|
|
188
|
+
"Wizard settings: voice_id, voice_name, voice_provider plus any field from "
|
|
189
|
+
"get_template_options (unset fields take the wizard defaults). "
|
|
190
|
+
"Optional thumbnail: {custom_prompt}."
|
|
191
|
+
)
|
|
192
|
+
),
|
|
193
|
+
],
|
|
194
|
+
) -> dict[str, Any]:
|
|
195
|
+
"""Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job)."""
|
|
196
|
+
try:
|
|
197
|
+
return _client().create_template(name=name, format=format, settings=settings)
|
|
198
|
+
except Exception as exc:
|
|
199
|
+
return _err(exc)
|
|
200
|
+
|
|
85
201
|
@mcp.tool(title="Create video job")
|
|
86
202
|
def create_job(
|
|
87
203
|
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
88
204
|
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
89
|
-
prompt: Annotated[str | None, Field(description="Topic/brief
|
|
90
|
-
script: Annotated[str | None, Field(description="
|
|
91
|
-
|
|
205
|
+
prompt: Annotated[str | None, Field(description="Topic/brief for Cliptude to write the VO. Never the video title. Prefer script after research.")] = None,
|
|
206
|
+
script: Annotated[str | None, Field(description="Spoken narration. Use this when the user gave a topic (after web search) or pasted a script. Cliptude does not rewrite it.")] = None,
|
|
207
|
+
voiceover_path: Annotated[
|
|
92
208
|
str | None,
|
|
93
|
-
Field(
|
|
209
|
+
Field(
|
|
210
|
+
description=(
|
|
211
|
+
"Local path to a narration audio file (MP3, M4A, WAV, …). "
|
|
212
|
+
"Cliptude transcribes it and skips TTS. Do not also send prompt or script. "
|
|
213
|
+
"Stdio / local MCP only — remote hosts should use the CLI."
|
|
214
|
+
),
|
|
215
|
+
),
|
|
216
|
+
] = None,
|
|
217
|
+
talking_head_path: Annotated[
|
|
218
|
+
str | None,
|
|
219
|
+
Field(
|
|
220
|
+
description=(
|
|
221
|
+
"Local path to a talking-head presenter video (MP4, MOV, WEBM, AVI). "
|
|
222
|
+
"Requires a Talking Head template. Cliptude transcribes it and skips TTS. "
|
|
223
|
+
"Do not also send prompt, script, or voiceover_path. "
|
|
224
|
+
"Stdio / local MCP only — remote hosts should use the CLI."
|
|
225
|
+
),
|
|
226
|
+
),
|
|
94
227
|
] = None,
|
|
228
|
+
duration: Annotated[
|
|
229
|
+
str | None,
|
|
230
|
+
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script). Ignored when voiceover_path or talking_head_path is set — duration comes from the file."),
|
|
231
|
+
] = None,
|
|
232
|
+
avatar_intro_only: Annotated[
|
|
233
|
+
bool | None,
|
|
234
|
+
Field(
|
|
235
|
+
description=(
|
|
236
|
+
"Avatar Video only: Avatar Intro Only. True = HeyGen in a short opening. "
|
|
237
|
+
"Omit to use the saved template. Other formats reject this field."
|
|
238
|
+
),
|
|
239
|
+
),
|
|
240
|
+
] = None,
|
|
241
|
+
avatar_ai_footage: Annotated[
|
|
242
|
+
bool | None,
|
|
243
|
+
Field(
|
|
244
|
+
description=(
|
|
245
|
+
"Avatar Video only: AI Image + AI Video instead of stock/YouTube. "
|
|
246
|
+
"Omit to use the saved template. Other formats reject this field."
|
|
247
|
+
),
|
|
248
|
+
),
|
|
249
|
+
] = None,
|
|
250
|
+
disable_animations: Annotated[
|
|
251
|
+
bool | None,
|
|
252
|
+
Field(description="True = no animated text reveals or motion graphics. Omit to use the saved template."),
|
|
253
|
+
] = None,
|
|
254
|
+
disable_overlays: Annotated[
|
|
255
|
+
bool | None,
|
|
256
|
+
Field(description="True = no text overlays, stat cards, or graphic elements over footage. Captions are unaffected. Omit to use the saved template."),
|
|
257
|
+
] = None,
|
|
258
|
+
disable_effects: Annotated[
|
|
259
|
+
bool | None,
|
|
260
|
+
Field(description="True = no color grading, film grain, light leaks, or stylized treatments. Ken Burns pan/zoom is unaffected. Omit to use the saved template."),
|
|
261
|
+
] = None,
|
|
262
|
+
disable_transitions: Annotated[
|
|
263
|
+
bool | None,
|
|
264
|
+
Field(description="True = no scene transitions; hard cuts only. Omit to use the saved template."),
|
|
265
|
+
] = None,
|
|
266
|
+
excluded_animation_types: Annotated[
|
|
267
|
+
list[str] | None,
|
|
268
|
+
Field(description="Animation-type strings to exclude from this video (see list_templates/get_template or the app's motion-graphics catalog for valid values). Omit to use the saved template."),
|
|
269
|
+
] = None,
|
|
270
|
+
excluded_transition_kinds: Annotated[
|
|
271
|
+
list[str] | None,
|
|
272
|
+
Field(description="Transition slugs to exclude from auto-selection, e.g. 'flip-horizontal', 'film-burn'. Omit to use the saved template."),
|
|
273
|
+
] = None,
|
|
274
|
+
) -> dict[str, Any]:
|
|
275
|
+
"""Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
|
|
276
|
+
try:
|
|
277
|
+
vo = (voiceover_path or "").strip() or None
|
|
278
|
+
th = (talking_head_path or "").strip() or None
|
|
279
|
+
if vo and th:
|
|
280
|
+
return {"error": "Upload either a talking head video or a voiceover — not both."}
|
|
281
|
+
if (vo or th) and ((prompt or "").strip() or (script or "").strip()):
|
|
282
|
+
kind = "talking head video" if th else "voiceover"
|
|
283
|
+
return {
|
|
284
|
+
"error": (
|
|
285
|
+
f"Upload a {kind}, or send a prompt / custom script — not both. "
|
|
286
|
+
"An uploaded file is transcribed and used as the narration."
|
|
287
|
+
)
|
|
288
|
+
}
|
|
289
|
+
return _client().create_job(
|
|
290
|
+
template_id=template_id,
|
|
291
|
+
title=title,
|
|
292
|
+
prompt=prompt,
|
|
293
|
+
script=script,
|
|
294
|
+
duration=duration,
|
|
295
|
+
voiceover_path=vo,
|
|
296
|
+
talking_head_path=th,
|
|
297
|
+
avatar_intro_only=avatar_intro_only,
|
|
298
|
+
avatar_ai_footage=avatar_ai_footage,
|
|
299
|
+
disable_animations=disable_animations,
|
|
300
|
+
disable_overlays=disable_overlays,
|
|
301
|
+
disable_effects=disable_effects,
|
|
302
|
+
disable_transitions=disable_transitions,
|
|
303
|
+
excluded_animation_types=excluded_animation_types,
|
|
304
|
+
excluded_transition_kinds=excluded_transition_kinds,
|
|
305
|
+
)
|
|
306
|
+
except Exception as exc:
|
|
307
|
+
return _err(exc)
|
|
308
|
+
|
|
309
|
+
@mcp.tool(title="Create script job")
|
|
310
|
+
def create_script(
|
|
311
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
312
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
313
|
+
prompt: Annotated[str, Field(min_length=1, description="Topic or brief. Cliptude researches and writes spoken narration. Never the video title.")],
|
|
314
|
+
duration: Annotated[
|
|
315
|
+
str | None,
|
|
316
|
+
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template."),
|
|
317
|
+
] = None,
|
|
318
|
+
) -> dict[str, Any]:
|
|
319
|
+
"""Start a script-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read script. Do not use create_job."""
|
|
320
|
+
try:
|
|
321
|
+
return _client().create_job(
|
|
322
|
+
template_id=template_id,
|
|
323
|
+
title=title,
|
|
324
|
+
prompt=prompt,
|
|
325
|
+
duration=duration,
|
|
326
|
+
output="script",
|
|
327
|
+
)
|
|
328
|
+
except Exception as exc:
|
|
329
|
+
return _err(exc)
|
|
330
|
+
|
|
331
|
+
@mcp.tool(title="Create voiceover job")
|
|
332
|
+
def create_voiceover(
|
|
333
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved template UUID")],
|
|
334
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
335
|
+
prompt: Annotated[str | None, Field(description="Topic/brief. Cliptude writes the narration then voices it. Never the video title.")] = None,
|
|
336
|
+
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
95
337
|
duration: Annotated[
|
|
96
338
|
str | None,
|
|
97
339
|
Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script)."),
|
|
98
340
|
] = None,
|
|
99
341
|
) -> dict[str, Any]:
|
|
100
|
-
"""Start
|
|
342
|
+
"""Start a TTS-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read voiceover.url. Provide prompt or script."""
|
|
343
|
+
try:
|
|
344
|
+
if not (prompt or "").strip() and not (script or "").strip():
|
|
345
|
+
return {"error": "Provide prompt or script."}
|
|
346
|
+
return _client().create_job(
|
|
347
|
+
template_id=template_id,
|
|
348
|
+
title=title,
|
|
349
|
+
prompt=prompt,
|
|
350
|
+
script=script,
|
|
351
|
+
duration=duration,
|
|
352
|
+
output="voiceover",
|
|
353
|
+
)
|
|
354
|
+
except Exception as exc:
|
|
355
|
+
return _err(exc)
|
|
356
|
+
|
|
357
|
+
@mcp.tool(title="Continue job into video")
|
|
358
|
+
def continue_job(
|
|
359
|
+
job_id: Annotated[str, Field(min_length=8, description="Completed script or voiceover job UUID, or a plan job with a locked plan")],
|
|
360
|
+
) -> dict[str, Any]:
|
|
361
|
+
"""Queue a completed script or voiceover job, or a plan job whose plan is locked, as a full video on the same id. Poll get_job until completed. Do not create a second job with the script or audio."""
|
|
101
362
|
try:
|
|
363
|
+
return _client().continue_job(job_id)
|
|
364
|
+
except Exception as exc:
|
|
365
|
+
return _err(exc)
|
|
366
|
+
|
|
367
|
+
@mcp.tool(title="Create agent-planned job")
|
|
368
|
+
def create_plan_job(
|
|
369
|
+
template_id: Annotated[str, Field(min_length=8, description="Saved Faceless Documentary, Faceless Top 10 or Avatar Video template UUID")],
|
|
370
|
+
title: Annotated[str, Field(min_length=1, max_length=255, description="Video title")],
|
|
371
|
+
prompt: Annotated[str | None, Field(description="Topic/brief; Cliptude writes the narration. Never the video title.")] = None,
|
|
372
|
+
script: Annotated[str | None, Field(description="Spoken narration to voice as-is. Omit prompt when you pass this.")] = None,
|
|
373
|
+
voiceover_path: Annotated[str | None, Field(description="Local audio file to use as the narration (aligned, not re-voiced). Omit prompt/script.")] = None,
|
|
374
|
+
duration: Annotated[str | None, Field(description="Duration bucket such as 6-8. Omit to use the template.")] = None,
|
|
375
|
+
) -> dict[str, Any]:
|
|
376
|
+
"""Start a job whose visuals YOU plan. Cliptude writes (if needed) and voices the narration, then stops at status plan_ready. It needs the full website price in credits but charges only the narration now; the rest is charged when the video completes, and the total equals the website price. Poll get_job until plan_ready, then get_narration."""
|
|
377
|
+
try:
|
|
378
|
+
if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path:
|
|
379
|
+
return {"error": "Provide prompt, script or voiceover_path."}
|
|
102
380
|
return _client().create_job(
|
|
103
381
|
template_id=template_id,
|
|
104
382
|
title=title,
|
|
105
383
|
prompt=prompt,
|
|
106
384
|
script=script,
|
|
107
|
-
|
|
385
|
+
voiceover_path=voiceover_path,
|
|
108
386
|
duration=duration,
|
|
387
|
+
output="plan",
|
|
109
388
|
)
|
|
110
389
|
except Exception as exc:
|
|
111
390
|
return _err(exc)
|
|
112
391
|
|
|
113
392
|
@mcp.tool(
|
|
114
|
-
title="Get
|
|
393
|
+
title="Get narration",
|
|
115
394
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
116
395
|
)
|
|
117
|
-
def
|
|
118
|
-
job_id: Annotated[str, Field(min_length=8, description="
|
|
396
|
+
def get_narration(
|
|
397
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
119
398
|
) -> dict[str, Any]:
|
|
120
|
-
"""
|
|
399
|
+
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, and pricing (website price, already charged, due at continue)."""
|
|
121
400
|
try:
|
|
122
|
-
return _client().
|
|
401
|
+
return _client().get_narration(job_id)
|
|
123
402
|
except Exception as exc:
|
|
124
403
|
return _err(exc)
|
|
125
404
|
|
|
126
405
|
@mcp.tool(
|
|
127
|
-
title="
|
|
406
|
+
title="Get graphics catalog",
|
|
128
407
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
129
408
|
)
|
|
130
|
-
def
|
|
131
|
-
|
|
409
|
+
def get_kind_catalog(
|
|
410
|
+
format: Annotated[str | None, Field(description="faceless_documentary, faceless_top_10 or avatar_video")] = None,
|
|
411
|
+
theme: Annotated[str | None, Field(description="Visual theme, to mark graphics the theme does not use")] = None,
|
|
412
|
+
compact: Annotated[bool, Field(description="One summary line per graphic (start here; the full catalog is large)")] = True,
|
|
413
|
+
types: Annotated[list[str] | None, Field(description="Full entries (description, prop_schema, media_slots, durations, preview) for just these animation types / overlay styles")] = None,
|
|
414
|
+
premium: Annotated[bool, Field(description="Only the premium boards (marked premium: true)")] = False,
|
|
132
415
|
) -> dict[str, Any]:
|
|
133
|
-
"""
|
|
416
|
+
"""Every motion graphic Cliptude can render: planner kinds, ~360 animation types and 20 overlay text styles. Read compact first, then fetch full entries for the types you intend to use: their props, media slots, hold times, caps and preview video. Entries marked `premium: true` are the premium boards (newest designs, each with its own timed sound cues); premium=true lists only those. Also lists `transitions` (slugs for beats[].transition_in), `reveal_styles` (beats[].reveal_next, with preview videos) and `sounds` (ids for graphic sound, transition_sound, reveal_sound and sfx, with a preview link to each file)."""
|
|
134
417
|
try:
|
|
135
|
-
return _client().
|
|
418
|
+
return _client().get_kind_catalog(format=format, theme=theme, compact=compact and not types, types=types, premium=premium)
|
|
136
419
|
except Exception as exc:
|
|
137
420
|
return _err(exc)
|
|
138
421
|
|
|
139
|
-
@mcp.tool(
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
422
|
+
@mcp.tool(
|
|
423
|
+
title="Check plan",
|
|
424
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
425
|
+
)
|
|
426
|
+
def check_plan(
|
|
427
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
428
|
+
plan: Annotated[dict[str, Any], Field(description="The cliptude.plan/v1 plan object (see the cliptude-plan skill)")],
|
|
429
|
+
) -> dict[str, Any]:
|
|
430
|
+
"""Validate a plan without storing it. Free, no LLM, up to 60 a minute. Returns valid, errors (each with path, code, message, hint), warnings, a scorecard against the reference targets, and the cost due at continue. Fix every error and check again; warnings are advice."""
|
|
431
|
+
try:
|
|
432
|
+
return _client().put_plan(job_id, plan, dry_run=True)
|
|
433
|
+
except Exception as exc:
|
|
434
|
+
return _err(exc)
|
|
435
|
+
|
|
436
|
+
@mcp.tool(title="Lock plan")
|
|
437
|
+
def lock_plan(
|
|
438
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
439
|
+
plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
|
|
143
440
|
) -> dict[str, Any]:
|
|
144
|
-
"""
|
|
441
|
+
"""Validate and store the plan, and apply its look (theme, colours, style, music) to the video. You may lock again to replace it until you call continue_job. Then call continue_job."""
|
|
145
442
|
try:
|
|
146
|
-
return _client().
|
|
443
|
+
return _client().put_plan(job_id, plan, dry_run=False)
|
|
444
|
+
except Exception as exc:
|
|
445
|
+
return _err(exc)
|
|
446
|
+
|
|
447
|
+
@mcp.tool(
|
|
448
|
+
title="Get locked plan",
|
|
449
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
450
|
+
)
|
|
451
|
+
def get_plan(
|
|
452
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID")],
|
|
453
|
+
) -> dict[str, Any]:
|
|
454
|
+
"""The locked plan, its hash and when it was locked."""
|
|
455
|
+
try:
|
|
456
|
+
return _client().get_plan(job_id)
|
|
457
|
+
except Exception as exc:
|
|
458
|
+
return _err(exc)
|
|
459
|
+
|
|
460
|
+
@mcp.tool(
|
|
461
|
+
title="Review the built video",
|
|
462
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
463
|
+
)
|
|
464
|
+
def get_plan_review(
|
|
465
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
|
|
466
|
+
) -> dict[str, Any]:
|
|
467
|
+
"""What the built design shows, before any render: every picture/clip in order (beat, time, the sentence under it, what you asked for, what was used, a link to the file) and every graphic (time on screen and the props it will be drawn with, or why it is missing). Review this, revise with check_plan/lock_plan + continue_job on the same job if needed, then render_project once."""
|
|
468
|
+
try:
|
|
469
|
+
return _client().get_plan_review(job_id)
|
|
470
|
+
except Exception as exc:
|
|
471
|
+
return _err(exc)
|
|
472
|
+
|
|
473
|
+
@mcp.tool(
|
|
474
|
+
title="Get plan sourcing report",
|
|
475
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
476
|
+
)
|
|
477
|
+
def get_plan_report(
|
|
478
|
+
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (after continue_job)")],
|
|
479
|
+
) -> dict[str, Any]:
|
|
480
|
+
"""For each media request in your plan (beat footage, graphic pictures): what was used (source, query, file) or the fallback and why, plus graphics planned vs rendered. Available once the design is built."""
|
|
481
|
+
try:
|
|
482
|
+
return _client().get_plan_report(job_id)
|
|
483
|
+
except Exception as exc:
|
|
484
|
+
return _err(exc)
|
|
485
|
+
|
|
486
|
+
@mcp.tool(
|
|
487
|
+
title="Get job",
|
|
488
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
489
|
+
)
|
|
490
|
+
def get_job(
|
|
491
|
+
job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
|
|
492
|
+
) -> dict[str, Any]:
|
|
493
|
+
"""Job status, progress, error, output url (SaaS) or path (Desktop), and script / voiceover when this was a partial job. can_continue is true when continue_job can turn it into a video."""
|
|
494
|
+
try:
|
|
495
|
+
return _client().get_job(job_id)
|
|
147
496
|
except Exception as exc:
|
|
148
497
|
return _err(exc)
|
|
149
498
|
|
|
@@ -175,6 +524,98 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
175
524
|
except Exception as exc:
|
|
176
525
|
return _err(exc)
|
|
177
526
|
|
|
527
|
+
@mcp.tool(
|
|
528
|
+
title="Open editor project",
|
|
529
|
+
annotations=ToolAnnotations(read_only_hint=False, open_world_hint=False),
|
|
530
|
+
)
|
|
531
|
+
def open_editor_project(
|
|
532
|
+
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
533
|
+
) -> dict[str, Any]:
|
|
534
|
+
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision and a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent."""
|
|
535
|
+
try:
|
|
536
|
+
return _client().open_editor_project(job_id)
|
|
537
|
+
except Exception as exc:
|
|
538
|
+
return _err(exc)
|
|
539
|
+
|
|
540
|
+
@mcp.tool(
|
|
541
|
+
title="Get editor project",
|
|
542
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
543
|
+
)
|
|
544
|
+
def get_editor_project(
|
|
545
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
546
|
+
) -> dict[str, Any]:
|
|
547
|
+
"""Current revision, compact timeline and latest render of an editor project."""
|
|
548
|
+
try:
|
|
549
|
+
return _client().get_editor_project(project_id)
|
|
550
|
+
except Exception as exc:
|
|
551
|
+
return _err(exc)
|
|
552
|
+
|
|
553
|
+
@mcp.tool(title="Run Cliptude Agent")
|
|
554
|
+
def run_agent(
|
|
555
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
556
|
+
prompt: Annotated[str, Field(min_length=1, description="Edit request in plain English")],
|
|
557
|
+
referenced_item_ids: Annotated[
|
|
558
|
+
list[str] | None, Field(description="Timeline item ids the request is about (from the timeline listing)")
|
|
559
|
+
] = None,
|
|
560
|
+
tier: Annotated[str, Field(description="fast or smart")] = "fast",
|
|
561
|
+
chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
|
|
562
|
+
) -> dict[str, Any]:
|
|
563
|
+
"""Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4."""
|
|
564
|
+
try:
|
|
565
|
+
return _client().run_agent(
|
|
566
|
+
project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
|
|
567
|
+
)
|
|
568
|
+
except Exception as exc:
|
|
569
|
+
return _err(exc)
|
|
570
|
+
|
|
571
|
+
@mcp.tool(
|
|
572
|
+
title="Get agent run",
|
|
573
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
574
|
+
)
|
|
575
|
+
def get_agent_run(
|
|
576
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
577
|
+
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
578
|
+
) -> dict[str, Any]:
|
|
579
|
+
"""Status of a Cliptude Agent run plus the agent's messages."""
|
|
580
|
+
try:
|
|
581
|
+
return _client().get_agent_run(project_id, run_id)
|
|
582
|
+
except Exception as exc:
|
|
583
|
+
return _err(exc)
|
|
584
|
+
|
|
585
|
+
@mcp.tool(title="Cancel agent run")
|
|
586
|
+
def cancel_agent_run(
|
|
587
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
588
|
+
run_id: Annotated[str, Field(min_length=8, description="Agent run id")],
|
|
589
|
+
) -> dict[str, Any]:
|
|
590
|
+
"""Cancel a queued or running Cliptude Agent run."""
|
|
591
|
+
try:
|
|
592
|
+
return _client().cancel_agent_run(project_id, run_id)
|
|
593
|
+
except Exception as exc:
|
|
594
|
+
return _err(exc)
|
|
595
|
+
|
|
596
|
+
@mcp.tool(title="Render editor project")
|
|
597
|
+
def render_project(
|
|
598
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
599
|
+
) -> dict[str, Any]:
|
|
600
|
+
"""Render the edited timeline to a new MP4 (charged like an editor export). Poll get_render for output_url."""
|
|
601
|
+
try:
|
|
602
|
+
return _client().render_project(project_id)
|
|
603
|
+
except Exception as exc:
|
|
604
|
+
return _err(exc)
|
|
605
|
+
|
|
606
|
+
@mcp.tool(
|
|
607
|
+
title="Get render",
|
|
608
|
+
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
609
|
+
)
|
|
610
|
+
def get_render(
|
|
611
|
+
render_id: Annotated[int, Field(description="Editor render id")],
|
|
612
|
+
) -> dict[str, Any]:
|
|
613
|
+
"""Status of an editor render; output_url when completed."""
|
|
614
|
+
try:
|
|
615
|
+
return _client().get_render(render_id)
|
|
616
|
+
except Exception as exc:
|
|
617
|
+
return _err(exc)
|
|
618
|
+
|
|
178
619
|
@mcp.tool(
|
|
179
620
|
title="Get account",
|
|
180
621
|
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
|
|
@@ -207,12 +648,107 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
207
648
|
"""Use a saved Cliptude template to generate a video from a topic or a custom script."""
|
|
208
649
|
return (
|
|
209
650
|
"List my Cliptude templates, pick the one I name, then create_job "
|
|
210
|
-
"with title plus prompt (topic)
|
|
651
|
+
"with title plus prompt (topic), script (full narration), "
|
|
652
|
+
"voiceover_path (local audio file), or talking_head_path "
|
|
653
|
+
"(presenter video on a Talking Head template). Poll get_job. "
|
|
654
|
+
"Avatar Video templates expose avatar_intro_only and avatar_ai_footage; "
|
|
655
|
+
"pass them on create_job to override the template."
|
|
211
656
|
)
|
|
212
657
|
|
|
213
658
|
return mcp
|
|
214
659
|
|
|
215
660
|
|
|
661
|
+
def _cors_json(payload: dict[str, Any]):
|
|
662
|
+
from starlette.responses import JSONResponse
|
|
663
|
+
|
|
664
|
+
response = JSONResponse(payload)
|
|
665
|
+
response.headers["Access-Control-Allow-Origin"] = "*"
|
|
666
|
+
response.headers["Access-Control-Allow-Headers"] = "Authorization, Content-Type"
|
|
667
|
+
response.headers["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
|
|
668
|
+
return response
|
|
669
|
+
|
|
670
|
+
|
|
671
|
+
def _discovery_starlette(inner):
|
|
672
|
+
"""Cursor's OAuth callback rediscovers AS via origin-root well-known, not WWW-Authenticate.
|
|
673
|
+
|
|
674
|
+
RFC 9728 path-inserted metadata lives at /.well-known/oauth-protected-resource/mcp.
|
|
675
|
+
Cursor also requests /.well-known/oauth-protected-resource (no /mcp). A 404 there
|
|
676
|
+
makes it treat mcp.cliptude.com as the authorization server and hang on token exchange.
|
|
677
|
+
|
|
678
|
+
The inner Streamable HTTP app's lifespan must be forwarded. Mount() does not
|
|
679
|
+
start it, and without session_manager.run() every POST /mcp raises
|
|
680
|
+
``Task group is not initialized``.
|
|
681
|
+
"""
|
|
682
|
+
from contextlib import asynccontextmanager
|
|
683
|
+
|
|
684
|
+
from starlette.applications import Starlette
|
|
685
|
+
from starlette.responses import Response
|
|
686
|
+
from starlette.routing import Mount, Route
|
|
687
|
+
|
|
688
|
+
from cliptude_mcp.auth import authorization_server_metadata, protected_resource_metadata
|
|
689
|
+
|
|
690
|
+
async def options(_request):
|
|
691
|
+
response = Response(status_code=204)
|
|
692
|
+
response.headers["Access-Control-Allow-Origin"] = "*"
|
|
693
|
+
response.headers["Access-Control-Allow-Headers"] = "Authorization, Content-Type"
|
|
694
|
+
response.headers["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
|
|
695
|
+
return response
|
|
696
|
+
|
|
697
|
+
async def prm(_request):
|
|
698
|
+
return _cors_json(protected_resource_metadata())
|
|
699
|
+
|
|
700
|
+
async def oauth_as(_request):
|
|
701
|
+
return _cors_json(authorization_server_metadata())
|
|
702
|
+
|
|
703
|
+
inner_lifespan = inner.router.lifespan_context
|
|
704
|
+
|
|
705
|
+
@asynccontextmanager
|
|
706
|
+
async def lifespan(app):
|
|
707
|
+
async with inner_lifespan(inner):
|
|
708
|
+
yield
|
|
709
|
+
|
|
710
|
+
return Starlette(
|
|
711
|
+
routes=[
|
|
712
|
+
Route("/.well-known/oauth-protected-resource", prm, methods=["GET"]),
|
|
713
|
+
Route("/.well-known/oauth-protected-resource", options, methods=["OPTIONS"]),
|
|
714
|
+
Route("/.well-known/oauth-authorization-server", oauth_as, methods=["GET"]),
|
|
715
|
+
Route("/.well-known/oauth-authorization-server", options, methods=["OPTIONS"]),
|
|
716
|
+
Mount("/", app=inner),
|
|
717
|
+
],
|
|
718
|
+
lifespan=lifespan,
|
|
719
|
+
)
|
|
720
|
+
|
|
721
|
+
|
|
722
|
+
def _run_http(mcp, host: str, port: int) -> None:
|
|
723
|
+
inner = None
|
|
724
|
+
transport_security = None
|
|
725
|
+
try:
|
|
726
|
+
from mcp.server.transport_security import TransportSecuritySettings
|
|
727
|
+
|
|
728
|
+
transport_security = TransportSecuritySettings(
|
|
729
|
+
enable_dns_rebinding_protection=True,
|
|
730
|
+
allowed_hosts=mcp_allowed_hosts(),
|
|
731
|
+
allowed_origins=mcp_allowed_origins(),
|
|
732
|
+
)
|
|
733
|
+
except ImportError:
|
|
734
|
+
transport_security = None
|
|
735
|
+
for attr in ("streamable_http_app", "http_app"):
|
|
736
|
+
fn = getattr(mcp, attr, None)
|
|
737
|
+
if not callable(fn):
|
|
738
|
+
continue
|
|
739
|
+
try:
|
|
740
|
+
inner = fn(host=host, transport_security=transport_security)
|
|
741
|
+
except TypeError:
|
|
742
|
+
inner = fn()
|
|
743
|
+
break
|
|
744
|
+
if inner is None:
|
|
745
|
+
mcp.run(transport="streamable-http", host=host, port=port)
|
|
746
|
+
return
|
|
747
|
+
import uvicorn
|
|
748
|
+
|
|
749
|
+
uvicorn.run(_discovery_starlette(inner), host=host, port=port)
|
|
750
|
+
|
|
751
|
+
|
|
216
752
|
def main() -> None:
|
|
217
753
|
transport = (os.environ.get("CLIPTUDE_MCP_TRANSPORT") or "stdio").strip().lower()
|
|
218
754
|
http_mode = transport in {"http", "streamable-http", "streamable_http"}
|
|
@@ -221,7 +757,7 @@ def main() -> None:
|
|
|
221
757
|
host = os.environ.get("CLIPTUDE_MCP_HOST", "0.0.0.0")
|
|
222
758
|
port = int(os.environ.get("CLIPTUDE_MCP_PORT") or "8787")
|
|
223
759
|
logger.info("Starting Streamable HTTP MCP on %s:%s", host, port)
|
|
224
|
-
mcp
|
|
760
|
+
_run_http(mcp, host, port)
|
|
225
761
|
return
|
|
226
762
|
mcp.run()
|
|
227
763
|
|