mcp-ticketer 0.3.2__py3-none-any.whl → 0.3.3__py3-none-any.whl

mcp_ticketer/__version__.py

@@ -1,6 +1,6 @@
 """Version information for mcp-ticketer package."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 __version_info__ = tuple(int(part) for part in __version__.split("."))
 
 # Package metadata

mcp_ticketer/adapters/aitrackdown.py

@@ -35,14 +35,17 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         super().__init__(config)
         self.base_path = Path(config.get("base_path", ".aitrackdown"))
         self.tickets_dir = self.base_path / "tickets"
+        self._comment_counter = 0  # Counter for unique comment IDs
 
         # Initialize AI-Trackdown if available
+        # Always create tickets directory (needed for both modes)
+        self.tickets_dir.mkdir(parents=True, exist_ok=True)
+
         if HAS_AITRACKDOWN:
             self.tracker = AITrackdown(str(self.base_path))
         else:
             # Fallback to direct file operations
             self.tracker = None
-            self.tickets_dir.mkdir(parents=True, exist_ok=True)
 
     def validate_credentials(self) -> tuple[bool, str]:
         """Validate that required credentials are present.
@@ -60,10 +63,15 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return True, ""
 
     def _get_state_mapping(self) -> dict[TicketState, str]:
-        """Map universal states to AI-Trackdown states."""
+        """Map universal states to AI-Trackdown states.
+
+        Note: We use the exact enum values (snake_case) to match what
+        Pydantic's use_enum_values=True produces. This ensures consistency
+        between what's written to files and what's read back.
+        """
         return {
             TicketState.OPEN: "open",
-            TicketState.IN_PROGRESS: "in-progress",
+            TicketState.IN_PROGRESS: "in_progress",  # snake_case, not kebab-case
             TicketState.READY: "ready",
             TicketState.TESTED: "tested",
             TicketState.DONE: "done",
@@ -87,6 +95,18 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
     def _task_from_ai_ticket(self, ai_ticket: dict[str, Any]) -> Task:
         """Convert AI-Trackdown ticket to universal Task."""
+        # Get user metadata from ticket file
+        user_metadata = ai_ticket.get("metadata", {})
+
+        # Create adapter metadata
+        adapter_metadata = {
+            "ai_ticket_id": ai_ticket.get("id"),
+            "source": "aitrackdown",
+        }
+
+        # Merge user metadata with adapter metadata (user takes priority)
+        combined_metadata = {**adapter_metadata, **user_metadata}
+
         return Task(
             id=ai_ticket.get("id"),
             title=ai_ticket.get("title", ""),
@@ -107,11 +127,23 @@ class AITrackdownAdapter(BaseAdapter[Task]):
                 if "updated_at" in ai_ticket
                 else None
             ),
-            metadata={"ai_trackdown": ai_ticket},
+            metadata=combined_metadata,  # Use merged metadata
         )
 
     def _epic_from_ai_ticket(self, ai_ticket: dict[str, Any]) -> Epic:
         """Convert AI-Trackdown ticket to universal Epic."""
+        # Get user metadata from ticket file
+        user_metadata = ai_ticket.get("metadata", {})
+
+        # Create adapter metadata
+        adapter_metadata = {
+            "ai_ticket_id": ai_ticket.get("id"),
+            "source": "aitrackdown",
+        }
+
+        # Merge user metadata with adapter metadata (user takes priority)
+        combined_metadata = {**adapter_metadata, **user_metadata}
+
         return Epic(
             id=ai_ticket.get("id"),
             title=ai_ticket.get("title", ""),
@@ -130,20 +162,20 @@ class AITrackdownAdapter(BaseAdapter[Task]):
                 if "updated_at" in ai_ticket and ai_ticket["updated_at"]
                 else None
             ),
-            metadata={"ai_trackdown": ai_ticket},
+            metadata=combined_metadata,  # Use merged metadata
         )
 
     def _task_to_ai_ticket(self, task: Task) -> dict[str, Any]:
         """Convert universal Task to AI-Trackdown ticket."""
         # Handle enum values that may be stored as strings due to use_enum_values=True
+        # Note: task.state is always a string due to ConfigDict(use_enum_values=True)
         state_value = task.state
         if isinstance(task.state, TicketState):
             state_value = self._get_state_mapping()[task.state]
         elif isinstance(task.state, str):
