mcp-ticketer 0.3.0__py3-none-any.whl → 2.2.9__py3-none-any.whl

mcp_ticketer/mcp/server/tools/milestone_tools.py

@@ -0,0 +1,338 @@
+"""Unified milestone management tools (v2.0.0).
+
+This module implements milestone management through a single unified `milestone()` interface.
+
+Version 2.0.0 changes:
+- Single `milestone()` function is the exposed MCP tool
+- All operations accessible via milestone(action="create"|"get"|"list"|"update"|"delete"|"get_issues")
+- Follows the pattern from ticket() and hierarchy() unified tools
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Literal
+
+from ....core.adapter import BaseAdapter
+from ..server_sdk import get_adapter, mcp
+
+logger = logging.getLogger(__name__)
+
+# Sentinel value to distinguish between "parameter not provided" and "explicitly None"
+_UNSET = object()
+
+
+def _build_adapter_metadata(
+    adapter: BaseAdapter,
+    milestone_id: str | None = None,
+) -> dict[str, Any]:
+    """Build adapter metadata for MCP responses.
+
+    Args:
+        adapter: The adapter that handled the operation
+        milestone_id: Optional milestone ID to include in metadata
+
+    Returns:
+        Dictionary with adapter metadata fields
+
+    """
+    metadata = {
+        "adapter": adapter.adapter_type,
+        "adapter_name": adapter.adapter_display_name,
+    }
+
+    if milestone_id:
+        metadata["milestone_id"] = milestone_id
+
+    return metadata
+
+
+@mcp.tool()
+async def milestone(
+    action: Literal["create", "get", "list", "update", "delete", "get_issues"],
+    # Entity identification
+    milestone_id: str | None = None,
+    # Creation/Update parameters
+    name: str | None = None,
+    target_date: str | None = None,
+    labels: list[str] | None = None,
+    description: str = "",
+    state: str | None = None,
+    # List/filter parameters
+    project_id: str | None = None,
+) -> dict[str, Any]:
+    """Unified milestone management tool for cross-platform milestone support.
+
+    A milestone is a list of labels with target dates, into which issues can be grouped.
+
+    Consolidates all milestone operations into a single interface with progress tracking.
+
+    Args:
+        action: Operation to perform:
+            - "create": Create new milestone
+            - "get": Get milestone by ID with progress
+            - "list": List milestones (optionally filtered)
+            - "update": Update milestone properties
+            - "delete": Delete milestone
+            - "get_issues": Get issues in milestone
+        milestone_id: Milestone ID (required for get, update, delete, get_issues)
+        name: Milestone name (required for create)
+        target_date: Target completion date (ISO format: YYYY-MM-DD)
+        labels: Labels that define this milestone (user's definition)
+        description: Milestone description
+        state: Milestone state (open, active, completed, closed)
+        project_id: Project/repository filter for list operations
+
+    Returns:
+        Operation results with status, data, and metadata
+
+    Raises:
+        ValueError: If action is invalid or required parameters missing
+
+    Examples:
+        # Create milestone
+        await milestone(
+            action="create",
+            name="v2.1.0 Release",
+            target_date="2025-12-31",
+            labels=["v2.1", "release"]
+        )
+
+        # Get milestone with progress
+        await milestone(action="get", milestone_id="milestone-123")
+
+        # List active milestones
+        await milestone(action="list", state="active")
+
+        # Update milestone
+        await milestone(
+            action="update",
+            milestone_id="milestone-123",
+            state="completed"
+        )
+
+        # Get issues in milestone
+        await milestone(action="get_issues", milestone_id="milestone-123")
+
+        # Delete milestone
+        await milestone(action="delete", milestone_id="milestone-123")
+
+    """
+    try:
+        # Get adapter from registry
+        adapter = get_adapter()
+
+        # Validate action
+        valid_actions = ["create", "get", "list", "update", "delete", "get_issues"]
+        if action not in valid_actions:
+            return {
+                "status": "error",
+                "error": f"Invalid action '{action}'. Must be one of: {', '.join(valid_actions)}",
+            }
+
+        # Route to appropriate handler
+        if action == "create":
+            return await _handle_create(
+                adapter, name, target_date, labels, description, project_id
+            )
+        elif action == "get":
+            return await _handle_get(adapter, milestone_id)
+        elif action == "list":
+            return await _handle_list(adapter, project_id, state)
+        elif action == "update":
+            return await _handle_update(
+                adapter, milestone_id, name, target_date, state, labels, description
+            )
+        elif action == "delete":
+            return await _handle_delete(adapter, milestone_id)
+        elif action == "get_issues":
+            return await _handle_get_issues(adapter, milestone_id, state)
+
+    except Exception as e:
+        logger.exception("Milestone operation failed")
+        return {
+            "status": "error",
+            "error": f"Milestone operation failed: {str(e)}",
+            "action": action,
+            "milestone_id": milestone_id,
+        }
+
+
+async def _handle_create(
+    adapter: BaseAdapter,
+    name: str | None,
+    target_date: str | None,
+    labels: list[str] | None,
+    description: str,
+    project_id: str | None,
+) -> dict[str, Any]:
+    """Handle milestone creation."""
+    if not name:
+        return {
+            "status": "error",
+            "error": "name is required for create action",
+        }
+
+    # Parse target_date if provided (expect date object, not string)
+    parsed_date = None
+    if target_date:
+        try:
+            # Try parsing as ISO date string
+            parsed_date = datetime.fromisoformat(target_date)
+        except ValueError:
+            return {
+                "status": "error",
+                "error": f"Invalid date format '{target_date}'. Use ISO format: YYYY-MM-DD",
+            }
+
+    milestone_obj = await adapter.milestone_create(
+        name=name,
+        target_date=parsed_date,
+        labels=labels or [],
+        description=description,
+        project_id=project_id,
+    )
+
+    return {
+        "status": "completed",
+        "message": f"Milestone '{name}' created successfully",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_obj.id),
+    }
+
+
+async def _handle_get(adapter: BaseAdapter, milestone_id: str | None) -> dict[str, Any]:
+    """Handle milestone retrieval with progress calculation."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for get action",
+        }
+
+    milestone_obj = await adapter.milestone_get(milestone_id)
+
+    if not milestone_obj:
+        return {
+            "status": "error",
+            "error": f"Milestone '{milestone_id}' not found",
+        }
+
+    return {
+        "status": "completed",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }
+
+
+async def _handle_list(
+    adapter: BaseAdapter,
+    project_id: str | None,
+    state: str | None,
+) -> dict[str, Any]:
+    """Handle milestone listing with optional filters."""
+    milestones = await adapter.milestone_list(project_id=project_id, state=state)
+
+    return {
+        "status": "completed",
+        "message": f"Found {len(milestones)} milestone(s)",
+        "milestones": [m.model_dump() for m in milestones],
+        "count": len(milestones),
+        "metadata": _build_adapter_metadata(adapter),
+    }
+
+
+async def _handle_update(
+    adapter: BaseAdapter,
+    milestone_id: str | None,
+    name: str | None,
+    target_date: str | None,
+    state: str | None,
+    labels: list[str] | None,
+    description: str | None,
+) -> dict[str, Any]:
+    """Handle milestone update."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for update action",
+        }
+
+    # Parse target_date if provided
+    parsed_date = None
+    if target_date:
+        try:
+            parsed_date = datetime.fromisoformat(target_date)
+        except ValueError:
+            return {
+                "status": "error",
+                "error": f"Invalid date format '{target_date}'. Use ISO format: YYYY-MM-DD",
+            }
+
+    milestone_obj = await adapter.milestone_update(
+        milestone_id=milestone_id,
+        name=name,
+        target_date=parsed_date,
+        state=state,
+        labels=labels,
+        description=description,
+    )
+
+    if not milestone_obj:
+        return {
+            "status": "error",
+            "error": f"Failed to update milestone '{milestone_id}'",
+        }
+
+    return {
+        "status": "completed",
+        "message": f"Milestone '{milestone_id}' updated successfully",
+        "milestone": milestone_obj.model_dump(),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }
+
+
+async def _handle_delete(
+    adapter: BaseAdapter, milestone_id: str | None
+) -> dict[str, Any]:
+    """Handle milestone deletion."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for delete action",
+        }
+
+    success = await adapter.milestone_delete(milestone_id)
+
+    if success:
+        return {
+            "status": "completed",
+            "message": f"Milestone '{milestone_id}' deleted successfully",
+            "metadata": _build_adapter_metadata(adapter, milestone_id),
+        }
+    else:
+        return {
+            "status": "error",
+            "error": f"Failed to delete milestone '{milestone_id}'",
+        }
+
+
+async def _handle_get_issues(
+    adapter: BaseAdapter,
+    milestone_id: str | None,
+    state: str | None,
+) -> dict[str, Any]:
+    """Handle getting issues in milestone."""
+    if not milestone_id:
+        return {
+            "status": "error",
+            "error": "milestone_id is required for get_issues action",
+        }
+
+    issues = await adapter.milestone_get_issues(milestone_id, state=state)
+
+    return {
+        "status": "completed",
+        "message": f"Found {len(issues)} issue(s) in milestone",
+        "issues": [issue.model_dump() for issue in issues],
+        "count": len(issues),
+        "metadata": _build_adapter_metadata(adapter, milestone_id),
+    }

