Upload 214 files

renderer_app.py

@@ -15,6 +15,11 @@ from renderer.studio import capability_catalog
 from renderer.templates import apply_creative_style, apply_preset, list_creative_styles, list_platform_profiles, list_templates
 
 
+def _mcp_description(summary: str, example: dict[str, Any]) -> str:
+    """Build a concise MCP description with a machine-readable JSON example."""
+    return f"{summary} Example JSON: {json.dumps(example, separators=(',', ':'), ensure_ascii=True)}"
+
+
 def create_dashboard() -> gr.Blocks:
     with gr.Blocks(title="Ava2lon Studio AI") as dashboard:
         gr.Markdown(
@@ -27,8 +32,8 @@ def create_dashboard() -> gr.Blocks:
             project_create = gr.Button("Create Project", variant="primary")
             project_list = gr.Button("Refresh Projects")
             project_output = gr.JSON(label="Projects")
-            project_create.click(fn=_create_project, inputs=[project_name, project_metadata], outputs=project_output)
-            project_list.click(fn=_list_projects, outputs=project_output)
+            project_create.click(fn=create_project, inputs=[project_name, project_metadata], outputs=project_output, api_name="create_project", api_description=_mcp_description("Create a project from a name and JSON metadata object.", {"name": "Campaign 01", "metadata_json": '{"platform":"tiktok"}'}))
+            project_list.click(fn=list_projects, outputs=project_output, api_name="list_projects", api_description=_mcp_description("List saved studio projects.", {}))
 
         with gr.Tab("Assets"):
             gr.Markdown("Use `/upload` or `/assets/upload` for multipart assets, then attach them to a project with `/project/assets/add`.")
@@ -36,7 +41,7 @@ def create_dashboard() -> gr.Blocks:
             asset_json = gr.Textbox(label="Asset JSON", lines=6, value=json.dumps({"path": "clip.mp4", "kind": "video"}, indent=2))
             asset_button = gr.Button("Attach Asset", variant="primary")
             asset_output = gr.JSON(label="Project")
-            asset_button.click(fn=_add_project_asset, inputs=[asset_project_id, asset_json], outputs=asset_output)
+            asset_button.click(fn=add_project_asset, inputs=[asset_project_id, asset_json], outputs=asset_output, api_name="add_project_asset", api_description=_mcp_description("Attach a media asset JSON object to an existing project.", {"project_id": "project_123", "asset_json": '{"path":"clip.mp4","kind":"video"}'}))
 
         with gr.Tab("Timeline"):
             timeline_project_id = gr.Textbox(label="Project ID")
@@ -48,7 +53,7 @@ def create_dashboard() -> gr.Blocks:
             )
             timeline_add_button = gr.Button("Add To Timeline", variant="primary")
             timeline_output = gr.JSON(label="Project")
-            timeline_add_button.click(fn=_timeline_add, inputs=[timeline_project_id, timeline_track_type, timeline_item], outputs=timeline_output)
+            timeline_add_button.click(fn=add_timeline_item, inputs=[timeline_project_id, timeline_track_type, timeline_item], outputs=timeline_output, api_name="add_timeline_item", api_description=_mcp_description("Add a typed item to a project timeline.", {"project_id": "project_123", "track_type": "video", "item_json": '{"media":"clip.mp4","start":0,"duration":5,"caption":"Hook"}'}))
 
             timeline_operation_json = gr.Textbox(
                 label="Operation JSON",
@@ -56,40 +61,40 @@ def create_dashboard() -> gr.Blocks:
                 value=json.dumps({"operation": "split", "item_id": "clip_123", "params": {"offset": 2.5}}, indent=2),
             )
             timeline_operation_button = gr.Button("Apply Operation")
-            timeline_operation_button.click(fn=_timeline_operation, inputs=[timeline_project_id, timeline_operation_json], outputs=timeline_output)
+            timeline_operation_button.click(fn=apply_timeline_operation, inputs=[timeline_project_id, timeline_operation_json], outputs=timeline_output, api_name="apply_timeline_operation", api_description=_mcp_description("Apply a timeline operation such as split, trim, insert, or ripple delete.", {"project_id": "project_123", "operation_json": '{"operation":"split","item_id":"clip_123","params":{"offset":2.5}}'}))
 
         with gr.Tab("Templates"):
             template_button = gr.Button("Load Template Catalog")
             template_output = gr.JSON(label="Templates")
-            template_button.click(fn=lambda: _catalog_section("templates"), outputs=template_output)
+            template_button.click(fn=load_template_catalog, outputs=template_output, api_name="load_template_catalog", api_description=_mcp_description("Load available render and caption templates.", {}))
 
         with gr.Tab("Effects"):
             effect_button = gr.Button("Load Effect Catalog")
             effect_output = gr.JSON(label="Effects")
-            effect_button.click(fn=lambda: _catalog_section("effects"), outputs=effect_output)
+            effect_button.click(fn=load_effect_catalog, outputs=effect_output, api_name="load_effect_catalog", api_description=_mcp_description("Load available video effects.", {}))
 
         with gr.Tab("Filters"):
             filter_button = gr.Button("Load Filter Catalog")
             filter_output = gr.JSON(label="Filters")
-            filter_button.click(fn=lambda: _catalog_section("filters"), outputs=filter_output)
+            filter_button.click(fn=load_filter_catalog, outputs=filter_output, api_name="load_filter_catalog", api_description=_mcp_description("Load available video filters.", {}))
 
         with gr.Tab("Captions"):
             caption_text = gr.Textbox(label="Caption source text", lines=6)
             caption_button = gr.Button("Submit Caption Job", variant="primary")
             caption_output = gr.JSON(label="Caption Job")
-            caption_button.click(fn=_submit_caption_generation, inputs=caption_text, outputs=caption_output)
+            caption_button.click(fn=submit_caption_job, inputs=caption_text, outputs=caption_output, api_name="submit_caption_job", api_description=_mcp_description("Submit a caption-generation job from source text.", {"text": "Launch faster with automated rendering."}))
 
         with gr.Tab("Audio"):
             audio_button = gr.Button("Load Audio Catalog")
             audio_output = gr.JSON(label="Audio")
-            audio_button.click(fn=lambda: {"audio": capability_catalog()["audio"], "music": capability_catalog()["music_generator"]}, outputs=audio_output)
+            audio_button.click(fn=load_audio_catalog, outputs=audio_output, api_name="load_audio_catalog", api_description=_mcp_description("Load audio-processing and music-generation capabilities.", {}))
 
         with gr.Tab("AI Tools"):
             ai_tool = gr.Dropdown(choices=capability_catalog()["ai_editing"], value="auto_viral_score", label="AI tool")
             ai_payload = gr.Textbox(label="AI payload JSON", lines=8, value=json.dumps({"platform": "tiktok", "text": "A strong opening hook"}, indent=2))
             ai_button = gr.Button("Submit AI Tool", variant="primary")
             ai_output = gr.JSON(label="AI Job")
-            ai_button.click(fn=_submit_ai_tool, inputs=[ai_tool, ai_payload], outputs=ai_output)
+            ai_button.click(fn=submit_ai_tool, inputs=[ai_tool, ai_payload], outputs=ai_output, api_name="submit_ai_tool", api_description=_mcp_description("Submit a configured AI editing tool job.", {"tool": "auto_viral_score", "payload": '{"platform":"tiktok","text":"A strong opening hook"}'}))
 
         with gr.Tab("Rendering"):
             render_json = gr.Textbox(
@@ -100,7 +105,7 @@ def create_dashboard() -> gr.Blocks:
             )
             render_button = gr.Button("Submit Render", variant="primary")
             render_output = gr.JSON(label="Submission")
-            render_button.click(fn=_submit_render_json, inputs=render_json, outputs=render_output)
+            render_button.click(fn=submit_render_job, inputs=render_json, outputs=render_output, api_name="submit_render_job", api_description=_mcp_description("Submit a validated JSON video render job.", {"payload": '{"scenes":[{"start":0,"duration":5,"media":"clip.mp4","caption":"Opening hook"}],"platform":"tiktok","output_name":"render.mp4"}'}))
 
         with gr.Tab("AI Reels"):
             script = gr.Textbox(label="Script", lines=6)
@@ -112,31 +117,31 @@ def create_dashboard() -> gr.Blocks:
             music = gr.File(label="Background Music", file_types=["audio"], type="filepath")
             ai_button = gr.Button("Submit AI Reel", variant="primary")
             ai_output = gr.JSON(label="Submission")
-            ai_button.click(fn=_submit_ai_reel, inputs=[script, voiceover, assets, template, creative_style, platform, music], outputs=ai_output)
+            ai_button.click(fn=submit_ai_reel, inputs=[script, voiceover, assets, template, creative_style, platform, music], outputs=ai_output, api_name="submit_ai_reel", api_description=_mcp_description("Create an AI reel from a script, voiceover, and visual assets. Upload files first and use the returned paths.", {"script": "Three automation tips.", "voiceover": "/tmp/voice.wav", "assets": ["/tmp/a.jpg", "/tmp/b.mp4"], "template": "tiktok_classic", "creative_style": "viral_shorts", "platform": "tiktok", "music": None}))
 
         with gr.Tab("Batch Render"):
             batch_json = gr.Textbox(label="Batch JSON", lines=14, value=json.dumps({"jobs": []}, indent=2))
             batch_button = gr.Button("Submit Batch", variant="primary")
             batch_output = gr.JSON(label="Batch Submission")
-            batch_button.click(fn=_submit_batch_json, inputs=batch_json, outputs=batch_output)
+            batch_button.click(fn=submit_batch_render, inputs=batch_json, outputs=batch_output, api_name="submit_batch_render", api_description=_mcp_description("Submit multiple render jobs from a JSON batch.", {"payload": '{"jobs":[{"scenes":[{"start":0,"duration":3,"media":"clip.mp4"}],"output_name":"clip-a.mp4"}]}'}))
 
         with gr.Tab("Job Status"):
             status_job_id = gr.Textbox(label="Job ID")
             status_button = gr.Button("Refresh")
             status_output = gr.JSON(label="Status")
-            status_button.click(fn=_job_status, inputs=status_job_id, outputs=status_output)
+            status_button.click(fn=get_job_status, inputs=status_job_id, outputs=status_output, api_name="get_job_status", api_description=_mcp_description("Retrieve the current state and metrics for a job.", {"job_id": "job_abc123"}))
 
         with gr.Tab("Logs"):
             logs_job_id = gr.Textbox(label="Job ID")
             logs_button = gr.Button("Load Logs")
             logs_output = gr.Textbox(label="Logs", lines=20)
-            logs_button.click(fn=_job_logs, inputs=logs_job_id, outputs=logs_output)
+            logs_button.click(fn=get_job_logs, inputs=logs_job_id, outputs=logs_output, api_name="get_job_logs", api_description=_mcp_description("Retrieve execution logs for a job.", {"job_id": "job_abc123"}))
 
         with gr.Tab("Downloads"):
             download_job_id = gr.Textbox(label="Job ID")
             download_button = gr.Button("Get Output")
             download_output = gr.File(label="Rendered Video")
-            download_button.click(fn=_download_path, inputs=download_job_id, outputs=download_output)
+            download_button.click(fn=get_download_path, inputs=download_job_id, outputs=download_output, api_name="get_download_path", api_description=_mcp_description("Return the completed artifact path for a job.", {"job_id": "job_abc123"}))
 
         with gr.Tab("Transcribe"):
             transcribe_audio = gr.File(label="Audio or Video", file_types=["audio", "video"], type="filepath")
@@ -149,16 +154,18 @@ def create_dashboard() -> gr.Blocks:
             transcribe_button = gr.Button("Transcribe", variant="primary")
             transcribe_output = gr.JSON(label="Transcript")
             transcribe_button.click(
-                fn=_transcribe_file,
+                fn=transcribe_audio_file,
                 inputs=[transcribe_audio, transcribe_model, transcribe_language],
                 outputs=transcribe_output,
+                api_name="transcribe_audio_file",
+                api_description=_mcp_description("Transcribe an uploaded audio or video file with word timestamps. Upload the file first and use its returned path.", {"path": "/tmp/interview.mp3", "model_size": "tiny", "language": "en"}),
             )
 
         with gr.Tab("Asset Inspector"):
             asset_path = gr.Textbox(label="Asset path")
             inspect_button = gr.Button("Inspect")
             inspect_output = gr.JSON(label="Metadata")
-            inspect_button.click(fn=_inspect_asset, inputs=asset_path, outputs=inspect_output)
+            inspect_button.click(fn=inspect_media_asset, inputs=asset_path, outputs=inspect_output, api_name="inspect_media_asset", api_description=_mcp_description("Inspect media codecs, streams, duration, and dimensions.", {"path": "/app/storage/video.mp4"}))
 
         with gr.Tab("AI Analysis"):
             analysis_media = gr.Textbox(label="Media URL or path")
@@ -167,9 +174,11 @@ def create_dashboard() -> gr.Blocks:
             analysis_button = gr.Button("Submit Analysis", variant="primary")
             analysis_output = gr.JSON(label="Analysis Job")
             analysis_button.click(
-                fn=_submit_analysis,
+                fn=submit_media_analysis,
                 inputs=[analysis_media, analysis_transcript, analysis_platform],
                 outputs=analysis_output,
+                api_name="submit_media_analysis",
+                api_description=_mcp_description("Analyze media for highlights, pacing, platform fit, and engagement signals.", {"media": "https://example.com/video.mp4", "transcript": "A strong opening hook and useful explanation.", "platform": "tiktok"}),
             )
 
         with gr.Tab("Clip Generator"):
@@ -177,14 +186,14 @@ def create_dashboard() -> gr.Blocks:
             clip_json = gr.Textbox(label="Clip JSON", lines=6, value=json.dumps([{"start": 0, "end": 8}], indent=2))
             clip_button = gr.Button("Generate Clips", variant="primary")
             clip_output = gr.JSON(label="Clip Job")
-            clip_button.click(fn=_submit_clips, inputs=[clip_media, clip_json], outputs=clip_output)
+            clip_button.click(fn=submit_clip_job, inputs=[clip_media, clip_json], outputs=clip_output, api_name="submit_clip_job", api_description=_mcp_description("Generate one or more clips from media and timed clip JSON.", {"media": "https://example.com/video.mp4", "clips_json": '[{"start":0,"end":8},{"start":20,"end":32}]'}))
 
         with gr.Tab("Metadata"):
             metadata_topic = gr.Textbox(label="Topic or transcript", lines=5)
             metadata_platform = gr.Dropdown(choices=list_platform_profiles(), value="tiktok", label="Platform")
             metadata_button = gr.Button("Generate Metadata", variant="primary")
             metadata_output = gr.JSON(label="Metadata Job")
-            metadata_button.click(fn=_submit_metadata, inputs=[metadata_topic, metadata_platform], outputs=metadata_output)
+            metadata_button.click(fn=submit_metadata_job, inputs=[metadata_topic, metadata_platform], outputs=metadata_output, api_name="submit_metadata_job", api_description=_mcp_description("Generate platform-aware title, description, hashtags, and chapters.", {"topic": "Five n8n video automation mistakes", "platform": "youtube_shorts"}))
 
         with gr.Tab("Publishing"):
             publish_media = gr.Textbox(label="Media URL or rendered output path")
@@ -192,46 +201,52 @@ def create_dashboard() -> gr.Blocks:
             publish_platforms = gr.Textbox(label="Platforms", value="youtube,tiktok,instagram")
             publish_button = gr.Button("Create Publish Draft", variant="primary")
             publish_output = gr.JSON(label="Publish Job")
