build_item

Instructions

Implementation Reference

• src/mcp_jenkins/jenkins/rest_client.py:603-630 (handler)

  The core implementation of build_item in the Jenkins REST client. Parses the fullname into folder/name, sends a POST request to the ITEM_BUILD endpoint, and returns the queue item number from the Location header.

  def build_item(
      self,
      *,
      fullname: str,
      build_type: Literal['build', 'buildWithParameters'],
      data: dict | None = None,
  ) -> int:
      """Trigger a build for a specific item.
  
      Warnings:
          If your job is configured with parameters, you must use 'buildWithParameters' as build_type.
  
      Args:
          fullname: The fullname of the job.
          build_type: The type of build to trigger.
          data: The parameters to trigger the build with. Required if build_type is 'buildWithParameters'.
  
      Return:
          The queue item number of the job.
      """
      folder, name = self._parse_fullname(fullname)
      response = self.request(
          'POST',
          rest_endpoint.ITEM_BUILD(folder=folder, name=name, build_type=build_type),
          data=data,
      )
  
      return int(response.headers.get('Location', None).strip('/').split('/')[-1])

• src/mcp_jenkins/server/item.py:87-104 (handler)

  The MCP tool handler for build_item. This is the async function decorated with @mcp.tool that exposes the tool to MCP clients. Delegates to the Jenkins REST client.

  @mcp.tool(tags=['write'])
  async def build_item(
      ctx: Context,
      fullname: str,
      build_type: Literal['build', 'buildWithParameters'],
      data: dict | None = None,
  ) -> int:
      """Build an item in Jenkins
  
      Args:
          fullname: The fullname of the item
          data: The parameters to trigger the build with. Required if build_type is 'buildWithParameters'.
          build_type: If your item is configured with parameters, you must use 'buildWithParameters' as build_type.
  
      Returns:
          The queue item number of the item.
      """
      return jenkins(ctx).build_item(fullname=fullname, build_type=build_type, data=data)

• src/mcp_jenkins/jenkins/rest_endpoint.py:22-22 (schema)

  The REST endpoint definition for ITEM_BUILD, which formats to '{folder}job/{name}/{build_type}'.

  ITEM_BUILD = RestEndpoint('{folder}job/{name}/{build_type}')

• src/mcp_jenkins/server/__init__.py:30-34 (registration)

  The mcp (JenkinsMCP) instance is created here, and the item module is imported (line 34) which triggers the @mcp.tool decorators to register build_item as an MCP tool.

  mcp = JenkinsMCP('mcp-jenkins', lifespan=lifespan)
  
  # Import tool modules to register them with the MCP server
  # This must happen after mcp is created so the @mcp.tool() decorators can reference it
  from mcp_jenkins.server import build, item, node, plugin, queue, view  # noqa: F401, E402

• src/mcp_jenkins/jenkins/rest_endpoint.py:1-46 (helper)

  The RestEndpoint class used by ITEM_BUILD. It supports string formatting via __call__ so endpoint templates like '{folder}job/{name}/{build_type}' can be filled in with parameters.

  from string import Formatter
  
  
  class RestEndpoint(str):
      def __new__(cls, value: str) -> str:
          obj = str.__new__(cls, value)
          obj._fields = {name for _, name, _, _ in Formatter().parse(value) if name}
          return obj
  
      def __call__(self, **kwargs: str | int) -> str:
          if missing := self._fields.difference(kwargs):
              raise KeyError(f'Missing: {missing}')
  
          return self.format(**kwargs)
  
  
  CRUMB = RestEndpoint('crumbIssuer/api/json')
  
  ITEM = RestEndpoint('{folder}job/{name}/api/json?depth={depth}')
  ITEMS = RestEndpoint('{folder}/api/json?tree={query}')
  ITEM_CONFIG = RestEndpoint('{folder}job/{name}/config.xml')
  ITEM_BUILD = RestEndpoint('{folder}job/{name}/{build_type}')
  
  QUEUE = RestEndpoint('queue/api/json?depth={depth}')
  QUEUE_ITEM = RestEndpoint('queue/item/{id}/api/json?depth={depth}')
  QUEUE_CANCEL_ITEM = RestEndpoint('queue/cancelItem?id={id}')
  
  NODE = RestEndpoint('computer/{name}/api/json?depth={depth}')
  NODES = RestEndpoint('computer/api/json?depth={depth}')
  NODE_CONFIG = RestEndpoint('computer/{name}/config.xml')
  
  VIEW = RestEndpoint('{view_path}/api/json?depth={depth}')
  VIEWS = RestEndpoint('api/json?tree=views[name,url]')
  
  BUILD = RestEndpoint('{folder}job/{name}/{number}/api/json?depth={depth}')
  BUILD_CONSOLE_OUTPUT = RestEndpoint('{folder}job/{name}/{number}/consoleText')
  BUILD_STOP = RestEndpoint('{folder}job/{name}/{number}/stop')
  BUILD_REPLAY = RestEndpoint('{folder}job/{name}/{number}/replay')
  BUILD_PARAMETERS = RestEndpoint('{folder}job/{name}/{number}/api/json?tree=actions[parameters[name,value]]')
  BUILD_TEST_REPORT = RestEndpoint('{folder}job/{name}/{number}/testReport/api/json?depth={depth}')
  BUILD_ARTIFACT = RestEndpoint('{folder}job/{name}/{number}/artifact/{relative_path}')
  BUILD_ARTIFACTS = RestEndpoint('{folder}job/{name}/{number}/api/json?tree=artifacts[fileName,relativePath,displayPath]')
  
  PLUGIN_LIST = RestEndpoint('pluginManager/api/json?depth={depth}')
  PLUGIN_LIST_TREE = RestEndpoint('pluginManager/api/json?tree=plugins[{tree}]')