jenkins_get_job

Instructions

Implementation Reference

• src/jenkins_mcp_server/tools.py:114-117 (handler)

  The handler function for the jenkins_get_job tool. It takes a job path (string or list of strings) and an optional tree parameter, builds the Jenkins API path via job_path(), and fetches JSON from the Jenkins API.

  @mcp.tool()
  def jenkins_get_job(job: str | list[str], tree: str | None = None) -> dict[str, Any]:
      """Get one job by Jenkins job path. Nested paths use slash-separated names or a list."""
      return _run(lambda: _get_json(job_path(job), params=_query(tree)))

• src/jenkins_mcp_server/tools.py:55-118 (registration)

  All tool registrations happen inside register_tools() which is called from __main__.py. The @mcp.tool() decorator on line 114 registers jenkins_get_job with the FastMCP server.

  def register_tools(mcp: FastMCP) -> None:
      @mcp.tool()
      def jenkins_whoami() -> dict[str, Any]:
          """Return the authenticated Jenkins identity from /whoAmI/api/json."""
          return _run(lambda: _get_json("whoAmI"))
  
      @mcp.tool()
      def jenkins_version() -> dict[str, Any]:
          """Return Jenkins version from the X-Jenkins response header."""
  
          def op() -> dict[str, Any]:
              with _client() as client:
                  response = client.request("GET", "api/json", params={"tree": "mode"})
                  return {
                      "version": response.headers.get("X-Jenkins"),
                      "session": response.headers.get("X-Jenkins-Session"),
                  }
  
          return _run(op)
  
      @mcp.tool()
      def jenkins_health() -> dict[str, Any]:
          """Return a small health snapshot from top-level Jenkins JSON and version headers."""
  
          def op() -> dict[str, Any]:
              with _client() as client:
                  response = client.request(
                      "GET",
                      "api/json",
                      params={
                          "tree": (
                              "mode,nodeDescription,nodeName,numExecutors,quietingDown,useCrumbs"
                          )
                      },
                  )
                  payload = response.json()
                  payload["version"] = response.headers.get("X-Jenkins")
                  return payload
  
          return _run(op)
  
      @mcp.tool()
      def jenkins_get_json(path: str, query: dict[str, str | int] | None = None) -> dict[str, Any]:
          """GET a relative Jenkins JSON API path. Rejects external URLs and traversal."""
  
          def op() -> Any:
              relative = append_api_json(normalize_relative_path(path))
              return _get_json(relative, params=query)
  
          return _run(op)
  
      @mcp.tool()
      def jenkins_list_jobs(
          tree: str = "jobs[name,fullName,url,color,_class]",
          depth: int | None = None,
      ) -> dict[str, Any]:
          """List jobs visible to the Jenkins user."""
          return _run(lambda: _get_json("api/json", params=_query(tree, depth)))
  
      @mcp.tool()
      def jenkins_get_job(job: str | list[str], tree: str | None = None) -> dict[str, Any]:
          """Get one job by Jenkins job path. Nested paths use slash-separated names or a list."""
          return _run(lambda: _get_json(job_path(job), params=_query(tree)))

• src/jenkins_mcp_server/tools.py:114-117 (schema)

  The input schema is defined by the function signature: 'job: str | list[str]' (required) and 'tree: str | None = None' (optional). The output is dict[str, Any] wrapped in {'ok': True, 'data': ...} via _run().

  @mcp.tool()
  def jenkins_get_job(job: str | list[str], tree: str | None = None) -> dict[str, Any]:
      """Get one job by Jenkins job path. Nested paths use slash-separated names or a list."""
      return _run(lambda: _get_json(job_path(job), params=_query(tree)))

• src/jenkins_mcp_server/client.py:67-77 (helper)

  The job_path() helper function converts a job path (string or list) into a Jenkins API URL path with proper encoding and 'job' segments.

  def job_path(job: str | list[str]) -> str:
      pieces = [piece for piece in job.split("/") if piece] if isinstance(job, str) else job
      if not pieces:
          raise PathValidationError("job must include at least one path segment")
  
      encoded: list[str] = []
      for piece in pieces:
          if not piece or piece in {".", ".."} or "/" in piece:
              raise PathValidationError("job path segments must be non-empty names")
          encoded.extend(["job", quote(piece, safe="")])
      return "/".join(encoded)

• src/jenkins_mcp_server/client.py:192-204 (helper)

  The _get_json() helper is called by the handler under the hood via the get_json() method on JenkinsClient. It performs the HTTP GET to the Jenkins API and returns parsed JSON.

  def get_json(self, path: str, params: Mapping[str, Any] | None = None) -> Json:
      response = self.request("GET", append_api_json(path), params=params)
      try:
          payload = response.json()
      except json.JSONDecodeError as exc:
          raise JenkinsHTTPError(
              response.status_code,
              "GET",
              normalize_relative_path(path),
              "Response was not JSON",
              _body_snippet(response),
          ) from exc
      return payload