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

mcp_ticketer/adapters/linear/client.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import asyncio
+import json
+import logging
 from typing import Any
 
 try:
     from gql import Client, gql
-    from gql.transport.exceptions import TransportError
+    from gql.transport.exceptions import TransportError, TransportQueryError
     from gql.transport.httpx import HTTPXAsyncTransport
 except ImportError:
     # Handle missing gql dependency gracefully
@@ -15,9 +17,12 @@ except ImportError:
     gql = None
     HTTPXAsyncTransport = None
     TransportError = Exception
+    TransportQueryError = Exception
 
 from ...core.exceptions import AdapterError, AuthenticationError, RateLimitError
 
+logger = logging.getLogger(__name__)
+
 
 class LinearGraphQLClient:
     """GraphQL client for Linear API with error handling and retry logic."""
@@ -26,6 +31,7 @@ class LinearGraphQLClient:
         """Initialize the Linear GraphQL client.
 
         Args:
+        ----
             api_key: Linear API key
             timeout: Request timeout in seconds
 
@@ -38,9 +44,11 @@ class LinearGraphQLClient:
         """Create a new GraphQL client instance.
 
         Returns:
+        -------
             Configured GraphQL client
 
         Raises:
+        ------
             AuthenticationError: If API key is invalid
             AdapterError: If client creation fails
 
@@ -80,14 +88,17 @@ class LinearGraphQLClient:
         """Execute a GraphQL query with error handling and retries.
 
         Args:
+        ----
             query_string: GraphQL query string
             variables: Query variables
             retries: Number of retry attempts
 
         Returns:
+        -------
             Query result data
 
         Raises:
+        ------
             AuthenticationError: If authentication fails
             RateLimitError: If rate limit is exceeded
             AdapterError: If query execution fails
@@ -95,16 +106,119 @@ class LinearGraphQLClient:
         """
         query = gql(query_string)
 
+        # Extract operation name from query for logging
+        operation_name = "unknown"
+        try:
+            # Simple extraction - look for 'query' or 'mutation' keyword
+            query_lower = query_string.strip().lower()
+            if query_lower.startswith("mutation"):
+                operation_name = (
+                    query_string.split("{")[0].strip().replace("mutation", "").strip()
+                )
+            elif query_lower.startswith("query"):
+                operation_name = (
+                    query_string.split("{")[0].strip().replace("query", "").strip()
+                )
+        except Exception:
+            pass  # Use default 'unknown' if extraction fails
+
         for attempt in range(retries + 1):
             try:
+                # Log request details before execution
+                logger.debug(
+                    f"[Linear GraphQL] Executing operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}"
+                )
+
                 client = self.create_client()
                 async with client as session:
                     result = await session.execute(
                         query, variable_values=variables or {}
                     )
+
+                # Log successful response
+                logger.debug(
+                    f"[Linear GraphQL] Operation successful: {operation_name}\n"
+                    f"Response:\n{json.dumps(result, indent=2, default=str)}"
+                )
+
                 return result
 