-            # Already a string, map to AI-Trackdown format if needed
-            state_value = task.state.replace(
-                "_", "-"
-            )  # Convert snake_case to kebab-case
+            # Already a string - keep as-is (don't convert to kebab-case)
+            # The state is already in snake_case format from the enum value
+            state_value = task.state
 
         return {
             "id": task.id,
@@ -157,20 +189,21 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             "assignee": task.assignee,
             "created_at": task.created_at.isoformat() if task.created_at else None,
             "updated_at": task.updated_at.isoformat() if task.updated_at else None,
+            "metadata": task.metadata or {},  # Serialize user metadata
             "type": "task",
         }
 
     def _epic_to_ai_ticket(self, epic: Epic) -> dict[str, Any]:
         """Convert universal Epic to AI-Trackdown ticket."""
         # Handle enum values that may be stored as strings due to use_enum_values=True
+        # Note: epic.state is always a string due to ConfigDict(use_enum_values=True)
         state_value = epic.state
         if isinstance(epic.state, TicketState):
             state_value = self._get_state_mapping()[epic.state]
         elif isinstance(epic.state, str):
-            # Already a string, map to AI-Trackdown format if needed
-            state_value = epic.state.replace(
-                "_", "-"
-            )  # Convert snake_case to kebab-case
+            # Already a string - keep as-is (don't convert to kebab-case)
+            # The state is already in snake_case format from the enum value
+            state_value = epic.state
 
         return {
             "id": epic.id,
@@ -182,6 +215,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             "child_issues": epic.child_issues,
             "created_at": epic.created_at.isoformat() if epic.created_at else None,
             "updated_at": epic.updated_at.isoformat() if epic.updated_at else None,
+            "metadata": epic.metadata or {},  # Serialize user metadata
             "type": "epic",
         }
 
@@ -307,8 +341,20 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
     async def update(
         self, ticket_id: str, updates: Union[dict[str, Any], Task]
-    ) -> Optional[Task]:
-        """Update a task."""
+    ) -> Optional[Union[Task, Epic]]:
+        """Update a task or epic.
+
+        Args:
+            ticket_id: ID of ticket to update
+            updates: Dictionary of updates or Task object with new values
+
+        Returns:
+            Updated Task or Epic, or None if ticket not found
+
+        Raises:
+            AttributeError: If update fails due to invalid fields
+
+        """
         # Read existing ticket
         existing = await self.read(ticket_id)
         if not existing:
@@ -332,8 +378,12 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
         existing.updated_at = datetime.now()
 
-        # Write back
-        ai_ticket = self._task_to_ai_ticket(existing)
+        # Write back - use appropriate converter based on ticket type
+        if isinstance(existing, Epic):
+            ai_ticket = self._epic_to_ai_ticket(existing)
+        else:
+            ai_ticket = self._task_to_ai_ticket(existing)
+
         if self.tracker:
             self.tracker.update_ticket(ticket_id, **updates)
         else:
@@ -448,10 +498,11 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
     async def add_comment(self, comment: Comment) -> Comment:
         """Add comment to a task."""
-        # Generate ID
+        # Generate ID with counter to ensure uniqueness
         if not comment.id:
             timestamp = datetime.now().strftime("%Y%m%d%H%M%S%f")
-            comment.id = f"comment-{timestamp}"
+            self._comment_counter += 1
+            comment.id = f"comment-{timestamp}-{self._comment_counter:04d}"
 
         comment.created_at = datetime.now()
 
@@ -472,14 +523,94 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         comments_dir = self.base_path / "comments"
 
         if comments_dir.exists():
+            # Get all comment files and filter by ticket_id first
             comment_files = sorted(comments_dir.glob("*.json"))
-            for comment_file in comment_files[offset : offset + limit]:
+            for comment_file in comment_files:
                 with open(comment_file) as f:
                     data = json.load(f)
                     if data.get("ticket_id") == ticket_id:
                         comments.append(Comment(**data))
 
