DefectDojo MCP Server

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)