@cliptude/cli 0.1.17 → 0.1.19
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/server.py +92 -17
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/server.py
CHANGED
|
@@ -48,6 +48,74 @@ def _err(exc: Exception) -> dict[str, Any]:
|
|
|
48
48
|
return {"error": str(exc)}
|
|
49
49
|
|
|
50
50
|
|
|
51
|
+
# Fields that make an MCP result too big to read (a 90 minute-class timeline index, per-word timings,
|
|
52
|
+
# whole-voiceover segment arrays) without helping an agent decide anything.
|
|
53
|
+
_BULKY_OPERATION_KEYS = frozenset({
|
|
54
|
+
"voice_segments", "chunk_alignments", "chunk_durations", "voiceover_chunks", "timing_metadata",
|
|
55
|
+
})
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _compact_operation(operation: Any) -> Any:
|
|
59
|
+
if not isinstance(operation, dict):
|
|
60
|
+
return operation
|
|
61
|
+
out: dict[str, Any] = {}
|
|
62
|
+
for key, value in operation.items():
|
|
63
|
+
if key in _BULKY_OPERATION_KEYS and isinstance(value, (list, dict)):
|
|
64
|
+
out[key] = f"<{len(value)} entries omitted>"
|
|
65
|
+
else:
|
|
66
|
+
out[key] = value
|
|
67
|
+
return out
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _compact_agent_run(data: Any) -> Any:
|
|
71
|
+
"""Agent run with the voice-segment arrays of its operations summarised (they repeat in messages)."""
|
|
72
|
+
if not isinstance(data, dict):
|
|
73
|
+
return data
|
|
74
|
+
out = dict(data)
|
|
75
|
+
run = out.get("run")
|
|
76
|
+
if isinstance(run, dict) and isinstance(run.get("applied_operations"), list):
|
|
77
|
+
out["run"] = {**run, "applied_operations": [_compact_operation(op) for op in run["applied_operations"]]}
|
|
78
|
+
messages = out.get("messages")
|
|
79
|
+
if isinstance(messages, list):
|
|
80
|
+
compact_messages = []
|
|
81
|
+
for message in messages:
|
|
82
|
+
if isinstance(message, dict) and isinstance(message.get("metadata"), dict):
|
|
83
|
+
meta = dict(message["metadata"])
|
|
84
|
+
if isinstance(meta.get("operations"), list):
|
|
85
|
+
meta["operations"] = [_compact_operation(op) for op in meta["operations"]]
|
|
86
|
+
message = {**message, "metadata": meta}
|
|
87
|
+
compact_messages.append(message)
|
|
88
|
+
out["messages"] = compact_messages
|
|
89
|
+
return out
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _compact_editor_project(data: Any) -> Any:
|
|
93
|
+
"""Editor project without voice_timing.spokenEventIndex (every word of the narration, 100 KB+)."""
|
|
94
|
+
if not isinstance(data, dict):
|
|
95
|
+
return data
|
|
96
|
+
project = data.get("project")
|
|
97
|
+
if not isinstance(project, dict) or not isinstance(project.get("voice_timing"), dict):
|
|
98
|
+
return data
|
|
99
|
+
timing = project["voice_timing"]
|
|
100
|
+
kept = {k: v for k, v in timing.items() if k != "spokenEventIndex"}
|
|
101
|
+
index = timing.get("spokenEventIndex")
|
|
102
|
+
if isinstance(index, dict) and isinstance(index.get("words"), list):
|
|
103
|
+
kept["spoken_words"] = len(index["words"])
|
|
104
|
+
return {**data, "project": {**project, "voice_timing": kept}}
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _compact_narration(data: Any, *, include_words: bool) -> Any:
|
|
108
|
+
"""Narration sentences without per-word timings unless asked (they are most of the payload)."""
|
|
109
|
+
if include_words or not isinstance(data, dict) or not isinstance(data.get("sentences"), list):
|
|
110
|
+
return data
|
|
111
|
+
sentences = []
|
|
112
|
+
for sentence in data["sentences"]:
|
|
113
|
+
if isinstance(sentence, dict) and "words" in sentence:
|
|
114
|
+
sentence = {k: v for k, v in sentence.items() if k != "words"}
|
|
115
|
+
sentences.append(sentence)
|
|
116
|
+
return {**data, "sentences": sentences, "words_omitted": True}
|
|
117
|
+
|
|
118
|
+
|
|
51
119
|
def mcp_allowed_hosts(resource_url: str | None = None) -> list[str]:
|
|
52
120
|
"""Host header values the Streamable HTTP transport should accept.
|
|
53
121
|
|
|
@@ -140,9 +208,12 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
140
208
|
"plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
|
|
141
209
|
"plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. Before giving the user "
|
|
142
210
|
"the editor link, open_editor_project and look at EVERY frame with view_scenes (0 to the end): replace "
|
|
143
|
-
"any dead body or gore, other brands, logos, game or
|
|
144
|
-
"contradicts the story, and any picture held over ~8 s, in a free revision, then review again. Generic "
|
|
145
|
-
"shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\").
|
|
211
|
+
"any dead body or gore, other brands, logos, album art, footage of a game, match or show the video is not about, title cards, pictures whose place or era "
|
|
212
|
+
"contradicts the story (a search naming a place can return a namesake elsewhere), near-black frames, clips floating in black bars, broken AI pictures and any picture held over ~8 s, in a free revision, then review again. Generic "
|
|
213
|
+
"shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\"). A video "
|
|
214
|
+
"about a video game, sport, creator or TV show searches the real thing (\"GTA 6 gameplay driving\", "
|
|
215
|
+
"\"Bellingham Real Madrid goal\", \"Kai Cenat stream\"): its own footage is the footage, broadcaster and "
|
|
216
|
+
"channel logos included, never real-world stand-ins for it. True "
|
|
146
217
|
"stories (real events and people) set sense.true_story and sense.people and never search for people: a "
|
|
147
218
|
"stranger on screen is taken for the real person (check_plan refuses it, stand_in_person; a dated topic "
|
|
148
219
|
"naming people counts as true unless true_story is false, and its year is the default era). See the "
|
|
@@ -655,7 +726,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
655
726
|
"Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
|
|
656
727
|
"store when it matches."))] = None,
|
|
657
728
|
) -> dict[str, Any]:
|
|
658
|
-
"""Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
|
|
729
|
+
"""Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). When no angles could be suggested the list is empty with an angles_note: pass your own angle (a title, or {title, problem, hook}) to draft_product_script. A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
|
|
659
730
|
try:
|
|
660
731
|
return _client().fetch_product_context(product_url_or_query, store_domain=store_domain)
|
|
661
732
|
except Exception as exc:
|
|
@@ -674,8 +745,9 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
674
745
|
"Length: 6-8, 10-12, 18-20, 30-40 or 50-60 (minutes), or a number of minutes from 6 to 60. "
|
|
675
746
|
"Default 6-8."))] = None,
|
|
676
747
|
template_id: Annotated[str | None, Field(description=(
|
|
677
|
-
"
|
|
678
|
-
"
|
|
748
|
+
"Template to use (voice, look, music): a Faceless Documentary, Top 10 or Avatar Video template "
|
|
749
|
+
"(an Avatar Video one puts the avatar on screen). Omit to use the latest Faceless Documentary one, "
|
|
750
|
+
"or a default Product Explainer template."))] = None,
|
|
679
751
|
title: Annotated[str | None, Field(description="Video title. Defaults to the angle title.")] = None,
|
|
680
752
|
discount_code: Annotated[str | None, Field(description="Discount code the merchant gave. Never invent one.")] = None,
|
|
681
753
|
cta_url: Annotated[str | None, Field(description="Where viewers should go. Defaults to the product page.")] = None,
|
|
@@ -703,7 +775,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
703
775
|
script_id: Annotated[str, Field(min_length=8, description="script_id / job_id from draft_product_script, once script_ready")],
|
|
704
776
|
aspect_ratio: Annotated[str, Field(description="16:9 (YouTube), 9:16, 1:1 or 4:5")] = "16:9",
|
|
705
777
|
) -> dict[str, Any]:
|
|
706
|
-
"""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;
|
|
778
|
+
"""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, credits_reserved, credits} immediately (credits: charged so far, held while it builds, and the full-generation estimate); quote them to the user. Never wait in this call. Poll get_product_video_status."""
|
|
707
779
|
try:
|
|
708
780
|
return _client().render_product_video(script_id, aspect_ratio=aspect_ratio)
|
|
709
781
|
except Exception as exc:
|
|
@@ -716,7 +788,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
716
788
|
def get_product_video_status(
|
|
717
789
|
job_id: Annotated[str, Field(min_length=8, description="Job id from draft_product_script / render_product_video")],
|
|
718
790
|
) -> dict[str, Any]:
|
|
719
|
-
"""Stage of a product video (script_drafting, script_ready, producing, ready_for_review, rendered, failed) with the script once written, the editor_url to preview, the MP4 URL once rendered, and next_step telling you what to do."""
|
|
791
|
+
"""Stage of a product video (script_drafting, script_ready, producing, ready_for_review, rendered, failed) with the script once written, the editor_url to preview, the MP4 URL once rendered, credits {charged, reserved, estimate, estimate_with_buffer} and next_step telling you what to do. The editor's export_credits_due is 0 until a first export exists (the first export of a video is free)."""
|
|
720
792
|
try:
|
|
721
793
|
return _client().get_product_video_status(job_id)
|
|
722
794
|
except Exception as exc:
|
|
@@ -810,10 +882,13 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
810
882
|
)
|
|
811
883
|
def get_narration(
|
|
812
884
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
885
|
+
include_words: Annotated[
|
|
886
|
+
bool, Field(description="Add every word's start/end to each sentence (large: about 10 KB a minute). Phrases in a plan are matched server-side, so leave it off unless you need word times.")
|
|
887
|
+
] = False,
|
|
813
888
|
) -> dict[str, Any]:
|
|
814
|
-
"""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, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
|
|
889
|
+
"""The narration you plan against: numbered sentences with start/end seconds (and every word's timing with include_words), narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
|
|
815
890
|
try:
|
|
816
|
-
return _client().get_narration(job_id)
|
|
891
|
+
return _compact_narration(_client().get_narration(job_id), include_words=include_words)
|
|
817
892
|
except Exception as exc:
|
|
818
893
|
return _err(exc)
|
|
819
894
|
|
|
@@ -1047,7 +1122,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1047
1122
|
) -> dict[str, Any]:
|
|
1048
1123
|
"""Open (or create) the timeline editor project for a completed video job. Returns project id, revision, a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent, and export_credits_due: what render_project would charge now."""
|
|
1049
1124
|
try:
|
|
1050
|
-
return _client().open_editor_project(job_id)
|
|
1125
|
+
return _compact_editor_project(_client().open_editor_project(job_id))
|
|
1051
1126
|
except Exception as exc:
|
|
1052
1127
|
return _err(exc)
|
|
1053
1128
|
|
|
@@ -1060,7 +1135,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1060
1135
|
) -> dict[str, Any]:
|
|
1061
1136
|
"""Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
|
|
1062
1137
|
try:
|
|
1063
|
-
return _client().get_editor_project(project_id)
|
|
1138
|
+
return _compact_editor_project(_client().get_editor_project(project_id))
|
|
1064
1139
|
except Exception as exc:
|
|
1065
1140
|
return _err(exc)
|
|
1066
1141
|
|
|
@@ -1073,7 +1148,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1073
1148
|
start_s: Annotated[float, Field(ge=0, description="First second to show")] = 0.0,
|
|
1074
1149
|
end_s: Annotated[float | None, Field(description="Stop before this second (default: the end)")] = None,
|
|
1075
1150
|
) -> list[str | Image]:
|
|
1076
|
-
"""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."""
|
|
1151
|
+
"""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: REPEATED PICTURE, HELD, AI STILL, DARK, BARS). 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."""
|
|
1077
1152
|
try:
|
|
1078
1153
|
data = _client().view_scenes(project_id, start_s=start_s, end_s=end_s)
|
|
1079
1154
|
except Exception as exc:
|
|
@@ -1097,11 +1172,11 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1097
1172
|
tier: Annotated[str, Field(description="fast or smart")] = "fast",
|
|
1098
1173
|
chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
|
|
1099
1174
|
) -> dict[str, Any]:
|
|
1100
|
-
"""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."""
|
|
1175
|
+
"""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. To use one exact picture (a product cover, a screenshot), paste its https link in the prompt: it is downloaded and applied as is, not searched for. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
|
|
1101
1176
|
try:
|
|
1102
|
-
return _client().run_agent(
|
|
1177
|
+
return _compact_agent_run(_client().run_agent(
|
|
1103
1178
|
project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
|
|
1104
|
-
)
|
|
1179
|
+
))
|
|
1105
1180
|
except Exception as exc:
|
|
1106
1181
|
return _err(exc)
|
|
1107
1182
|
|
|
@@ -1115,7 +1190,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
1115
1190
|
) -> dict[str, Any]:
|
|
1116
1191
|
"""Status of a Cliptude Agent run plus the agent's messages."""
|
|
1117
1192
|
try:
|
|
1118
|
-
return _client().get_agent_run(project_id, run_id)
|
|
1193
|
+
return _compact_agent_run(_client().get_agent_run(project_id, run_id))
|
|
1119
1194
|
except Exception as exc:
|
|
1120
1195
|
return _err(exc)
|
|
1121
1196
|
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED