mcp-ticketer 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

mcp_ticketer/cli/mcp_configure.py

@@ -5,7 +5,6 @@ import os
 import shutil
 import sys
 from pathlib import Path
-from typing import Optional
 
 from rich.console import Console
 
@@ -171,7 +170,7 @@ def save_claude_mcp_config(config_path: Path, config: dict) -> None:
 
 
 def create_mcp_server_config(
-    binary_path: str, project_config: dict, cwd: Optional[str] = None
+    binary_path: str, project_config: dict, cwd: str | None = None
 ) -> dict:
     """Create MCP server configuration for mcp-ticketer.
 

mcp_ticketer/cli/ticket_commands.py

@@ -5,7 +5,6 @@ import json
 import os
 from enum import Enum
 from pathlib import Path
-from typing import Optional
 
 import typer
 from rich.console import Console
@@ -36,7 +35,7 @@ console = Console()
 
 
 # Configuration functions (moved from main.py to avoid circular import)
-def load_config(project_dir: Optional[Path] = None) -> dict:
+def load_config(project_dir: Path | None = None) -> dict:
     """Load configuration from project-local config file."""
     import logging
 
@@ -73,7 +72,7 @@ def save_config(config: dict) -> None:
 
 
 def get_adapter(
-    override_adapter: Optional[str] = None, override_config: Optional[dict] = None
+    override_adapter: str | None = None, override_config: dict | None = None
 ):
     """Get configured adapter instance."""
     config = load_config()
@@ -108,7 +107,7 @@ def get_adapter(
     return AdapterRegistry.get_adapter(adapter_type, adapter_config)
 
 
-def _discover_from_env_files() -> Optional[str]:
+def _discover_from_env_files() -> str | None:
     """Discover adapter configuration from .env or .env.local files.
 
     Returns:
@@ -191,29 +190,29 @@ def _save_adapter_to_config(adapter_name: str) -> None:
 @app.command()
 def create(
     title: str = typer.Argument(..., help="Ticket title"),
-    description: Optional[str] = typer.Option(
+    description: str | None = typer.Option(
         None, "--description", "-d", help="Ticket description"
     ),
     priority: Priority = typer.Option(
         Priority.MEDIUM, "--priority", "-p", help="Priority level"
     ),
-    tags: Optional[list[str]] = typer.Option(
+    tags: list[str] | None = typer.Option(
         None, "--tag", "-t", help="Tags (can be specified multiple times)"
     ),
-    assignee: Optional[str] = typer.Option(
+    assignee: str | None = typer.Option(
         None, "--assignee", "-a", help="Assignee username"
     ),
-    project: Optional[str] = typer.Option(
+    project: str | None = typer.Option(
         None,
         "--project",
         help="Parent project/epic ID (synonym for --epic)",
     ),
-    epic: Optional[str] = typer.Option(
+    epic: str | None = typer.Option(
         None,
         "--epic",
         help="Parent epic/project ID (synonym for --project)",
     ),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -417,14 +416,14 @@ def create(
 
 @app.command("list")
 def list_tickets(
-    state: Optional[TicketState] = typer.Option(
+    state: TicketState | None = typer.Option(
         None, "--state", "-s", help="Filter by state"
     ),
-    priority: Optional[Priority] = typer.Option(
+    priority: Priority | None = typer.Option(
         None, "--priority", "-p", help="Filter by priority"
     ),
     limit: int = typer.Option(10, "--limit", "-l", help="Maximum number of tickets"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -474,7 +473,7 @@ def list_tickets(
 def show(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
     comments: bool = typer.Option(False, "--comments", "-c", help="Show comments"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -524,7 +523,7 @@ def show(
 def comment(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
     content: str = typer.Argument(..., help="Comment content"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -559,17 +558,15 @@ def comment(
 @app.command()
 def update(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
-    title: Optional[str] = typer.Option(None, "--title", help="New title"),
-    description: Optional[str] = typer.Option(
+    title: str | None = typer.Option(None, "--title", help="New title"),
+    description: str | None = typer.Option(
         None, "--description", "-d", help="New description"
     ),
-    priority: Optional[Priority] = typer.Option(
+    priority: Priority | None = typer.Option(
         None, "--priority", "-p", help="New priority"
     ),
-    assignee: Optional[str] = typer.Option(
-        None, "--assignee", "-a", help="New assignee"
-    ),
-    adapter: Optional[AdapterType] = typer.Option(
+    assignee: str | None = typer.Option(None, "--assignee", "-a", help="New assignee"),
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -625,13 +622,13 @@ def update(
 @app.command()
 def transition(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
-    state_positional: Optional[TicketState] = typer.Argument(
+    state_positional: TicketState | None = typer.Argument(
         None, help="Target state (positional - deprecated, use --state instead)"
     ),
-    state: Optional[TicketState] = typer.Option(
+    state: TicketState | None = typer.Option(
         None, "--state", "-s", help="Target state (recommended)"
     ),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
@@ -692,12 +689,12 @@ def transition(
 
 @app.command()
 def search(
-    query: Optional[str] = typer.Argument(None, help="Search query"),
-    state: Optional[TicketState] = typer.Option(None, "--state", "-s"),
-    priority: Optional[Priority] = typer.Option(None, "--priority", "-p"),
-    assignee: Optional[str] = typer.Option(None, "--assignee", "-a"),
+    query: str | None = typer.Argument(None, help="Search query"),
+    state: TicketState | None = typer.Option(None, "--state", "-s"),
+    priority: Priority | None = typer.Option(None, "--priority", "-p"),
+    assignee: str | None = typer.Option(None, "--assignee", "-a"),
     limit: int = typer.Option(10, "--limit", "-l"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:

mcp_ticketer/cli/utils.py

@@ -4,9 +4,10 @@ import asyncio
 import json
 import logging
 import os
+from collections.abc import Callable
 from functools import wraps
 from pathlib import Path
-from typing import Any, Callable, Optional, TypeVar
+from typing import Any, TypeVar
 
 import typer
 from rich.console import Console
@@ -154,7 +155,7 @@ class CommonPatterns:
 
     @staticmethod
     def get_adapter(
-        override_adapter: Optional[str] = None, override_config: Optional[dict] = None
+        override_adapter: str | None = None, override_config: dict | None = None
     ):
         """Get configured adapter instance with environment variable support."""
         config = CommonPatterns.load_config()
@@ -206,7 +207,7 @@ class CommonPatterns:
     def queue_operation(
         ticket_data: dict[str, Any],
         operation: str,
-        adapter_name: Optional[str] = None,
+        adapter_name: str | None = None,
         show_progress: bool = True,
     ) -> str:
         """Queue an operation and optionally start the worker."""
@@ -265,7 +266,7 @@ class CommonPatterns:
         console.print(table)
 
     @staticmethod
-    def display_ticket_details(ticket: Task, comments: Optional[list] = None) -> None:
+    def display_ticket_details(ticket: Task, comments: list | None = None) -> None:
         """Display detailed ticket information."""
         console.print(f"\n[bold]Ticket: {ticket.id}[/bold]")
         console.print(f"Title: {ticket.title}")
@@ -334,7 +335,7 @@ def with_adapter(f: Callable) -> Callable:
     """Decorator to inject adapter instance into CLI commands."""
 
     @wraps(f)
-    def wrapper(adapter: Optional[str] = None, *args, **kwargs):
+    def wrapper(adapter: str | None = None, *args, **kwargs):
         adapter_instance = CommonPatterns.get_adapter(override_adapter=adapter)
         return f(adapter_instance, *args, **kwargs)
 
@@ -446,7 +447,7 @@ class ConfigValidator:
         return issues
 
     @staticmethod
-    def _get_env_var(adapter_type: str, field: str) -> Optional[str]:
+    def _get_env_var(adapter_type: str, field: str) -> str | None:
         """Get corresponding environment variable name for a config field."""
         env_mapping = {
             "github": {
@@ -520,14 +521,14 @@ def create_standard_ticket_command(operation: str):
     """Create a standard ticket operation command."""
 
     def command_template(
-        ticket_id: Optional[str] = None,
-        title: Optional[str] = None,
-        description: Optional[str] = None,
-        priority: Optional[Priority] = None,
-        state: Optional[TicketState] = None,
-        assignee: Optional[str] = None,
-        tags: Optional[list[str]] = None,
-        adapter: Optional[str] = None,
+        ticket_id: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        priority: Priority | None = None,
+        state: TicketState | None = None,
+        assignee: str | None = None,
+        tags: list[str] | None = None,
+        adapter: str | None = None,
     ):
         """Template for ticket commands."""
         # Build ticket data
@@ -568,8 +569,8 @@ class TicketCommands:
     @handle_adapter_errors
     async def list_tickets(
         adapter_instance,
-        state: Optional[TicketState] = None,
-        priority: Optional[Priority] = None,
+        state: TicketState | None = None,
+        priority: Priority | None = None,
         limit: int = 10,
     ):
         """List tickets with filters."""
@@ -603,11 +604,11 @@ class TicketCommands:
     @staticmethod
     def create_ticket(
         title: str,
-        description: Optional[str] = None,
+        description: str | None = None,
         priority: Priority = Priority.MEDIUM,
-        tags: Optional[list[str]] = None,
-        assignee: Optional[str] = None,
-        adapter: Optional[str] = None,
+        tags: list[str] | None = None,
+        assignee: str | None = None,
+        adapter: str | None = None,
     ) -> str:
         """Create a new ticket."""
         ticket_data = {
@@ -622,7 +623,7 @@ class TicketCommands:
 
     @staticmethod
     def update_ticket(
-        ticket_id: str, updates: dict[str, Any], adapter: Optional[str] = None
+        ticket_id: str, updates: dict[str, Any], adapter: str | None = None
     ) -> str:
         """Update a ticket."""
         if not updates:
@@ -634,7 +635,7 @@ class TicketCommands:
 
     @staticmethod
     def transition_ticket(
-        ticket_id: str, state: TicketState, adapter: Optional[str] = None
+        ticket_id: str, state: TicketState, adapter: str | None = None
     ) -> str:
         """Transition ticket state."""
         ticket_data = {

mcp_ticketer/core/__init__.py

@@ -1,13 +1,14 @@
 """Core models and abstractions for MCP Ticketer."""
 
 from .adapter import BaseAdapter
-from .models import Comment, Epic, Priority, Task, TicketState, TicketType
+from .models import Attachment, Comment, Epic, Priority, Task, TicketState, TicketType
 from .registry import AdapterRegistry
 
 __all__ = [
     "Epic",
     "Task",
     "Comment",
+    "Attachment",
     "TicketState",
     "Priority",
     "TicketType",

mcp_ticketer/core/adapter.py

@@ -1,11 +1,16 @@
 """Base adapter abstract class for ticket systems."""
 
+from __future__ import annotations
+
 import builtins
 from abc import ABC, abstractmethod
-from typing import Any, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
 
+if TYPE_CHECKING:
+    from .models import Attachment
+
 # Generic type for tickets
 T = TypeVar("T", Epic, Task)
 
@@ -57,7 +62,7 @@ class BaseAdapter(ABC, Generic[T]):
         pass
 
     @abstractmethod
-    async def read(self, ticket_id: str) -> Optional[T]:
+    async def read(self, ticket_id: str) -> T | None:
         """Read a ticket by ID.
 
         Args:
@@ -70,7 +75,7 @@ class BaseAdapter(ABC, Generic[T]):
         pass
 
     @abstractmethod
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[T]:
+    async def update(self, ticket_id: str, updates: dict[str, Any]) -> T | None:
         """Update a ticket.
 
         Args:
@@ -98,7 +103,7 @@ class BaseAdapter(ABC, Generic[T]):
 
     @abstractmethod
     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[T]:
         """List tickets with pagination and filters.
 
@@ -129,7 +134,7 @@ class BaseAdapter(ABC, Generic[T]):
     @abstractmethod
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[T]:
+    ) -> T | None:
         """Transition ticket to a new state.
 
         Args:
@@ -225,8 +230,8 @@ class BaseAdapter(ABC, Generic[T]):
     # Epic/Issue/Task Hierarchy Methods
 
     async def create_epic(
-        self, title: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Epic]:
+        self, title: str, description: str | None = None, **kwargs
+    ) -> Epic | None:
         """Create epic (top-level grouping).
 
         Args:
@@ -249,7 +254,7 @@ class BaseAdapter(ABC, Generic[T]):
             return result
         return None
 
-    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:
@@ -284,10 +289,10 @@ class BaseAdapter(ABC, Generic[T]):
     async def create_issue(
         self,
         title: str,
-        description: Optional[str] = None,
-        epic_id: Optional[str] = None,
+        description: str | None = None,
+        epic_id: str | None = None,
         **kwargs,
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Create issue, optionally linked to epic.
 
         Args:
@@ -325,8 +330,8 @@ class BaseAdapter(ABC, Generic[T]):
         return [r for r in results if isinstance(r, Task) and r.is_issue()]
 
     async def create_task(
-        self, title: str, parent_id: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Task]:
+        self, title: str, parent_id: str, description: str | None = None, **kwargs
+    ) -> Task | None:
         """Create task as sub-ticket of parent issue.
 
         Args:
@@ -375,6 +380,70 @@ class BaseAdapter(ABC, Generic[T]):
         results = await self.list(filters=filters)
         return [r for r in results if isinstance(r, Task) and r.is_task()]
 
+    # Attachment methods
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: str | None = None,
+    ) -> Attachment:
+        """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
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments. "
+            "Use comments to reference external files instead."
+        )
+
+    async def get_attachments(self, ticket_id: str) -> list[Attachment]:
+        """Get all attachments for a ticket.
+
+        Args:
+            ticket_id: Ticket identifier
+
+        Returns:
+            List of attachments (empty if none or not supported)
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments."
+        )
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str,
+    ) -> bool:
+        """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
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support attachment deletion."
+        )
+
     async def close(self) -> None:
         """Close adapter and cleanup resources."""
         pass

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, Union
+from typing import Any, Optional
 
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -27,23 +27,23 @@ class BaseAdapterConfig(BaseModel):
     """Base configuration for all adapters."""
 
     type: AdapterType
-    name: Optional[str] = None
+    name: str | None = None
     enabled: bool = True
     timeout: float = 30.0
     max_retries: int = 3
-    rate_limit: Optional[dict[str, Any]] = None
+    rate_limit: dict[str, Any] | None = None
 
 
 class GitHubConfig(BaseAdapterConfig):
     """GitHub adapter configuration."""
 
     type: AdapterType = AdapterType.GITHUB
-    token: Optional[str] = Field(None, env="GITHUB_TOKEN")
-    owner: Optional[str] = Field(None, env="GITHUB_OWNER")
-    repo: Optional[str] = Field(None, env="GITHUB_REPO")
+    token: str | None = Field(None, env="GITHUB_TOKEN")
+    owner: str | None = Field(None, env="GITHUB_OWNER")
+    repo: str | None = Field(None, env="GITHUB_REPO")
     api_url: str = "https://api.github.com"
     use_projects_v2: bool = False
-    custom_priority_scheme: Optional[dict[str, list[str]]] = None
+    custom_priority_scheme: dict[str, list[str]] | None = None
 
     @field_validator("token", mode="before")
     @classmethod
@@ -77,10 +77,10 @@ class JiraConfig(BaseAdapterConfig):
     """JIRA adapter configuration."""
 
     type: AdapterType = AdapterType.JIRA
-    server: Optional[str] = Field(None, env="JIRA_SERVER")
-    email: Optional[str] = Field(None, env="JIRA_EMAIL")
-    api_token: Optional[str] = Field(None, env="JIRA_API_TOKEN")
-    project_key: Optional[str] = Field(None, env="JIRA_PROJECT_KEY")
+    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")
     cloud: bool = True
     verify_ssl: bool = True
 
@@ -116,10 +116,10 @@ class LinearConfig(BaseAdapterConfig):
     """Linear adapter configuration."""
 
     type: AdapterType = AdapterType.LINEAR
-    api_key: Optional[str] = Field(None, env="LINEAR_API_KEY")
-    workspace: Optional[str] = None
-    team_key: Optional[str] = None  # Short team key like "BTA"
-    team_id: Optional[str] = None  # UUID team identifier
+    api_key: str | None = Field(None, env="LINEAR_API_KEY")
+    workspace: str | None = None
+    team_key: str | None = None  # Short team key like "BTA"
+    team_id: str | None = None  # UUID team identifier
     api_url: str = "https://api.linear.app/graphql"
 
     @model_validator(mode="after")
@@ -150,7 +150,7 @@ class QueueConfig(BaseModel):
     """Queue configuration."""
 
     provider: str = "sqlite"
-    connection_string: Optional[str] = None
+    connection_string: str | None = None
     batch_size: int = 10
     max_concurrent: int = 5
     retry_attempts: int = 3
@@ -162,7 +162,7 @@ class LoggingConfig(BaseModel):
 
     level: str = "INFO"
     format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    file: Optional[str] = None
+    file: str | None = None
     max_size: str = "10MB"
     backup_count: int = 5
 
@@ -171,12 +171,12 @@ class AppConfig(BaseModel):
     """Main application configuration."""
 
     adapters: dict[
-        str, Union[GitHubConfig, JiraConfig, LinearConfig, AITrackdownConfig]
+        str, GitHubConfig | JiraConfig | LinearConfig | AITrackdownConfig
     ] = {}
     queue: QueueConfig = QueueConfig()
     logging: LoggingConfig = LoggingConfig()
     cache_ttl: int = 300  # Cache TTL in seconds
-    default_adapter: Optional[str] = None
+    default_adapter: str | None = None
 
     @model_validator(mode="after")
     def validate_adapters(self):
@@ -196,7 +196,7 @@ class AppConfig(BaseModel):
 
         return self
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         return self.adapters.get(adapter_name)
 
@@ -211,7 +211,7 @@ class ConfigurationManager:
     """Centralized configuration management with caching and validation."""
 
     _instance: Optional["ConfigurationManager"] = None
-    _config: Optional[AppConfig] = None
+    _config: AppConfig | None = None
     _config_file_paths: list[Path] = []
 
     def __new__(cls) -> "ConfigurationManager":
@@ -266,7 +266,7 @@ class ConfigurationManager:
             logger.debug("No project-local config files found, will use defaults")
 
     @lru_cache(maxsize=1)
-    def load_config(self, config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+    def load_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Load and validate configuration from file and environment.
 
         Args:
@@ -437,7 +437,7 @@ class ConfigurationManager:
             return self.load_config()
         return self._config
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         config = self.get_config()
         return config.get_adapter_config(adapter_name)
@@ -457,9 +457,7 @@ class ConfigurationManager:
         config = self.get_config()
         return config.logging
 
-    def reload_config(
-        self, config_file: Optional[Union[str, Path]] = None
-    ) -> AppConfig:
+    def reload_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Reload configuration from file."""
         # Clear cache
         self.load_config.cache_clear()
@@ -492,7 +490,7 @@ class ConfigurationManager:
         self._config_cache[key] = value
         return value
 
-    def create_sample_config(self, output_path: Union[str, Path]) -> None:
+    def create_sample_config(self, output_path: str | Path) -> None:
         """Create a sample configuration file."""
         sample_config = {
             "adapters": {
@@ -539,11 +537,11 @@ def get_config() -> AppConfig:
     return config_manager.get_config()
 
 
-def get_adapter_config(adapter_name: str) -> Optional[BaseAdapterConfig]:
+def get_adapter_config(adapter_name: str) -> BaseAdapterConfig | None:
     """Get configuration for a specific adapter."""
     return config_manager.get_adapter_config(adapter_name)
 
 
-def reload_config(config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+def reload_config(config_file: str | Path | None = None) -> AppConfig:
     """Reload the global configuration."""
     return config_manager.reload_config(config_file)