arcade-mcp/toolkits/jira/arcade_jira/tools/priorities.py

import asyncio
from typing import Annotated, Any, cast

from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Atlassian

import arcade_jira.cache as cache
from arcade_jira.client import JiraClient
from arcade_jira.constants import JIRA_API_REQUEST_TIMEOUT, PrioritySchemeOrderBy
from arcade_jira.exceptions import JiraToolExecutionError, MultipleItemsFoundError, NotFoundError
from arcade_jira.utils import (
    add_pagination_to_response,
    clean_priority_dict,
    clean_priority_scheme_dict,
    clean_project_dict,
    find_priorities_by_project,
    find_unique_project,
    remove_none_values,
)


@tool(requires_auth=Atlassian(scopes=["read:jira-work"]))
async def get_priority_by_id(
    context: ToolContext,
    priority_id: Annotated[str, "The ID of the priority to retrieve."],
) -> Annotated[dict[str, Any], "The priority"]:
    """Get the details of a priority by its ID."""
    client = JiraClient(context.get_auth_token_or_empty())
    try:
        response = await client.get(f"/priority/{priority_id}")
    except NotFoundError:
        return {"error": f"Priority not found with id '{priority_id}'"}
    return {"priority": clean_priority_dict(response)}


@tool(requires_auth=Atlassian(scopes=["manage:jira-configuration"]))
async def list_priority_schemes(
    context: ToolContext,
    scheme_name: Annotated[
        str | None, "Filter by scheme name. Defaults to None (returns all scheme names)."
    ] = None,
    limit: Annotated[
        int,
        "The maximum number of priority schemes to return. Min of 1, max of 50. Defaults to 50.",
    ] = 50,
    offset: Annotated[
        int, "The number of priority schemes to skip. Defaults to 0 (start from the first scheme)."
    ] = 0,
    order_by: Annotated[
        PrioritySchemeOrderBy,
        "The order in which to return the priority schemes. Defaults to name ascending.",
    ] = PrioritySchemeOrderBy.NAME_ASCENDING,
) -> Annotated[dict[str, Any], "The priority schemes available"]:
    """Browse the priority schemes available in Jira."""
    limit = max(min(limit, 50), 1)
    client = JiraClient(context.get_auth_token_or_empty())
    api_response = await client.get(
        "/priorityscheme",
        params=remove_none_values({
            "startAt": offset,
            "maxResults": limit,
            "schemeName": scheme_name,
            "orderBy": order_by.to_api_value(),
        }),
    )
    cloud_name = cache.get_cloud_name(context.get_auth_token_or_empty())
    schemes = [clean_priority_scheme_dict(scheme, cloud_name) for scheme in api_response["values"]]
    response = {
        "priority_schemes": schemes,
        "isLast": api_response.get("isLast"),
    }
    return add_pagination_to_response(response, schemes, limit, offset)


@tool(requires_auth=Atlassian(scopes=["manage:jira-configuration"]))
async def list_priorities_associated_with_a_priority_scheme(
    context: ToolContext,
    scheme_id: Annotated[str, "The ID of the priority scheme to retrieve priorities for."],
    limit: Annotated[
        int,
        "The maximum number of priority schemes to return. Min of 1, max of 50. Defaults to 50.",
    ] = 50,
    offset: Annotated[
        int, "The number of priority schemes to skip. Defaults to 0 (start from the first scheme)."
    ] = 0,
) -> Annotated[dict[str, Any], "The priorities associated with the priority scheme"]:
    """Browse the priorities associated with a priority scheme."""
    client = JiraClient(context.get_auth_token_or_empty())
    api_response = await client.get(
        f"/priorityscheme/{scheme_id}/priorities",
        params={
            "startAt": offset,
            "maxResults": limit,
        },
    )
    priorities = [clean_priority_dict(priority) for priority in api_response["values"]]
    response = {
        "priorities": priorities,
        "isLast": api_response.get("isLast"),
    }
    return add_pagination_to_response(response, priorities, limit, offset)


@tool(requires_auth=Atlassian(scopes=["manage:jira-configuration"]))
async def list_projects_associated_with_a_priority_scheme(
    context: ToolContext,
    scheme_id: Annotated[str, "The ID of the priority scheme to retrieve projects for."],
    project: Annotated[
        str | None, "Filter by project ID, key or name. Defaults to None (returns all projects)."
    ] = None,
    limit: Annotated[
        int,
        "The maximum number of projects to return. Min of 1, max of 50. Defaults to 50.",
    ] = 50,
    offset: Annotated[
        int, "The number of projects to skip. Defaults to 0 (start from the first project)."
    ] = 0,
) -> Annotated[dict[str, Any], "The projects associated with the priority scheme"]:
    """Browse the projects associated with a priority scheme."""
    if project:
        try:
            project_data = await find_unique_project(context, project)
        except (NotFoundError, MultipleItemsFoundError) as exc:
            return {"error": exc.message}
        else:
            project = project_data["id"]

    client = JiraClient(context.get_auth_token_or_empty())
    api_response = await client.get(
        f"/priorityscheme/{scheme_id}/projects",
        params=remove_none_values({
            "startAt": offset,
            "maxResults": limit,
            "projectId": project,
        }),
    )
    cloud_name = cache.get_cloud_name(context.get_auth_token_or_empty())
    projects = [clean_project_dict(project, cloud_name) for project in api_response["values"]]
    response = {
        "projects": projects,
        "isLast": api_response.get("isLast"),
    }
    return add_pagination_to_response(response, projects, limit, offset)


@tool(requires_auth=Atlassian(scopes=["manage:jira-configuration"]))
async def list_priorities_available_to_a_project(
    context: ToolContext,
    project: Annotated[str, "The ID, key or name of the project to retrieve priorities for."],
) -> Annotated[
    dict[str, Any],
    "The priorities available to be used in issues in the specified Jira project",
]:
    """Browse the priorities available to be used in issues in the specified Jira project.

    This tool may need to loop through several API calls to get all priorities associated with
    a specific project. In Jira environments with too many Projects or Priority Schemes,
    the search may take too long, and the tool call will timeout.
    """
    try:
        project_data = await find_unique_project(context, project)
    except (NotFoundError, MultipleItemsFoundError) as exc:
        return {"error": exc.message}

    try:
        return await asyncio.wait_for(
            find_priorities_by_project(context, project_data),
            timeout=JIRA_API_REQUEST_TIMEOUT,
        )
    except asyncio.TimeoutError:
        return {"error": f"The operation timed out after {JIRA_API_REQUEST_TIMEOUT} seconds."}
    except JiraToolExecutionError as error:
        return {"error": error.message}


@tool(requires_auth=Atlassian(scopes=["manage:jira-configuration"]))
async def list_priorities_available_to_an_issue(
    context: ToolContext,
    issue: Annotated[str, "The ID or key of the issue to retrieve priorities for."],
) -> Annotated[dict[str, Any], "The priorities available to be used in the specified Jira issue"]:
    """Browse the priorities available to be used in the specified Jira issue."""
    from arcade_jira.tools.issues import get_issue_by_id

    issue_response = await get_issue_by_id(context, issue)
    if issue_response.get("error"):
        return cast(dict[str, Any], issue_response)

    issue_data = issue_response["issue"]
    project = issue_data["project"]["id"]

    response = await list_priorities_available_to_a_project(context, project)

    return {
        "issue": {
            "id": issue_data["id"],
            "key": issue_data["key"],
            "title": issue_data["title"],
        },
        "project": response["project"],
        "priorities_available": response["priorities_available"],
    }