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.")