Jenkins MCP Tool

Instructions

Note: For deployment tasks, it is recommended to use get_scenario_list() and search_jobs_by_scenario().

Args:
    server_name: Jenkins server name
    keyword: Search keyword

Returns:
    List of matching jobs

Implementation Reference

• src/jenkins/tools/mcp_tools.py:72-87 (handler)

  The MCP tool handler for 'search_jobs', decorated with @mcp.tool(). It takes server_name and keyword, creates a JenkinsAPIClient instance, and delegates to its search_jobs method to perform the search.

  @mcp.tool()
  def search_jobs(server_name: str, keyword: str) -> List[JobInfo]:
      """Search Jenkins jobs on the specified server.
  
      Note: For deployment tasks, it is recommended to use get_scenario_list() and search_jobs_by_scenario().
  
      Args:
          server_name: Jenkins server name
          keyword: Search keyword
  
      Returns:
          List of matching jobs
      """
      client = JenkinsAPIClient(server_name)
      return client.search_jobs(keyword)

• src/jenkins/tools/client.py:501-535 (helper)

  Core implementation of search_jobs in JenkinsAPIClient class. Fetches the jobs tree from Jenkins API (up to 4 nested levels), recursively collects all jobs, filters those matching the keyword in name or fullName (case-insensitive), retrieves detailed JobInfo for matches using get_job_info, and returns the list.

  def search_jobs(self, keyword: str) -> List[JobInfo]:
      """Search jobs.
  
      Args:
          keyword: Search keyword
  
      Returns:
          List of matching jobs
  
      Raises:
          JenkinsError: API request failed
      """
      api_url = (
          f"{self._client.base_url}/api/json?tree=jobs[name,url,fullName,"
          "jobs[name,url,fullName,jobs[name,url,fullName,jobs[name,url,fullName]]]]"
      )
  
      response = self._make_request("GET", api_url)
      response.raise_for_status()
  
      data = response.json()
      all_jobs = self._collect_all_jobs(data.get("jobs", []))
  
      # Filter matching jobs
      matching_jobs = []
      for job in all_jobs:
          if (
              keyword.lower() in job["name"].lower()
              or keyword.lower() in job.get("fullName", "").lower()
          ):
              job_info = self.get_job_info(job["fullName"])
              matching_jobs.append(job_info)
  
      return matching_jobs

• src/jenkins/tools/client.py:536-565 (helper)

  Recursive private helper method used by search_jobs to flatten nested job structures from the Jenkins API response into a flat list containing name, fullName, and url for each job.

  def _collect_all_jobs(
      self, jobs: List[Dict[str, Any]], parent: str = ""
  ) -> List[Dict[str, Any]]:
      """Recursively collect all jobs.
  
      Args:
          jobs: List of jobs
          parent: Parent job path
  
      Returns:
          Flattened job list
      """
      result = []
      for job in jobs:
          name = job.get("fullName") or (
              f"{parent}/{job['name']}" if parent else job["name"]
          )
          result.append(
              {
                  "name": job["name"],
                  "fullName": name,
                  "url": job["url"],
              }
          )
  
          if "jobs" in job and job["jobs"]:
              result.extend(self._collect_all_jobs(job["jobs"], name))
  
      return result

• src/jenkins/tools/types.py:65-77 (schema)

  TypedDict schema defining the structure of JobInfo objects returned by search_jobs.

  class JobInfo(TypedDict):
      """Job info."""
  
      name: str
      fullName: str
      url: str
      description: Optional[str]
      buildable: bool
      color: str
      is_parameterized: bool
      last_build_number: Optional[int]
      last_build_url: Optional[str]