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

mcp_ticketer/mcp/server/diagnostic_helper.py

@@ -0,0 +1,175 @@
+"""Diagnostic helper for MCP error handling.
+
+Provides quick diagnostic checks and error classification to help users
+troubleshoot system configuration issues when MCP tools encounter errors.
+"""
+
+import logging
+from enum import Enum
+from typing import Any
+
+from ...core.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    StateTransitionError,
+    TimeoutError,
+    ValidationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorSeverity(Enum):
+    """Classification of error severity for diagnostic suggestions."""
+
+    CRITICAL = "critical"  # Always suggest diagnostics
+    MEDIUM = "medium"  # Suggest if pattern detected
+    LOW = "low"  # Never suggest diagnostics
+
+
+# Map exception types to severity levels
+ERROR_SEVERITY_MAP = {
+    AuthenticationError: ErrorSeverity.CRITICAL,
+    ConfigurationError: ErrorSeverity.CRITICAL,
+    NetworkError: ErrorSeverity.CRITICAL,
+    TimeoutError: ErrorSeverity.CRITICAL,
+    NotFoundError: ErrorSeverity.MEDIUM,
+    PermissionError: ErrorSeverity.MEDIUM,
+    RateLimitError: ErrorSeverity.MEDIUM,
+    ValidationError: ErrorSeverity.LOW,
+    StateTransitionError: ErrorSeverity.LOW,
+}
+
+
+def should_suggest_diagnostics(exception: Exception) -> bool:
+    """Determine if error response should include diagnostic suggestion.
+
+    Args:
+        exception: The exception that was raised
+
+    Returns:
+        True if diagnostics should be suggested
+
+    """
+    severity = get_error_severity(exception)
+    return severity in (ErrorSeverity.CRITICAL, ErrorSeverity.MEDIUM)
+
+
+def get_error_severity(exception: Exception) -> ErrorSeverity:
+    """Get severity level for an exception.
+
+    Args:
+        exception: The exception to classify
+
+    Returns:
+        Error severity level
+
+    """
+    exception_type = type(exception)
+    return ERROR_SEVERITY_MAP.get(exception_type, ErrorSeverity.MEDIUM)
+
+
+async def get_quick_diagnostic_info() -> dict[str, Any]:
+    """Get lightweight diagnostic info without running full test suite.
+
+    Performs fast checks (< 100ms) to provide immediate troubleshooting hints:
+    - Adapter configuration status
+    - Credential presence
+    - Queue system status
+
+    Returns:
+        Dictionary with quick diagnostic results
+
+    """
+    info: dict[str, Any] = {}
+
+    try:
+        # Check adapter configuration (fast file read)
+        from ...cli.utils import CommonPatterns
+
+        config = CommonPatterns.load_config()
+        adapters = config.get("adapters", {})
+
+        info["adapter_configured"] = len(adapters) > 0
+        info["configured_adapters"] = list(adapters.keys())
+        info["default_adapter"] = config.get("default_adapter")
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic config check failed: {e}")
+        info["adapter_configured"] = False
+        info["config_error"] = str(e)
+
+    try:
+        # Check queue system status (fast status check, no operations)
+        from ...queue.worker import Worker
+
+        worker = Worker()
+        info["queue_running"] = worker.running
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic queue check failed: {e}")
+        info["queue_running"] = False
+
+    try:
+        # Get version information
+        from ...__version__ import __version__
+
+        info["mcp_ticketer_version"] = __version__
+
+    except Exception as e:
+        logger.debug(f"Quick diagnostic version check failed: {e}")
+        info["mcp_ticketer_version"] = "unknown"
+
+    return info
+
+
+def build_diagnostic_suggestion(
+    exception: Exception, quick_info: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Build diagnostic suggestion dict for error response.
+
+    Args:
+        exception: The exception that occurred
+        quick_info: Optional quick diagnostic info (from get_quick_diagnostic_info())
+
+    Returns:
+        Diagnostic suggestion dictionary for inclusion in error response
+
+    """
+    severity = get_error_severity(exception)
+
+    suggestion: dict[str, Any] = {
+        "severity": severity.value,
+        "message": _get_severity_message(severity),
+        "recommendation": _get_recommendation(severity),
+        "command": "Use the 'system_diagnostics' MCP tool or CLI: mcp-ticketer doctor",
+    }
+
+    if quick_info:
+        suggestion["quick_checks"] = quick_info
+
+    return suggestion
+
+
+def _get_severity_message(severity: ErrorSeverity) -> str:
+    """Get human-readable message for severity level."""
+    messages = {
+        ErrorSeverity.CRITICAL: "This appears to be a system configuration issue",
+        ErrorSeverity.MEDIUM: "This may indicate a configuration or permission issue",
+        ErrorSeverity.LOW: "This is a validation or input error",
+    }
+    return messages.get(severity, "An error occurred")
+
+
+def _get_recommendation(severity: ErrorSeverity) -> str:
+    """Get recommendation text for severity level."""
+    recommendations = {
+        ErrorSeverity.CRITICAL: "Run system diagnostics to identify the problem",
+        ErrorSeverity.MEDIUM: "Consider running diagnostics if the issue persists",
+        ErrorSeverity.LOW: "Check your input and try again",
+    }
+    return recommendations.get(severity, "Review the error message")

mcp_ticketer/mcp/server/main.py

@@ -48,23 +48,6 @@ from .dto import (
 )
 from .response_builder import ResponseBuilder
 
-# Load environment variables early (prioritize .env.local)
-# Check for .env.local first (takes precedence)
-env_local_file = Path.cwd() / ".env.local"
-if env_local_file.exists():
-    load_dotenv(env_local_file, override=True)
-    sys.stderr.write(f"[MCP Server] Loaded environment from: {env_local_file}\n")
-else:
-    # Fall back to .env
-    env_file = Path.cwd() / ".env"
-    if env_file.exists():
-        load_dotenv(env_file, override=True)
-        sys.stderr.write(f"[MCP Server] Loaded environment from: {env_file}\n")
-    else:
-        # Try default dotenv loading (searches upward)
-        load_dotenv(override=True)
-        sys.stderr.write("[MCP Server] Loaded environment from default search path\n")
-
 
 class MCPTicketServer:
     """MCP server for ticket operations over stdio - synchronous implementation."""
@@ -75,6 +58,7 @@ class MCPTicketServer:
         """Initialize MCP server.
 
         Args:
+        ----
             adapter_type: Type of adapter to use
             config: Adapter configuration
 
@@ -88,9 +72,11 @@ class MCPTicketServer:
         """Handle JSON-RPC request.
 
         Args:
+        ----
             request: JSON-RPC request
 
         Returns:
+        -------
             JSON-RPC response
 
         """
@@ -175,11 +161,13 @@ class MCPTicketServer:
         """Create error response.
 
         Args:
+        ----
             request_id: Request ID
             code: Error code
             message: Error message
 
         Returns:
+        -------
             Error response
 
         """
@@ -195,7 +183,7 @@ class MCPTicketServer:
         request = CreateTicketRequest(**params)
 
         # Build task from validated DTO
-        task = Task(
+        task = Task(  # type: ignore[call-arg]
             title=request.title,
             description=request.description,
             priority=Priority(request.priority),
@@ -273,7 +261,7 @@ class MCPTicketServer:
 
     async def _handle_search(self, params: dict[str, Any]) -> dict[str, Any]:
         """Handle ticket search - SYNCHRONOUS."""
-        query = SearchQuery(
+        query = SearchQuery(  # type: ignore[call-arg]
             query=params.get("query"),
             state=TicketState(params["state"]) if params.get("state") else None,
             priority=Priority(params["priority"]) if params.get("priority") else None,
@@ -309,7 +297,7 @@ class MCPTicketServer:
         operation = params.get("operation", "add")
 
         if operation == "add":
-            comment = Comment(
+            comment = Comment(  # type: ignore[call-arg]
                 ticket_id=params["ticket_id"],
                 content=params["content"],
                 author=params.get("author"),
@@ -343,12 +331,17 @@ class MCPTicketServer:
         request = CreateEpicRequest(**params)
 
         # Build epic from validated DTO
-        epic = Epic(
+        metadata: dict[str, Any] = {}
+        if request.target_date:
+            metadata["target_date"] = request.target_date
+        if request.lead_id:
+            metadata["lead_id"] = request.lead_id
+
+        epic = Epic(  # type: ignore[call-arg]
             title=request.title,
             description=request.description,
             child_issues=request.child_issues,
-            target_date=request.target_date,
-            lead_id=request.lead_id,
+            metadata=metadata,
         )
 
         # Create directly
@@ -389,7 +382,7 @@ class MCPTicketServer:
         request = CreateIssueRequest(**params)
 
         # Build task (issue) from validated DTO
-        task = Task(
+        task = Task(  # type: ignore[call-arg]
             title=request.title,
             description=request.description,
             parent_epic=request.epic_id,  # Issues are tasks under epics
@@ -422,7 +415,7 @@ class MCPTicketServer:
         request = CreateTaskRequest(**params)
 
         # Build task from validated DTO
-        task = Task(
+        task = Task(  # type: ignore[call-arg]
             title=request.title,
             parent_issue=request.parent_id,
             description=request.description,
@@ -454,16 +447,19 @@ class MCPTicketServer:
                 )
 
             # Build tree structure
-            tree = {"epic": epic.model_dump(), "issues": []}
+            tree: dict[str, Any] = {"epic": epic.model_dump(), "issues": []}
 
             # Get issues in epic if depth allows (depth 1 = epic only, depth 2+ = issues)
             if max_depth > 1:
                 issues = await self.adapter.list_issues_by_epic(epic_id)
                 for issue in issues:
-                    issue_node = {"issue": issue.model_dump(), "tasks": []}
+                    issue_node: dict[str, Any] = {
+                        "issue": issue.model_dump(),
+                        "tasks": [],
+                    }
 
                     # Get tasks in issue if depth allows (depth 3+ = tasks)
-                    if max_depth > 2:
+                    if max_depth > 2 and issue.id:
                         tasks = await self.adapter.list_tasks_by_issue(issue.id)
                         issue_node["tasks"] = [task.model_dump() for task in tasks]
 
@@ -561,7 +557,7 @@ class MCPTicketServer:
         include_parents = params.get("include_parents", True)
 
         # Perform basic search
-        search_query = SearchQuery(
+        search_query = SearchQuery(  # type: ignore[call-arg]
             query=query,
             state=TicketState(params["state"]) if params.get("state") else None,
             priority=Priority(params["priority"]) if params.get("priority") else None,
@@ -666,6 +662,12 @@ class MCPTicketServer:
                         "error": str(e),
                         "ticket_id": ticket_id,
                     }
+            # Fallback if not GitHub adapter instance
+            return {
+                "success": False,
+                "error": "GitHub adapter not properly initialized",
+                "ticket_id": ticket_id,
+            }
         elif "linear" in adapter_name:
             # Linear adapter needs GitHub config for PR creation
             from ..adapters.linear import LinearAdapter
@@ -710,6 +712,12 @@ class MCPTicketServer:
                         "error": str(e),
                         "ticket_id": ticket_id,
                     }
+            # Fallback if not Linear adapter instance
+            return {
+                "success": False,
+                "error": "Linear adapter not properly initialized",
+                "ticket_id": ticket_id,
+            }
         else:
             return {
                 "success": False,
@@ -734,9 +742,11 @@ class MCPTicketServer:
 
             if isinstance(self.adapter, GitHubAdapter):
                 try:
-                    result = await self.adapter.link_existing_pull_request(
-                        ticket_id=ticket_id,
-                        pr_url=pr_url,
+                    result: dict[str, Any] = (
+                        await self.adapter.link_existing_pull_request(
+                            ticket_id=ticket_id,
+                            pr_url=pr_url,
+                        )
                     )
                     return result
                 except Exception as e:
@@ -746,16 +756,25 @@ class MCPTicketServer:
                         "ticket_id": ticket_id,
                         "pr_url": pr_url,
                     }
+            # Fallback if not GitHub adapter instance
+            return {
+                "success": False,
+                "error": "GitHub adapter not properly initialized",
+                "ticket_id": ticket_id,
+                "pr_url": pr_url,
+            }
         elif "linear" in adapter_name:
             from ..adapters.linear import LinearAdapter
 
             if isinstance(self.adapter, LinearAdapter):
                 try:
-                    result = await self.adapter.link_to_pull_request(
-                        ticket_id=ticket_id,
-                        pr_url=pr_url,
+                    link_result: dict[str, Any] = (
+                        await self.adapter.link_to_pull_request(
+                            ticket_id=ticket_id,
+                            pr_url=pr_url,
+                        )
                     )
-                    return result
+                    return link_result
                 except Exception as e:
                     return {
                         "success": False,
@@ -763,6 +782,13 @@ class MCPTicketServer:
                         "ticket_id": ticket_id,
                         "pr_url": pr_url,
                     }
+            # Fallback if not Linear adapter instance
+            return {
+                "success": False,
+                "error": "Linear adapter not properly initialized",
+                "ticket_id": ticket_id,
+                "pr_url": pr_url,
+            }
         else:
             return {
                 "success": False,
@@ -775,9 +801,11 @@ class MCPTicketServer:
         """Handle initialize request from MCP client.
 
         Args:
+        ----
             params: Initialize parameters
 
         Returns:
+        -------
             Server capabilities
 
         """
@@ -906,9 +934,11 @@ class MCPTicketServer:
         """Handle tool invocation from MCP client.
 
         Args:
+        ----
             params: Contains 'name' and 'arguments' fields
 
         Returns:
+        -------
             MCP formatted response with content array
 
         """
@@ -1050,8 +1080,8 @@ class MCPTicketServer:
         await self.adapter.close()
 
 
-async def main():
-    """Main entry point for MCP server - kept for backward compatibility.
+async def main() -> None:
+    """Run main entry point for MCP server - kept for backward compatibility.
 
     This function is maintained in case it's being called directly,
     but the preferred way is now through the CLI: `mcp-ticketer mcp`
@@ -1063,62 +1093,94 @@ async def main():
     # Load configuration
     import json
     import logging
-    from pathlib import Path
 
     logger = logging.getLogger(__name__)
 
+    # Load environment variables AFTER working directory has been set by __main__.py
+    # This ensures we load .env files from the target project directory, not from where the command is executed
+    env_local_file = Path.cwd() / ".env.local"
+    if env_local_file.exists():
+        load_dotenv(env_local_file, override=True)
+        sys.stderr.write(f"[MCP Server] Loaded environment from: {env_local_file}\n")
+        logger.debug(f"Loaded environment from: {env_local_file}")
+    else:
+        # Fall back to .env
+        env_file = Path.cwd() / ".env"
+        if env_file.exists():
+            load_dotenv(env_file, override=True)
+            sys.stderr.write(f"[MCP Server] Loaded environment from: {env_file}\n")
+            logger.debug(f"Loaded environment from: {env_file}")
+        else:
+            # Try default dotenv loading (searches upward)
+            load_dotenv(override=True)
+            sys.stderr.write(
+                "[MCP Server] Loaded environment from default search path\n"
+            )
+            logger.debug("Loaded environment from default search path")
+
     # Initialize defaults
     adapter_type = "aitrackdown"
     adapter_config = {"base_path": DEFAULT_BASE_PATH}
 
-    # Priority 1: Check .env files (highest priority for MCP)
-    env_config = _load_env_configuration()
-    if env_config and env_config.get("adapter_type"):
-        adapter_type = env_config["adapter_type"]
-        adapter_config = env_config["adapter_config"]
-        logger.info(f"Using adapter from .env files: {adapter_type}")
-        logger.info(f"Built adapter config from .env: {list(adapter_config.keys())}")
-    else:
-        # Priority 2: Check project-local config file
-        config_file = Path.cwd() / ".mcp-ticketer" / "config.json"
-        if config_file.exists():
-            # Validate config is within project
-            try:
-                if not config_file.resolve().is_relative_to(Path.cwd().resolve()):
-                    logger.error(
-                        f"Security violation: Config file {config_file} "
-                        "is not within project directory"
-                    )
-                    raise ValueError(
-                        f"Security violation: Config file {config_file} "
-                        "is not within project directory"
-                    )
-            except (ValueError, RuntimeError):
-                # is_relative_to may raise ValueError in some cases
-                pass
+    # Priority 1: Check project-local config file (highest priority)
+    config_file = Path.cwd() / ".mcp-ticketer" / "config.json"
+    config_loaded = False
 
-            try:
-                with open(config_file) as f:
-                    config = json.load(f)
-                    adapter_type = config.get("default_adapter", "aitrackdown")
-                    # Get adapter-specific config
-                    adapters_config = config.get("adapters", {})
-                    adapter_config = adapters_config.get(adapter_type, {})
-                    # Fallback to legacy config format
-                    if not adapter_config and "config" in config:
-                        adapter_config = config["config"]
-                    logger.info(
-                        f"Loaded MCP configuration from project-local: {config_file}"
-                    )
-            except (OSError, json.JSONDecodeError) as e:
-                logger.warning(f"Could not load project config: {e}, using defaults")
-                adapter_type = "aitrackdown"
-                adapter_config = {"base_path": DEFAULT_BASE_PATH}
-        else:
-            # Priority 3: Default to aitrackdown
-            logger.info("No configuration found, defaulting to aitrackdown adapter")
-            adapter_type = "aitrackdown"
-            adapter_config = {"base_path": DEFAULT_BASE_PATH}
+    if config_file.exists():
+        # Validate config is within project
+        try:
+            if not config_file.resolve().is_relative_to(Path.cwd().resolve()):
+                logger.error(
+                    f"Security violation: Config file {config_file} "
+                    "is not within project directory"
+                )
+                raise ValueError(
+                    f"Security violation: Config file {config_file} "
+                    "is not within project directory"
+                )
+        except (ValueError, RuntimeError):
+            # is_relative_to may raise ValueError in some cases
+            pass
+
+        try:
+            with open(config_file) as f:
+                config = json.load(f)
+                adapter_type = config.get("default_adapter", "aitrackdown")
+                # Get adapter-specific config
+                adapters_config = config.get("adapters", {})
+                adapter_config = adapters_config.get(adapter_type, {})
+                # Fallback to legacy config format
+                if not adapter_config and "config" in config:
+                    adapter_config = config["config"]
+                config_loaded = True
+                logger.info(
+                    f"Loaded MCP configuration from project-local: {config_file}"
+                )
+                sys.stderr.write(
+                    f"[MCP Server] Using adapter from config: {adapter_type}\n"
+                )
+        except (OSError, json.JSONDecodeError) as e:
+            logger.warning(f"Could not load project config: {e}, will try .env files")
+
+    # Priority 2: Check .env files (only if no config file found)
+    if not config_loaded:
+        env_config = _load_env_configuration()
+        if env_config and env_config.get("adapter_type"):
+            adapter_type = env_config["adapter_type"]
+            adapter_config = env_config["adapter_config"]
+            config_loaded = True
+            logger.info(f"Using adapter from .env files: {adapter_type}")
+            logger.info(
+                f"Built adapter config from .env: {list(adapter_config.keys())}"
+            )
+            sys.stderr.write(f"[MCP Server] Using adapter from .env: {adapter_type}\n")
+
+    # Priority 3: Default to aitrackdown
+    if not config_loaded:
+        logger.info("No configuration found, defaulting to aitrackdown adapter")
+        sys.stderr.write("[MCP Server] No config found, using default: aitrackdown\n")
+        adapter_type = "aitrackdown"
+        adapter_config = {"base_path": DEFAULT_BASE_PATH}
 
     # Log final configuration for debugging
     logger.info(f"Starting MCP server with adapter: {adapter_type}")
@@ -1130,20 +1192,48 @@ async def main():
 
 
 def _load_env_configuration() -> dict[str, Any] | None:
-    """Load adapter configuration from .env files.
+    """Load adapter configuration from environment variables and .env files.
 
-    Checks .env.local first (highest priority), then .env.
+    Priority order (highest to lowest):
+    1. os.environ (set by MCP clients like Claude Desktop)
+    2. .env.local file (local overrides)
+    3. .env file (default configuration)
 
     Returns:
+    -------
         Dictionary with 'adapter_type' and 'adapter_config' keys, or None if no config found
 
     """
-    from pathlib import Path
+    import os
 
-    # Check for .env files in order of preference
-    env_files = [".env.local", ".env"]
     env_vars = {}
 
+    # Priority 1: Check process environment variables (set by MCP client)
+    # This allows Claude Desktop and other MCP clients to configure the adapter
+    relevant_env_keys = [
+        "MCP_TICKETER_ADAPTER",
+        "LINEAR_API_KEY",
+        "LINEAR_TEAM_ID",
+        "LINEAR_TEAM_KEY",
+        "LINEAR_API_URL",
+        "JIRA_SERVER",
+        "JIRA_EMAIL",
+        "JIRA_API_TOKEN",
+        "JIRA_PROJECT_KEY",
+        "GITHUB_TOKEN",
+        "GITHUB_OWNER",
+        "GITHUB_REPO",
+        "MCP_TICKETER_BASE_PATH",
+    ]
+
+    for key in relevant_env_keys:
+        if os.environ.get(key):
+            env_vars[key] = os.environ[key]
+
+    # Priority 2: Check .env files (only for keys not already set)
+    # This allows .env files to provide fallback values
+    env_files = [".env.local", ".env"]
+
     for env_file in env_files:
         env_path = Path.cwd() / env_file
         if env_path.exists():
@@ -1156,7 +1246,9 @@ def _load_env_configuration() -> dict[str, Any] | None:
                             key, value = line.split("=", 1)
                             key = key.strip()
                             value = value.strip().strip('"').strip("'")
-                            if value:  # Only add non-empty values
+
+                            # Only set if not already in env_vars (os.environ takes priority)
+                            if key not in env_vars and value:
                                 env_vars[key] = value
             except Exception:
                 continue
@@ -1192,14 +1284,16 @@ def _build_adapter_config_from_env_vars(
     """Build adapter configuration from parsed environment variables.
 
     Args:
+    ----
         adapter_type: Type of adapter to configure
         env_vars: Dictionary of environment variables from .env files
 
     Returns:
+    -------
         Dictionary of adapter configuration
 
     """
-    config = {}
+    config: dict[str, Any] = {}
 
     if adapter_type == "linear":
         # Linear adapter configuration