mcp-ticketer 0.1.30__py3-none-any.whl → 1.2.11__py3-none-any.whl

mcp_ticketer/mcp/server/tools/pr_tools.py

@@ -0,0 +1,152 @@
+"""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, mcp
+
+
+@mcp.tool()
+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,
+        }
+
+
+@mcp.tool()
+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/search_tools.py

@@ -0,0 +1,215 @@
+"""Search and query tools for finding tickets.
+
+This module implements advanced search capabilities for tickets using
+various filters and criteria.
+"""
+
+import logging
+from typing import Any
+
+from ....core.models import Priority, SearchQuery, TicketState
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_search(
+    query: str | None = None,
+    state: str | None = None,
+    priority: str | None = None,
+    tags: list[str] | None = None,
+    assignee: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Search tickets using advanced filters.
+
+    Searches for tickets matching the specified criteria. All filters are
+    optional and can be combined.
+
+    Args:
+        query: Text search query to match against title and description
+        state: Filter by state - must be one of: open, in_progress, ready, tested, done, closed, waiting, blocked
+        priority: Filter by priority - must be one of: low, medium, high, critical
+        tags: Filter by tags - tickets must have all specified tags
+        assignee: Filter by assigned user ID or email
+        limit: Maximum number of results to return (default: 10, max: 100)
+
+    Returns:
+        List of tickets matching search criteria, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Add warning for unscoped searches
+        if not query and not (state or priority or tags or assignee):
+            logging.warning(
+                "Unscoped search with no query or filters. "
+                "This will search ALL tickets across all projects. "
+                "Tip: Configure default_project or default_team for automatic scoping."
+            )
+
+        # Validate and build search query
+        state_enum = None
+        if state is not None:
+            try:
+                state_enum = TicketState(state.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid state '{state}'. Must be one of: open, in_progress, ready, tested, done, closed, waiting, blocked",
+                }
+
+        priority_enum = None
+        if priority is not None:
+            try:
+                priority_enum = Priority(priority.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
+                }
+
+        # Create search query
+        search_query = SearchQuery(
+            query=query,
+            state=state_enum,
+            priority=priority_enum,
+            tags=tags,
+            assignee=assignee,
+            limit=min(limit, 100),  # Enforce max limit
+        )
+
+        # Execute search via adapter
+        results = await adapter.search(search_query)
+
+        return {
+            "status": "completed",
+            "tickets": [ticket.model_dump() for ticket in results],
+            "count": len(results),
+            "query": {
+                "text": query,
+                "state": state,
+                "priority": priority,
+                "tags": tags,
+                "assignee": assignee,
+            },
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to search tickets: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_search_hierarchy(
+    query: str,
+    include_children: bool = True,
+    max_depth: int = 3,
+) -> dict[str, Any]:
+    """Search tickets and include their hierarchy.
+
+    Performs a text search and returns matching tickets along with their
+    hierarchical context (parent epics/issues and child issues/tasks).
+
+    Args:
+        query: Text search query to match against title and description
+        include_children: Whether to include child tickets in results
+        max_depth: Maximum hierarchy depth to include (1-3, default: 3)
+
+    Returns:
+        List of tickets with hierarchy information, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Validate max_depth
+        if max_depth < 1 or max_depth > 3:
+            return {
+                "status": "error",
+                "error": "max_depth must be between 1 and 3",
+            }
+
+        # Create search query
+        search_query = SearchQuery(
+            query=query,
+            limit=50,  # Reasonable limit for hierarchical search
+        )
+
+        # Execute search via adapter
+        results = await adapter.search(search_query)
+
+        # Build hierarchical results
+        hierarchical_results = []
+        for ticket in results:
+            ticket_data = {
+                "ticket": ticket.model_dump(),
+                "hierarchy": {},
+            }
+
+            # Get parent epic if applicable
+            parent_epic_id = getattr(ticket, "parent_epic", None)
+            if parent_epic_id and max_depth >= 2:
+                try:
+                    parent_epic = await adapter.read(parent_epic_id)
+                    if parent_epic:
+                        ticket_data["hierarchy"][
+                            "parent_epic"
+                        ] = parent_epic.model_dump()
+                except Exception:
+                    pass  # Parent not found, continue
+
+            # Get parent issue if applicable (for tasks)
+            parent_issue_id = getattr(ticket, "parent_issue", None)
+            if parent_issue_id and max_depth >= 2:
+                try:
+                    parent_issue = await adapter.read(parent_issue_id)
+                    if parent_issue:
+                        ticket_data["hierarchy"][
+                            "parent_issue"
+                        ] = parent_issue.model_dump()
+                except Exception:
+                    pass  # Parent not found, continue
+
+            # Get children if requested
+            if include_children and max_depth >= 2:
+                children = []
+
+                # Get child issues (for epics)
+                child_issue_ids = getattr(ticket, "child_issues", [])
+                for child_id in child_issue_ids:
+                    try:
+                        child = await adapter.read(child_id)
+                        if child:
+                            children.append(child.model_dump())
+                    except Exception:
+                        pass  # Child not found, continue
+
+                # Get child tasks (for issues)
+                child_task_ids = getattr(ticket, "children", [])
+                for child_id in child_task_ids:
+                    try:
+                        child = await adapter.read(child_id)
+                        if child:
+                            children.append(child.model_dump())
+                    except Exception:
+                        pass  # Child not found, continue
+
+                if children:
+                    ticket_data["hierarchy"]["children"] = children
+
+            hierarchical_results.append(ticket_data)
+
+        return {
+            "status": "completed",
+            "results": hierarchical_results,
+            "count": len(hierarchical_results),
+            "query": query,
+            "max_depth": max_depth,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to search with hierarchy: {str(e)}",
+        }