-            publish_button.click(fn=_submit_publish, inputs=[publish_media, publish_title, publish_platforms], outputs=publish_output)
+            publish_button.click(fn=create_publish_draft, inputs=[publish_media, publish_title, publish_platforms], outputs=publish_output, api_name="create_publish_draft", api_description=_mcp_description("Create a publishing draft for one or more platforms.", {"media": "/app/exports/render.mp4", "title": "Automation Tips", "platforms": "youtube,tiktok,instagram"}))
 
         with gr.Tab("Settings"):
             settings_button = gr.Button("Load Settings")
             settings_output = gr.JSON(label="Settings")
-            settings_button.click(fn=_settings_payload, outputs=settings_output)
+            settings_button.click(fn=get_runtime_settings, outputs=settings_output, api_name="get_runtime_settings", api_description=_mcp_description("Return renderer configuration and runtime capability settings.", {}))
 
         with gr.Tab("Queue Monitor"):
             queue_button = gr.Button("Refresh Queue")
             queue_output = gr.JSON(label="Queue")
-            queue_button.click(fn=_queue_status, outputs=queue_output)
+            queue_button.click(fn=get_queue_status, outputs=queue_output, api_name="get_queue_status", api_description=_mcp_description("Return queue counts and active render jobs.", {}))
 
     return dashboard
 
 
-def _submit_render_json(payload: str) -> dict[str, Any]:
+def submit_render_job(payload: str) -> dict[str, Any]:
+    """Submit a validated JSON timeline for asynchronous video rendering."""
     data = apply_creative_style(apply_preset(json.loads(payload)))
     request = Timeline.request_from_payload(data)
     job_id = job_manager.submit_render(request)
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _create_project(name: str, metadata_json: str) -> dict[str, Any]:
+def create_project(name: str, metadata_json: str) -> dict[str, Any]:
+    """Create a persistent studio project with optional JSON metadata."""
     metadata = json.loads(metadata_json or "{}")
     return {"project": project_manager.create(name, metadata=metadata)}
 
 
-def _list_projects() -> dict[str, Any]:
+def list_projects() -> dict[str, Any]:
+    """List all persistent studio projects."""
     return {"projects": project_manager.list()}
 
 
-def _add_project_asset(project_id: str, asset_json: str) -> dict[str, Any]:
+def add_project_asset(project_id: str, asset_json: str) -> dict[str, Any]:
+    """Attach a media asset JSON object to an existing project."""
     return {"project": project_manager.add_asset(project_id, json.loads(asset_json or "{}"))}
 
 
-def _timeline_add(project_id: str, track_type: str, item_json: str) -> dict[str, Any]:
+def add_timeline_item(project_id: str, track_type: str, item_json: str) -> dict[str, Any]:
+    """Add a JSON item to a video, audio, text, overlay, sticker, or subtitle track."""
     return {"project": project_manager.add_to_timeline(project_id, json.loads(item_json or "{}"), track_type=track_type)}
 
 
