create_engagement

Instructions

Implementation Reference

• src/defectdojo/engagements_tools.py:63-121 (handler)

  The primary handler function for the 'create_engagement' MCP tool. It validates input parameters, constructs the API payload, calls the DefectDojo client to create the engagement, and returns a structured success/error response.

  async def create_engagement(product_id: int, name: str, target_start: str, target_end: str, status: str, lead_id: int = None, description: str = None, version: str = None, build_id: str = None, commit_hash: str = None, branch_tag: str = None, engagement_type: str = None, deduplication_on_engagement: bool = None, tags: list = None):
      """
      Creates a new engagement in DefectDojo.
  
      Args:
          product_id: ID of the product.
          name: Name of the engagement.
          target_start: Start date (YYYY-MM-DD).
          target_end: End date (YYYY-MM-DD).
          status: Engagement status ('Not Started', 'Blocked', 'Cancelled', 'Completed', 'In Progress', 'On Hold', 'Waiting for Resource').
          lead_id: Optional ID of the engagement lead (user ID).
          description: Optional engagement description.
          version: Optional product version tested.
          build_id: Optional build ID.
          commit_hash: Optional commit hash.
          branch_tag: Optional branch or tag.
          engagement_type: Optional engagement type ('Interactive' or 'CI/CD').
          deduplication_on_engagement: Optional flag to enable deduplication within this engagement.
          tags: Optional list of tags.
  
      Returns:
          JSON response from the API.
      """
      # endpoint = "/api/v2/engagements/" # Endpoint handled by client method
      valid_statuses = ["Not Started", "Blocked", "Cancelled", "Completed", "In Progress", "On Hold", "Waiting for Resource"]
      if status not in valid_statuses:
          # Use raise ValueError for internal validation errors
          raise ValueError(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"]:
           raise ValueError(f"Invalid engagement_type '{engagement_type}'. Must be 'Interactive' or 'CI/CD'.")
  
      data = {
          "product": product_id,
          "name": name,
          "target_start": target_start,
          "target_end": target_end,
          "status": status, # Use API expected casing directly
      }
      # Add optional fields cleanly
      if lead_id is not None: data["lead"] = lead_id
      if description is not None: data["description"] = description
      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 # Assumes API accepts list directly
  
      client = get_client()
      result = await client.create_engagement(data)
  
      # Return structured response
      if "error" in result:
          return {"status": "error", "error": result["error"], "details": result.get("details", "")}
  
      return {"status": "success", "data": result}

• src/defectdojo/tools.py:74-78 (registration)

  Main registration of the 'create_engagement' tool using mcp.tool() in the central tools.py registration function. Imports the handler from engagements_tools.py.

  mcp.tool(
      name="create_engagement",
      description="Create a new engagement in DefectDojo"
      # Schema inferred from type hints and docstring
  )(create_engagement)

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

  Modular registration function in engagements_tools.py that registers the 'create_engagement' tool (along with related engagement tools). This may be called internally or for testing.

  def register_tools(mcp):
      """Register engagement-related tools with the MCP server instance."""
      mcp.tool(name="list_engagements", description="List engagements with optional filtering and pagination support")(list_engagements)
      mcp.tool(name="get_engagement", description="Get a specific engagement by ID")(get_engagement)
      mcp.tool(name="create_engagement", description="Create a new engagement")(create_engagement)
      mcp.tool(name="update_engagement", description="Update an existing engagement")(update_engagement)
      mcp.tool(name="close_engagement", description="Close an engagement")(close_engagement)

• src/defectdojo/client.py:78-80 (helper)

  Helper method in DefectDojoClient that performs the actual HTTP POST request to create an engagement. Called by the tool handler.

  async def create_engagement(self, data: Dict[str, Any]) -> Dict[str, Any]:
      """Create a new engagement."""
      return await self._request("POST", "/api/v2/engagements/", json=data)