Jira MCP Server

Instructions

Implementation Reference

• src/mcp_server_jira/server.py:982-1014 (handler)

  Main handler function for the 'transition_jira_issue' MCP tool. Validates inputs and delegates to JiraV3APIClient.transition_issue for execution.

  async def transition_jira_issue(
      self,
      issue_key: str,
      transition_id: str,
      comment: Optional[str] = None,
      fields: Optional[Dict[str, Any]] = None,
  ) -> bool:
      """Transition an issue to a new state using v3 REST API"""
      logger.info("Starting transition_jira_issue...")
  
      try:
          # Use v3 API client
          v3_client = self._get_v3_api_client()
          await v3_client.transition_issue(
              issue_id_or_key=issue_key,
              transition_id=transition_id,
              fields=fields,
              comment=comment,
          )
  
          logger.info(
              f"Successfully transitioned issue {issue_key} to transition {transition_id}"
          )
          return True
  
      except Exception as e:
          error_msg = (
              f"Failed to transition {issue_key}: {type(e).__name__}: {str(e)}"
          )
          logger.error(error_msg, exc_info=True)
          print(error_msg)
          raise ValueError(error_msg)

• src/mcp_server_jira/jira_v3_api.py:294-371 (helper)

  Core helper method in JiraV3APIClient that constructs the transition payload and performs the POST request to Jira's /rest/api/3/issue/{key}/transitions endpoint.

  async def transition_issue(
      self,
      issue_id_or_key: str,
      transition_id: str,
      fields: Optional[Dict[str, Any]] = None,
      comment: Optional[str] = None,
      history_metadata: Optional[Dict[str, Any]] = None,
      properties: Optional[list] = None,
  ) -> Dict[str, Any]:
      """
      Transition an issue using the v3 REST API.
  
      Performs an issue transition and, if the transition has a screen,
      updates the fields from the transition screen.
  
      Args:
          issue_id_or_key: Issue ID or key (required)
          transition_id: ID of the transition to perform (required)
          fields: Dict containing field names and values to update during transition
          comment: Simple string comment to add during transition
          history_metadata: Optional history metadata for the transition
          properties: Optional list of properties to set
  
      Returns:
          Empty dictionary on success (204 No Content response)
  
      Raises:
          ValueError: If required parameters are missing or transition fails
      """
      if not issue_id_or_key:
          raise ValueError("issue_id_or_key is required")
  
      if not transition_id:
          raise ValueError("transition_id is required")
  
      # Build the request payload
      payload = {"transition": {"id": transition_id}}
  
      # Add fields if provided
      if fields:
          payload["fields"] = fields
  
      # Add comment if provided - convert simple string to ADF format
      if comment:
          payload["update"] = {
              "comment": [
                  {
                      "add": {
                          "body": {
                              "type": "doc",
                              "version": 1,
                              "content": [
                                  {
                                      "type": "paragraph",
                                      "content": [{"type": "text", "text": comment}],
                                  }
                              ],
                          }
                      }
                  }
              ]
          }
  
      # Add optional metadata
      if history_metadata:
          payload["historyMetadata"] = history_metadata
  
      if properties:
          payload["properties"] = properties
  
      endpoint = f"/issue/{issue_id_or_key}/transitions"
      logger.debug(f"Transitioning issue with v3 API endpoint: {endpoint}")
      logger.debug(f"Transition payload: {json.dumps(payload, indent=2)}")
  
      response_data = await self._make_v3_api_request("POST", endpoint, data=payload)
      logger.debug(f"Transition response: {response_data}")
      return response_data

• src/mcp_server_jira/server.py:1302-1326 (registration)

  Tool registration in list_tools() including the name 'transition_jira_issue', description, and input schema definition.

      name=JiraTools.TRANSITION_ISSUE.value,
      description="Transition a Jira issue to a new status",
      inputSchema={
          "type": "object",
          "properties": {
              "issue_key": {
                  "type": "string",
                  "description": "The issue key (e.g., PROJECT-123)",
              },
              "transition_id": {
                  "type": "string",
                  "description": "ID of the transition to perform (get IDs using get_transitions)",
              },
              "comment": {
                  "type": "string",
                  "description": "Comment to add during transition (optional)",
              },
              "fields": {
                  "type": "object",
                  "description": "Additional fields to update during transition (optional)",
              },
          },
          "required": ["issue_key", "transition_id"],
      },
  ),

• src/mcp_server_jira/server.py:103-106 (schema)

  Pydantic model used for typing transition results (used by get_jira_transitions).

  class JiraTransitionResult(BaseModel):
      id: str
      name: str

• src/mcp_server_jira/server.py:1480-1494 (registration)

  Dispatch logic in call_tool() that maps the tool call to the transition_jira_issue handler.

  case JiraTools.TRANSITION_ISSUE.value:
      logger.info("Calling async tool transition_jira_issue...")
      issue_key = arguments.get("issue_key")
      transition_id = arguments.get("transition_id")
      if not issue_key or not transition_id:
          raise ValueError(
              "Missing required arguments: issue_key and transition_id"
          )
      comment = arguments.get("comment")
      fields = arguments.get("fields")
      result = await jira_server.transition_jira_issue(
          issue_key, transition_id, comment, fields
      )
      logger.info("Async tool transition_jira_issue completed.")