-        return comments[:limit]
+        # Apply limit and offset AFTER filtering
+        return comments[offset : offset + limit]
+
+    async def get_epic(self, epic_id: str) -> Optional[Epic]:
+        """Get epic by ID.
+
+        Args:
+            epic_id: Epic ID to retrieve
+
+        Returns:
+            Epic if found, None otherwise
+
+        """
+        ticket = await self.read(epic_id)
+        if ticket:
+            # Check if it's an Epic (can be Epic instance or have epic ticket_type)
+            if isinstance(ticket, Epic):
+                return ticket
+            # Check ticket_type (may be string or enum)
+            ticket_type_str = (
+                str(ticket.ticket_type).lower()
+                if hasattr(ticket, "ticket_type")
+                else None
+            )
+            if ticket_type_str and "epic" in ticket_type_str:
+                return Epic(**ticket.model_dump())
+        return None
+
+    async def list_epics(self, limit: int = 10, offset: int = 0) -> builtins.list[Epic]:
+        """List all epics.
+
+        Args:
+            limit: Maximum number of epics to return
+            offset: Number of epics to skip
+
+        Returns:
+            List of epics
+
+        """
+        all_tickets = await self.list(limit=100, offset=0, filters={"type": "epic"})
+        epics = []
+        for ticket in all_tickets:
+            if ticket.ticket_type == "epic":
+                epics.append(Epic(**ticket.model_dump()))
+        return epics[offset : offset + limit]
+
+    async def list_issues_by_epic(self, epic_id: str) -> builtins.list[Task]:
+        """List all issues belonging to an epic.
+
+        Args:
+            epic_id: Epic ID to get issues for
+
+        Returns:
+            List of issues (tasks with parent_epic set)
+
+        """
+        all_tickets = await self.list(limit=1000, offset=0, filters={})
+        issues = []
+        for ticket in all_tickets:
+            if hasattr(ticket, "parent_epic") and ticket.parent_epic == epic_id:
+                issues.append(ticket)
+        return issues
+
+    async def list_tasks_by_issue(self, issue_id: str) -> builtins.list[Task]:
+        """List all tasks belonging to an issue.
+
+        Args:
+            issue_id: Issue ID (parent task) to get child tasks for
+
+        Returns:
+            List of tasks
+
+        """
+        all_tickets = await self.list(limit=1000, offset=0, filters={})
+        tasks = []
+        for ticket in all_tickets:
+            # Check if this ticket has parent_issue matching the issue
+            if hasattr(ticket, "parent_issue") and ticket.parent_issue == issue_id:
+                tasks.append(ticket)
+        return tasks
 
 
 # Register the adapter

mcp_ticketer/adapters/github.py

@@ -3,7 +3,7 @@
 import builtins
 import re
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
 import httpx
 
@@ -603,7 +603,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             labels_to_update = update_data.get("labels", current_labels)
             all_priority_labels = []
             for labels in GitHubStateMapping.PRIORITY_LABELS.values():
-                all_priority_labels.extend([l.lower() for l in labels])
+                all_priority_labels.extend([label.lower() for label in labels])
 
             labels_to_update = [
                 label
@@ -1334,7 +1334,7 @@ Fixes #{issue_number}
             "message": f"Successfully linked PR #{pr_number} to issue #{issue_number}",
         }
 
