mcp-ticketer 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

mcp_ticketer/mcp/tools/search_tools.py

@@ -0,0 +1,206 @@
+"""Search and query tools for finding tickets.
+
+This module implements advanced search capabilities for tickets using
+various filters and criteria.
+"""
+
+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()
+
+        # 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/tools/ticket_tools.py

@@ -0,0 +1,277 @@
+"""Basic CRUD operations for tickets.
+
+This module implements the core create, read, update, delete, and list
+operations for tickets using the FastMCP SDK.
+"""
+
+from typing import Any
+
+from ...core.models import Priority, Task, TicketState
+from ..server_sdk import get_adapter, mcp
+
+
+@mcp.tool()
+async def ticket_create(
+    title: str,
+    description: str = "",
+    priority: str = "medium",
+    tags: list[str] | None = None,
+    assignee: str | None = None,
+) -> dict[str, Any]:
+    """Create a new ticket with specified details.
+
+    Args:
+        title: Ticket title (required)
+        description: Detailed description of the ticket
+        priority: Priority level - must be one of: low, medium, high, critical
+        tags: List of tags to categorize the ticket
+        assignee: User ID or email to assign the ticket to
+
+    Returns:
+        Created ticket details including ID and metadata, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Validate and convert priority
+        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 task object
+        task = Task(
+            title=title,
+            description=description or "",
+            priority=priority_enum,
+            tags=tags or [],
+            assignee=assignee,
+        )
+
+        # Create via adapter
+        created = await adapter.create(task)
+
+        return {
+            "status": "completed",
+            "ticket": created.model_dump(),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to create ticket: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_read(ticket_id: str) -> dict[str, Any]:
+    """Read a ticket by its ID.
+
+    Args:
+        ticket_id: Unique identifier of the ticket to retrieve
+
+    Returns:
+        Ticket details if found, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+        ticket = await adapter.read(ticket_id)
+
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        return {
+            "status": "completed",
+            "ticket": ticket.model_dump(),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to read ticket: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_update(
+    ticket_id: str,
+    title: str | None = None,
+    description: str | None = None,
+    priority: str | None = None,
+    state: str | None = None,
+    assignee: str | None = None,
+    tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """Update an existing ticket.
+
+    Args:
+        ticket_id: Unique identifier of the ticket to update
+        title: New title for the ticket
+        description: New description for the ticket
+        priority: New priority - must be one of: low, medium, high, critical
+        state: New state - must be one of: open, in_progress, ready, tested, done, closed, waiting, blocked
+        assignee: User ID or email to assign the ticket to
+        tags: New list of tags (replaces existing tags)
+
+    Returns:
+        Updated ticket details, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Build updates dictionary with only provided fields
+        updates: dict[str, Any] = {}
+
+        if title is not None:
+            updates["title"] = title
+        if description is not None:
+            updates["description"] = description
+        if assignee is not None:
+            updates["assignee"] = assignee
+        if tags is not None:
+            updates["tags"] = tags
+
+        # Validate and convert priority if provided
+        if priority is not None:
+            try:
+                updates["priority"] = Priority(priority.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
+                }
+
+        # Validate and convert state if provided
+        if state is not None:
+            try:
+                updates["state"] = 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",
+                }
+
+        # Update via adapter
+        updated = await adapter.update(ticket_id, updates)
+
+        if updated is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found or update failed",
+            }
+
+        return {
+            "status": "completed",
+            "ticket": updated.model_dump(),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to update ticket: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_delete(ticket_id: str) -> dict[str, Any]:
+    """Delete a ticket by its ID.
+
+    Args:
+        ticket_id: Unique identifier of the ticket to delete
+
+    Returns:
+        Success confirmation or error information
+
+    """
+    try:
+        adapter = get_adapter()
+        success = await adapter.delete(ticket_id)
+
+        if not success:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found or delete failed",
+            }
+
+        return {
+            "status": "completed",
+            "message": f"Ticket {ticket_id} deleted successfully",
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to delete ticket: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_list(
+    limit: int = 10,
+    offset: int = 0,
+    state: str | None = None,
+    priority: str | None = None,
+    assignee: str | None = None,
+) -> dict[str, Any]:
+    """List tickets with pagination and optional filters.
+
+    Args:
+        limit: Maximum number of tickets to return (default: 10)
+        offset: Number of tickets to skip for pagination (default: 0)
+        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
+        assignee: Filter by assigned user ID or email
+
+    Returns:
+        List of tickets matching criteria, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Build filters dictionary
+        filters: dict[str, Any] = {}
+
+        if state is not None:
+            try:
+                filters["state"] = 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",
+                }
+
+        if priority is not None:
+            try:
+                filters["priority"] = Priority(priority.lower())
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
+                }
+
+        if assignee is not None:
+            filters["assignee"] = assignee
+
+        # List tickets via adapter
+        tickets = await adapter.list(
+            limit=limit, offset=offset, filters=filters if filters else None
+        )
+
+        return {
+            "status": "completed",
+            "tickets": [ticket.model_dump() for ticket in tickets],
+            "count": len(tickets),
+            "limit": limit,
+            "offset": offset,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to list tickets: {str(e)}",
+        }

mcp_ticketer/queue/health_monitor.py

@@ -4,7 +4,7 @@ import logging
 import time
 from datetime import datetime, timedelta
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 import psutil
 
@@ -30,8 +30,8 @@ class HealthAlert:
         self,
         level: HealthStatus,
         message: str,
-        details: Optional[dict[str, Any]] = None,
-        timestamp: Optional[datetime] = None,
+        details: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
     ):
         self.level = level
         self.message = message