+            except TransportQueryError as e:
+                """
+                Handle GraphQL validation errors (e.g., duplicate label names).
+                TransportQueryError is a subclass of TransportError with .errors attribute.
+
+                Related: 1M-398 - Label duplicate error handling
+                """
+                # Log detailed error information
+                logger.error(
+                    f"[Linear GraphQL] TransportQueryError occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error: {e}\n"
+                    f"Error details: {e.errors if hasattr(e, 'errors') else 'No error details'}"
+                )
+
+                if e.errors:
+                    error = e.errors[0]
+                    error_msg = error.get("message", "Unknown GraphQL error")
+
+                    # Parse extensions for field-specific details (enhanced debugging)
+                    extensions = error.get("extensions", {})
+
+                    # Check for user-presentable message (clearer error for users)
+                    user_message = extensions.get("userPresentableMessage")
+                    if user_message:
+                        error_msg = user_message
+
+                    # Check for argument path (which field failed validation)
+                    arg_path = extensions.get("argumentPath")
+                    if arg_path:
+                        field_path = ".".join(str(p) for p in arg_path)
+                        error_msg = f"{error_msg} (field: {field_path})"
+
+                    # Check for validation errors (additional context)
+                    validation_errors = extensions.get("validationErrors")
+                    if validation_errors:
+                        error_msg = (
+                            f"{error_msg}\nValidation errors: {validation_errors}"
+                        )
+
+                    # Log full error context for debugging
+                    logger.error(
+                        "Linear GraphQL error: %s (extensions: %s)",
+                        error_msg,
+                        extensions,
+                    )
+
+                    # Check for duplicate label errors specifically
+                    if (
+                        "duplicate" in error_msg.lower()
+                        and "label" in error_msg.lower()
+                    ):
+                        raise AdapterError(
+                            f"Label already exists: {error_msg}", "linear"
+                        ) from e
+
+                    # Other validation errors
+                    raise AdapterError(
+                        f"Linear GraphQL validation error: {error_msg}", "linear"
+                    ) from e
+
+                # Fallback if no errors attribute
+                raise AdapterError(f"Linear GraphQL error: {e}", "linear") from e
+
             except TransportError as e:
+                # Log transport error details
+                logger.error(
+                    f"[Linear GraphQL] TransportError occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error: {e}\n"
+                    f"Status code: {e.response.status if hasattr(e, 'response') and e.response else 'N/A'}"
+                )
+
                 # Handle HTTP errors
                 if hasattr(e, "response") and e.response:
                     status_code = e.response.status
@@ -139,6 +253,16 @@ class LinearGraphQLClient:
                 raise AdapterError(f"Linear API transport error: {e}", "linear") from e
 
             except Exception as e:
+                # Log generic error details
+                logger.error(
+                    f"[Linear GraphQL] Unexpected error occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error type: {type(e).__name__}\n"
+                    f"Error: {e}",
+                    exc_info=True,
+                )
+
                 # GraphQL or other errors
                 error_msg = str(e)
 
@@ -175,14 +299,17 @@ class LinearGraphQLClient:
         """Execute a GraphQL mutation with error handling.
 
         Args:
+        ----
             mutation_string: GraphQL mutation string
             variables: Mutation variables
             retries: Number of retry attempts
 
         Returns:
+        -------
             Mutation result data
 
         Raises:
+        ------
             AuthenticationError: If authentication fails
             RateLimitError: If rate limit is exceeded
             AdapterError: If mutation execution fails
@@ -194,9 +321,20 @@ class LinearGraphQLClient:
         """Test the connection to Linear API.
 
         Returns:
+        -------
             True if connection is successful, False otherwise
 
+        Design Decision: Enhanced Debug Logging (1M-431)
+        -------------------------------------------------
+        Added comprehensive logging to diagnose connection failures.
+        Logs API key preview, query results, and specific failure reasons
+        to help users troubleshoot authentication and configuration issues.
+
         """
+        import logging
+
+        logger = logging.getLogger(__name__)
+
         try:
             # Simple query to test authentication
             test_query = """
@@ -204,23 +342,53 @@ class LinearGraphQLClient:
                     viewer {
                         id
                         name
+                        email
                     }
                 }
             """
 
+            logger.debug(
+                f"Testing Linear API connection with API key: {self.api_key[:20]}..."
+            )
             result = await self.execute_query(test_query)
-            return bool(result.get("viewer"))
 
-        except Exception:
+            # Log the actual response for debugging
+            logger.debug(f"Linear API test response: {result}")
+
+            viewer = result.get("viewer")
+
+            if not viewer:
+                logger.warning(
+                    f"Linear test connection query succeeded but returned no viewer data. "
+                    f"Response: {result}"
+                )
+                return False
+
+            if not viewer.get("id"):
+                logger.warning(f"Linear viewer missing id field. Viewer data: {viewer}")
+                return False
+
+            logger.info(
+                f"Linear API connected successfully as: {viewer.get('name')} ({viewer.get('email')})"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(
+                f"Linear connection test failed: {type(e).__name__}: {e}",
+                exc_info=True,
+            )
             return False
 
     async def get_team_info(self, team_id: str) -> dict[str, Any] | None:
         """Get team information by ID.
 
         Args:
+        ----
             team_id: Linear team ID
 
         Returns:
+        -------
             Team information or None if not found
 
         """
@@ -246,9 +414,11 @@ class LinearGraphQLClient:
         """Get user information by email.
 
         Args:
+        ----
             email: User email address
 
         Returns:
+        -------
             User information or None if not found
 
         """
@@ -278,9 +448,11 @@ class LinearGraphQLClient:
         """Search users by display name or full name.
 
         Args:
+        ----
             name: Display name or full name to search for
 
         Returns:
+        -------
             List of matching users (may be empty)
 
         """

mcp_ticketer/adapters/linear/mappers.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Any
 
-from ...core.models import Comment, Epic, Priority, Task, TicketState
+from ...core.models import Attachment, Comment, Epic, Priority, Task, TicketState
 from .types import extract_linear_metadata, get_universal_priority, get_universal_state
 
 
@@ -16,9 +16,11 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
     with a parent issue).
 
     Args:
+    ----
         issue_data: Raw Linear issue data from GraphQL
 
     Returns:
+    -------
         Universal Task model
 
     """
@@ -31,10 +33,11 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
     linear_priority = issue_data.get("priority", 3)
     priority = get_universal_priority(linear_priority)
 
-    # Map state
+    # Map state with synonym matching (1M-164)
     state_data = issue_data.get("state", {})
     state_type = state_data.get("type", "unstarted")
-    state = get_universal_state(state_type)
+    state_name = state_data.get("name")  # Extract state name for synonym matching
+    state = get_universal_state(state_type, state_name)
 
     # Extract assignee
     assignee = None
@@ -76,6 +79,9 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
             issue_data["updatedAt"].replace("Z", "+00:00")
         )
 
+    # Extract child issue IDs
+    children = extract_child_issue_ids(issue_data)
+
     # Extract Linear-specific metadata
     linear_metadata = extract_linear_metadata(issue_data)
     metadata = {"linear": linear_metadata} if linear_metadata else {}
@@ -91,6 +97,7 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
         tags=tags,
         parent_epic=parent_epic,
         parent_issue=parent_issue,
+        children=children,
         created_at=created_at,
         updated_at=updated_at,
         metadata=metadata,
@@ -101,9 +108,11 @@ def map_linear_project_to_epic(project_data: dict[str, Any]) -> Epic:
     """Convert Linear project data to universal Epic model.
 
     Args:
+    ----
         project_data: Raw Linear project data from GraphQL
 
     Returns:
+    -------
         Universal Epic model
 
     """
@@ -137,7 +146,7 @@ def map_linear_project_to_epic(project_data: dict[str, Any]) -> Epic:
         )
 
     # Extract Linear-specific metadata
-    metadata = {"linear": {}}
+    metadata: dict[str, Any] = {"linear": {}}
     if project_data.get("url"):
         metadata["linear"]["linear_url"] = project_data["url"]
     if project_data.get("icon"):