mcp_ticketer/mcp/server/tools/session_tools.py

@@ -0,0 +1,170 @@
+"""MCP tools for session and ticket association management."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from ....core.session_state import SessionStateManager
+from ..server_sdk import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def attach_ticket(
+    action: str,
+    ticket_id: str | None = None,
+) -> dict[str, Any]:
+    """Associate current work session with a ticket.
+
+    This tool helps track which ticket your current work is related to.
+    The association persists for the session (30 minutes of inactivity).
+
+    **Important**: It's recommended to associate work with a ticket for proper
+    tracking and organization.
+
+    Actions:
+    - **set**: Associate work with a specific ticket
+    - **clear**: Remove current ticket association
+    - **none**: Opt out of ticket association for this session
+    - **status**: Check current ticket association
+
+    Args:
+        action: What to do with the ticket association (set/clear/none/status)
+        ticket_id: Ticket ID to associate (e.g., "PROJ-123", UUID), required for 'set'
+
+    Returns:
+        Success status and current session state
+
+    Examples:
+        # Associate with a ticket
+        attach_ticket(action="set", ticket_id="PROJ-123")
+
+        # Opt out for this session
+        attach_ticket(action="none")
+
+        # Check current status
+        attach_ticket(action="status")
+
+    """
+    try:
+        manager = SessionStateManager(project_path=Path.cwd())
+        state = manager.load_session()
+
+        if action == "set":
+            if not ticket_id:
+                return {
+                    "success": False,
+                    "error": "ticket_id is required when action='set'",
+                    "guidance": "Please provide a ticket ID to associate with this session",
+                }
+
+            manager.set_current_ticket(ticket_id)
+            return {
+                "success": True,
+                "message": f"Work session now associated with ticket: {ticket_id}",
+                "current_ticket": ticket_id,
+                "session_id": state.session_id,
+                "opted_out": False,
+            }
+
+        elif action == "clear":
+            manager.set_current_ticket(None)
+            return {
+                "success": True,
+                "message": "Ticket association cleared",
+                "current_ticket": None,
+                "session_id": state.session_id,
+                "opted_out": False,
+                "guidance": "You can associate with a ticket anytime using attach_ticket(action='set', ticket_id='...')",
+            }
+
+        elif action == "none":
+            manager.opt_out_ticket()
+            return {
+                "success": True,
+                "message": "Opted out of ticket association for this session",
+                "current_ticket": None,
+                "session_id": state.session_id,
+                "opted_out": True,
+                "note": "This opt-out will reset after 30 minutes of inactivity",
+            }
+
+        elif action == "status":
+            current_ticket = manager.get_current_ticket()
+
+            if state.ticket_opted_out:
+                status_msg = "No ticket associated (opted out for this session)"
+            elif current_ticket:
+                status_msg = f"Currently associated with ticket: {current_ticket}"
+            else:
+                status_msg = "No ticket associated"
+
+            return {
+                "success": True,
+                "message": status_msg,
+                "current_ticket": current_ticket,
+                "session_id": state.session_id,
+                "opted_out": state.ticket_opted_out,
+                "guidance": (
+                    (
+                        "Associate with a ticket: attach_ticket(action='set', ticket_id='...')\n"
+                        "Opt out: attach_ticket(action='none')"
+                    )
+                    if not current_ticket and not state.ticket_opted_out
+                    else None
+                ),
+            }
+
+        else:
+            return {
+                "success": False,
+                "error": f"Invalid action: {action}",
+                "valid_actions": ["set", "clear", "none", "status"],
+            }
+
+    except Exception as e:
+        logger.error(f"Error in attach_ticket: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+@mcp.tool()
+async def get_session_info() -> dict[str, Any]:
+    """Get current session information and ticket association status.
+
+    Returns session metadata including ID, current ticket, and activity status.
+
+    Returns:
+        Session information dictionary
+
+    Example:
+        {
+            "session_id": "abc-123",
+            "current_ticket": "PROJ-123",
+            "opted_out": false,
+            "last_activity": "2025-01-19T20:00:00"
+        }
+
+    """
+    try:
+        manager = SessionStateManager(project_path=Path.cwd())
+        state = manager.load_session()
+
+        return {
+            "success": True,
+            "session_id": state.session_id,
+            "current_ticket": state.current_ticket,
+            "opted_out": state.ticket_opted_out,
+            "last_activity": state.last_activity,
+            "session_timeout_minutes": 30,
+        }
+
+    except Exception as e:
+        logger.error(f"Error in get_session_info: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+        }