@@ -52,7 +52,7 @@ class QueueHealthMonitor:
     QUEUE_BACKLOG_WARNING = 10  # Warn if more than 10 pending items
     QUEUE_BACKLOG_CRITICAL = 50  # Critical if more than 50 pending items
 
-    def __init__(self, queue: Optional[Queue] = None):
+    def __init__(self, queue: Queue | None = None):
         """Initialize health monitor.
 
         Args:

mcp_ticketer/queue/manager.py

@@ -7,7 +7,7 @@ import subprocess
 import sys
 import time
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 import psutil
 
@@ -304,7 +304,7 @@ class WorkerManager:
 
         return status
 
-    def _get_pid(self) -> Optional[int]:
+    def _get_pid(self) -> int | None:
         """Get worker PID from file.
 
         Returns:

mcp_ticketer/queue/queue.py

@@ -8,7 +8,7 @@ from dataclasses import asdict, dataclass
 from datetime import datetime, timedelta
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 
 class QueueStatus(str, Enum):
@@ -30,12 +30,12 @@ class QueueItem:
     operation: str
     status: QueueStatus
     created_at: datetime
-    processed_at: Optional[datetime] = None
-    error_message: Optional[str] = None
+    processed_at: datetime | None = None
+    error_message: str | None = None
     retry_count: int = 0
-    result: Optional[dict[str, Any]] = None
-    project_dir: Optional[str] = None
-    adapter_config: Optional[dict[str, Any]] = None  # Adapter configuration
+    result: dict[str, Any] | None = None
+    project_dir: str | None = None
+    adapter_config: dict[str, Any] | None = None  # Adapter configuration
 
     def to_dict(self) -> dict:
         """Convert to dictionary for storage."""
@@ -67,7 +67,7 @@ class QueueItem:
 class Queue:
     """Thread-safe SQLite queue for ticket operations."""
 
-    def __init__(self, db_path: Optional[Path] = None):
+    def __init__(self, db_path: Path | None = None):
         """Initialize queue with database connection.
 
         Args:
@@ -139,8 +139,8 @@ class Queue:
         ticket_data: dict[str, Any],
         adapter: str,
         operation: str,
-        project_dir: Optional[str] = None,
-        adapter_config: Optional[dict[str, Any]] = None,
+        project_dir: str | None = None,
+        adapter_config: dict[str, Any] | None = None,
     ) -> str:
         """Add item to queue.
 
@@ -186,7 +186,7 @@ class Queue:
 
         return queue_id
 
-    def get_next_pending(self) -> Optional[QueueItem]:
+    def get_next_pending(self) -> QueueItem | None:
         """Get next pending item from queue atomically.
 
         Returns:
@@ -251,9 +251,9 @@ class Queue:
         self,
         queue_id: str,
         status: QueueStatus,
-        error_message: Optional[str] = None,
-        result: Optional[dict[str, Any]] = None,
-        expected_status: Optional[QueueStatus] = None,
+        error_message: str | None = None,
+        result: dict[str, Any] | None = None,
+        expected_status: QueueStatus | None = None,
     ) -> bool:
         """Update queue item status atomically.
 
@@ -328,7 +328,7 @@ class Queue:
                     raise
 
     def increment_retry(
-        self, queue_id: str, expected_status: Optional[QueueStatus] = None
+        self, queue_id: str, expected_status: QueueStatus | None = None
     ) -> int:
         """Increment retry count and reset to pending atomically.
 
@@ -387,7 +387,7 @@ class Queue:
                     conn.rollback()
                     raise
 
-    def get_item(self, queue_id: str) -> Optional[QueueItem]:
+    def get_item(self, queue_id: str) -> QueueItem | None:
         """Get specific queue item by ID.
 
         Args:
@@ -409,7 +409,7 @@ class Queue:
             return QueueItem.from_row(row) if row else None
 
     def list_items(
-        self, status: Optional[QueueStatus] = None, limit: int = 50
+        self, status: QueueStatus | None = None, limit: int = 50
     ) -> list[QueueItem]:
         """List queue items.
 

mcp_ticketer/queue/ticket_registry.py

@@ -5,13 +5,13 @@ import sqlite3
 import threading
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 
 class TicketRegistry:
     """Persistent registry for tracking ticket IDs and their lifecycle."""
 
-    def __init__(self, db_path: Optional[Path] = None):
+    def __init__(self, db_path: Path | None = None):
         """Initialize ticket registry.
 
         Args:
@@ -130,10 +130,10 @@ class TicketRegistry:
         self,
         queue_id: str,
         status: str,
-        ticket_id: Optional[str] = None,
-        result_data: Optional[dict[str, Any]] = None,
-        error_message: Optional[str] = None,
-        retry_count: Optional[int] = None,
+        ticket_id: str | None = None,
+        result_data: dict[str, Any] | None = None,
+        error_message: str | None = None,
+        retry_count: int | None = None,
     ) -> None:
         """Update ticket operation status.
 
@@ -179,7 +179,7 @@ class TicketRegistry:
                 )
                 conn.commit()
 
-    def get_ticket_info(self, queue_id: str) -> Optional[dict[str, Any]]:
+    def get_ticket_info(self, queue_id: str) -> dict[str, Any] | None:
         """Get ticket information by queue ID.
 
         Args:

mcp_ticketer/queue/worker.py

@@ -7,7 +7,7 @@ import threading
 import time
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from dotenv import load_dotenv
 
@@ -58,7 +58,7 @@ class Worker:
 
     def __init__(
         self,
-        queue: Optional[Queue] = None,
+        queue: Queue | None = None,
         batch_size: int = DEFAULT_BATCH_SIZE,
         max_concurrent: int = DEFAULT_MAX_CONCURRENT,
     ):