mcp_ticketer/mcp/server/tools/pr_tools.py

@@ -0,0 +1,150 @@
+"""Pull request integration tools for tickets.
+
+This module implements tools for linking tickets with pull requests and
+creating PRs from tickets. Note that PR functionality may not be available
+in all adapters.
+"""
+
+from typing import Any
+
+from ..server_sdk import get_adapter
+
+
+async def ticket_create_pr(
+    ticket_id: str,
+    title: str,
+    description: str = "",
+    source_branch: str | None = None,
+    target_branch: str = "main",
+) -> dict[str, Any]:
+    """Create a pull request linked to a ticket.
+
+    Creates a new pull request and automatically links it to the specified
+    ticket. This functionality may not be available in all adapters.
+
+    Args:
+        ticket_id: Unique identifier of the ticket to link the PR to
+        title: Pull request title
+        description: Pull request description
+        source_branch: Source branch for the PR (if not specified, may use ticket ID)
+        target_branch: Target branch for the PR (default: main)
+
+    Returns:
+        Created PR details and link information, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Check if adapter supports PR operations
+        if not hasattr(adapter, "create_pull_request"):
+            return {
+                "status": "error",
+                "error": f"Pull request creation not supported by {type(adapter).__name__} adapter",
+                "ticket_id": ticket_id,
+            }
+
+        # Read ticket to validate it exists
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Use ticket ID as source branch if not specified
+        if source_branch is None:
+            source_branch = f"feature/{ticket_id}"
+
+        # Create PR via adapter
+        pr_data = await adapter.create_pull_request(
+            ticket_id=ticket_id,
+            title=title,
+            description=description,
+            source_branch=source_branch,
+            target_branch=target_branch,
+        )
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "pull_request": pr_data,
+        }
+
+    except AttributeError:
+        return {
+            "status": "error",
+            "error": "Pull request creation not supported by this adapter",
+            "ticket_id": ticket_id,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to create pull request: {str(e)}",
+            "ticket_id": ticket_id,
+        }
+
+
+async def ticket_link_pr(
+    ticket_id: str,
+    pr_url: str,
+) -> dict[str, Any]:
+    """Link an existing pull request to a ticket.
+
+    Associates an existing pull request (identified by URL) with a ticket.
+    This is typically done by adding the PR URL to the ticket's metadata
+    or as a comment.
+
+    Args:
+        ticket_id: Unique identifier of the ticket
+        pr_url: URL of the pull request to link
+
+    Returns:
+        Link confirmation and updated ticket details, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Read ticket to validate it exists
+        ticket = await adapter.read(ticket_id)
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Check if adapter has specialized PR linking
+        if hasattr(adapter, "link_pull_request"):
+            result = await adapter.link_pull_request(ticket_id=ticket_id, pr_url=pr_url)
+            return {
+                "status": "completed",
+                "ticket_id": ticket_id,
+                "pr_url": pr_url,
+                "result": result,
+            }
+
+        # Fallback: Add PR link as comment
+        from ....core.models import Comment
+
+        comment = Comment(
+            ticket_id=ticket_id,
+            content=f"Pull Request: {pr_url}",
+        )
+
+        created_comment = await adapter.add_comment(comment)
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "pr_url": pr_url,
+            "method": "comment",
+            "comment": created_comment.model_dump(),
+        }
+
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to link pull request: {str(e)}",
+            "ticket_id": ticket_id,
+        }