-def _timeline_operation(project_id: str, operation_json: str) -> dict[str, Any]:
+def apply_timeline_operation(project_id: str, operation_json: str) -> dict[str, Any]:
+    """Apply a JSON timeline operation such as split, trim, insert, or ripple delete."""
     data = json.loads(operation_json or "{}")
     return {
         "project": project_manager.timeline_operation(
@@ -248,14 +263,37 @@ def _catalog_section(section: str) -> dict[str, Any]:
     return {section: catalog.get(section)}
 
 
-def _submit_caption_generation(text: str) -> dict[str, Any]:
+def load_template_catalog() -> dict[str, Any]:
+    """Return available render and caption template capabilities."""
+    return _catalog_section("templates")
+
+
+def load_effect_catalog() -> dict[str, Any]:
+    """Return available video effect capabilities."""
+    return _catalog_section("effects")
+
+
+def load_filter_catalog() -> dict[str, Any]:
+    """Return available video filter capabilities."""
+    return _catalog_section("filters")
+
+
+def load_audio_catalog() -> dict[str, Any]:
+    """Return audio-processing and music-generation capabilities."""
+    catalog = capability_catalog()
+    return {"audio": catalog["audio"], "music": catalog["music_generator"]}
+
+
+def submit_caption_job(text: str) -> dict[str, Any]:
+    """Submit an asynchronous caption-generation job from source text."""
     from renderer.studio import StudioTaskProcessor
 
     job_id = job_manager.submit_task(lambda task_id, log: StudioTaskProcessor(settings, log=log).caption_generate({"text": text}, task_id))
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _submit_ai_tool(tool: str, payload: str) -> dict[str, Any]:
+def submit_ai_tool(tool: str, payload: str) -> dict[str, Any]:
+    """Submit an AI editing tool using its name and a JSON payload."""
     from renderer.studio import StudioTaskProcessor
 
     data = json.loads(payload or "{}")
@@ -263,13 +301,14 @@ def _submit_ai_tool(tool: str, payload: str) -> dict[str, Any]:
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _submit_batch_json(payload: str) -> dict[str, Any]:
+def submit_batch_render(payload: str) -> dict[str, Any]:
+    """Submit multiple asynchronous render jobs from a JSON jobs array."""
     data = json.loads(payload)
     requests = [Timeline.request_from_payload(apply_creative_style(apply_preset(job))) for job in data.get("jobs", [])]
     return {"job_ids": job_manager.submit_batch(requests)}
 
 
-def _submit_ai_reel(
+def submit_ai_reel(
     script: str,
     voiceover: str,
     assets: list[str],
@@ -278,6 +317,7 @@ def _submit_ai_reel(
     platform: str,
     music: str | None,
 ) -> dict[str, Any]:
+    """Create an AI reel from a script, voiceover, visual assets, style, and music."""
     request = AIReelsRequest(
         script=script,
         voiceover=voiceover,
@@ -291,26 +331,31 @@ def _submit_ai_reel(
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _job_status(job_id: str) -> dict[str, Any]:
+def get_job_status(job_id: str) -> dict[str, Any]:
+    """Return state, metrics, artifact metadata, and errors for a job ID."""
     return job_manager.get(job_id).__dict__
 
 
-def _job_logs(job_id: str) -> str:
+def get_job_logs(job_id: str) -> str:
+    """Return execution log messages for a job ID."""
     return "\n\n".join(job_manager.get(job_id).logs)
 
 
-def _download_path(job_id: str) -> str | None:
+def get_download_path(job_id: str) -> str | None:
+    """Return the local artifact path when a job has completed."""
     record = job_manager.get(job_id)
     if record.state != "COMPLETED":
         return None
     return record.output_path
 
 
-def _inspect_asset(path: str) -> dict[str, Any]:
+def inspect_media_asset(path: str) -> dict[str, Any]:
+    """Inspect a local media asset for streams, codecs, duration, and dimensions."""
     return RenderEngine(settings).inspect_asset(path)
 
 
-def _transcribe_file(path: str, model_size: str, language: str) -> dict[str, Any]:
+def transcribe_audio_file(path: str, model_size: str, language: str) -> dict[str, Any]:
+    """Transcribe an uploaded audio or video file with optional language selection."""
     return RenderEngine(settings).transcribe(
         path,
         model_size=model_size,
@@ -319,7 +364,8 @@ def _transcribe_file(path: str, model_size: str, language: str) -> dict[str, Any
     )
 
 
-def _submit_analysis(media: str, transcript: str, platform: str) -> dict[str, Any]:
+def submit_media_analysis(media: str, transcript: str, platform: str) -> dict[str, Any]:
+    """Analyze media for highlights, pacing, retention, engagement, and platform fit."""
     from renderer.platform import PlatformProcessor
 
     job_id = job_manager.submit_task(
@@ -328,7 +374,8 @@ def _submit_analysis(media: str, transcript: str, platform: str) -> dict[str, An
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _submit_clips(media: str, clips_json: str) -> dict[str, Any]:
+def submit_clip_job(media: str, clips_json: str) -> dict[str, Any]:
+    """Generate timed clips from a media path or URL and a JSON clip specification."""
     from renderer.platform import PlatformProcessor
 
     clips = json.loads(clips_json)
@@ -336,14 +383,16 @@ def _submit_clips(media: str, clips_json: str) -> dict[str, Any]:
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _submit_metadata(topic: str, platform: str) -> dict[str, Any]:
+def submit_metadata_job(topic: str, platform: str) -> dict[str, Any]:
+    """Generate platform-aware title, description, hashtags, keywords, and chapters."""
     from renderer.platform import PlatformProcessor
 
     job_id = job_manager.submit_task(lambda task_id, log: PlatformProcessor(settings, log=log).metadata(task_id, topic=topic, platform=platform))
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _submit_publish(media: str, title: str, platforms: str) -> dict[str, Any]:
+def create_publish_draft(media: str, title: str, platforms: str) -> dict[str, Any]:
+    """Create an asynchronous publishing draft for comma-separated platforms."""
     from renderer.platform import PlatformProcessor
 
     payload = {"media": media, "title": title, "platforms": [item.strip() for item in platforms.split(",") if item.strip()], "draft": True}
@@ -351,11 +400,13 @@ def _submit_publish(media: str, title: str, platforms: str) -> dict[str, Any]:
     return {"job_id": job_id, "status": f"/status/{job_id}", "download": f"/download/{job_id}"}
 
 
-def _queue_status() -> dict[str, Any]:
+def get_queue_status() -> dict[str, Any]:
+    """Return queue totals, state counts, worker limits, and active jobs."""
     return job_manager.summary()
 
 
-def _settings_payload() -> dict[str, Any]:
+def get_runtime_settings() -> dict[str, Any]:
+    """Return renderer paths, worker settings, Whisper settings, and capabilities."""
     return {
         "product": "Ava2lon Studio AI",
         "base_dir": str(settings.base_dir),

tests/test_mcp_metadata.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import ast
+import json
+import unittest
+from pathlib import Path
+
+
+class MCPMetadataTests(unittest.TestCase):
+    def test_every_dashboard_tool_has_public_name_and_description(self) -> None:
+        tree = ast.parse(Path("renderer_app.py").read_text(encoding="utf-8-sig"))
+        functions = {
+            node.name: node
+            for node in tree.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        }
+        events = [
+            node
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "click"
+        ]
+
+        self.assertEqual(len(events), 25)
+        for event in events:
+            keywords = {item.arg: item.value for item in event.keywords if item.arg}
+            callback = keywords.get("fn")
+            self.assertIsInstance(callback, ast.Name, "MCP callbacks must be named functions")
+            callback_name = callback.id
+            self.assertFalse(callback_name.startswith("_"), f"Private MCP callback: {callback_name}")
+            self.assertIn(callback_name, functions)
+            self.assertTrue(ast.get_docstring(functions[callback_name]), f"Missing docstring: {callback_name}")
+
+            api_name = keywords.get("api_name")
+            description = keywords.get("api_description")
+            self.assertIsInstance(api_name, ast.Constant, f"Missing api_name: {callback_name}")
+            self.assertTrue(api_name.value, f"Empty api_name: {callback_name}")
+            self.assertIsInstance(description, ast.Call, f"Missing structured api_description: {callback_name}")
+            self.assertIsInstance(description.func, ast.Name)
+            self.assertEqual(description.func.id, "_mcp_description")
+            self.assertEqual(len(description.args), 2)
+
+            summary = ast.literal_eval(description.args[0])
+            example = ast.literal_eval(description.args[1])
+            self.assertTrue(summary, f"Empty description: {callback_name}")
+            self.assertIsInstance(example, dict, f"Example must be an object: {callback_name}")
+            encoded = json.dumps(example, separators=(",", ":"), ensure_ascii=True)
+            self.assertEqual(json.loads(encoded), example)
+
+            parameters = [argument.arg for argument in functions[callback_name].args.args]
+            self.assertEqual(set(example), set(parameters), f"Example keys do not match: {callback_name}")
+
+
+if __name__ == "__main__":
+    unittest.main()