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

mcp_ticketer/core/state_matcher.py

@@ -199,7 +199,6 @@ class SemanticStateMatcher:
             "complete",
             "finished",
             "resolved",
-            "closed",
             "done done",
             "done-done",
             "delivered",
@@ -271,17 +270,51 @@ class SemanticStateMatcher:
         """Initialize the semantic state matcher.
 
         Creates reverse lookup dictionary for O(1) synonym matching.
+        Detects and logs duplicate synonyms across states.
         """
+        import logging
+
+        logger = logging.getLogger(__name__)
+
         # Build reverse lookup: synonym -> (state, is_exact)
         self._synonym_to_state: dict[str, tuple[TicketState, bool]] = {}
 
+        # Track duplicates for validation
+        duplicate_check: dict[str, list[TicketState]] = {}
+
         for state in TicketState:
             # Add exact state value
-            self._synonym_to_state[state.value.lower()] = (state, True)
+            normalized_value = state.value.lower()
+            self._synonym_to_state[normalized_value] = (state, True)
+
+            if normalized_value not in duplicate_check:
+                duplicate_check[normalized_value] = []
+            duplicate_check[normalized_value].append(state)
 
             # Add all synonyms
             for synonym in self.STATE_SYNONYMS.get(state, []):
-                self._synonym_to_state[synonym.lower()] = (state, False)
+                normalized_synonym = synonym.lower()
+
+                # Check for duplicates
+                if normalized_synonym in duplicate_check:
+                    duplicate_check[normalized_synonym].append(state)
+                else:
+                    duplicate_check[normalized_synonym] = [state]
+
+                self._synonym_to_state[normalized_synonym] = (state, False)
+
+        # Log warnings for any duplicates found (excluding expected state value duplicates)
+        for synonym, states in duplicate_check.items():
+            if len(states) > 1:
+                # Filter out duplicate state values (they're expected - exact match + synonym)
+                unique_states = list(set(states))
+                if len(unique_states) > 1:
+                    logger.warning(
+                        "Duplicate synonym '%s' found in multiple states: %s. "
+                        "This may cause non-deterministic behavior.",
+                        synonym,
+                        ", ".join(s.value for s in unique_states),
+                    )
 
     def match_state(
         self,

mcp_ticketer/mcp/server/__main__.py

@@ -43,7 +43,8 @@ def run_server() -> None:
             os.chdir(project_path)
             sys.stderr.write(f"[MCP Server] Working directory: {project_path}\n")
         except OSError as e:
-            sys.stderr.write(f"Warning: Could not change to project directory: {e}\n")
+            sys.stderr.write(f"Error: Could not change to project directory: {e}\n")
+            sys.exit(1)
 
     # Run the async main function
     try:

mcp_ticketer/mcp/server/routing.py

@@ -637,6 +637,74 @@ class TicketRouter:
                 f"Failed to route list_tasks_by_issue operation: {str(e)}"
             ) from e
 