@@ -165,10 +174,12 @@ def map_linear_comment_to_comment(
     """Convert Linear comment data to universal Comment model.
 
     Args:
+    ----
         comment_data: Raw Linear comment data from GraphQL
         ticket_id: ID of the ticket this comment belongs to
 
     Returns:
+    -------
         Universal Comment model
 
     """
@@ -212,10 +223,12 @@ def build_linear_issue_input(task: Task, team_id: str) -> dict[str, Any]:
     or for a sub-issue when task.parent_issue is provided.
 
     Args:
+    ----
         task: Universal Task model
         team_id: Linear team ID
 
     Returns:
+    -------
         Linear issue input dictionary
 
     """
@@ -246,10 +259,19 @@ def build_linear_issue_input(task: Task, team_id: str) -> dict[str, Any]:
     if task.parent_epic:
         issue_input["projectId"] = task.parent_epic
 
-    # Add labels (tags) if provided
-    if task.tags:
-        # Note: This returns label names, will be resolved to IDs by adapter
-        issue_input["labelIds"] = task.tags  # Temporary - adapter will resolve
+    # DO NOT set labelIds here - adapter will handle label resolution
+    # Labels are resolved from names to UUIDs in LinearAdapter._create_task()
+    # If we set it here, we create a type mismatch (names vs UUIDs)
+    # The adapter's label resolution logic (lines 982-988) handles this properly
+    #
+    # Bug Fix (v1.1.1): Previously, setting labelIds to tag names here caused
+    # "Argument Validation Error" from Linear's GraphQL API. The API requires
+    # UUIDs (e.g., "uuid-1"), not names (e.g., "bug"). This was fixed by:
+    # 1. Removing labelIds assignment in mapper (this file)
+    # 2. Adding UUID validation in adapter._create_task() (adapter.py:1047-1060)
+    # 3. Changing GraphQL labelIds type to [String!]! (queries.py)
+    #
+    # See: docs/TROUBLESHOOTING.md#issue-argument-validation-error-when-creating-issues-with-labels
 
     # Add Linear-specific metadata
     if task.metadata and "linear" in task.metadata:
@@ -268,9 +290,11 @@ def build_linear_issue_update_input(updates: dict[str, Any]) -> dict[str, Any]:
     """Build Linear issue update input from update dictionary.
 
     Args:
+    ----
         updates: Dictionary of fields to update
 
     Returns:
+    -------
         Linear issue update input dictionary
 
     """
@@ -320,9 +344,11 @@ def extract_child_issue_ids(issue_data: dict[str, Any]) -> list[str]:
     """Extract child issue IDs from Linear issue data.
 
     Args:
+    ----
         issue_data: Raw Linear issue data from GraphQL
 
     Returns:
+    -------
         List of child issue identifiers
 
     """
@@ -330,3 +356,172 @@ def extract_child_issue_ids(issue_data: dict[str, Any]) -> list[str]:
     if issue_data.get("children", {}).get("nodes"):
         child_ids = [child["identifier"] for child in issue_data["children"]["nodes"]]
     return child_ids
+
+
+def map_linear_attachment_to_attachment(
+    attachment_data: dict[str, Any], ticket_id: str
+) -> Attachment:
+    """Convert Linear attachment data to universal Attachment model.
+
+    Args:
+    ----
+        attachment_data: Raw Linear attachment data from GraphQL
+        ticket_id: ID of the ticket this attachment belongs to
+
+    Returns:
+    -------
+        Universal Attachment model
+
+    Note:
+    ----
+        Linear attachment URLs require authentication with API key.
+        URLs are in format: https://files.linear.app/workspace/attachment-id/filename
+        Authentication header: Authorization: Bearer {api_key}
+
+    """
+    # Extract basic fields
+    attachment_id = attachment_data.get("id")
+    title = attachment_data.get("title", "Untitled")
+    url = attachment_data.get("url")
+    subtitle = attachment_data.get("subtitle")
+
+    # Extract dates
+    created_at = None
+    if attachment_data.get("createdAt"):
+        created_at = datetime.fromisoformat(
+            attachment_data["createdAt"].replace("Z", "+00:00")
+        )
+
+    if attachment_data.get("updatedAt"):
+        datetime.fromisoformat(attachment_data["updatedAt"].replace("Z", "+00:00"))
+
+    # Build metadata with Linear-specific fields
+    metadata = {
+        "linear": {
+            "id": attachment_id,
+            "title": title,
+            "subtitle": subtitle,
+            "metadata": attachment_data.get("metadata"),
+            "updated_at": attachment_data.get("updatedAt"),
+        }
+    }
+
+    return Attachment(
+        id=attachment_id,
+        ticket_id=ticket_id,
+        filename=title,  # Linear uses 'title' as filename
+        url=url,
+        content_type=None,  # Linear doesn't provide MIME type in GraphQL
+        size_bytes=None,  # Linear doesn't provide size in GraphQL
+        created_at=created_at,
+        created_by=None,  # Not included in standard fragment
+        description=subtitle,
+        metadata=metadata,
+    )
+
+
+def task_to_compact_format(task: Task) -> dict[str, Any]:
+    """Convert Task to compact format for efficient token usage.
+
+    Compact format includes only essential fields, reducing token usage by ~70-80%
+    compared to full Task serialization.
+
+    Args:
+    ----
+        task: Universal Task model
+
+    Returns:
+    -------
+        Compact dictionary with minimal essential fields
+
+    Design Decision: Compact Format Fields (1M-554)
+    -----------------------------------------------
+    Rationale: Selected fields based on token efficiency analysis and user needs.
+    Full Task serialization averages ~600 tokens per item. Compact format targets
+    ~120 tokens per item (80% reduction).
+
+    Essential fields included:
+    - id: Required for all operations (identifier)
+    - title: Primary user-facing information
+    - state: Critical for workflow understanding
+    - priority: Important for triage and filtering
+    - assignee: Key for task assignment visibility
+
+    Fields excluded:
+    - description: Often large (100-500 tokens), available via get()
+    - creator: Less critical for list views
+    - tags: Available in full format, not essential for scanning
+    - children: Hierarchy details available via dedicated queries
+    - created_at/updated_at: Not essential for list scanning
+    - metadata: Platform-specific, not needed in compact view
+
+    Performance: Reduces typical 50-item list from ~30,000 to ~6,000 tokens.
+
+    """
+    # Handle state - can be TicketState enum or string
+    state_value = None
+    if task.state:
+        state_value = task.state.value if hasattr(task.state, "value") else task.state
+
+    # Handle priority - can be Priority enum or string
+    priority_value = None
+    if task.priority:
+        priority_value = (
+            task.priority.value if hasattr(task.priority, "value") else task.priority
+        )
+
+    return {
+        "id": task.id,
+        "title": task.title,
+        "state": state_value,
+        "priority": priority_value,
+        "assignee": task.assignee,
+    }
+
+
+def epic_to_compact_format(epic: Epic) -> dict[str, Any]:
+    """Convert Epic to compact format for efficient token usage.
+
+    Compact format includes only essential fields, reducing token usage by ~70-80%
+    compared to full Epic serialization.
+
+    Args:
+    ----
+        epic: Universal Epic model
+
+    Returns:
+    -------
+        Compact dictionary with minimal essential fields
+
+    Design Decision: Epic Compact Format (1M-554)
+    ---------------------------------------------
+    Rationale: Epics typically have less metadata than tasks, but descriptions
+    can still be large. Compact format focuses on overview information.
+
+    Essential fields:
+    - id: Required for all operations
+    - title: Primary identifier
+    - state: Project status
+    - child_count: Useful for project overview (if available)
+
+    Performance: Similar token reduction to task compact format.
+
+    """
+    # Handle state - can be TicketState enum or string
+    state_value = None
+    if epic.state:
+        state_value = epic.state.value if hasattr(epic.state, "value") else epic.state
+
+    compact = {
+        "id": epic.id,
+        "title": epic.title,
+        "state": state_value,
+    }
+
+    # Include child count if available in metadata
+    if epic.metadata and "linear" in epic.metadata:
+        linear_meta = epic.metadata["linear"]
+        if "issue_count" in linear_meta:
+            compact["child_count"] = linear_meta["issue_count"]
+
+    return compact