Jenkins MCP Tool

Instructions

Implementation Reference

• src/jenkins/tools/mcp_tools.py:104-173 (handler)

  The main MCP handler for the 'trigger_build' tool. It handles parameter validation, logging via context, checks for required job parameters, and delegates the actual build trigger to JenkinsAPIClient.trigger_build.
  @mcp.tool() def trigger_build( server_name: str, job_full_name: str, params: Any = None, ctx: Context = None ) -> TriggerResult: """Trigger Jenkins job build. Automatically determines parameter requirements and waits to obtain build_number. Args: server_name: Jenkins server name job_full_name: Full job name params: Optional parameter dict ctx: MCP context (for logging) Returns: Dict containing build_number or queue_id Raises: JenkinsParameterError: Missing required parameters JenkinsError: Trigger failed """ client = JenkinsAPIClient(server_name) # Parameter type conversion build_params: ParameterDict = {} if params: if isinstance(params, dict): build_params = params else: # Try to convert other types try: build_params = dict(params) except (TypeError, ValueError): if ctx: ctx.log( "warning", f"Invalid params type: {type(params)}, ignoring parameters", ) build_params = {} # Check required parameters job_params = client.get_job_parameters(job_full_name) if job_params: required_params = [p for p in job_params if p["default"] is None] missing_params = [] for param in required_params: if not build_params or param["name"] not in build_params: missing_params.append(param) if missing_params: # Build detailed error message param_details = [] for param in missing_params: detail = f"{param['name']} (type: {param['type']}, default: {param['default']}" if param.get("choices"): detail += f", choices: {param['choices']}" detail += ")" param_details.append(detail) error_msg = f"This job requires required parameters, please provide them before execution. Missing parameters: {', '.join(param_details)}" raise JenkinsParameterError(error_msg, [p["name"] for p in missing_params]) if ctx: ctx.log("info", f"Triggering build for {job_full_name} on {server_name}") if build_params: ctx.log("debug", f"Build parameters: {build_params}") return client.trigger_build(job_full_name, build_params)
• src/jenkins/tools/client.py:247-290 (helper)

  The helper method in JenkinsAPIClient that performs the actual HTTP POST request to trigger the Jenkins build, handles parameterized vs non-parameterized builds, extracts queue ID, and waits for the build to start.
  def trigger_build( self, job_full_name: str, params: Optional[ParameterDict] = None ) -> TriggerResult: """Trigger build. Args: job_full_name: Full job name params: Build parameters Returns: Trigger result Raises: JenkinsError: Trigger failed """ job_url = self._build_job_url(job_full_name) # Check job parameters job_params = self.get_job_parameters(job_full_name) if job_params: # Parameterized build build_url = f"{job_url}/buildWithParameters" build_params = params or {} else: # Non-parameterized build build_url = f"{job_url}/build" build_params = {} response = self._make_request("POST", build_url, params=build_params) response.raise_for_status() # Get queue location queue_location = response.headers.get("Location", "") queue_id = None if queue_location: match = re.search(r"/queue/item/(\d+)/", queue_location) if match: queue_id = int(match.group(1)) # Wait for build to start return self._wait_for_build_start(queue_id, queue_location)
• src/jenkins/tools/types.py:112-121 (schema)

  Type definition (TypedDict) for the TriggerResult returned by trigger_build, defining the output schema.
  class TriggerResult(TypedDict): """Trigger build result.""" status: Literal["BUILD_STARTED", "QUEUED"] build_number: Optional[int] build_url: Optional[str] queue_id: Optional[int] queue_url: Optional[str] message: Optional[str]
• src/jenkins/tools/__init__.py:4-4 (registration)

  Import statement that loads all @mcp.tool() decorated functions from mcp_tools.py, thereby registering the 'trigger_build' tool with the MCP server.
  from .mcp_tools import * # noqa