stop_build
Stop Jenkins builds on specific servers, handle permission errors, and verify termination status. Input server name, job name, and build number to ensure precise control over CI/CD processes.
Instructions
Stop Jenkins build.
Intelligently handles permission errors and will automatically check build status to confirm if it has already been terminated.
Args:
server_name: Jenkins server name
job_full_name: Full job name
build_number: Build number
ctx: MCP context (for logging)
Returns:
Stop result
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| build_number | Yes | ||
| job_full_name | Yes | ||
| server_name | Yes |
Implementation Reference
- src/jenkins/tools/mcp_tools.py:191-233 (handler)MCP tool handler for the 'stop_build' tool. It is decorated with @mcp.tool() for registration, creates a JenkinsAPIClient, performs logging via context, calls the underlying client.stop_build method, handles results with additional logging, and returns StopResult.@mcp.tool() def stop_build( server_name: str, job_full_name: str, build_number: int, ctx: Context = None ) -> StopResult: """Stop Jenkins build. Intelligently handles permission errors and will automatically check build status to confirm if it has already been terminated. Args: server_name: Jenkins server name job_full_name: Full job name build_number: Build number ctx: MCP context (for logging) Returns: Stop result """ client = JenkinsAPIClient(server_name) if ctx: ctx.log( "info", f"Stopping build #{build_number} for {job_full_name} on {server_name}", ) try: result = client.stop_build(job_full_name, build_number) if ctx: if result["status"] == "ALREADY_TERMINATED": ctx.log("info", "Build was already terminated") elif result["status"] == "STOP_REQUESTED": ctx.log("info", "Stop request sent successfully") elif result["status"] == "NOT_FOUND": ctx.log("warning", "Build not found") return result except Exception as e: if ctx: ctx.log("error", f"Failed to stop build: {e}") raise
- src/jenkins/tools/types.py:123-127 (schema)Output schema definition for the stop_build tool using TypedDict, defining the status (enum-like) and optional URL.class StopResult(TypedDict): """Stop build result.""" status: Literal["STOP_REQUESTED", "ALREADY_TERMINATED", "NOT_FOUND"] url: Optional[str]
- src/jenkins/tools/client.py:418-445 (helper)Helper method in JenkinsAPIClient that implements the core logic for stopping a Jenkins build via API POST to /stop endpoint, handles 404 (not found), 403 (permission, delegates to status check), and returns StopResult.def stop_build(self, job_full_name: str, build_number: int) -> StopResult: """Stop build. Args: job_full_name: Full job name build_number: Build number Returns: Stop result Raises: JenkinsError: Stop failed """ job_url = self._build_job_url(job_full_name) stop_url = f"{job_url}/{build_number}/stop" response = self._make_request("POST", stop_url) if response.status_code == 404: return {"status": "NOT_FOUND", "url": None} if response.status_code == 403: # Permission error, check build status return self._handle_stop_permission_error(job_full_name, build_number) response.raise_for_status() return {"status": "STOP_REQUESTED", "url": stop_url}
- src/jenkins/tools/client.py:446-473 (helper)Supporting helper method called on permission errors during stop_build, polls build status up to 10 times to check if already terminated.def _handle_stop_permission_error( self, job_full_name: str, build_number: int ) -> StopResult: """Handle permission error when stopping build. Args: job_full_name: Full job name build_number: Build number Returns: Stop result """ # Loop to check build status, confirm if already terminated for attempt in range(10): try: build_info = self.get_build_status(job_full_name, build_number) if not build_info.get("building", True): return {"status": "ALREADY_TERMINATED", "url": None} except (JenkinsBuildNotFoundError, JenkinsError): # Build not found or query failed, consider as terminated return {"status": "ALREADY_TERMINATED", "url": None} if attempt < 9: time.sleep(1) # Still building after 10 checks, raise permission error raise JenkinsPermissionError("stop build", f"{job_full_name}#{build_number}")