update_engagement

Instructions

Implementation Reference

• src/defectdojo/engagements_tools.py:124-196 (handler)

  The primary handler for the 'update_engagement' MCP tool. Validates inputs, constructs PATCH data from optional parameters, invokes the DefectDojo client API call, and formats the response.

  async def update_engagement(engagement_id: int, name: Optional[str] = None,
                             target_start: Optional[str] = None, # Renamed from start_date
                             target_end: Optional[str] = None,   # Renamed from end_date
                             status: Optional[str] = None,
                             description: Optional[str] = None,
                             # Add other updatable fields from API schema if needed
                             lead_id: Optional[int] = None,
                             version: Optional[str] = None,
                             build_id: Optional[str] = None,
                             commit_hash: Optional[str] = None,
                             branch_tag: Optional[str] = None,
                             engagement_type: Optional[str] = None,
                             deduplication_on_engagement: Optional[bool] = None,
                             tags: Optional[list] = None
                             ) -> Dict[str, Any]:
      """Update an existing engagement. Only provided fields are updated.
  
      Args:
          engagement_id: ID of the engagement to update.
          name: Optional new name.
          target_start: Optional new start date (YYYY-MM-DD).
          target_end: Optional new end date (YYYY-MM-DD).
          status: Optional new status ('Not Started', 'Blocked', 'Cancelled', 'Completed', 'In Progress', 'On Hold', 'Waiting for Resource').
          description: Optional new description.
          lead_id: Optional new lead ID.
          version: Optional new version.
          build_id: Optional new build ID.
          commit_hash: Optional new commit hash.
          branch_tag: Optional new branch/tag.
          engagement_type: Optional new engagement type ('Interactive', 'CI/CD').
          deduplication_on_engagement: Optional new deduplication setting.
          tags: Optional new list of tags (will replace existing tags).
  
      Returns:
          Dictionary with status and data/error.
      """
      # Validate status if provided
      if status:
          valid_statuses = ["Not Started", "Blocked", "Cancelled", "Completed", "In Progress", "On Hold", "Waiting for Resource"]
          if status not in valid_statuses:
               return {"status": "error", "error": f"Invalid status '{status}'. Must be one of: {', '.join(valid_statuses)}"}
  
      # Validate engagement_type if provided
      if engagement_type and engagement_type not in ["Interactive", "CI/CD"]:
           return {"status": "error", "error": f"Invalid engagement_type '{engagement_type}'. Must be 'Interactive' or 'CI/CD'."}
  
      # Prepare data payload with only provided fields
      data = {}
      if name is not None: data["name"] = name
      if target_start is not None: data["target_start"] = target_start
      if target_end is not None: data["target_end"] = target_end
      if status is not None: data["status"] = status # Send as is after validation
      if description is not None: data["description"] = description
      if lead_id is not None: data["lead"] = lead_id
      if version is not None: data["version"] = version
      if build_id is not None: data["build_id"] = build_id
      if commit_hash is not None: data["commit_hash"] = commit_hash
      if branch_tag is not None: data["branch_tag"] = branch_tag
      if engagement_type is not None: data["engagement_type"] = engagement_type
      if deduplication_on_engagement is not None: data["deduplication_on_engagement"] = deduplication_on_engagement
      if tags is not None: data["tags"] = tags # PATCH usually replaces arrays
  
      # If no fields were provided, return an error
      if not data:
          return {"status": "error", "error": "At least one field must be provided for update"}
  
      client = get_client()
      result = await client.update_engagement(engagement_id, data)
  
      if "error" in result:
          return {"status": "error", "error": result["error"], "details": result.get("details", "")}
  
      return {"status": "success", "data": result}

• src/defectdojo/tools.py:80-83 (registration)

  Registration of the update_engagement tool handler using the FastMCP decorator in the central tools.py module, which aggregates all tools.

  mcp.tool(
      name="update_engagement",
      description="Update an existing engagement"
  )(update_engagement)

• src/defectdojo/engagements_tools.py:232-232 (registration)

  Modular registration of the tool within the engagements_tools.py module's register_tools function.

  mcp.tool(name="update_engagement", description="Update an existing engagement")(update_engagement)

• src/defectdojo/client.py:82-84 (helper)

  Underlying DefectDojoClient method that executes the HTTP PATCH request to the DefectDojo API for updating an engagement.

  async def update_engagement(self, engagement_id: int, data: Dict[str, Any]) -> Dict[str, Any]:
      """Update an existing engagement."""
      return await self._request("PATCH", f"/api/v2/engagements/{engagement_id}/", json=data)