MCP server for Jianying (剪映) video editing automation, enabling programmatic creation of video drafts with support for video, audio, text, effects, animations, and export functionality
This MCP server exposes 20 video editing tools for the JianYing (剪映) platform via fastmcp. While all tools have names and descriptions, there are substantial gaps in schema completeness, parameter documentation, and error handling guidance. Most tools accept complex parameters (IDs, file paths, format strings) with minimal validation hints or structured constraints. Descriptions are present but often generic (e.g., 'Create a draft' vs. 'Create a new video draft with specified dimensions and frame rate'). No tool annotations (readOnlyHint/destructiveHint/idempotentHint) are visible. Output schemas are not documented in the tool definitions. The server is STDIO-only, which caps protocol readiness at 50 regardless of other factors.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present. The MCP spec recommends these to help agents understand tool safety and retry behavior.
Many tool descriptions are generic or lack context for LLM selection. Examples: 'Create a draft' (create_draft), 'Add animation' (add_video_animation), 'Add filter' (add_video_filter). Descriptions should specify WHAT the tool does, WHEN to use it, and any prerequisites or constraints.
Add tool annotations (readOnlyHint=true/false, destructiveHint=true/false, idempotentHint=true/false) to all tool definitions. Mark read-only tools (rules, find_effects_by_type, parse_media_info) with readOnlyHint=true. Mark write/destructive tools (create_draft, export_draft, all add_* tools) with destructiveHint=true. Mark idempotent operations with idempotentHint=true.
Expand tool descriptions to 150 - 300 characters, following the pattern: 'Verb + what + when. E.g., for add_video_segment: 'Add a video clip to a timeline track, specifying both the source time range (what to extract) and target time range (where to place it). Use for composing multi-clip sequences.'
Define explicit enums for string parameters with known sets: animation_type in add_video_animation (IntroType, OutroType, GroupAnimationType); filling_type in add_video_background_filling (blur, color, mosaic, extended); track_type in create_track (video, audio, text).
Document output schemas for all tools. Example for create_draft: 'Returns {success: bool, data: {draft_id: string, draft_name: string, width: int, height: int, fps: int}, message: string}'. This enables LLM chaining (e.g., draft_id can be passed to create_track).
For time-range parameters (target_start_end, source_start_end), add a formal pattern constraint in schema and a clear description: 'Format: "<start>-<end>" where start and end are in seconds (e.g., '1s', '1.5s', '500ms'). Start must be >= 0 and < end. E.g., '1s-4.2s' means from 1 second to 4.2 seconds.'
Complex parameters like 'target_start_end' (format '1s-4.2s') and 'source_start_end' lack clear format validation guidance in descriptions. LLMs may misinterpret or pass malformed strings. Should include explicit format constraints and examples.
Output schemas are not documented in tool definitions. LLMs cannot plan downstream tool calls or extract required IDs (e.g., 'audio_segment_id' from add_audio_segment) without knowing the response structure.
Error handling code (visible in add_audio_segment and add_audio_effect) does return actionable messages (e.g., 'Invalid status: must be low|medium|high|urgent'), which is good. However, not all tools show equivalent validation. Some tools may fail silently or return generic errors.
Parameters with dependent constraints (e.g., 'filling_type' in add_video_background_filling determines which of 'blur', 'color', 'mosaic_size' params apply) are documented inline but could be clearer. Should state: 'filling_type=color requires color param; filling_type=blur requires blur param.'
Several tools accept 'object' or 'array' parameters with minimal schema detail (e.g., 'clip_settings: object', 'border: object', 'params: array'). These should define the internal structure, field types, and allowed keys.
For complex object parameters (clip_settings, style, border, background), document their internal fields. Example: 'clip_settings: {brightness: number 0-100, contrast: number 0-100, saturation: number 0-100}'.
Add validation error examples to descriptions where applicable. E.g., for speed: 'Must be > 0. Example invalid values: 0, -1.5 (LLM learns to avoid these).'
Ensure all error paths return ToolResponse with success=false and a message that guides the LLM toward recovery. Example: 'Draft not found. Verify draft_id is correct, or call create_draft to make a new draft first.'
Consolidate tools where LLMs might conflate them. E.g., add_video_animation, add_video_transition, and add_video_effect overlap in purpose. Consider naming them more distinctly: apply_intro_animation, apply_transition_effect, apply_special_effect.
Document parameter dependencies explicitly. E.g., for add_video_background_filling: 'If filling_type=blur, blur param is required (0-1). If filling_type=color, color param is required (hex string #RRGGBB). If filling_type=mosaic, mosaic_size param is required (0-1). Mutually exclusive, only one filling_type applies per call.'