mcp-ticketer 0.3.1__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.1"
+__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",
         }
 
@@ -245,15 +279,14 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
         Returns:
             Created Epic instance
+
         """
-        epic = Epic(
-            title=title,
-            description=description,
-            **kwargs
-        )
+        epic = Epic(title=title, description=description, **kwargs)
         return await self.create(epic)
 
-    async def create_issue(self, title: str, parent_epic: str = None, description: str = None, **kwargs) -> Task:
+    async def create_issue(
+        self, title: str, parent_epic: str = None, description: str = None, **kwargs
+    ) -> Task:
         """Create a new issue.
 
         Args:
@@ -264,16 +297,16 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
         Returns:
             Created Task instance (representing an issue)
+
         """
         task = Task(
-            title=title,
-            description=description,
-            parent_epic=parent_epic,
-            **kwargs
+            title=title, description=description, parent_epic=parent_epic, **kwargs
         )
         return await self.create(task)
 
-    async def create_task(self, title: str, parent_id: str, description: str = None, **kwargs) -> Task:
+    async def create_task(
+        self, title: str, parent_id: str, description: str = None, **kwargs
+    ) -> Task:
         """Create a new task under an issue.
 
         Args:
@@ -284,12 +317,10 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
         Returns:
             Created Task instance
+
         """
         task = Task(
-            title=title,
-            description=description,
-            parent_issue=parent_id,
-            **kwargs
+            title=title, description=description, parent_issue=parent_id, **kwargs
         )
         return await self.create(task)
 
@@ -310,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:
@@ -335,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:
@@ -451,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()
 
@@ -475,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

@@ -1,17 +1,16 @@
 """GitHub adapter implementation using REST API v3 and GraphQL API v4."""
 
 import builtins
-import os
 import re
 from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
 import httpx
 
 from ..core.adapter import BaseAdapter
+from ..core.env_loader import load_adapter_config, validate_adapter_config
 from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
 from ..core.registry import AdapterRegistry
-from ..core.env_loader import load_adapter_config, validate_adapter_config
 
 
 class GitHubStateMapping:
@@ -158,11 +157,15 @@ class GitHubAdapter(BaseAdapter[Task]):
         # Validate required configuration
         missing_keys = validate_adapter_config("github", full_config)
         if missing_keys:
-            raise ValueError(f"GitHub adapter missing required configuration: {', '.join(missing_keys)}")
+            raise ValueError(
+                f"GitHub adapter missing required configuration: {', '.join(missing_keys)}"
+            )
 
         # Get authentication token - support both 'api_key' and 'token' for compatibility
         self.token = (
-            full_config.get("api_key") or full_config.get("token") or full_config.get("token")
+            full_config.get("api_key")
+            or full_config.get("token")
+            or full_config.get("token")
         )
 
         # Get repository information
@@ -600,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
@@ -1331,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"
@@ -1339,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

@@ -3,26 +3,24 @@
 import asyncio
 import builtins
 import logging
-import os
 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
 
 from ..core.adapter import BaseAdapter
+from ..core.env_loader import load_adapter_config, validate_adapter_config
 from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
 from ..core.registry import AdapterRegistry
-from ..core.env_loader import load_adapter_config, validate_adapter_config
 
 logger = logging.getLogger(__name__)
 
 
 def parse_jira_datetime(date_str: str) -> Optional[datetime]:
-    """
-    Parse JIRA datetime strings which can be in various formats.
+    """Parse JIRA datetime strings which can be in various formats.
 
     JIRA can return dates in formats like:
     - 2025-10-24T14:12:18.771-0400
@@ -34,13 +32,13 @@ def parse_jira_datetime(date_str: str) -> Optional[datetime]:
 
     try:
         # Handle Z timezone
-        if date_str.endswith('Z'):
-            return datetime.fromisoformat(date_str.replace('Z', '+00:00'))
+        if date_str.endswith("Z"):
+            return datetime.fromisoformat(date_str.replace("Z", "+00:00"))
 
         # Handle timezone formats like -0400, +0500 (need to add colon)
-        if re.match(r'.*[+-]\d{4}$', date_str):
+        if re.match(r".*[+-]\d{4}$", date_str):
             # Insert colon in timezone: -0400 -> -04:00
-            date_str = re.sub(r'([+-]\d{2})(\d{2})$', r'\1:\2', date_str)
+            date_str = re.sub(r"([+-]\d{2})(\d{2})$", r"\1:\2", date_str)
 
         return datetime.fromisoformat(date_str)
 
@@ -49,15 +47,15 @@ def parse_jira_datetime(date_str: str) -> Optional[datetime]:
         return None
 
 
-def extract_text_from_adf(adf_content: Union[str, Dict[str, Any]]) -> str:
-    """
-    Extract plain text from Atlassian Document Format (ADF).
+def extract_text_from_adf(adf_content: Union[str, dict[str, Any]]) -> str:
+    """Extract plain text from Atlassian Document Format (ADF).
 
     Args:
         adf_content: Either a string (already plain text) or ADF document dict
 
     Returns:
         Plain text string extracted from the ADF content
+
     """
     if isinstance(adf_content, str):
         return adf_content
@@ -65,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 ""
@@ -136,7 +134,9 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
         # Validate required configuration
         missing_keys = validate_adapter_config("jira", full_config)
         if missing_keys:
-            raise ValueError(f"JIRA adapter missing required configuration: {', '.join(missing_keys)}")
+            raise ValueError(
+                f"JIRA adapter missing required configuration: {', '.join(missing_keys)}"
+            )
 
         # Configuration
         self.server = full_config.get("server", "")
@@ -803,14 +803,9 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
                 "content": [
                     {
                         "type": "paragraph",
-                        "content": [
-                            {
-                                "type": "text",
-                                "text": comment.content
-                            }
-                        ]
+                        "content": [{"type": "text", "text": comment.content}],
                     }
-                ]
+                ],
             }
         }
 
@@ -821,7 +816,9 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
 
         # Update comment with JIRA data
         comment.id = result.get("id")
-        comment.created_at = parse_jira_datetime(result.get("created")) or datetime.now()
+        comment.created_at = (
+            parse_jira_datetime(result.get("created")) or datetime.now()
+        )
         comment.author = result.get("author", {}).get("displayName", comment.author)
         comment.metadata["jira"] = result
 
@@ -943,23 +940,27 @@ 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 []
 
         try:
             # Get project role users
-            project_data = await self._make_request("GET", f"project/{self.project_key}")
+            project_data = await self._make_request(
+                "GET", f"project/{self.project_key}"
+            )
 
             # 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:
-                        role_data = await self._make_request("GET", f"project/{self.project_key}/role/{role_id}")
+                        role_data = await self._make_request(
+                            "GET", f"project/{self.project_key}/role/{role_id}"
+                        )
                         if "actors" in role_data:
                             for actor in role_data["actors"]:
                                 if actor.get("type") == "atlassian-user-role-actor":
@@ -985,13 +986,13 @@ class JiraAdapter(BaseAdapter[Union[Epic, Task]]):
                 users_data = await self._make_request(
                     "GET",
                     "user/assignable/search",
-                    params={"project": self.project_key, "maxResults": 50}
+                    params={"project": self.project_key, "maxResults": 50},
                 )
                 return users_data if isinstance(users_data, list) else []
             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/__init__.py

@@ -11,7 +11,7 @@ The adapter is split into multiple modules for better organization:
 
 Usage:
     from mcp_ticketer.adapters.linear import LinearAdapter
-    
+
     config = {
         "api_key": "your_linear_api_key",
         "team_id": "your_team_id"