mcp-ticketer 0.12.0__py3-none-any.whl → 2.2.13__py3-none-any.whl

mcp_ticketer/mcp/server/tools/search_tools.py

@@ -4,11 +4,14 @@ 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
 
+logger = logging.getLogger(__name__)
+
 
 @mcp.tool()
 async def ticket_search(
@@ -17,12 +20,39 @@ async def ticket_search(
     priority: str | None = None,
     tags: list[str] | None = None,
     assignee: str | None = None,
+    project_id: str | None = None,
+    milestone_id: str | None = None,
     limit: int = 10,
+    include_hierarchy: bool = False,
+    include_children: bool = True,
+    max_depth: int = 3,
 ) -> dict[str, Any]:
-    """Search tickets using advanced filters.
+    """Search tickets with optional hierarchy information and milestone filtering.
+
+    **Consolidates:**
+    - ticket_search() → Default behavior (include_hierarchy=False)
+    - ticket_search_hierarchy() → Set include_hierarchy=True
+
+    ⚠️ Project Filtering Required:
+    This tool requires project_id parameter OR default_project configuration.
+    To set default project: config_set_default_project(project_id="YOUR-PROJECT")
+    To check current config: config_get()
 
-    Searches for tickets matching the specified criteria. All filters are
-    optional and can be combined.
+    Exception: Single ticket operations (ticket_read) don't require project filtering.
+
+    **Search Filters:**
+    - query: Text search in title and description
+    - state: Filter by workflow state
+    - priority: Filter by priority level
+    - tags: Filter by tags (AND logic)
+    - assignee: Filter by assigned user
+    - project_id: Scope to specific project
+    - milestone_id: Filter by milestone (NEW in 1M-607)
+
+    **Hierarchy Options:**
+    - include_hierarchy: Include parent/child relationships (default: False)
+    - include_children: Include child tickets (default: True, requires include_hierarchy=True)
+    - max_depth: Maximum hierarchy depth (default: 3, requires include_hierarchy=True)
 
     Args:
         query: Text search query to match against title and description
@@ -30,15 +60,64 @@ async def ticket_search(
         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
+        project_id: Project/epic ID (required unless default_project configured)
+        milestone_id: Filter by milestone ID (NEW in 1M-607)
         limit: Maximum number of results to return (default: 10, max: 100)
+        include_hierarchy: Include parent/child relationships (default: False)
+        include_children: Include child tickets in hierarchy (default: True)
+        max_depth: Maximum hierarchy depth to traverse (default: 3)
 
     Returns:
         List of tickets matching search criteria, or error information
 
+    Examples:
+        # Simple search (backward compatible)
+        await ticket_search(query="authentication bug", state="open", limit=5)
+
+        # Search with hierarchy
+        await ticket_search(
+            query="oauth implementation",
+            project_id="proj-123",
+            include_hierarchy=True,
+            max_depth=2
+        )
+
+        # Search within milestone
+        await ticket_search(
+            milestone_id="milestone-123",
+            state="open",
+            limit=20
+        )
+
     """
     try:
+        # Validate project context (NEW: Required for search operations)
+        from pathlib import Path
+
+        from ....core.project_config import ConfigResolver
+
+        resolver = ConfigResolver(project_path=Path.cwd())
+        config = resolver.load_project_config()
+        final_project = project_id or (config.default_project if config else None)
+
+        if not final_project:
+            return {
+                "status": "error",
+                "error": "project_id required. Provide project_id parameter or configure default_project.",
+                "help": "Use config_set_default_project(project_id='YOUR-PROJECT') to set default project",
+                "check_config": "Use config_get() to view current configuration",
+            }
+
         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:
@@ -60,19 +139,116 @@ async def ticket_search(
                     "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
                 }
 
-        # Create search query
+        # Create search query with project scoping
         search_query = SearchQuery(
             query=query,
             state=state_enum,
             priority=priority_enum,
             tags=tags,
             assignee=assignee,
+            project=final_project,  # Always required for search operations
             limit=min(limit, 100),  # Enforce max limit
         )
 
         # Execute search via adapter
         results = await adapter.search(search_query)
 
+        # Filter by milestone if requested (NEW in 1M-607)
+        if milestone_id:
+            try:
+                # Get issues in milestone
+                milestone_issues = await adapter.milestone_get_issues(
+                    milestone_id, state=state
+                )
+                milestone_issue_ids = {issue.id for issue in milestone_issues}
+
+                # Filter search results to only include milestone issues
+                results = [
+                    ticket for ticket in results if ticket.id in milestone_issue_ids
+                ]
+            except Exception as e:
+                logger.warning(f"Failed to filter by milestone {milestone_id}: {e}")
+                # Continue with unfiltered results if milestone filtering fails
+
+        # Add hierarchy if requested
+        if include_hierarchy:
+            # Validate max_depth
+            if max_depth < 1 or max_depth > 3:
+                return {
+                    "status": "error",
+                    "error": "max_depth must be between 1 and 3",
+                }
+
+            # 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,
+            }
+
+        # Standard search response
         return {
             "status": "completed",
             "tickets": [ticket.model_dump() for ticket in results],
@@ -83,6 +259,7 @@ async def ticket_search(
                 "priority": priority,
                 "tags": tags,
                 "assignee": assignee,
+                "project": final_project,
             },
         }
     except Exception as e:
@@ -95,112 +272,47 @@ async def ticket_search(
 @mcp.tool()
 async def ticket_search_hierarchy(
     query: str,
+    project_id: str | None = None,
     include_children: bool = True,
     max_depth: int = 3,
 ) -> dict[str, Any]:
-    """Search tickets and include their hierarchy.
+    """DEPRECATED: Use ticket_search(include_hierarchy=True, ...) instead.
 
-    Performs a text search and returns matching tickets along with their
-    hierarchical context (parent epics/issues and child issues/tasks).
+    This tool will be removed in v2.0.0. Migrate to the unified ticket_search tool.
 
     Args:
         query: Text search query to match against title and description
+        project_id: Project/epic ID (required unless default_project configured)
         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()
+    Migration:
+        Before (ticket_search_hierarchy):
+        >>> await ticket_search_hierarchy(query="feature", project_id="proj-123", max_depth=2)
 
-        # Validate max_depth
-        if max_depth < 1 or max_depth > 3:
-            return {
-                "status": "error",
-                "error": "max_depth must be between 1 and 3",
-            }
+        After (ticket_search with include_hierarchy):
+        >>> await ticket_search(query="feature", project_id="proj-123", include_hierarchy=True, max_depth=2)
 
-        # 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": {},
-            }
+    See: docs/UPGRADING-v2.0.md#ticket-search-consolidation
 
-            # 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)}",
-        }
+    """
+    import warnings
+
+    warnings.warn(
+        "ticket_search_hierarchy is deprecated. Use ticket_search(include_hierarchy=True, ...) instead. "
+        "See docs/UPGRADING-v2.0.md#ticket-search-consolidation",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    # Route to unified ticket_search tool
+    return await ticket_search(
+        query=query,
+        project_id=project_id,
+        include_hierarchy=True,
+        include_children=include_children,
+        max_depth=max_depth,
+    )

mcp_ticketer/mcp/server/tools/session_tools.py

@@ -0,0 +1,308 @@
+"""MCP tools for session and ticket association management.
+
+This module implements tools for session management and user ticket operations.
+
+Features:
+- user_session: Unified interface for user ticket queries and session info
+- attach_ticket: Associate work session with ticket
+
+All tools follow the MCP response pattern:
+    {
+        "status": "completed" | "error",
+        "data": {...}
+    }
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Literal
+
+from ....core.session_state import SessionStateManager
+from ..server_sdk import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def user_session(
+    action: Literal["get_my_tickets", "get_session_info"],
+    state: str | None = None,
+    project_id: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Unified user session management tool.
+
+    Handles user ticket queries and session information through a single
+    interface. This tool consolidates get_my_tickets and get_session_info.
+
+    Args:
+        action: Operation to perform. Valid values:
+            - "get_my_tickets": Get tickets assigned to default user
+            - "get_session_info": Get current session information
+        state: Filter tickets by state (for get_my_tickets only)
+        project_id: Filter tickets by project (for get_my_tickets only)
+        limit: Maximum tickets to return (for get_my_tickets, default: 10, max: 100)
+
+    Returns:
+        Results dictionary containing operation-specific data
+
+    Raises:
+        ValueError: If action is invalid
+
+    Examples:
+        # Get user's tickets
+        result = await user_session(
+            action="get_my_tickets",
+            state="open",
+            limit=20
+        )
+
+        # Get user's tickets with project filter
+        result = await user_session(
+            action="get_my_tickets",
+            project_id="PROJ-123",
+            state="in_progress"
+        )
+
+        # Get session info
+        result = await user_session(
+            action="get_session_info"
+        )
+
+    Migration from old tools:
+        - get_my_tickets(state=..., limit=...) → user_session(action="get_my_tickets", state=..., limit=...)
+        - get_session_info() → user_session(action="get_session_info")
+
+    See: docs/mcp-api-reference.md for detailed response formats
+    """
+    action_lower = action.lower()
+
+    # Route to appropriate handler based on action
+    if action_lower == "get_my_tickets":
+        # Inline implementation of get_my_tickets
+        try:
+            from ....core.models import TicketState
+            from ....core.project_config import ConfigResolver, TicketerConfig
+            from ..server_sdk import get_adapter
+
+            # Validate limit
+            if limit > 100:
+                limit = 100
+
+            # Load configuration to get default user and project
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+
+            if not config.default_user:
+                return {
+                    "status": "error",
+                    "error": "No default user configured. Use config_set_default_user() to set a default user first.",
+                    "setup_command": "config_set_default_user",
+                }
+
+            # Validate project context (Required for list operations)
+            final_project = project_id or config.default_project
+
+            if not final_project:
+                return {
+                    "status": "error",
+                    "error": "project_id required. Provide project_id parameter or configure default_project.",
+                    "help": "Use config_set_default_project(project_id='YOUR-PROJECT') to set default project",
+                    "check_config": "Use config_get() to view current configuration",
+                }
+
+            # Validate state if provided
+            state_filter = None
+            if state is not None:
+                try:
+                    state_filter = TicketState(state.lower())
+                except ValueError:
+                    valid_states = [s.value for s in TicketState]
+                    return {
+                        "status": "error",
+                        "error": f"Invalid state '{state}'. Must be one of: {', '.join(valid_states)}",
+                        "valid_states": valid_states,
+                    }
+
+            # Build filters with required project scoping
+            filters: dict[str, Any] = {
+                "assignee": config.default_user,
+                "project": final_project,
+            }
+            if state_filter:
+                filters["state"] = state_filter
+
+            # Query adapter
+            adapter = get_adapter()
+            tickets = await adapter.list(limit=limit, offset=0, filters=filters)
+
+            # Build adapter metadata
+            metadata = {
+                "adapter": adapter.adapter_type,
+                "adapter_name": adapter.adapter_display_name,
+            }
+
+            return {
+                "status": "completed",
+                **metadata,
+                "tickets": [ticket.model_dump() for ticket in tickets],
+                "count": len(tickets),
+                "user": config.default_user,
+                "state_filter": state if state else "all",
+                "limit": limit,
+            }
+        except Exception as e:
+            return {
+                "status": "error",
+                "error": f"Failed to retrieve tickets: {str(e)}",
+            }
+    elif action_lower == "get_session_info":
+        # Inline implementation of get_session_info
+        try:
+            manager = SessionStateManager(project_path=Path.cwd())
+            state_obj = manager.load_session()
+
+            return {
+                "success": True,
+                "session_id": state_obj.session_id,
+                "current_ticket": state_obj.current_ticket,
+                "opted_out": state_obj.ticket_opted_out,
+                "last_activity": state_obj.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),
+            }
+    else:
+        valid_actions = ["get_my_tickets", "get_session_info"]
+        return {
+            "status": "error",
+            "error": f"Invalid action '{action}'. Must be one of: {', '.join(valid_actions)}",
+            "valid_actions": valid_actions,
+            "hint": "Use user_session(action='get_my_tickets'|'get_session_info', ...)",
+        }
+
+
+@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),
+        }