@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.
@@ -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
- "Generate Cliptude videos from a saved template. "
45
- "Call list_templates, then create_job with template_id + title + prompt or script. "
46
- "create_job returns immediately; poll get_job until completed or failed. "
47
- "If the user pastes a full narration, pass it as script, not prompt."
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. Cliptude writes the narration.")] = None,
90
- script: Annotated[str | None, Field(description="Custom spoken narration. Cliptude does not rewrite it.")] = None,
91
- faceless_coding: Annotated[
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(description='Use "external" for Faceless Explainer BYO HTML. Omit for Cliptude coding.'),
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 generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt and/or script."""
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
- faceless_coding=faceless_coding,
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 job",
393
+ title="Get narration",
115
394
  annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
116
395
  )
117
- def get_job(
118
- job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
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
- """Job status, progress, error, and output url (SaaS) or path (Desktop)."""
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().get_job(job_id)
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="Download coding kit",
406
+ title="Get graphics catalog",
128
407
  annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
129
408
  )
130
- def download_coding_kit(
131
- job_id: Annotated[str, Field(min_length=8, description="Job UUID")],
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
- """Return coding_kit url or path after awaiting_project. Never returns zip bytes. Do not wait for the MP4."""
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().download_coding_kit(job_id)
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(title="Submit Faceless project")
140
- def submit_faceless_project(
141
- job_id: Annotated[str, Field(min_length=8, description="Job UUID")],
142
- zip_path: Annotated[str, Field(min_length=1, description="Local path to the project zip")],
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
- """Upload a local Faceless project zip (storyboard.json + frames). Returns 202. Poll get_job. Do not wait for the MP4."""
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().submit_faceless_project(job_id, zip_path)
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) or script (full narration). Poll get_job."
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.run(transport="streamable-http", host=host, port=port)
760
+ _run_http(mcp, host, port)
225
761
  return
226
762
  mcp.run()
227
763