-    async def get_collaborators(self) -> List[Dict[str, Any]]:
+    async def get_collaborators(self) -> builtins.list[dict[str, Any]]:
         """Get repository collaborators."""
         response = await self.client.get(
             f"/repos/{self.owner}/{self.repo}/collaborators"
@@ -1342,7 +1342,7 @@ Fixes #{issue_number}
         response.raise_for_status()
         return response.json()
 
-    async def get_current_user(self) -> Optional[Dict[str, Any]]:
+    async def get_current_user(self) -> Optional[dict[str, Any]]:
         """Get current authenticated user information."""
         response = await self.client.get("/user")
         response.raise_for_status()

mcp_ticketer/adapters/jira.py

@@ -6,7 +6,7 @@ import logging
 import re
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Optional, Union
 
 import httpx
 from httpx import AsyncClient, HTTPStatusError, TimeoutException
@@ -47,7 +47,7 @@ def parse_jira_datetime(date_str: str) -> Optional[datetime]:
         return None
 
 
-def extract_text_from_adf(adf_content: Union[str, Dict[str, Any]]) -> str:
+def extract_text_from_adf(adf_content: Union[str, dict[str, Any]]) -> str:
     """Extract plain text from Atlassian Document Format (ADF).
 
     Args:
@@ -63,7 +63,7 @@ def extract_text_from_adf(adf_content: Union[str, Dict[str, Any]]) -> str:
     if not isinstance(adf_content, dict):
         return str(adf_content) if adf_content else ""
 
-    def extract_text_recursive(node: Dict[str, Any]) -> str:
+    def extract_text_recursive(node: dict[str, Any]) -> str:
         """Recursively extract text from ADF nodes."""
         if not isinstance(node, dict):
             return ""
@@ -940,7 +940,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
         return sprints_data.get("values", [])
 
-    async def get_project_users(self) -> List[Dict[str, Any]]:
+    async def get_project_users(self) -> builtins.list[dict[str, Any]]:
         """Get users who have access to the project."""
         if not self.project_key:
             return []
@@ -954,7 +954,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
             # Get users from project roles
             users = []
             if "roles" in project_data:
-                for role_name, role_url in project_data["roles"].items():
+                for _role_name, role_url in project_data["roles"].items():
                     # Extract role ID from URL
                     role_id = role_url.split("/")[-1]
                     try:
@@ -992,7 +992,7 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
             except Exception:
                 return []
 
-    async def get_current_user(self) -> Optional[Dict[str, Any]]:
+    async def get_current_user(self) -> Optional[dict[str, Any]]:
         """Get current authenticated user information."""
         try:
             return await self._make_request("GET", "myself")

mcp_ticketer/adapters/linear/adapter.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import os
-from typing import Any, Dict, List, Optional, Union
+from typing import Any
 
 try:
     from gql import gql
@@ -12,6 +12,8 @@ except ImportError:
     gql = None
     TransportQueryError = Exception
 
+import builtins
+
 from ...core.adapter import BaseAdapter
 from ...core.models import Comment, Epic, SearchQuery, Task, TicketState
 from ...core.registry import AdapterRegistry
@@ -58,7 +60,7 @@ class LinearAdapter(BaseAdapter[Task]):
     - mappers.py: Data transformation logic
     """
 
-    def __init__(self, config: Dict[str, Any]):
+    def __init__(self, config: dict[str, Any]):
         """Initialize Linear adapter.
 
         Args:
@@ -75,10 +77,10 @@ class LinearAdapter(BaseAdapter[Task]):
         """
         # Initialize instance variables before calling super().__init__
         # because parent constructor calls _get_state_mapping()
-        self._team_data: Optional[Dict[str, Any]] = None
-        self._workflow_states: Optional[Dict[str, Dict[str, Any]]] = None
-        self._labels_cache: Optional[List[Dict[str, Any]]] = None
-        self._users_cache: Optional[Dict[str, Dict[str, Any]]] = None
+        self._team_data: dict[str, Any] | None = None
+        self._workflow_states: dict[str, dict[str, Any]] | None = None
+        self._labels_cache: list[dict[str, Any]] | None = None
+        self._users_cache: dict[str, dict[str, Any]] | None = None
         self._initialized = False
 
         super().__init__(config)
@@ -214,7 +216,7 @@ class LinearAdapter(BaseAdapter[Task]):
         except Exception as e:
             raise ValueError(f"Failed to load workflow states: {e}")
 
-    def _get_state_mapping(self) -> Dict[TicketState, str]:
+    def _get_state_mapping(self) -> dict[TicketState, str]:
         """Get mapping from universal states to Linear workflow state IDs.
 
         Returns:
@@ -245,7 +247,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
         return mapping
 
-    async def _get_user_id(self, user_identifier: str) -> Optional[str]:
+    async def _get_user_id(self, user_identifier: str) -> str | None:
         """Get Linear user ID from email or display name.
 
         Args:
@@ -266,7 +268,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
     # CRUD Operations
 
-    async def create(self, ticket: Union[Epic, Task]) -> Union[Epic, Task]:
+    async def create(self, ticket: Epic | Task) -> Epic | Task:
         """Create a new Linear issue or project with full field support.
 
         Args:
@@ -394,7 +396,7 @@ class LinearAdapter(BaseAdapter[Task]):
         except Exception as e:
             raise ValueError(f"Failed to create Linear project: {e}")
 
-    async def read(self, ticket_id: str) -> Optional[Task]:
+    async def read(self, ticket_id: str) -> Task | None:
         """Read a Linear issue by identifier with full details.
 
         Args:
@@ -432,7 +434,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
         return None
 
-    async def update(self, ticket_id: str, updates: Dict[str, Any]) -> Optional[Task]:
+    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Task | None:
         """Update a Linear issue with comprehensive field support.
 
         Args:
@@ -519,8 +521,8 @@ class LinearAdapter(BaseAdapter[Task]):
             return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[Dict[str, Any]] = None
-    ) -> List[Task]:
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
+    ) -> builtins.list[Task]:
         """List Linear issues with optional filtering.
 
         Args:
@@ -578,7 +580,7 @@ class LinearAdapter(BaseAdapter[Task]):
         except Exception as e:
             raise ValueError(f"Failed to list Linear issues: {e}")
 
-    async def search(self, query: SearchQuery) -> List[Task]:
+    async def search(self, query: SearchQuery) -> builtins.list[Task]:
         """Search Linear issues using comprehensive filters.
 
         Args:
@@ -644,7 +646,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Transition Linear issue to new state with workflow validation.
 
         Args:
@@ -749,7 +751,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
     async def get_comments(
         self, ticket_id: str, limit: int = 10, offset: int = 0
-    ) -> List[Comment]:
+    ) -> builtins.list[Comment]:
         """Get comments for a Linear issue.
 
         Args:

mcp_ticketer/adapters/linear/client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Dict, Optional
+from typing import Any
 
 try:
     from gql import Client, gql
@@ -74,9 +74,9 @@ class LinearGraphQLClient:
     async def execute_query(
         self,
         query_string: str,
-        variables: Optional[Dict[str, Any]] = None,
+        variables: dict[str, Any] | None = None,
         retries: int = 3,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Execute a GraphQL query with error handling and retries.
 
         Args:
@@ -161,9 +161,9 @@ class LinearGraphQLClient:
     async def execute_mutation(
         self,
         mutation_string: str,
-        variables: Optional[Dict[str, Any]] = None,
+        variables: dict[str, Any] | None = None,
         retries: int = 3,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Execute a GraphQL mutation with error handling.
 
         Args:
@@ -206,7 +206,7 @@ class LinearGraphQLClient:
         except Exception:
             return False
 
-    async def get_team_info(self, team_id: str) -> Optional[Dict[str, Any]]:
+    async def get_team_info(self, team_id: str) -> dict[str, Any] | None:
         """Get team information by ID.
 
         Args:
@@ -234,7 +234,7 @@ class LinearGraphQLClient:
         except Exception:
             return None
 
-    async def get_user_by_email(self, email: str) -> Optional[Dict[str, Any]]:
+    async def get_user_by_email(self, email: str) -> dict[str, Any] | None:
         """Get user information by email.
 
         Args:

mcp_ticketer/adapters/linear/mappers.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any, Dict, List
+from typing import Any
 
 from ...core.models import Comment, Epic, Priority, Task, TicketState
 from .types import extract_linear_metadata, get_universal_priority, get_universal_state
 
 
-def map_linear_issue_to_task(issue_data: Dict[str, Any]) -> Task:
+def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
     """Convert Linear issue data to universal Task model.
 
     Args:
@@ -94,7 +94,7 @@ def map_linear_issue_to_task(issue_data: Dict[str, Any]) -> Task:
     )
 
 
-def map_linear_project_to_epic(project_data: Dict[str, Any]) -> Epic:
+def map_linear_project_to_epic(project_data: dict[str, Any]) -> Epic:
     """Convert Linear project data to universal Epic model.
 
     Args:
@@ -157,7 +157,7 @@ def map_linear_project_to_epic(project_data: Dict[str, Any]) -> Epic:
 
 
 def map_linear_comment_to_comment(
-    comment_data: Dict[str, Any], ticket_id: str
+    comment_data: dict[str, Any], ticket_id: str
 ) -> Comment:
     """Convert Linear comment data to universal Comment model.
 
@@ -202,7 +202,7 @@ def map_linear_comment_to_comment(
     )
 
 
-def build_linear_issue_input(task: Task, team_id: str) -> Dict[str, Any]:
+def build_linear_issue_input(task: Task, team_id: str) -> dict[str, Any]:
     """Build Linear issue input from universal Task model.
 
     Args:
@@ -259,7 +259,7 @@ def build_linear_issue_input(task: Task, team_id: str) -> Dict[str, Any]:
     return issue_input
 
 
-def build_linear_issue_update_input(updates: Dict[str, Any]) -> Dict[str, Any]:
+def build_linear_issue_update_input(updates: dict[str, Any]) -> dict[str, Any]:
     """Build Linear issue update input from update dictionary.
 
     Args:
@@ -311,7 +311,7 @@ def build_linear_issue_update_input(updates: Dict[str, Any]) -> Dict[str, Any]:
     return update_input
 
 
-def extract_child_issue_ids(issue_data: Dict[str, Any]) -> List[str]:
+def extract_child_issue_ids(issue_data: dict[str, Any]) -> list[str]:
     """Extract child issue IDs from Linear issue data.
 
     Args: