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

mcp_ticketer/adapters/linear/client.py

@@ -7,7 +7,7 @@ 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,6 +15,7 @@ except ImportError:
     gql = None
     HTTPXAsyncTransport = None
     TransportError = Exception
+    TransportQueryError = Exception
 
 from ...core.exceptions import AdapterError, AuthenticationError, RateLimitError
 
@@ -26,6 +27,7 @@ class LinearGraphQLClient:
         """Initialize the Linear GraphQL client.
 
         Args:
+        ----
             api_key: Linear API key
             timeout: Request timeout in seconds
 
@@ -38,9 +40,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 +84,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
@@ -104,6 +111,33 @@ class LinearGraphQLClient:
                     )
                 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
+                """
+                if e.errors:
+                    error_msg = e.errors[0].get("message", "Unknown GraphQL error")
+
+                    # 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:
                 # Handle HTTP errors
                 if hasattr(e, "response") and e.response:
@@ -175,14 +209,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 +231,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 +252,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 +324,11 @@ class LinearGraphQLClient:
         """Get user information by email.
 
         Args:
+        ----
             email: User email address
 
         Returns:
+        -------
             User information or None if not found
 
         """
@@ -278,9 +358,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,65 @@ 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,
+    )

mcp_ticketer/adapters/linear/queries.py

@@ -351,7 +351,8 @@ SEARCH_ISSUE_BY_IDENTIFIER_QUERY = """
 """
 
 LIST_PROJECTS_QUERY = (
-    PROJECT_FRAGMENT
+    TEAM_FRAGMENT  # Required by PROJECT_FRAGMENT which uses ...TeamFields
+    + PROJECT_FRAGMENT
     + """
     query ListProjects($filter: ProjectFilter, $first: Int!) {
         projects(filter: $filter, first: $first, orderBy: updatedAt) {
@@ -387,3 +388,169 @@ GET_CURRENT_USER_QUERY = (
     }
 """
 )
+
+CREATE_LABEL_MUTATION = """
+    mutation CreateLabel($input: IssueLabelCreateInput!) {
+        issueLabelCreate(input: $input) {
+            success
+            issueLabel {
+                id
+                name
+                color
+                description
+            }
+        }
+    }
+"""
+
+LIST_CYCLES_QUERY = """
+    query GetCycles($teamId: String!, $first: Int!, $after: String) {
+        team(id: $teamId) {
+            cycles(first: $first, after: $after) {
+                nodes {
+                    id
+                    name
+                    number
+                    startsAt
+                    endsAt
+                    completedAt
+                    progress
+                }
+                pageInfo {
+                    hasNextPage
+                    endCursor
+                }
+            }
+        }
+    }
+"""
+
+GET_ISSUE_STATUS_QUERY = """
+    query GetIssueStatus($issueId: String!) {
+        issue(id: $issueId) {
+            id
+            state {
+                id
+                name
+                type
+                color
+                description
+                position
+            }
+        }
+    }
+"""
+
+LIST_ISSUE_STATUSES_QUERY = """
+    query GetWorkflowStates($teamId: String!) {
+        team(id: $teamId) {
+            states {
+                nodes {
+                    id
+                    name
+                    type
+                    color
+                    description
+                    position
+                }
+            }
+        }
+    }
+"""
+
+GET_CUSTOM_VIEW_QUERY = (
+    ISSUE_LIST_FRAGMENTS
+    + """
+    query GetCustomView($viewId: String!, $first: Int!) {
+        customView(id: $viewId) {
+            id
+            name
+            description
+            issues(first: $first) {
+                nodes {
+                    ...IssueCompactFields
+                }
+                pageInfo {
+                    hasNextPage
+                }
+            }
+        }
+    }
+"""
+)
+
+# Project Update queries and mutations (1M-238)
+
+PROJECT_UPDATE_FRAGMENT = """
+    fragment ProjectUpdateFields on ProjectUpdate {
+        id
+        body
+        health
+        createdAt
+        updatedAt
+        diffMarkdown
+        url
+        user {
+            id
+            name
+            email
+        }
+        project {
+            id
+            name
+            slugId
+        }
+    }
+"""
+
+CREATE_PROJECT_UPDATE_MUTATION = (
+    PROJECT_UPDATE_FRAGMENT
+    + """
+    mutation ProjectUpdateCreate(
+        $projectId: String!
+        $body: String!
+        $health: ProjectUpdateHealthType
+    ) {
+        projectUpdateCreate(
+            input: {
+                projectId: $projectId
+                body: $body
+                health: $health
+            }
+        ) {
+            success
+            projectUpdate {
+                ...ProjectUpdateFields
+            }
+        }
+    }
+"""
+)
+
+LIST_PROJECT_UPDATES_QUERY = (
+    PROJECT_UPDATE_FRAGMENT
+    + """
+    query ProjectUpdates($projectId: String!, $first: Int) {
+        project(id: $projectId) {
+            id
+            name
+            projectUpdates(first: $first) {
+                nodes {
+                    ...ProjectUpdateFields
+                }
+            }
+        }
+    }
+"""
+)
+
+GET_PROJECT_UPDATE_QUERY = (
+    PROJECT_UPDATE_FRAGMENT
+    + """
+    query ProjectUpdate($id: String!) {
+        projectUpdate(id: $id) {
+            ...ProjectUpdateFields
+        }
+    }
+"""
+)