Jenkins MCP Tool

Instructions

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

Implementation Reference

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

  MCP tool handler for 'trigger_build': validates job parameters, handles logging via context, and delegates to Jenkins client.

  @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)

  Low-level JenkinsAPIClient.trigger_build method: performs HTTP POST to Jenkins API to queue the build and waits for it 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-120 (schema)

  TypedDict schema defining the return type TriggerResult for the trigger_build tool.

  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/server.py:93-97 (registration)

  Implicit registration via import of jenkins.tools module (which imports mcp_tools.py) after FastMCP server creation.

  import jenkins.tools  # noqa
  import jenkins.resources  # noqa
  import jenkins.prompts  # noqa