+    async def validate_project_access(
+        self, project_url: str, test_connection: bool = True
+    ) -> dict[str, Any]:
+        """Validate project URL and test accessibility.
+
+        This method provides comprehensive validation for project URLs:
+        1. Parses URL to extract platform and project ID
+        2. Validates adapter configuration exists
+        3. Validates adapter credentials
+        4. Optionally tests project accessibility via API
+
+        Args:
+            project_url: Project URL to validate
+            test_connection: If True, test actual API connectivity (default: True)
+
+        Returns:
+            Validation result dictionary with:
+            - valid (bool): Whether validation passed
+            - platform (str): Detected platform
+            - project_id (str): Extracted project ID
+            - adapter_configured (bool): Whether adapter is configured
+            - error (str): Error message if validation failed
+            - suggestions (list): Suggested actions to resolve error
+
+        Examples:
+            >>> router = TicketRouter(...)
+            >>> result = await router.validate_project_access("https://linear.app/team/project/abc-123")
+            >>> if result["valid"]:
+            ...     print(f"Project {result['project_id']} is accessible")
+            ... else:
+            ...     print(f"Error: {result['error']}")
+
+        """
+        try:
+            # Import project validator
+            # Create validator (use router's config for consistency)
+            from pathlib import Path
+
+            from ...core.project_validator import ProjectValidator
+
+            validator = ProjectValidator(project_path=Path.cwd())
+
+            # Validate project URL
+            validation_result = validator.validate_project_url(
+                url=project_url, test_connection=test_connection
+            )
+
+            # Convert dataclass to dictionary
+            return {
+                "valid": validation_result.valid,
+                "platform": validation_result.platform,
+                "project_id": validation_result.project_id,
+                "adapter_configured": validation_result.adapter_configured,
+                "adapter_valid": validation_result.adapter_valid,
+                "error": validation_result.error,
+                "error_type": validation_result.error_type,
+                "suggestions": validation_result.suggestions,
+                "credential_errors": validation_result.credential_errors,
+            }
+
+        except Exception as e:
+            logger.error(f"Project validation failed: {e}")
+            return {
+                "valid": False,
+                "error": f"Validation failed with exception: {str(e)}",
+                "error_type": "validation_error",
+            }
+
     async def close(self) -> None:
         """Close all cached adapter connections.
 

mcp_ticketer/mcp/server/tools/__init__.py

@@ -17,13 +17,14 @@ Modules:
     label_tools: Label management, normalization, deduplication, and cleanup
     project_update_tools: Project status update management (1M-238)
     project_status_tools: Project status analysis and work planning (1M-316)
+    milestone_tools: Milestone management and progress tracking (1M-607)
+    attachment_tools: File attachment management (ticket_attach, ticket_attachments)
 
 Note:
     instruction_tools: Removed from MCP server (CLI-only as of Phase 2 Sprint 2.3)
     pr_tools: Removed from MCP server (CLI-only as of Phase 2 Sprint 1.3)
-    attachment_tools: Removed from MCP server (CLI-only as of Phase 2 Sprint 1.3)
     These tools are available via CLI commands but not exposed through MCP interface.
-    Use filesystem MCP for file operations and GitHub MCP for PR management.
+    Use GitHub MCP for PR management.
 
 """
 
@@ -31,13 +32,14 @@ Note:
 # Order matters - import core functionality first
 from . import (
     analysis_tools,  # noqa: F401
-    # attachment_tools removed - CLI-only (Phase 2 Sprint 1.3 - use filesystem MCP)
+    attachment_tools,  # noqa: F401
     bulk_tools,  # noqa: F401
     comment_tools,  # noqa: F401
     config_tools,  # noqa: F401
     hierarchy_tools,  # noqa: F401
     # instruction_tools removed - CLI-only (Phase 2 Sprint 2.3)
     label_tools,  # noqa: F401
+    milestone_tools,  # noqa: F401
     # pr_tools removed - CLI-only (Phase 2 Sprint 1.3 - use GitHub MCP)
     project_status_tools,  # noqa: F401
     project_update_tools,  # noqa: F401
@@ -49,13 +51,14 @@ from . import (
 
 __all__ = [
     "analysis_tools",
-    # "attachment_tools" removed - CLI-only (Phase 2 Sprint 1.3)
+    "attachment_tools",
     "bulk_tools",
     "comment_tools",
     "config_tools",
     "hierarchy_tools",
     # "instruction_tools" removed - CLI-only (Phase 2 Sprint 2.3)
     "label_tools",
+    "milestone_tools",
     # "pr_tools" removed - CLI-only (Phase 2 Sprint 1.3)
     "project_status_tools",
     "project_update_tools",

mcp_ticketer/mcp/server/tools/attachment_tools.py

@@ -10,9 +10,10 @@ from pathlib import Path
 from typing import Any
 
 from ....core.models import Comment, TicketType
-from ..server_sdk import get_adapter
+from ..server_sdk import get_adapter, mcp
 
 
+@mcp.tool()
 async def ticket_attach(
     ticket_id: str,
     file_path: str,
@@ -144,6 +145,7 @@ async def ticket_attach(
         }
 
 
+@mcp.tool()
 async def ticket_attachments(
     ticket_id: str,
 ) -> dict[str, Any]:  # Keep as dict for MCP compatibility

mcp_ticketer/mcp/server/tools/config_tools.py

@@ -26,6 +26,7 @@ Performance: Configuration is cached in memory by ConfigResolver,
 so repeated reads are fast (O(1) after first load).
 """
 
+import logging
 import warnings
 from pathlib import Path
 from typing import Any
@@ -39,6 +40,8 @@ from ....core.project_config import (
 from ....core.registry import AdapterRegistry
 from ..server_sdk import mcp
 
+logger = logging.getLogger(__name__)
+
 
 def get_resolver() -> ConfigResolver:
     """Get or create the configuration resolver.
@@ -57,6 +60,55 @@ def get_resolver() -> ConfigResolver:
     return ConfigResolver(project_path=Path.cwd())
 
 
+def _safe_load_config() -> TicketerConfig:
+    """Safely load project configuration, preserving existing adapters.
+
+    This function prevents data loss when updating config fields by:
+    1. Attempting to load existing configuration
+    2. If file doesn't exist: create new empty config (first-time setup OK)
+    3. If file exists but fails to load: raise error to prevent data wipe
+
+    Returns:
+        Loaded or new TicketerConfig instance
+
+    Raises:
+        RuntimeError: If config file exists but cannot be loaded
+
+    Design Rationale:
+        The pattern `config = resolver.load_project_config() or TicketerConfig()`
+        is DANGEROUS because load_project_config() returns None on ANY failure
+        (file read error, JSON parse error, etc), which creates an empty config
+        and wipes all adapter configurations when saved.
+
+        This function prevents data loss by explicitly checking if the file
+        exists before deciding whether to create a new config.
+    """
+    resolver = get_resolver()
+    config_path = resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH
+
+    # Try to load existing config
+    config = resolver.load_project_config()
+
+    # If config loaded successfully, return it
+    if config is not None:
+        return config
+
+    # Config is None - need to determine if this is first-time setup or an error
+    if config_path.exists():
+        # File exists but failed to load - this is an error condition
+        # DO NOT create empty config and wipe existing data
+        raise RuntimeError(
+            f"Configuration file exists at {config_path} but failed to load. "
+            f"This may indicate a corrupted or invalid JSON file. "
+            f"Please check the file manually before retrying. "
+            f"To prevent data loss, this operation was aborted."
+        )
+
+    # File doesn't exist - first-time setup, safe to create new config
+    logger.info(f"No configuration file found at {config_path}, creating new config")
+    return TicketerConfig()
+
+
 @mcp.tool()
 async def config(
     action: str,
@@ -68,7 +120,9 @@ async def config(
     credentials: dict[str, Any] | None = None,
     set_as_default: bool = True,
     test_connection: bool = True,
-    **kwargs: Any,
+    # Explicitly define optional parameters (previously in **kwargs)
+    project_key: str | None = None,
+    user_email: str | None = None,
 ) -> dict[str, Any]:
     """Unified configuration management tool with action-based routing (v2.0.0).
 
@@ -79,6 +133,7 @@ async def config(
         action: Operation to perform. Valid values:
             - "get": Get current configuration
             - "set": Set a configuration value (requires key and value)
+            - "set_project_from_url": Set default project from URL with validation (requires value=URL)
             - "validate": Validate all adapter configurations
             - "test": Test adapter connectivity (requires adapter_name)
             - "list_adapters": List all available adapters
@@ -93,7 +148,8 @@ async def config(
         credentials: Adapter credentials dict (for action="setup_wizard")
         set_as_default: Set adapter as default (for action="setup_wizard", default: True)
         test_connection: Test connection during setup (for action="setup_wizard", default: True)
-        **kwargs: Additional parameters passed to underlying functions
+        project_key: Project key for JIRA adapter (for action="set" with key="project")
+        user_email: User email for adapter-specific user identification (for action="set" with key="user")
 
     Returns:
         Response dict with status and action-specific data
@@ -150,6 +206,16 @@ async def config(
     # Route based on action
     if action_lower == "get":
         return await config_get()
+    elif action_lower == "set_project_from_url":
+        if value is None:
+            return {
+                "status": "error",
+                "error": "Parameter 'value' (project URL) is required for action='set_project_from_url'",
+                "hint": "Use config(action='set_project_from_url', value='https://linear.app/...')",
+            }
+        return await config_set_project_from_url(
+            project_url=str(value), test_connection=test_connection
+        )
     elif action_lower == "set":
         if key is None:
             return {
@@ -163,7 +229,15 @@ async def config(
                 "error": "Parameter 'value' is required for action='set'",
                 "hint": "Use config(action='set', key='adapter', value='linear')",
             }
-        return await config_set(key=key, value=value, **kwargs)
+
+        # Build extra params dict from non-None values
+        extra_params = {}
+        if project_key is not None:
+            extra_params["project_key"] = project_key
+        if user_email is not None:
+            extra_params["user_email"] = user_email
+
+        return await config_set(key=key, value=value, **extra_params)
     elif action_lower == "validate":
         return await config_validate()
     elif action_lower == "test":
@@ -207,6 +281,7 @@ async def config(
         valid_actions = [
             "get",
             "set",
+            "set_project_from_url",
             "validate",
             "test",
             "list_adapters",
@@ -359,9 +434,8 @@ async def config_set_primary_adapter(adapter: str) -> dict[str, Any]:
                 "valid_adapters": valid_adapters,
             }
 
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Store previous adapter for response
         previous_adapter = config.default_adapter
@@ -370,6 +444,7 @@ async def config_set_primary_adapter(adapter: str) -> dict[str, Any]:
         config.default_adapter = adapter.lower()
 
         # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -407,9 +482,8 @@ async def config_set_default_project(
         stacklevel=2,
     )
     try:
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Store previous project for response
         previous_project = config.default_project or config.default_epic
@@ -419,6 +493,7 @@ async def config_set_default_project(
         config.default_epic = project_id if project_id else None
 
         # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -459,9 +534,8 @@ async def config_set_default_user(
         stacklevel=2,
     )
     try:
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Store previous user for response
         previous_user = config.default_user
@@ -470,6 +544,7 @@ async def config_set_default_user(
         config.default_user = user_id if user_id else None
 
         # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -576,12 +651,14 @@ async def config_set_default_tags(
                     "error": f"Tag '{tag}' is too long (max 50 characters)",
                 }
 
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Update config
         config.default_tags = [tag.strip() for tag in tags]
+
+        # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -624,15 +701,17 @@ async def config_set_default_team(
                 "error": "Team ID must be at least 1 character",
             }
 
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Store previous team for response
         previous_team = config.default_team
 
         # Update default team
         config.default_team = team_id.strip()
+
+        # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -676,15 +755,17 @@ async def config_set_default_cycle(
                 "error": "Cycle ID must be at least 1 character",
             }
 
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Store previous cycle for response
         previous_cycle = config.default_cycle
 
         # Update default cycle
         config.default_cycle = cycle_id.strip()
+
+        # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -727,13 +808,15 @@ async def config_set_default_epic(
                 "error": "Epic/project ID must be at least 2 characters",
             }
 
-        # Load current configuration
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         # Update config (set both for compatibility)
         config.default_epic = epic_id.strip()
         config.default_project = epic_id.strip()
+
+        # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         return {
@@ -776,10 +859,13 @@ async def config_set_assignment_labels(labels: list[str]) -> dict[str, Any]:
                     "error": f"Invalid label '{label}': must be 2-50 characters",
                 }
 
-        resolver = get_resolver()
-        config = resolver.load_project_config() or TicketerConfig()
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
 
         config.assignment_labels = labels if labels else None
+
+        # Save configuration
+        resolver = get_resolver()
         resolver.save_project_config(config)
 
         config_path = Path.cwd() / ".mcp-ticketer" / "config.json"
@@ -1292,10 +1378,11 @@ async def config_setup_wizard(
         test_error = None
 
         if test_connection:
-            # Save config temporarily for testing
-            resolver = get_resolver()
-            config = resolver.load_project_config() or TicketerConfig()
+            # Save config temporarily for testing (preserves adapters)
+            config = _safe_load_config()
             config.adapters[adapter_lower] = adapter_config
+
+            resolver = get_resolver()
             resolver.save_project_config(config)
 
             # Test the adapter with enhanced error handling (1M-431)
@@ -1361,18 +1448,20 @@ async def config_setup_wizard(
                     ],
                 }
         else:
-            # Save config without testing
-            resolver = get_resolver()
-            config = resolver.load_project_config() or TicketerConfig()
+            # Save config without testing (preserves adapters)
+            config = _safe_load_config()
             config.adapters[adapter_lower] = adapter_config
+
+            resolver = get_resolver()
             resolver.save_project_config(config)
 
         # Step 8: Set as default if enabled
         if set_as_default:
-            # Update default adapter
-            resolver = get_resolver()
-            config = resolver.load_project_config() or TicketerConfig()
+            # Update default adapter (preserves adapters)
+            config = _safe_load_config()
             config.default_adapter = adapter_lower
+
+            resolver = get_resolver()
             resolver.save_project_config(config)
 
         # Step 9: Return success
@@ -1398,6 +1487,115 @@ async def config_setup_wizard(
         }
 
 
+async def config_set_project_from_url(
+    project_url: str,
+    test_connection: bool = True,
+) -> dict[str, Any]:
+    """Set default project from URL with comprehensive validation.
+
+    This function provides enhanced project URL handling:
+    1. Parses project URL to detect platform
+    2. Validates adapter configuration and credentials
+    3. Optionally tests project accessibility
+    4. Sets as default project if all validations pass
+
+    Args:
+        project_url: Project URL from any supported platform
+        test_connection: Test project accessibility (default: True)
+
+    Returns:
+        ConfigResponse with status, platform, project_id, validation details
+
+    Examples:
+        # Set Linear project with validation
+        config_set_project_from_url("https://linear.app/team/project/abc-123")
+
+        # Set GitHub project without connectivity test
+        config_set_project_from_url("https://github.com/owner/repo/projects/1", test_connection=False)
+
+    Error Scenarios:
+        - Invalid URL format: Returns parsing error with format examples
+        - Adapter not configured: Returns setup instructions for platform
+        - Invalid credentials: Returns credential validation errors
+        - Project not accessible: Returns accessibility error with troubleshooting
+
+    """
+    try:
+        # Import project validator
+        from ....core.project_validator import ProjectValidator
+
+        # Create validator
+        validator = ProjectValidator(project_path=Path.cwd())
+
+        # Validate project URL
+        result = validator.validate_project_url(
+            url=project_url, test_connection=test_connection
+        )
+
+        # Check validation result
+        if not result.valid:
+            return {
+                "status": "error",
+                "error": result.error,
+                "error_type": result.error_type,
+                "platform": result.platform,
+                "project_id": result.project_id,
+                "adapter_configured": result.adapter_configured,
+                "adapter_valid": result.adapter_valid,
+                "suggestions": result.suggestions,
+                "credential_errors": result.credential_errors,
+                "adapter_config": result.adapter_config,
+            }
+
+        # Validation passed - set as default project
+        project_id = result.project_id
+        platform = result.platform
+
+        # Load current configuration safely (preserves adapters)
+        config = _safe_load_config()
+
+        # 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
+        config.default_epic = project_id
+
+        # Also update default adapter to match the project's platform
+        previous_adapter = config.default_adapter
+        config.default_adapter = platform
+
+        # Save configuration
+        resolver = get_resolver()
+        resolver.save_project_config(config)
+
+        return {
+            "status": "completed",
+            "message": f"Default project set to '{project_id}' from {platform.title()}",
+            "platform": platform,
+            "project_id": project_id,
+            "project_url": project_url,
+            "previous_project": previous_project,
+            "new_project": project_id,
+            "adapter_changed": previous_adapter != platform,
+            "previous_adapter": previous_adapter,
+            "new_adapter": platform,
+            "validated": True,
+            "connection_tested": test_connection,
+            "config_path": str(resolver.project_path / resolver.PROJECT_CONFIG_SUBPATH),
+        }
+
+    except Exception as e:
+        import traceback
+
+        logger.error(f"Failed to set project from URL: {e}", exc_info=True)
+        return {
+            "status": "error",
+            "error": f"Failed to set project from URL: {str(e)}",
+            "traceback": traceback.format_exc(),
+        }
+
+
 def _mask_sensitive_values(config: dict[str, Any]) -> dict[str, Any]:
     """Mask sensitive values in configuration dictionary.