transition_jira_issue

Move a Jira issue to a new status by specifying the issue key and transition ID, optionally adding comments or updating fields during the process.

Instructions

Transition a Jira issue to a new status

Input Schema

TableJSON Schema

Name	Required	Description
`comment`	No	Comment to add during transition (optional)
`fields`	No	Additional fields to update during transition (optional)
`issue_key`	Yes	The issue key (e.g., PROJECT-123)
`transition_id`	Yes	ID of the transition to perform (get IDs using get_transitions)

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

Jira MCP Server