@cliptude/cli 0.1.13 → 0.1.15
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/cli.py +3 -1
- package/cliptude_mcp/client.py +10 -2
- package/cliptude_mcp/server.py +42 -11
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/cli.py
CHANGED
|
@@ -525,6 +525,8 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
525
525
|
rn = sub.add_parser("render", help="Render an edited project to a new MP4")
|
|
526
526
|
rn.add_argument("project_id")
|
|
527
527
|
rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
|
|
528
|
+
rn.add_argument("--accept-quality-findings", action="store_true",
|
|
529
|
+
help="Agent-planned jobs: render although plan-review still lists plan quality findings")
|
|
528
530
|
|
|
529
531
|
rs = sub.add_parser("render-status", help="Get an editor render (output_url when done)")
|
|
530
532
|
rs.add_argument("render_id")
|
|
@@ -760,7 +762,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
760
762
|
elif args.cmd == "agent-tiers":
|
|
761
763
|
_print(client.agent_tiers())
|
|
762
764
|
elif args.cmd == "render":
|
|
763
|
-
payload = client.render_project(args.project_id)
|
|
765
|
+
payload = client.render_project(args.project_id, accept_quality_findings=args.accept_quality_findings)
|
|
764
766
|
if args.wait:
|
|
765
767
|
render_id = (payload.get("render") or {}).get("id")
|
|
766
768
|
payload = _wait(lambda: client.get_render(render_id), lambda p: (p.get("render") or {}).get("status"))
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -860,6 +860,13 @@ class CliptudeClient:
|
|
|
860
860
|
params = {"design": "1"} if design else None
|
|
861
861
|
return self.request("GET", f"/api/v1/editor-projects/{project_id}", params=params)
|
|
862
862
|
|
|
863
|
+
def view_scenes(self, project_id: int | str, *, start_s: float = 0.0, end_s: float | None = None) -> Any:
|
|
864
|
+
"""Contact sheets (base64 JPEG) of the timeline's pictures, clip frames and graphics, with a legend."""
|
|
865
|
+
params: dict[str, Any] = {"start_s": start_s}
|
|
866
|
+
if end_s is not None:
|
|
867
|
+
params["end_s"] = end_s
|
|
868
|
+
return self.request("GET", f"/api/v1/editor-projects/{project_id}/scenes", params=params)
|
|
869
|
+
|
|
863
870
|
def agent_tiers(self) -> Any:
|
|
864
871
|
return self.request("GET", "/api/v1/agent/tiers")
|
|
865
872
|
|
|
@@ -897,9 +904,10 @@ class CliptudeClient:
|
|
|
897
904
|
def cancel_agent_run(self, project_id: int | str, run_id: str) -> Any:
|
|
898
905
|
return self.request("POST", f"/api/v1/editor-projects/{project_id}/agent/runs/{run_id}/cancel")
|
|
899
906
|
|
|
900
|
-
def render_project(self, project_id: int | str) -> Any:
|
|
907
|
+
def render_project(self, project_id: int | str, *, accept_quality_findings: bool = False) -> Any:
|
|
901
908
|
"""Render the edited timeline to a new MP4: free the first time, then 10% of the original generation."""
|
|
902
|
-
|
|
909
|
+
body = {"accept_quality_findings": True} if accept_quality_findings else None
|
|
910
|
+
return self.request("POST", f"/api/v1/editor-projects/{project_id}/render", json_body=body)
|
|
903
911
|
|
|
904
912
|
def get_render(self, render_id: int | str) -> Any:
|
|
905
913
|
return self.request("GET", f"/api/v1/editor-renders/{render_id}")
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -2,11 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
+
import base64
|
|
6
|
+
import json
|
|
5
7
|
import logging
|
|
6
8
|
import os
|
|
7
9
|
import sys
|
|
8
10
|
from typing import Annotated, Any
|
|
9
11
|
|
|
12
|
+
from mcp.server.mcpserver import Image
|
|
10
13
|
from pydantic import Field
|
|
11
14
|
|
|
12
15
|
from cliptude_mcp.client import CliptudeApiError, CliptudeClient, set_request_token
|
|
@@ -119,6 +122,8 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
119
122
|
"prompt/script/voiceover_path (template format must be talking_head). "
|
|
120
123
|
"Avatar Video: list_avatars gives avatar ids; put one in create_template settings as "
|
|
121
124
|
"avatar_profile_id (with the voice), or pass avatar_profile_id on create_job to override. "
|
|
125
|
+
"Before you create a template or job with an avatar, show the user its thumbnail_url and name and "
|
|
126
|
+
"wait for them to confirm it is the presenter they want (names repeat; the avatar is paid for). "
|
|
122
127
|
"Avatar Video templates may include avatar_intro_only "
|
|
123
128
|
"(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
|
|
124
129
|
"on create_job to override the template, or omit them to keep the template. "
|
|
@@ -127,11 +132,13 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
127
132
|
"plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
|
|
128
133
|
"plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
|
|
129
134
|
"cliptude-plan skill. "
|
|
130
|
-
"PRODUCT VIDEOS (
|
|
135
|
+
"PRODUCT VIDEOS (the user's connected store, or a product page from a store they sell for): "
|
|
131
136
|
"fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
|
|
132
137
|
"duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
|
|
133
|
-
"review the script, render_product_video
|
|
134
|
-
"
|
|
138
|
+
"review the script, render_product_video (this starts the build, not the final MP4), poll until "
|
|
139
|
+
"ready_for_review, open_editor_project and look at every picture and graphic yourself with "
|
|
140
|
+
"view_scenes (contact sheets; media links may not open for you), give the user editor_url, and only after they approve render with "
|
|
141
|
+
"render_project + get_render. "
|
|
135
142
|
"Never publish anything to a store or YouTube without the user's explicit go-ahead."
|
|
136
143
|
),
|
|
137
144
|
}
|
|
@@ -308,7 +315,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
308
315
|
limit: Annotated[int, Field(ge=1, le=100)] = 50,
|
|
309
316
|
offset: Annotated[int, Field(ge=0)] = 0,
|
|
310
317
|
) -> dict[str, Any]:
|
|
311
|
-
"""Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice."""
|
|
318
|
+
"""Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice. Show the user the thumbnail_url and name and get their OK before you spend credits on it: several avatars share a name."""
|
|
312
319
|
try:
|
|
313
320
|
return _client().list_avatars(section=section, search=search, gender=gender, limit=limit, offset=offset)
|
|
314
321
|
except Exception as exc:
|
|
@@ -584,8 +591,8 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
584
591
|
)
|
|
585
592
|
def fetch_product_context(
|
|
586
593
|
product_url_or_query: Annotated[str, Field(min_length=1, description=(
|
|
587
|
-
"A product page URL
|
|
588
|
-
"
|
|
594
|
+
"A product page URL from the user's own store (Shopify, e.g. https://store.com/products/handle; "
|
|
595
|
+
"WooCommerce or Etsy work through the page's structured data), a connected store's "
|
|
589
596
|
"product id/handle, or a search term together with store_domain."))],
|
|
590
597
|
store_domain: Annotated[str | None, Field(description=(
|
|
591
598
|
"Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
|
|
@@ -639,7 +646,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
639
646
|
script_id: Annotated[str, Field(min_length=8, description="script_id / job_id from draft_product_script, once script_ready")],
|
|
640
647
|
aspect_ratio: Annotated[str, Field(description="16:9 (YouTube), 9:16, 1:1 or 4:5")] = "16:9",
|
|
641
648
|
) -> dict[str, Any]:
|
|
642
|
-
"""
|
|
649
|
+
"""Start BUILDING the video from the approved script on the same job id: voiceover, sourcing, motion graphics, and the merchant's real product photos composited into the closing product boards. This does not render the final MP4: when the build is done (ready_for_review) review it, show the user the editor_url and wait for their go-ahead before render_project. Returns {job_id, status, stage, editor_url, estimated_minutes} immediately; never wait in this call. Poll get_product_video_status."""
|
|
643
650
|
try:
|
|
644
651
|
return _client().render_product_video(script_id, aspect_ratio=aspect_ratio)
|
|
645
652
|
except Exception as exc:
|
|
@@ -808,7 +815,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
808
815
|
def get_plan_review(
|
|
809
816
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
|
|
810
817
|
) -> dict[str, Any]:
|
|
811
|
-
"""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).
|
|
818
|
+
"""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), plus quality_findings: Cliptude's quality checks on the build. Fix every finding with fix_in "plan" (follow its how); fix_in "cliptude" ones are not yours. Revise with check_plan/lock_plan + continue_job on the same job, review again, then render_project once (it refuses while plan findings remain unless accept_quality_findings is true)."""
|
|
812
819
|
try:
|
|
813
820
|
return _client().get_plan_review(job_id)
|
|
814
821
|
except Exception as exc:
|
|
@@ -990,6 +997,26 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
990
997
|
except Exception as exc:
|
|
991
998
|
return _err(exc)
|
|
992
999
|
|
|
1000
|
+
@mcp.tool(
|
|
1001
|
+
title="View scenes",
|
|
1002
|
+
annotations=ToolAnnotations(title="View scenes", read_only_hint=True, open_world_hint=False),
|
|
1003
|
+
)
|
|
1004
|
+
def view_scenes(
|
|
1005
|
+
project_id: Annotated[int, Field(description="Editor project id")],
|
|
1006
|
+
start_s: Annotated[float, Field(ge=0, description="First second to show")] = 0.0,
|
|
1007
|
+
end_s: Annotated[float | None, Field(description="Stop before this second (default: the end)")] = None,
|
|
1008
|
+
) -> list[str | Image]:
|
|
1009
|
+
"""See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
|
|
1010
|
+
try:
|
|
1011
|
+
data = _client().view_scenes(project_id, start_s=start_s, end_s=end_s)
|
|
1012
|
+
except Exception as exc:
|
|
1013
|
+
return [json.dumps(_err(exc))]
|
|
1014
|
+
sheets = data.pop("sheets", None) or []
|
|
1015
|
+
out: list[str | Image] = [json.dumps(data, ensure_ascii=False)]
|
|
1016
|
+
for sheet in sheets:
|
|
1017
|
+
out.append(Image(data=base64.b64decode(sheet["jpeg_base64"]), format="jpeg"))
|
|
1018
|
+
return out
|
|
1019
|
+
|
|
993
1020
|
@mcp.tool(
|
|
994
1021
|
title="Run Cliptude Agent",
|
|
995
1022
|
annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=False),
|
|
@@ -1003,7 +1030,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1003
1030
|
tier: Annotated[str, Field(description="fast or smart")] = "fast",
|
|
1004
1031
|
chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
|
|
1005
1032
|
) -> dict[str, Any]:
|
|
1006
|
-
"""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."""
|
|
1033
|
+
"""Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
|
|
1007
1034
|
try:
|
|
1008
1035
|
return _client().run_agent(
|
|
1009
1036
|
project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
|
|
@@ -1045,10 +1072,14 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1045
1072
|
)
|
|
1046
1073
|
def render_project(
|
|
1047
1074
|
project_id: Annotated[int, Field(description="Editor project id")],
|
|
1075
|
+
accept_quality_findings: Annotated[
|
|
1076
|
+
bool,
|
|
1077
|
+
Field(description="Agent-planned jobs only: render although get_plan_review still lists quality_findings with fix_in \"plan\". Set it only after trying to fix them, or when the user says to ship as is."),
|
|
1078
|
+
] = False,
|
|
1048
1079
|
) -> dict[str, Any]:
|
|
1049
|
-
"""Render the edited timeline to a new MP4. The first export of a project is free; later exports cost 10% of the original generation (export_credits_due on the project says the exact amount). Poll get_render for output_url."""
|
|
1080
|
+
"""Render the edited timeline to a new MP4. The first export of a project is free; later exports cost 10% of the original generation (export_credits_due on the project says the exact amount). Poll get_render for output_url. On an agent-planned job, a build with quality_findings the plan can fix returns 409 quality_findings_open: revise the plan and review again first."""
|
|
1050
1081
|
try:
|
|
1051
|
-
return _client().render_project(project_id)
|
|
1082
|
+
return _client().render_project(project_id, accept_quality_findings=accept_quality_findings)
|
|
1052
1083
|
except Exception as exc:
|
|
1053
1084
|
return _err(exc)
|
|
1054
1085
|
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED