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

mcp_ticketer/mcp/server/tools/config_tools.py

@@ -0,0 +1,381 @@
+"""Configuration management tools for MCP ticketer.
+
+This module provides tools for managing project-local configuration including
+default adapter, project, and user settings. All configuration is stored in
+.mcp-ticketer/config.json within the project root.
+
+Design Decision: Project-Local Configuration Only
+-------------------------------------------------
+For security and isolation, this module ONLY manages project-local configuration
+stored in .mcp-ticketer/config.json. It never reads from or writes to user home
+directory or system-wide locations to prevent configuration leakage across projects.
+
+Configuration stored:
+- default_adapter: Primary adapter to use for ticket operations
+- default_project: Default epic/project ID for new tickets
+- default_user: Default assignee for new tickets (user_id or email)
+- default_epic: Alias for default_project (backward compatibility)
+
+Error Handling:
+- All tools validate input before modifying configuration
+- Adapter names are validated against AdapterRegistry
+- Configuration file is created atomically to prevent corruption
+- Detailed error messages for invalid configurations
+
+Performance: Configuration is cached in memory by ConfigResolver,
+so repeated reads are fast (O(1) after first load).
+"""
+
+from pathlib import Path
+from typing import Any
+
+from ....core.project_config import AdapterType, ConfigResolver, TicketerConfig
+from ..server_sdk import mcp
+
+
+def get_resolver() -> ConfigResolver:
+    """Get or create the configuration resolver.
+
+    Returns:
+        ConfigResolver instance for current working directory
+
+    Design Decision: Uses CWD as project root, assuming MCP server
+    is started from project directory. This matches user expectations
+    and aligns with how other development tools operate.
+
+    Note: Creates a new resolver each time to avoid caching issues
+    in tests and ensure current working directory is always used.
+
+    """
+    return ConfigResolver(project_path=Path.cwd())
+
+
+@mcp.tool()
+async def config_set_primary_adapter(adapter: str) -> dict[str, Any]:
+    """Set the default adapter for ticket operations.
+
+    Updates the project-local configuration (.mcp-ticketer/config.json)
+    to use the specified adapter as the default for all ticket operations.
+
+    Args:
+        adapter: Adapter name to set as primary. Must be one of:
+            - "aitrackdown" (file-based tracking)
+            - "linear" (Linear.app)
+            - "github" (GitHub Issues)
+            - "jira" (Atlassian JIRA)
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - message: Success or error message
+        - previous_adapter: Previous default adapter (if successful)
+        - new_adapter: New default adapter (if successful)
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await config_set_primary_adapter("linear")
+        >>> print(result)
+        {
+            "status": "completed",
+            "message": "Default adapter set to 'linear'",
+            "previous_adapter": "aitrackdown",
+            "new_adapter": "linear"
+        }
+
+    Error Conditions:
+        - Invalid adapter name: Returns error with valid options
+        - Configuration file write failure: Returns error with file path
+
+    """
+    try:
+        # Validate adapter name against registry
+        valid_adapters = [adapter_type.value for adapter_type in AdapterType]
+        if adapter.lower() not in valid_adapters:
+            return {
+                "status": "error",
+                "error": f"Invalid adapter '{adapter}'. Must be one of: {', '.join(valid_adapters)}",
+                "valid_adapters": valid_adapters,
+            }
+
+        # Load current configuration
+        resolver = get_resolver()
+        config = resolver.load_project_config() or TicketerConfig()
+
+        # Store previous adapter for response
+        previous_adapter = config.default_adapter
+
+        # Update default adapter
+        config.default_adapter = adapter.lower()
+
+        # Save configuration
+        resolver.save_project_config(config)
+
+        return {
+            "status": "completed",
+            "message": f"Default adapter set to '{adapter.lower()}'",
+            "previous_adapter": previous_adapter,
+            "new_adapter": adapter.lower(),
+            "config_path": str(resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to set default adapter: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def config_set_default_project(
+    project_id: str,
+    project_key: str | None = None,
+) -> dict[str, Any]:
+    """Set the default project/epic for new tickets.
+
+    Updates the project-local configuration to automatically assign new tickets
+    to the specified project or epic. This is useful for teams working primarily
+    on a single project or feature area.
+
+    Args:
+        project_id: Project or epic ID to set as default (required)
+        project_key: Optional project key (for adapters that use keys vs IDs)
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - message: Success or error message
+        - previous_project: Previous default project (if any)
+        - new_project: New default project ID
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await config_set_default_project("PROJ-123")
+        >>> print(result)
+        {
+            "status": "completed",
+            "message": "Default project set to 'PROJ-123'",
+            "previous_project": None,
+            "new_project": "PROJ-123"
+        }
+
+    Usage Notes:
+        - This sets both default_project and default_epic (for backward compatibility)
+        - Empty string or null clears the default project
+        - Project ID is not validated (allows flexibility across adapters)
+
+    """
+    try:
+        # Load current configuration
+        resolver = get_resolver()
+        config = resolver.load_project_config() or TicketerConfig()
+
+        # Store previous project for response
+        previous_project = config.default_project or config.default_epic
+
+        # Update default project (and epic for backward compat)
+        config.default_project = project_id if project_id else None
+        config.default_epic = project_id if project_id else None
+
+        # Save configuration
+        resolver.save_project_config(config)
+
+        return {
+            "status": "completed",
+            "message": (
+                f"Default project set to '{project_id}'"
+                if project_id
+                else "Default project cleared"
+            ),
+            "previous_project": previous_project,
+            "new_project": project_id,
+            "config_path": str(resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to set default project: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def config_set_default_user(
+    user_id: str,
+    user_email: str | None = None,
+) -> dict[str, Any]:
+    """Set the default assignee for new tickets.
+
+    Updates the project-local configuration to automatically assign new tickets
+    to the specified user. Supports both user IDs and email addresses depending
+    on adapter requirements.
+
+    Args:
+        user_id: User identifier or email to set as default assignee (required)
+        user_email: Optional email (for adapters that require separate email field)
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - message: Success or error message
+        - previous_user: Previous default user (if any)
+        - new_user: New default user ID
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await config_set_default_user("user123")
+        >>> print(result)
+        {
+            "status": "completed",
+            "message": "Default user set to 'user123'",
+            "previous_user": None,
+            "new_user": "user123"
+        }
+
+    Example with email:
+        >>> result = await config_set_default_user("user@example.com")
+        >>> print(result)
+        {
+            "status": "completed",
+            "message": "Default user set to 'user@example.com'",
+            "previous_user": "old_user@example.com",
+            "new_user": "user@example.com"
+        }
+
+    Usage Notes:
+        - User ID/email is not validated (allows flexibility across adapters)
+        - Empty string or null clears the default user
+        - Some adapters prefer email, others prefer user UUID
+
+    """
+    try:
+        # Load current configuration
+        resolver = get_resolver()
+        config = resolver.load_project_config() or TicketerConfig()
+
+        # Store previous user for response
+        previous_user = config.default_user
+
+        # Update default user
+        config.default_user = user_id if user_id else None
+
+        # Save configuration
+        resolver.save_project_config(config)
+
+        return {
+            "status": "completed",
+            "message": (
+                f"Default user set to '{user_id}'"
+                if user_id
+                else "Default user cleared"
+            ),
+            "previous_user": previous_user,
+            "new_user": user_id,
+            "config_path": str(resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to set default user: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def config_get() -> dict[str, Any]:
+    """Get current configuration settings.
+
+    Retrieves the current project-local configuration including default adapter,
+    project, user, and all adapter-specific settings.
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - config: Complete configuration dictionary including:
+            - default_adapter: Primary adapter name
+            - default_project: Default project/epic ID (if set)
+            - default_user: Default assignee (if set)
+            - adapters: All adapter configurations
+            - hybrid_mode: Hybrid mode settings (if enabled)
+        - config_path: Path to configuration file
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await config_get()
+        >>> print(result)
+        {
+            "status": "completed",
+            "config": {
+                "default_adapter": "linear",
+                "default_project": "PROJ-123",
+                "default_user": "user@example.com",
+                "adapters": {
+                    "linear": {"api_key": "***", "team_id": "..."}
+                }
+            },
+            "config_path": "/project/.mcp-ticketer/config.json"
+        }
+
+    Usage Notes:
+        - Sensitive values (API keys) are masked in the response
+        - Returns default values if no configuration file exists
+        - Configuration is merged from multiple sources (env vars, .env files, config.json)
+
+    """
+    try:
+        # Load current configuration
+        resolver = get_resolver()
+        config = resolver.load_project_config() or TicketerConfig()
+
+        # Convert to dictionary
+        config_dict = config.to_dict()
+
+        # Mask sensitive values (API keys, tokens)
+        masked_config = _mask_sensitive_values(config_dict)
+
+        config_path = resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH
+        config_exists = config_path.exists()
+
+        return {
+            "status": "completed",
+            "config": masked_config,
+            "config_path": str(config_path),
+            "config_exists": config_exists,
+            "message": (
+                "Configuration retrieved successfully"
+                if config_exists
+                else "No configuration file found, showing defaults"
+            ),
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to retrieve configuration: {str(e)}",
+        }
+
+
+def _mask_sensitive_values(config: dict[str, Any]) -> dict[str, Any]:
+    """Mask sensitive values in configuration dictionary.
+
+    Args:
+        config: Configuration dictionary
+
+    Returns:
+        Configuration dictionary with sensitive values masked
+
+    Implementation Details:
+        - Recursively processes nested dictionaries
+        - Masks any field containing: key, token, password, secret
+        - Preserves structure for debugging while protecting credentials
+
+    """
+    masked = {}
+    sensitive_keys = {"api_key", "token", "password", "secret", "api_token"}
+
+    for key, value in config.items():
+        if isinstance(value, dict):
+            # Recursively mask nested dictionaries
+            masked[key] = _mask_sensitive_values(value)
+        elif any(sensitive in key.lower() for sensitive in sensitive_keys):
+            # Mask sensitive values
+            masked[key] = "***" if value else None
+        else:
+            masked[key] = value
+
+    return masked

mcp_ticketer/mcp/server/tools/hierarchy_tools.py

@@ -7,10 +7,13 @@ This module implements tools for managing the three-level ticket hierarchy:
 """
 
 from datetime import datetime
+from pathlib import Path
 from typing import Any
 
 from ....core.models import Epic, Priority, Task, TicketType
+from ....core.project_config import ConfigResolver, TicketerConfig
 from ..server_sdk import get_adapter, mcp
+from .ticket_tools import detect_and_apply_labels
 
 
 @mcp.tool()
@@ -159,8 +162,13 @@ async def issue_create(
     epic_id: str | None = None,
     assignee: str | None = None,
     priority: str = "medium",
+    tags: list[str] | None = None,
+    auto_detect_labels: bool = True,
 ) -> dict[str, Any]:
-    """Create a new issue (standard work item).
+    """Create a new issue (standard work item) with automatic label detection.
+
+    This tool automatically scans available labels/tags and intelligently
+    applies relevant ones based on the issue title and description.
 
     Args:
         title: Issue title (required)
@@ -168,6 +176,8 @@ async def issue_create(
         epic_id: Parent epic ID to link this issue to
         assignee: User ID or email to assign the issue to
         priority: Priority level - must be one of: low, medium, high, critical
+        tags: List of tags to categorize the issue (auto-detection adds to these)
+        auto_detect_labels: Automatically detect and apply relevant labels (default: True)
 
     Returns:
         Created issue details including ID and metadata, or error information
@@ -185,14 +195,41 @@ async def issue_create(
                 "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
             }
 
+        # Use default_user if no assignee specified
+        final_assignee = assignee
+        if final_assignee is None:
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+            if config.default_user:
+                final_assignee = config.default_user
+
+        # Use default_project if no epic_id specified
+        final_epic_id = epic_id
+        if final_epic_id is None:
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+            # Try default_project first, fall back to default_epic
+            if config.default_project:
+                final_epic_id = config.default_project
+            elif config.default_epic:
+                final_epic_id = config.default_epic
+
+        # Auto-detect labels if enabled
+        final_tags = tags
+        if auto_detect_labels:
+            final_tags = await detect_and_apply_labels(
+                adapter, title, description or "", tags
+            )
+
         # Create issue (Task with ISSUE type)
         issue = Task(
             title=title,
             description=description or "",
             ticket_type=TicketType.ISSUE,
-            parent_epic=epic_id,
-            assignee=assignee,
+            parent_epic=final_epic_id,
+            assignee=final_assignee,
             priority=priority_enum,
+            tags=final_tags or [],
         )
 
         # Create via adapter
@@ -201,6 +238,8 @@ async def issue_create(
         return {
             "status": "completed",
             "issue": created.model_dump(),
+            "labels_applied": created.tags or [],
+            "auto_detected": auto_detect_labels,
         }
     except Exception as e:
         return {
@@ -261,8 +300,13 @@ async def task_create(
     issue_id: str | None = None,
     assignee: str | None = None,
     priority: str = "medium",
+    tags: list[str] | None = None,
+    auto_detect_labels: bool = True,
 ) -> dict[str, Any]:
-    """Create a new task (sub-work item).
+    """Create a new task (sub-work item) with automatic label detection.
+
+    This tool automatically scans available labels/tags and intelligently
+    applies relevant ones based on the task title and description.
 
     Args:
         title: Task title (required)
@@ -270,6 +314,8 @@ async def task_create(
         issue_id: Parent issue ID to link this task to
         assignee: User ID or email to assign the task to
         priority: Priority level - must be one of: low, medium, high, critical
+        tags: List of tags to categorize the task (auto-detection adds to these)
+        auto_detect_labels: Automatically detect and apply relevant labels (default: True)
 
     Returns:
         Created task details including ID and metadata, or error information
@@ -287,14 +333,30 @@ async def task_create(
                 "error": f"Invalid priority '{priority}'. Must be one of: low, medium, high, critical",
             }
 
+        # Use default_user if no assignee specified
+        final_assignee = assignee
+        if final_assignee is None:
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config = resolver.load_project_config() or TicketerConfig()
+            if config.default_user:
+                final_assignee = config.default_user
+
+        # Auto-detect labels if enabled
+        final_tags = tags
+        if auto_detect_labels:
+            final_tags = await detect_and_apply_labels(
+                adapter, title, description or "", tags
+            )
+
         # Create task (Task with TASK type)
         task = Task(
             title=title,
             description=description or "",
             ticket_type=TicketType.TASK,
             parent_issue=issue_id,
-            assignee=assignee,
+            assignee=final_assignee,
             priority=priority_enum,
+            tags=final_tags or [],
         )
 
         # Create via adapter
@@ -303,6 +365,8 @@ async def task_create(
         return {
             "status": "completed",
             "task": created.model_dump(),
+            "labels_applied": created.tags or [],
+            "auto_detected": auto_detect_labels,
         }
     except Exception as e:
         return {
@@ -311,6 +375,91 @@ async def task_create(
         }
 
 
+@mcp.tool()
+async def epic_update(
+    epic_id: str,
+    title: str | None = None,
+    description: str | None = None,
+    state: str | None = None,
+    target_date: str | None = None,
+) -> dict[str, Any]:
+    """Update an existing epic's metadata and description.
+
+    Args:
+        epic_id: Epic identifier (required)
+        title: New title for the epic
+        description: New description for the epic
+        state: New state (open, in_progress, done, closed)
+        target_date: Target completion date in ISO format (YYYY-MM-DD)
+
+    Returns:
+        Updated epic details, or error information
+
+    """
+    try:
+        adapter = get_adapter()
+
+        # Check if adapter supports epic updates
+        if not hasattr(adapter, "update_epic"):
+            return {
+                "status": "error",
+                "error": f"Epic updates not supported by {type(adapter).__name__} adapter",
+                "epic_id": epic_id,
+                "note": "Use ticket_update instead for basic field updates",
+            }
+
+        # Build updates dictionary
+        updates = {}
+        if title is not None:
+            updates["title"] = title
+        if description is not None:
+            updates["description"] = description
+        if state is not None:
+            updates["state"] = state
+        if target_date is not None:
+            # Parse target date if provided
+            try:
+                target_datetime = datetime.fromisoformat(target_date)
+                updates["target_date"] = target_datetime
+            except ValueError:
+                return {
+                    "status": "error",
+                    "error": f"Invalid date format '{target_date}'. Use ISO format: YYYY-MM-DD",
+                }
+
+        if not updates:
+            return {
+                "status": "error",
+                "error": "No updates provided. At least one field (title, description, state, target_date) must be specified.",
+            }
+
+        # Update via adapter
+        updated = await adapter.update_epic(epic_id, updates)  # type: ignore
+
+        if updated is None:
+            return {
+                "status": "error",
+                "error": f"Epic {epic_id} not found or update failed",
+            }
+
+        return {
+            "status": "completed",
+            "epic": updated.model_dump(),
+        }
+    except AttributeError as e:
+        return {
+            "status": "error",
+            "error": f"Epic update method not available: {str(e)}",
+            "epic_id": epic_id,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to update epic: {str(e)}",
+            "epic_id": epic_id,
+        }
+
+
 @mcp.tool()
 async def hierarchy_tree(
     epic_id: str,