mcp_ticketer/mcp/server/tools/project_status_tools.py

@@ -0,0 +1,158 @@
+"""MCP tools for project status analysis and work planning.
+
+This module provides PM-focused tools to analyze project health and
+generate intelligent work plans with recommendations.
+
+Tools:
+- project_status: Comprehensive project/epic analysis with health assessment
+"""
+
+import logging
+from typing import Any
+
+from ....analysis.project_status import StatusAnalyzer
+from ....core.project_config import ConfigResolver
+from ..server_sdk import get_adapter, mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def project_status(project_id: str | None = None) -> dict[str, Any]:
+    """Analyze project/epic status and generate work plan with recommendations.
+
+    Provides comprehensive project analysis including:
+    - Health assessment (on_track, at_risk, off_track)
+    - Status breakdown by state and priority
+    - Dependency analysis and critical path
+    - Top 3 recommended tickets to start next
+    - Blocker identification
+    - Work distribution by assignee
+    - Actionable recommendations for project managers
+
+    Args:
+        project_id: ID of the project/epic to analyze (optional, uses default_project if not provided)
+
+    Returns:
+        Complete project status analysis with recommendations, or error information
+
+    Example:
+        # Analyze specific project
+        result = await project_status(project_id="eac28953c267")
+
+        # Analyze default project
+        result = await project_status()
+
+    Example Response:
+        {
+            "status": "success",
+            "project_id": "eac28953c267",
+            "project_name": "MCP Ticketer",
+            "health": "at_risk",
+            "summary": {
+                "total": 4,
+                "open": 3,
+                "in_progress": 1,
+                "done": 0
+            },
+            "recommended_next": [
+                {
+                    "ticket_id": "1M-317",
+                    "title": "Fix project organization",
+                    "priority": "critical",
+                    "reason": "Critical priority, Unblocks 2 tickets",
+                    "blocks": ["1M-315", "1M-316"]
+                }
+            ],
+            "recommendations": [
+                "Resolve 1M-317 first (critical) - Unblocks 2 tickets",
+                "1 critical priority ticket needs attention"
+            ]
+        }
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Use default project if not provided
+        if not project_id:
+            resolver = ConfigResolver()
+            config = resolver.resolve()
+            project_id = config.default_project
+
+            if not project_id:
+                return {
+                    "status": "error",
+                    "error": "No project_id provided and no default_project configured",
+                    "message": "Use config_set_project to set a default project, or provide project_id parameter",
+                }
+
+        # Read the epic/project to get name
+        try:
+            epic = await adapter.read(project_id)
+            if epic is None:
+                return {
+                    "status": "error",
+                    "error": f"Project/Epic {project_id} not found",
+                }
+            project_name = epic.title or project_id
+        except Exception as e:
+            logger.warning(
+                f"Failed to read project {project_id} for name: {e}. Using ID as name."
+            )
+            project_name = project_id
+
+        # Get all child issues
+        child_issue_ids = getattr(epic, "child_issues", [])
+
+        if not child_issue_ids:
+            return {
+                "status": "success",
+                "project_id": project_id,
+                "project_name": project_name,
+                "health": "on_track",
+                "summary": {"total": 0},
+                "message": "Project has no tickets yet",
+                "recommended_next": [],
+                "recommendations": ["Project is empty - Create tickets to get started"],
+            }
+
+        # Fetch each child issue
+        tickets = []
+        for issue_id in child_issue_ids:
+            try:
+                issue = await adapter.read(issue_id)
+                if issue:
+                    tickets.append(issue)
+            except Exception as e:
+                logger.warning(f"Failed to read issue {issue_id}: {e}")
+                continue
+
+        if not tickets:
+            return {
+                "status": "success",
+                "project_id": project_id,
+                "project_name": project_name,
+                "health": "at_risk",
+                "summary": {"total": 0},
+                "message": f"Could not load tickets for project (found {len(child_issue_ids)} IDs but couldn't read them)",
+                "recommended_next": [],
+                "recommendations": ["Check ticket IDs and permissions"],
+            }
+
+        # Perform status analysis
+        analyzer = StatusAnalyzer()
+        result = analyzer.analyze(project_id, project_name, tickets)
+
+        # Convert to dict and add success status
+        result_dict = result.model_dump()
+        result_dict["status"] = "success"
+
+        return result_dict
+
+    except Exception as e:
+        logger.error(f"Error analyzing project status: {e}", exc_info=True)
+        return {
+            "status": "error",
+            "error": f"Failed to analyze project status: {str(e)}",
+        }