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

mcp_ticketer/core/adapter.py

@@ -7,6 +7,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
+from .state_matcher import get_state_matcher
 
 if TYPE_CHECKING:
     from .models import Attachment
@@ -22,17 +23,52 @@ class BaseAdapter(ABC, Generic[T]):
         """Initialize adapter with configuration.
 
         Args:
+        ----
             config: Adapter-specific configuration dictionary
 
         """
         self.config = config
         self._state_mapping = self._get_state_mapping()
 
+    @property
+    def adapter_type(self) -> str:
+        """Return lowercase adapter type identifier.
+
+        This identifier is used in MCP responses to show which adapter
+        handled the operation (e.g., "linear", "github", "jira", "asana").
+
+        Returns:
+        -------
+            Lowercase adapter type (e.g., "linear", "github")
+
+        """
+        # Extract adapter type from class name
+        # LinearAdapter -> linear, GitHubAdapter -> github
+        class_name = self.__class__.__name__
+        if class_name.endswith("Adapter"):
+            adapter_name = class_name[: -len("Adapter")]
+        else:
+            adapter_name = class_name
+
+        return adapter_name.lower()
+
+    @property
+    def adapter_display_name(self) -> str:
+        """Return human-readable adapter name.
+
+        Returns:
+        -------
+            Title-cased adapter name (e.g., "Linear", "Github", "Jira")
+
+        """
+        return self.adapter_type.title()
+
     @abstractmethod
     def _get_state_mapping(self) -> dict[TicketState, str]:
         """Get mapping from universal states to system-specific states.
 
         Returns:
+        -------
             Dictionary mapping TicketState to system-specific state strings
 
         """
@@ -43,6 +79,7 @@ class BaseAdapter(ABC, Generic[T]):
         """Validate that required credentials are present.
 
         Returns:
+        -------
             (is_valid, error_message) - Tuple of validation result and error message
 
         """
@@ -53,9 +90,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Create a new ticket.
 
         Args:
+        ----
             ticket: Ticket to create (Epic or Task)
 
         Returns:
+        -------
             Created ticket with ID populated
 
         """
@@ -66,9 +105,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Read a ticket by ID.
 
         Args:
+        ----
             ticket_id: Unique ticket identifier
 
         Returns:
+        -------
             Ticket if found, None otherwise
 
         """
@@ -79,10 +120,12 @@ class BaseAdapter(ABC, Generic[T]):
         """Update a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             updates: Fields to update
 
         Returns:
+        -------
             Updated ticket if successful, None otherwise
 
         """
@@ -93,9 +136,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Delete a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             True if deleted, False otherwise
 
         """
@@ -108,11 +153,13 @@ class BaseAdapter(ABC, Generic[T]):
         """List tickets with pagination and filters.
 
         Args:
+        ----
             limit: Maximum number of tickets
             offset: Skip this many tickets
             filters: Optional filter criteria
 
         Returns:
+        -------
             List of tickets matching criteria
 
         """
@@ -123,9 +170,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Search tickets using advanced query.
 
         Args:
+        ----
             query: Search parameters
 
         Returns:
+        -------
             List of tickets matching search criteria
 
         """
@@ -138,10 +187,12 @@ class BaseAdapter(ABC, Generic[T]):
         """Transition ticket to a new state.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             target_state: Target state
 
         Returns:
+        -------
             Updated ticket if transition successful, None otherwise
 
         """
@@ -152,9 +203,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Add a comment to a ticket.
 
         Args:
+        ----
             comment: Comment to add
 
         Returns:
+        -------
             Created comment with ID populated
 
         """
@@ -167,11 +220,13 @@ class BaseAdapter(ABC, Generic[T]):
         """Get comments for a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             limit: Maximum number of comments
             offset: Skip this many comments
 
         Returns:
+        -------
             List of comments for the ticket
 
         """
@@ -181,9 +236,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Map universal state to system-specific state.
 
         Args:
+        ----
             state: Universal ticket state
 
         Returns:
+        -------
             System-specific state string
 
         """
@@ -193,31 +250,88 @@ class BaseAdapter(ABC, Generic[T]):
         """Map system-specific state to universal state.
 
         Args:
+        ----
             system_state: System-specific state string
 
         Returns:
+        -------
             Universal ticket state
 
         """
         reverse_mapping = {v: k for k, v in self._state_mapping.items()}
         return reverse_mapping.get(system_state, TicketState.OPEN)
 
+    def get_available_states(self) -> list[str]:
+        """Get list of adapter-specific available states.
+
+        Returns adapter-specific state names that can be used for
+        semantic state matching. Override in subclasses to provide
+        platform-specific state names.
+
+        Returns:
+        -------
+            List of adapter-specific state names
+
+        Example:
+        -------
+            >>> # Linear adapter override
+            >>> def get_available_states(self):
+            ...     return ["Backlog", "Todo", "In Progress", "Done", "Canceled"]
+
+        """
+        # Default: return universal state values
+        return [state.value for state in TicketState]
+
+    def resolve_state(self, user_input: str) -> TicketState:
+        """Resolve user input to universal state using semantic matcher.
+
+        Uses the semantic state matcher to interpret natural language
+        inputs and resolve them to universal TicketState values.
+
+        Args:
+        ----
+            user_input: Natural language state input (e.g., "working on it")
+
+        Returns:
+        -------
+            Resolved universal TicketState
+
+        Example:
+        -------
+            >>> adapter = get_adapter()
+            >>> state = adapter.resolve_state("working on it")
+            >>> print(state)
+            TicketState.IN_PROGRESS
+
+        """
+        matcher = get_state_matcher()
+        adapter_states = self.get_available_states()
+        result = matcher.match_state(user_input, adapter_states)
+        return result.state
+
     async def validate_transition(
         self, ticket_id: str, target_state: TicketState
     ) -> bool:
         """Validate if state transition is allowed.
 
+        Validates both workflow rules and parent/child state constraints:
+        - Parent issues must remain at least as complete as their most complete child
+        - Standard workflow transitions must be valid
+
         Args:
+        ----
             ticket_id: Ticket identifier
             target_state: Target state
 
         Returns:
+        -------
             True if transition is valid
 
         """
         ticket = await self.read(ticket_id)
         if not ticket:
             return False
+
         # Handle case where state might be stored as string due to use_enum_values=True
         current_state = ticket.state
         if isinstance(current_state, str):
@@ -225,7 +339,35 @@ class BaseAdapter(ABC, Generic[T]):
                 current_state = TicketState(current_state)
             except ValueError:
                 return False
-        return current_state.can_transition_to(target_state)
+
+        # Check workflow transition validity
+        if not current_state.can_transition_to(target_state):
+            return False
+
+        # Check parent/child state constraint
+        # If this ticket has children, ensure target state >= max child state
+        if isinstance(ticket, Task):
+            # Get all children
+            children = await self.list_tasks_by_issue(ticket_id)
+            if children:
+                # Find max child completion level
+                max_child_level = 0
+                for child in children:
+                    child_state = child.state
+                    if isinstance(child_state, str):
+                        try:
+                            child_state = TicketState(child_state)
+                        except ValueError:
+                            continue
+                    max_child_level = max(
+                        max_child_level, child_state.completion_level()
+                    )
+
+                # Target state must be at least as complete as most complete child
+                if target_state.completion_level() < max_child_level:
+                    return False
+
+        return True
 
     # Epic/Issue/Task Hierarchy Methods
 
@@ -235,11 +377,13 @@ class BaseAdapter(ABC, Generic[T]):
         """Create epic (top-level grouping).
 
         Args:
+        ----
             title: Epic title
             description: Epic description
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created epic or None if failed
 
         """
@@ -258,9 +402,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Get epic by ID.
 
         Args:
+        ----
             epic_id: Epic identifier
 
         Returns:
+        -------
             Epic if found, None otherwise
 
         """
@@ -274,9 +420,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all epics.
 
         Args:
+        ----
             **kwargs: Adapter-specific filter parameters
 
         Returns:
+        -------
             List of epics
 
         """
@@ -296,12 +444,14 @@ class BaseAdapter(ABC, Generic[T]):
         """Create issue, optionally linked to epic.
 
         Args:
+        ----
             title: Issue title
             description: Issue description
             epic_id: Optional parent epic ID
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created issue or None if failed
 
         """
@@ -318,9 +468,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all issues in epic.
 
         Args:
+        ----
             epic_id: Epic identifier
 
         Returns:
+        -------
             List of issues belonging to epic
 
         """
@@ -335,15 +487,18 @@ class BaseAdapter(ABC, Generic[T]):
         """Create task as sub-ticket of parent issue.
 
         Args:
+        ----
             title: Task title
             parent_id: Required parent issue ID
             description: Task description
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created task or None if failed
 
         Raises:
+        ------
             ValueError: If parent_id is not provided
 
         """
@@ -369,9 +524,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all tasks under an issue.
 
         Args:
+        ----
             issue_id: Issue identifier
 
         Returns:
+        -------
             List of tasks belonging to issue
 
         """
@@ -390,14 +547,17 @@ class BaseAdapter(ABC, Generic[T]):
         """Attach a file to a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             file_path: Local file path to upload
             description: Optional attachment description
 
         Returns:
+        -------
             Created Attachment with metadata
 
         Raises:
+        ------
             NotImplementedError: If adapter doesn't support attachments
             FileNotFoundError: If file doesn't exist
             ValueError: If ticket doesn't exist or upload fails
@@ -412,9 +572,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Get all attachments for a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             List of attachments (empty if none or not supported)
 
         """
@@ -430,13 +592,16 @@ class BaseAdapter(ABC, Generic[T]):
         """Delete an attachment (optional implementation).
 
         Args:
+        ----
             ticket_id: Ticket identifier
             attachment_id: Attachment identifier
 
         Returns:
+        -------
             True if deleted, False otherwise
 
         Raises:
+        ------
             NotImplementedError: If adapter doesn't support deletion
 
         """

mcp_ticketer/core/config.py

@@ -6,7 +6,7 @@ import os
 from enum import Enum
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -38,9 +38,9 @@ class GitHubConfig(BaseAdapterConfig):
     """GitHub adapter configuration."""
 
     type: AdapterType = AdapterType.GITHUB
-    token: str | None = Field(None, env="GITHUB_TOKEN")
-    owner: str | None = Field(None, env="GITHUB_OWNER")
-    repo: str | None = Field(None, env="GITHUB_REPO")
+    token: str | None = Field(default=None)
+    owner: str | None = Field(default=None)
+    repo: str | None = Field(default=None)
     api_url: str = "https://api.github.com"
     use_projects_v2: bool = False
     custom_priority_scheme: dict[str, list[str]] | None = None
@@ -53,7 +53,7 @@ class GitHubConfig(BaseAdapterConfig):
             v = os.getenv("GITHUB_TOKEN")
         if not v:
             raise ValueError("GitHub token is required")
-        return v
+        return cast(str, v)
 
     @field_validator("owner", mode="before")
     @classmethod
@@ -63,7 +63,7 @@ class GitHubConfig(BaseAdapterConfig):
             v = os.getenv("GITHUB_OWNER")
         if not v:
             raise ValueError("GitHub owner is required")
-        return v
+        return cast(str, v)
 
     @field_validator("repo", mode="before")
     @classmethod
@@ -73,17 +73,17 @@ class GitHubConfig(BaseAdapterConfig):
             v = os.getenv("GITHUB_REPO")
         if not v:
             raise ValueError("GitHub repo is required")
-        return v
+        return cast(str, v)
 
 
 class JiraConfig(BaseAdapterConfig):
     """JIRA adapter configuration."""
 
     type: AdapterType = AdapterType.JIRA
-    server: str | None = Field(None, env="JIRA_SERVER")
-    email: str | None = Field(None, env="JIRA_EMAIL")
-    api_token: str | None = Field(None, env="JIRA_API_TOKEN")
-    project_key: str | None = Field(None, env="JIRA_PROJECT_KEY")
+    server: str | None = Field(default=None)
+    email: str | None = Field(default=None)
+    api_token: str | None = Field(default=None)
+    project_key: str | None = Field(default=None)
     cloud: bool = True
     verify_ssl: bool = True
 
@@ -95,7 +95,7 @@ class JiraConfig(BaseAdapterConfig):
             v = os.getenv("JIRA_SERVER")
         if not v:
             raise ValueError("JIRA server URL is required")
-        return v.rstrip("/")
+        return cast(str, v).rstrip("/")
 
     @field_validator("email", mode="before")
     @classmethod
@@ -105,7 +105,7 @@ class JiraConfig(BaseAdapterConfig):
             v = os.getenv("JIRA_EMAIL")
         if not v:
             raise ValueError("JIRA email is required")
-        return v
+        return cast(str, v)
 
     @field_validator("api_token", mode="before")
     @classmethod
@@ -115,14 +115,14 @@ class JiraConfig(BaseAdapterConfig):
             v = os.getenv("JIRA_API_TOKEN")
         if not v:
             raise ValueError("JIRA API token is required")
-        return v
+        return cast(str, v)
 
 
 class LinearConfig(BaseAdapterConfig):
     """Linear adapter configuration."""
 
     type: AdapterType = AdapterType.LINEAR
-    api_key: str | None = Field(None, env="LINEAR_API_KEY")
+    api_key: str | None = Field(default=None)
     workspace: str | None = None
     team_key: str | None = None  # Short team key like "BTA"
     team_id: str | None = None  # UUID team identifier
@@ -143,7 +143,7 @@ class LinearConfig(BaseAdapterConfig):
             v = os.getenv("LINEAR_API_KEY")
         if not v:
             raise ValueError("Linear API key is required")
-        return v
+        return cast(str, v)
 
 
 class AITrackdownConfig(BaseAdapterConfig):
@@ -343,16 +343,16 @@ class ConfigurationManager:
         try:
             with open(config_path, encoding="utf-8") as file:
                 if config_path.suffix.lower() in [".yaml", ".yml"]:
-                    return yaml.safe_load(file) or {}
+                    return cast(dict[str, Any], yaml.safe_load(file) or {})
                 elif config_path.suffix.lower() == ".json":
-                    return json.load(file)
+                    return cast(dict[str, Any], json.load(file))
                 else:
                     # Try YAML first, then JSON
                     content = file.read()
                     try:
-                        return yaml.safe_load(content) or {}
+                        return cast(dict[str, Any], yaml.safe_load(content) or {})
                     except yaml.YAMLError:
-                        return json.loads(content)
+                        return cast(dict[str, Any], json.loads(content))
         except Exception as e:
             logger.error(f"Error loading config file {config_path}: {e}")
             return {}
@@ -382,7 +382,7 @@ class ConfigurationManager:
                 }
 
             # Convert discovered adapters to config format
-            config_data = {"adapters": {}, "default_adapter": None}
+            config_data: dict[str, Any] = {"adapters": {}, "default_adapter": None}
 
             for adapter in discovered.adapters:
                 adapter_config = {"type": adapter.adapter_type, "enabled": True}

mcp_ticketer/core/exceptions.py

@@ -1,4 +1,10 @@
-"""Exception classes for MCP Ticketer."""
+"""Exception classes for MCP Ticketer.
+
+Error Severity Classification:
+    CRITICAL - System-level issues (auth, config, network) → Always suggest diagnostics
+    MEDIUM - Resource issues (not found, permissions) → Suggest diagnostics
+    LOW - User input errors (validation, state transitions) → No diagnostics
+"""
 
 from __future__ import annotations