JianYing MCP

Instructions

Implementation Reference

• jianyingdraft/tool/video_tool.py:615-708 (handler)

  The primary MCP tool handler for 'add_video_effect'. It validates parameters, verifies effect existence using JianYingResourceManager, resolves draft_id and track_name from index_manager, and delegates execution to the service layer.

  @mcp.tool()
  def add_video_effect(
          video_segment_id: str,
          effect_type: str,
          params: Optional[List[Optional[float]]] = None
  ) -> ToolResponse:
      """
      为视频片段添加特效
  
      Args:
          video_segment_id: 视频片段ID，通过add_video_segment获得
          effect_type: 特效类型名称，可以使用find_effects_by_type工具，资源类型选择VIDEO_SCENE、VIDEO_CHARACTER，从而获取特效类型有哪些
          params: 特效参数列表（可选），参数范围0-100，具体参数数量和含义取决于特效类型
      """
      # 参数验证
      if params:
          for i, param in enumerate(params):
              if param is not None and not (0.0 <= param <= 100.0):
                  return ToolResponse(
                      success=False,
                      message=f"参数{i + 1}超出范围，必须在0-100之间，当前值: {param}"
                  )
  
      # 特效存在性验证 - 先在 VIDEO_SCENE 中查找
      effects = manager.find_by_type(
          effect_type="VIDEO_SCENE",
          keyword=effect_type,
          limit=1
      )
  
      # 如果在 VIDEO_SCENE 中没找到，再在 VIDEO_CHARACTER 中查找
      if not effects:
          effects = manager.find_by_type(
              effect_type="VIDEO_CHARACTER",
              keyword=effect_type,
              limit=1
          )
  
      # 检查是否找到完全匹配的特效
      exact_match = False
      if effects:
          for effect in effects:
              if effect.get('name') == effect_type:
                  exact_match = True
                  break
  
      if not effects or not exact_match:
          # 获取建议特效
          scene_suggestions = manager.find_by_type("VIDEO_SCENE", keyword=effect_type)
          char_suggestions = manager.find_by_type("VIDEO_CHARACTER", keyword=effect_type)
  
          all_suggestions = []
          for effect in scene_suggestions + char_suggestions:
              if effect.get('name'):
                  all_suggestions.append(effect.get('name'))
  
          return ToolResponse(
              success=False,
              message=f"未找到特效 '{effect_type}'，请确认名称是否正确，或使用建议名称",
              data={
                  "error_type": "effect_not_found",
                  "effect_name": effect_type,
                  "suggestions": all_suggestions
              }
          )
  
      # 通过video_segment_id获取相关信息
      draft_id = index_manager.get_draft_id_by_video_segment_id(video_segment_id)
      track_info = index_manager.get_track_info_by_video_segment_id(video_segment_id)
  
      if not draft_id:
          return ToolResponse(
              success=False,
              message=f"未找到视频片段ID对应的草稿: {video_segment_id}"
          )
  
      if not track_info:
          return ToolResponse(
              success=False,
              message=f"未找到视频片段ID对应的轨道信息: {video_segment_id}"
          )
  
      track_name = track_info.get("track_name")
  
      # 调用服务层处理业务逻辑
      result = add_video_effect_service(
          draft_id=draft_id,
          video_segment_id=video_segment_id,
          effect_type=effect_type,
          params=params,
          track_name=track_name
      )
  
      return result

• jianyingdraft/services/video_service.py:576-646 (helper)

  Helper service function that instantiates VideoSegment for the given draft and segment, applies the effect via video_segment.add_effect(), and wraps the result in ToolResponse.

  def add_video_effect_service(
      draft_id: str,
      video_segment_id: str,
      effect_type: str,
      params: Optional[List[Optional[float]]] = None,
      track_name: Optional[str] = None
  ) -> ToolResponse:
      """
      视频特效添加服务 - 为视频片段添加特效
  
      Args:
          draft_id: 草稿ID
          video_segment_id: 视频片段ID
          effect_type: 特效类型名称，如 "1998", "70s", "CCD闪光" 等
          params: 特效参数列表，参数范围0-100（可选）
          track_name: 轨道名称（可选）
  
      Returns:
          ToolResponse: 包含操作结果的响应对象
      """
      try:
          # 创建VideoSegment实例，传入video_segment_id
          video_segment = VideoSegment(draft_id, video_segment_id=video_segment_id, track_name=track_name)
  
          # 调用视频特效添加方法
          result_data = video_segment.add_effect(
              effect_type=effect_type,
              params=params
          )
  
          # 构建返回数据
          response_data = {
              "video_segment_id": video_segment_id,
              "draft_id": draft_id,
              "effect_type": effect_type,
              "add_effect": result_data
          }
  
          # 添加可选参数到返回数据
          if params:
              response_data["params"] = params
          if track_name:
              response_data["track_name"] = track_name
  
          return ToolResponse(
              success=True,
              message=f"视频特效添加成功: {effect_type}",
              data=response_data
          )
  
      except ValueError as e:
          # 处理参数错误
          return ToolResponse(
              success=False,
              message=f"参数错误: {str(e)}"
          )
  
      except NameError as e:
          # 处理轨道不存在错误
          return ToolResponse(
              success=False,
              message=f"轨道错误: {str(e)}"
          )
  
      except Exception as e:
          # 处理其他未预期的错误
          return ToolResponse(
              success=False,
              message=f"视频特效添加失败: {str(e)}"
          )

• jianyingdraft/server.py:28-28 (registration)

  Registration of video tools (including add_video_effect) by calling video_tools(mcp) in the main server setup.

  video_tools(mcp)