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

mcp_ticketer/__version__.py

@@ -1,6 +1,6 @@
 """Version information for mcp-ticketer package."""
 
-__version__ = "0.3.5"
+__version__ = "0.12.0"
 __version_info__ = tuple(int(part) for part in __version__.split("."))
 
 # Package metadata
@@ -27,7 +27,7 @@ __features__ = {
 }
 
 
-def get_version():
+def get_version() -> str:
     """Return the full version string with build metadata if available."""
     version = __version__
     if __build__:
@@ -37,6 +37,6 @@ def get_version():
     return version
 
 
-def get_user_agent():
+def get_user_agent() -> str:
     """Return a user agent string for API requests."""
     return f"{__title__}/{__version__}"

mcp_ticketer/adapters/__init__.py

@@ -1,6 +1,7 @@
 """Adapter implementations for various ticket systems."""
 
 from .aitrackdown import AITrackdownAdapter
+from .asana import AsanaAdapter
 from .github import GitHubAdapter
 from .hybrid import HybridAdapter
 from .jira import JiraAdapter
@@ -8,6 +9,7 @@ from .linear import LinearAdapter
 
 __all__ = [
     "AITrackdownAdapter",
+    "AsanaAdapter",
     "LinearAdapter",
     "JiraAdapter",
     "GitHubAdapter",

mcp_ticketer/adapters/aitrackdown.py

@@ -2,14 +2,25 @@
 
 import builtins
 import json
+import logging
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 from ..core.adapter import BaseAdapter
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
+from ..core.models import (
+    Attachment,
+    Comment,
+    Epic,
+    Priority,
+    SearchQuery,
+    Task,
+    TicketState,
+)
 from ..core.registry import AdapterRegistry
 
+logger = logging.getLogger(__name__)
+
 # Import ai-trackdown-pytools when available
 try:
     from ai_trackdown_pytools import AITrackdown
@@ -80,7 +91,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             TicketState.CLOSED: "closed",
         }
 
-    def _priority_to_ai(self, priority: Union[Priority, str]) -> str:
+    def _priority_to_ai(self, priority: Priority | str) -> str:
         """Convert universal priority to AI-Trackdown priority."""
         if isinstance(priority, Priority):
             return priority.value
@@ -219,7 +230,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             "type": "epic",
         }
 
-    def _read_ticket_file(self, ticket_id: str) -> Optional[dict[str, Any]]:
+    def _read_ticket_file(self, ticket_id: str) -> dict[str, Any] | None:
         """Read ticket from file system."""
         ticket_file = self.tickets_dir / f"{ticket_id}.json"
         if ticket_file.exists():
@@ -233,7 +244,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         with open(ticket_file, "w") as f:
             json.dump(data, f, indent=2, default=str)
 
-    async def create(self, ticket: Union[Task, Epic]) -> Union[Task, Epic]:
+    async def create(self, ticket: Task | Epic) -> Task | Epic:
         """Create a new task."""
         # Generate ID if not provided
         if not ticket.id:
@@ -269,7 +280,9 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
         return ticket
 
-    async def create_epic(self, title: str, description: str = None, **kwargs) -> Epic:
+    async def create_epic(
+        self, title: str, description: str = None, **kwargs: Any
+    ) -> Epic:
         """Create a new epic.
 
         Args:
@@ -285,7 +298,11 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return await self.create(epic)
 
     async def create_issue(
-        self, title: str, parent_epic: str = None, description: str = None, **kwargs
+        self,
+        title: str,
+        parent_epic: str = None,
+        description: str = None,
+        **kwargs: Any,
     ) -> Task:
         """Create a new issue.
 
@@ -305,7 +322,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return await self.create(task)
 
     async def create_task(
-        self, title: str, parent_id: str, description: str = None, **kwargs
+        self, title: str, parent_id: str, description: str = None, **kwargs: Any
     ) -> Task:
         """Create a new task under an issue.
 
@@ -324,7 +341,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         )
         return await self.create(task)
 
-    async def read(self, ticket_id: str) -> Optional[Union[Task, Epic]]:
+    async def read(self, ticket_id: str) -> Task | Epic | None:
         """Read a task by ID."""
         if self.tracker:
             ai_ticket = self.tracker.get_ticket(ticket_id)
@@ -340,8 +357,8 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return None
 
     async def update(
-        self, ticket_id: str, updates: Union[dict[str, Any], Task]
-    ) -> Optional[Union[Task, Epic]]:
+        self, ticket_id: str, updates: dict[str, Any] | Task
+    ) -> Task | Epic | None:
         """Update a task or epic.
 
         Args:
@@ -403,7 +420,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
     ) -> list[Task]:
         """List tasks with pagination."""
         tasks = []
@@ -487,7 +504,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Transition task to new state."""
         # Validate transition
         if not await self.validate_transition(ticket_id, target_state):
@@ -534,7 +551,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         # Apply limit and offset AFTER filtering
         return comments[offset : offset + limit]
 
-    async def get_epic(self, epic_id: str) -> Optional[Epic]:
+    async def get_epic(self, epic_id: str) -> Epic | None:
         """Get epic by ID.
 
         Args:
@@ -612,6 +629,238 @@ class AITrackdownAdapter(BaseAdapter[Task]):
                 tasks.append(ticket)
         return tasks
 
+    def _sanitize_filename(self, filename: str) -> str:
+        """Sanitize filename to prevent security issues.
+
+        Args:
+            filename: Original filename
+
+        Returns:
+            Sanitized filename safe for filesystem
+
+        """
+        # Remove path separators and other dangerous characters
+        safe_chars = set(
+            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._- "
+        )
+        sanitized = "".join(c if c in safe_chars else "_" for c in filename)
+
+        # Ensure filename is not empty
+        if not sanitized.strip():
+            return "unnamed_file"
+
+        return sanitized.strip()
+
+    def _guess_content_type(self, file_path: Path) -> str:
+        """Guess MIME type from file extension.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            MIME type string
+
+        """
+        import mimetypes
+
+        content_type, _ = mimetypes.guess_type(str(file_path))
+        return content_type or "application/octet-stream"
+
+    def _calculate_checksum(self, file_path: Path) -> str:
+        """Calculate SHA256 checksum of file.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            Hexadecimal checksum string
+
+        """
+        import hashlib
+
+        sha256 = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            # Read in chunks to handle large files
+            for chunk in iter(lambda: f.read(4096), b""):
+                sha256.update(chunk)
+
+        return sha256.hexdigest()
+
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: str | None = None,
+    ) -> Attachment:
+        """Attach a file to a ticket (local filesystem storage).
+
+        Args:
+            ticket_id: Ticket identifier
+            file_path: Local file path to attach
+            description: Optional attachment description
+
+        Returns:
+            Attachment metadata
+
+        Raises:
+            ValueError: If ticket doesn't exist
+            FileNotFoundError: If file doesn't exist
+
+        """
+        import shutil
+
+        # Validate ticket exists
+        ticket = await self.read(ticket_id)
+        if not ticket:
+            raise ValueError(f"Ticket {ticket_id} not found")
+
+        # Validate file exists
+        source_path = Path(file_path).resolve()
+        if not source_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Check file size (max 100MB for local storage)
+        size_mb = source_path.stat().st_size / (1024 * 1024)
+        if size_mb > 100:
+            raise ValueError(f"File too large: {size_mb:.2f}MB (max: 100MB)")
+
+        # Create attachments directory for this ticket
+        attachments_dir = self.base_path / "attachments" / ticket_id
+        attachments_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate unique filename with timestamp
+        timestamp = datetime.now().strftime("%Y%m%d%H%M%S%f")
+        safe_filename = self._sanitize_filename(source_path.name)
+        attachment_id = f"{timestamp}-{safe_filename}"
+        dest_path = attachments_dir / attachment_id
+
+        # Copy file to attachments directory
+        shutil.copy2(source_path, dest_path)
+
+        # Create attachment metadata
+        attachment = Attachment(
+            id=attachment_id,
+            ticket_id=ticket_id,
+            filename=source_path.name,
+            url=f"file://{dest_path.absolute()}",
+            content_type=self._guess_content_type(source_path),
+            size_bytes=source_path.stat().st_size,
+            created_at=datetime.now(),
+            description=description,
+            metadata={
+                "original_path": str(source_path),
+                "storage_path": str(dest_path),
+                "checksum": self._calculate_checksum(dest_path),
+            },
+        )
+
+        # Save metadata to JSON file
+        metadata_file = attachments_dir / f"{attachment_id}.json"
+        with open(metadata_file, "w") as f:
+            # Convert to dict and handle datetime serialization
+            data = attachment.model_dump()
+            json.dump(data, f, indent=2, default=str)
+
+        return attachment
+
+    async def get_attachments(self, ticket_id: str) -> builtins.list[Attachment]:
+        """Get all attachments for a ticket with path traversal protection.
+
+        Args:
+            ticket_id: Ticket identifier
+
+        Returns:
+            List of attachments (empty if none)
+
+        """
+        # Resolve and validate attachments directory
+        attachments_dir = (self.base_path / "attachments" / ticket_id).resolve()
+
+        # CRITICAL SECURITY CHECK: Ensure ticket directory is within base attachments
+        base_attachments = (self.base_path / "attachments").resolve()
+        if not str(attachments_dir).startswith(str(base_attachments)):
+            raise ValueError("Invalid ticket_id: path traversal detected")
+
+        if not attachments_dir.exists():
+            return []
+
+        attachments = []
+        for metadata_file in attachments_dir.glob("*.json"):
+            try:
+                with open(metadata_file) as f:
+                    data = json.load(f)
+                    # Convert ISO datetime strings back to datetime objects
+                    if isinstance(data.get("created_at"), str):
+                        data["created_at"] = datetime.fromisoformat(
+                            data["created_at"].replace("Z", "+00:00")
+                        )
+                    attachment = Attachment(**data)
+                    attachments.append(attachment)
+            except (json.JSONDecodeError, ValueError) as e:
+                # Log error but continue processing other attachments
+                logger.warning(
+                    "Failed to load attachment metadata from %s: %s",
+                    metadata_file,
+                    e,
+                )
+                continue
+
+        # Sort by creation time (newest first)
+        return sorted(
+            attachments,
+            key=lambda a: a.created_at or datetime.min,
+            reverse=True,
+        )
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str,
+    ) -> bool:
+        """Delete an attachment and its metadata with path traversal protection.
+
+        Args:
+            ticket_id: Ticket identifier
+            attachment_id: Attachment identifier
+
+        Returns:
+            True if deleted, False if not found
+
+        """
+        # Resolve base directory
+        attachments_dir = (self.base_path / "attachments" / ticket_id).resolve()
+
+        # Validate attachments directory exists
+        if not attachments_dir.exists():
+            return False
+
+        # Resolve file paths
+        attachment_file = (attachments_dir / attachment_id).resolve()
+        metadata_file = (attachments_dir / f"{attachment_id}.json").resolve()
+
+        # CRITICAL SECURITY CHECK: Ensure paths are within attachments_dir
+        base_resolved = attachments_dir.resolve()
+        if not str(attachment_file).startswith(str(base_resolved)):
+            raise ValueError(
+                "Invalid attachment path: path traversal detected in attachment_id"
+            )
+        if not str(metadata_file).startswith(str(base_resolved)):
+            raise ValueError(
+                "Invalid attachment path: path traversal detected in attachment_id"
+            )
+
+        # Delete files if they exist
+        deleted = False
+        if attachment_file.exists():
+            attachment_file.unlink()
+            deleted = True
+
+        if metadata_file.exists():
+            metadata_file.unlink()
+            deleted = True
+
+        return deleted
+
 
 # Register the adapter
 AdapterRegistry.register("aitrackdown", AITrackdownAdapter)

mcp_ticketer/adapters/asana/__init__.py

@@ -0,0 +1,15 @@
+"""Asana adapter for mcp-ticketer.
+
+This adapter provides comprehensive integration with Asana's REST API,
+supporting ticket management operations including:
+
+- CRUD operations for projects and tasks
+- Hierarchical structure (Epic → Issue → Task)
+- State transitions via custom fields
+- User assignment and tag management
+- Comment and attachment support
+"""
+
+from .adapter import AsanaAdapter
+
+__all__ = ["AsanaAdapter"]