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

py_mcp_installer/src/py_mcp_installer/platform_detector.py

@@ -0,0 +1,451 @@
+"""Platform detection logic for all supported AI coding tools.
+
+This module implements comprehensive platform detection with confidence scoring
+and multi-layered validation.
+
+Detection Strategy:
+1. Check for config file existence (+0.4 confidence)
+2. Validate config format (JSON/TOML parsing) (+0.3 confidence)
+3. Check CLI availability (+0.2 confidence)
+4. Check environment variables (+0.1 confidence)
+
+Supported Platforms:
+- Claude Code (claude_code)
+- Claude Desktop (claude_desktop)
+- Cursor (cursor)
+- Auggie (auggie)
+- Codex (codex)
+- Gemini CLI (gemini_cli)
+- Windsurf (windsurf)
+- Antigravity (antigravity) - TBD
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from .exceptions import PlatformDetectionError
+from .types import Platform, PlatformInfo, Scope
+from .utils import parse_json_safe, parse_toml_safe, resolve_command_path
+
+
+class PlatformDetector:
+    """Detect which AI coding tool platform is currently running.
+
+    This class provides methods to detect all supported platforms with
+    confidence scoring, allowing intelligent selection in multi-platform
+    environments.
+
+    Example:
+        >>> detector = PlatformDetector()
+        >>> info = detector.detect()
+        >>> print(f"{info.platform}: {info.confidence}")
+        Platform.CLAUDE_CODE: 1.0
+    """
+
+    def __init__(self) -> None:
+        """Initialize platform detector."""
+        pass
+
+    def detect(self) -> PlatformInfo:
+        """Auto-detect current platform with highest confidence.
+
+        Runs all platform-specific detectors and returns the one with
+        highest confidence score.
+
+        Returns:
+            PlatformInfo for detected platform
+
+        Raises:
+            PlatformDetectionError: If no platforms detected
+
+        Example:
+            >>> detector = PlatformDetector()
+            >>> info = detector.detect()
+            >>> if info.confidence > 0.8:
+            ...     print(f"Detected {info.platform} with high confidence")
+        """
+        # Run all detectors
+        detectors = [
+            self.detect_claude_code,
+            self.detect_claude_desktop,
+            self.detect_cursor,
+            self.detect_auggie,
+            self.detect_codex,
+            self.detect_gemini_cli,
+            self.detect_windsurf,
+            self.detect_antigravity,
+        ]
+
+        results: list[tuple[float, Path | None]] = []
+        for detector_func in detectors:
+            confidence, config_path = detector_func()
+            results.append((confidence, config_path))
+
+        # Find platform with highest confidence
+        max_confidence = max(r[0] for r in results)
+
+        if max_confidence == 0.0:
+            raise PlatformDetectionError("No supported platforms detected")
+
+        # Map results back to platforms
+        platform_results = list(
+            zip(
+                [
+                    Platform.CLAUDE_CODE,
+                    Platform.CLAUDE_DESKTOP,
+                    Platform.CURSOR,
+                    Platform.AUGGIE,
+                    Platform.CODEX,
+                    Platform.GEMINI_CLI,
+                    Platform.WINDSURF,
+                    Platform.ANTIGRAVITY,
+                ],
+                results,
+            )
+        )
+
+        # Get platform with max confidence
+        for platform, (confidence, config_path) in platform_results:
+            if confidence == max_confidence:
+                # Determine CLI availability
+                cli_available = False
+                if platform in (Platform.CLAUDE_CODE, Platform.CLAUDE_DESKTOP):
+                    cli_available = resolve_command_path("claude") is not None
+                elif platform == Platform.CURSOR:
+                    cli_available = resolve_command_path("cursor") is not None
+
+                return PlatformInfo(
+                    platform=platform,
+                    confidence=confidence,
+                    config_path=config_path,
+                    cli_available=cli_available,
+                    scope_support=Scope.BOTH,
+                )
+
+        # Should never reach here, but fallback to unknown
+        return PlatformInfo(
+            platform=Platform.UNKNOWN,
+            confidence=0.0,
+            config_path=None,
+            cli_available=False,
+            scope_support=Scope.BOTH,
+        )
+
+    # ========================================================================
+    # Platform-Specific Detectors
+    # ========================================================================
+
+    def detect_claude_code(self) -> tuple[float, Path | None]:
+        """Detect Claude Code installation.
+
+        Config locations (in priority order):
+        1. ~/.config/claude/mcp.json (new location)
+        2. .claude.json (legacy project-level)
+        3. ~/.claude.json (legacy global)
+
+        Returns:
+            Tuple of (confidence, config_path)
+            - confidence: 0.0-1.0
+            - config_path: Path if found, None otherwise
+
+        Example:
+            >>> detector = PlatformDetector()
+            >>> confidence, path = detector.detect_claude_code()
+            >>> if confidence > 0.5:
+            ...     print(f"Found Claude Code config at {path}")
+        """
+        confidence = 0.0
+        config_path: Path | None = None
+
+        # Priority 1: New location (~/.config/claude/mcp.json)
+        new_config = Path.home() / ".config" / "claude" / "mcp.json"
+        if new_config.exists():
+            config_path = new_config
+            confidence += 0.4
+
+            # Validate JSON
+            try:
+                parse_json_safe(new_config)
+                confidence += 0.3
+            except Exception:
+                pass  # Invalid JSON reduces confidence
+
+        # Priority 2: Legacy project location (.claude.json)
+        elif Path(".claude.json").exists():
+            config_path = Path(".claude.json")
+            confidence += 0.4
+
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Priority 3: Legacy global location (~/.claude.json)
+        elif (Path.home() / ".claude.json").exists():
+            config_path = Path.home() / ".claude.json"
+            confidence += 0.4
+
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check CLI availability
+        if resolve_command_path("claude") is not None:
+            confidence += 0.2
+
+        # Check environment variables
+        if os.getenv("CLAUDE_CODE_ENV"):
+            confidence += 0.1
+
+        return (min(confidence, 1.0), config_path)
+
+    def detect_claude_desktop(self) -> tuple[float, Path | None]:
+        """Detect Claude Desktop installation.
+
+        Config locations (platform-specific):
+        - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+        - Linux: ~/.config/Claude/claude_desktop_config.json
+        - Windows: %APPDATA%/Claude/claude_desktop_config.json
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path: Path | None = None
+
+        # Determine platform-specific config path
+        if sys.platform == "darwin":
+            # macOS
+            config_path = (
+                Path.home()
+                / "Library"
+                / "Application Support"
+                / "Claude"
+                / "claude_desktop_config.json"
+            )
+        elif sys.platform == "win32":
+            # Windows
+            appdata = os.environ.get("APPDATA", "")
+            if appdata:
+                config_path = Path(appdata) / "Claude" / "claude_desktop_config.json"
+        else:
+            # Linux
+            config_path = (
+                Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+            )
+
+        # Check if config exists
+        if config_path and config_path.exists():
+            confidence += 0.4
+
+            # Validate JSON
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check CLI availability (Claude Desktop uses same CLI as Claude Code)
+        if resolve_command_path("claude") is not None:
+            confidence += 0.2
+
+        # Check for Claude Desktop process
+        if sys.platform == "darwin":
+            # Check if Claude.app exists
+            claude_app = Path("/Applications/Claude.app")
+            if claude_app.exists():
+                confidence += 0.1
+
+        return (min(confidence, 1.0), config_path)
+
+    def detect_cursor(self) -> tuple[float, Path | None]:
+        """Detect Cursor installation.
+
+        Config location: ~/.cursor/mcp.json
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path = Path.home() / ".cursor" / "mcp.json"
+
+        # Check if config exists
+        if config_path.exists():
+            confidence += 0.4
+
+            # Validate JSON
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check CLI availability
+        if resolve_command_path("cursor") is not None:
+            confidence += 0.2
+
+        # Check for Cursor directory
+        if (Path.home() / ".cursor").exists():
+            confidence += 0.1
+
+        return (min(confidence, 1.0), config_path if config_path.exists() else None)
+
+    def detect_auggie(self) -> tuple[float, Path | None]:
+        """Detect Auggie installation.
+
+        Config location: ~/.augment/settings.json
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path = Path.home() / ".augment" / "settings.json"
+
+        # Check if config exists
+        if config_path.exists():
+            confidence += 0.4
+
+            # Validate JSON
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check for Auggie directory
+        if (Path.home() / ".augment").exists():
+            confidence += 0.2
+
+        # Check environment
+        if os.getenv("AUGGIE_HOME"):
+            confidence += 0.1
+
+        return (min(confidence, 1.0), config_path if config_path.exists() else None)
+
+    def detect_codex(self) -> tuple[float, Path | None]:
+        """Detect Codex installation.
+
+        Config location: ~/.codex/config.toml
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path = Path.home() / ".codex" / "config.toml"
+
+        # Check if config exists
+        if config_path.exists():
+            confidence += 0.4
+
+            # Validate TOML
+            try:
+                parse_toml_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check for Codex directory
+        if (Path.home() / ".codex").exists():
+            confidence += 0.2
+
+        # Check CLI
+        if resolve_command_path("codex") is not None:
+            confidence += 0.1
+
+        return (min(confidence, 1.0), config_path if config_path.exists() else None)
+
+    def detect_gemini_cli(self) -> tuple[float, Path | None]:
+        """Detect Gemini CLI installation.
+
+        Config locations (in priority order):
+        1. .gemini/settings.json (project-level)
+        2. ~/.gemini/settings.json (user-level)
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path: Path | None = None
+
+        # Priority 1: Project-level config
+        project_config = Path(".gemini") / "settings.json"
+        if project_config.exists():
+            config_path = project_config
+            confidence += 0.4
+
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Priority 2: User-level config
+        elif (Path.home() / ".gemini" / "settings.json").exists():
+            config_path = Path.home() / ".gemini" / "settings.json"
+            confidence += 0.4
+
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check for Gemini directory
+        if (Path.home() / ".gemini").exists() or Path(".gemini").exists():
+            confidence += 0.2
+
+        # Check CLI
+        if resolve_command_path("gemini") is not None:
+            confidence += 0.1
+
+        return (min(confidence, 1.0), config_path)
+
+    def detect_windsurf(self) -> tuple[float, Path | None]:
+        """Detect Windsurf installation.
+
+        Config location: ~/.codeium/windsurf/mcp_config.json
+
+        Returns:
+            Tuple of (confidence, config_path)
+        """
+        confidence = 0.0
+        config_path = Path.home() / ".codeium" / "windsurf" / "mcp_config.json"
+
+        # Check if config exists
+        if config_path.exists():
+            confidence += 0.4
+
+            # Validate JSON
+            try:
+                parse_json_safe(config_path)
+                confidence += 0.3
+            except Exception:
+                pass
+
+        # Check for Windsurf directory
+        if (Path.home() / ".codeium" / "windsurf").exists():
+            confidence += 0.2
+
+        # Check for Windsurf app (macOS)
+        if sys.platform == "darwin":
+            windsurf_app = Path("/Applications/Windsurf.app")
+            if windsurf_app.exists():
+                confidence += 0.1
+
+        return (min(confidence, 1.0), config_path if config_path.exists() else None)
+
+    def detect_antigravity(self) -> tuple[float, Path | None]:
+        """Detect Antigravity installation.
+
+        Note: Config location not yet documented. This is a placeholder
+        implementation that always returns 0.0 confidence.
+
+        Returns:
+            Tuple of (confidence=0.0, config_path=None)
+        """
+        # TODO: Update when Antigravity config location is documented
+        return (0.0, None)

py_mcp_installer/src/py_mcp_installer/platforms/__init__.py

@@ -0,0 +1,26 @@
+"""Platform-specific implementations for MCP installation.
+
+This module provides platform-specific strategies and configurations
+for different AI coding tools.
+
+Supported platforms:
+- Claude Code (claude_code.py)
+- Cursor (cursor.py)
+- Codex (codex.py)
+
+Each platform module provides:
+- Configuration path detection
+- Installation strategy selection
+- Platform-specific validation
+- Command building utilities
+"""
+
+from .claude_code import ClaudeCodeStrategy
+from .codex import CodexStrategy
+from .cursor import CursorStrategy
+
+__all__ = [
+    "ClaudeCodeStrategy",
+    "CursorStrategy",
+    "CodexStrategy",
+]

py_mcp_installer/src/py_mcp_installer/platforms/claude_code.py

@@ -0,0 +1,225 @@
+"""Claude Code platform implementation.
+
+This module provides platform-specific logic for Claude Code, including
+configuration paths, installation strategies, and validation.
+
+Claude Code supports:
+- Project-level config: .claude.json or ~/.config/claude/mcp.json
+- Global config: ~/.config/claude/mcp.json
+- Native CLI: claude mcp add/remove
+- JSON manipulation fallback
+"""
+
+from pathlib import Path
+
+from ..command_builder import CommandBuilder
+from ..installation_strategy import (
+    InstallationStrategy,
+    JSONManipulationStrategy,
+    NativeCLIStrategy,
+)
+from ..types import InstallMethod, MCPServerConfig, Platform, Scope
+from ..utils import resolve_command_path
+
+
+class ClaudeCodeStrategy:
+    """Claude Code platform implementation.
+
+    Provides configuration paths and installation strategies for Claude Code.
+
+    Example:
+        >>> strategy = ClaudeCodeStrategy()
+        >>> config_path = strategy.get_config_path(Scope.PROJECT)
+        >>> installer = strategy.get_strategy(Scope.PROJECT)
+        >>> result = installer.install(server, Scope.PROJECT)
+    """
+
+    def __init__(self) -> None:
+        """Initialize Claude Code strategy."""
+        self.platform = Platform.CLAUDE_CODE
+        self.config_format = "json"
+
+    def get_config_path(self, scope: Scope) -> Path:
+        """Get configuration path for scope.
+
+        Priority order:
+        1. Project scope: .claude.json (legacy) or ~/.config/claude/mcp.json (new)
+        2. Global scope: ~/.config/claude/mcp.json
+
+        Args:
+            scope: Installation scope (PROJECT or GLOBAL)
+
+        Returns:
+            Path to configuration file
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> path = strategy.get_config_path(Scope.PROJECT)
+            >>> print(path)
+            /home/user/.config/claude/mcp.json
+        """
+        if scope == Scope.PROJECT:
+            # Check for new location first
+            new_config = Path.home() / ".config" / "claude" / "mcp.json"
+            if new_config.exists():
+                return new_config
+
+            # Fallback to legacy project-level config
+            legacy_project = Path(".claude.json")
+            if legacy_project.exists():
+                return legacy_project
+
+            # Default to new location if creating new config
+            return new_config
+
+        else:  # Scope.GLOBAL
+            # Global config always in new location
+            return Path.home() / ".config" / "claude" / "mcp.json"
+
+    def get_strategy(self, scope: Scope) -> InstallationStrategy:
+        """Get appropriate installation strategy for scope.
+
+        Prefers native CLI if available, falls back to JSON manipulation.
+
+        Args:
+            scope: Installation scope
+
+        Returns:
+            Installation strategy instance
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> installer = strategy.get_strategy(Scope.PROJECT)
+            >>> if installer.validate():
+            ...     result = installer.install(server, Scope.PROJECT)
+        """
+        # Prefer native CLI if available
+        if resolve_command_path("claude"):
+            return NativeCLIStrategy(self.platform, "claude")
+
+        # Fallback to JSON manipulation
+        config_path = self.get_config_path(scope)
+        return JSONManipulationStrategy(self.platform, config_path)
+
+    def get_strategy_with_fallback(
+        self, scope: Scope
+    ) -> tuple[InstallationStrategy, InstallationStrategy | None]:
+        """Get primary strategy and fallback strategy.
+
+        Returns both native CLI and JSON strategies for graceful fallback.
+
+        Args:
+            scope: Installation scope
+
+        Returns:
+            Tuple of (primary_strategy, fallback_strategy)
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> primary, fallback = strategy.get_strategy_with_fallback(Scope.PROJECT)
+            >>> try:
+            ...     result = primary.install(server, Scope.PROJECT)
+            ... except InstallationError:
+            ...     if fallback:
+            ...         result = fallback.install(server, Scope.PROJECT)
+        """
+        config_path = self.get_config_path(scope)
+
+        # Primary: Native CLI if available
+        primary: InstallationStrategy | None = None
+        if resolve_command_path("claude"):
+            primary = NativeCLIStrategy(self.platform, "claude")
+
+        # Fallback: Always JSON
+        fallback = JSONManipulationStrategy(self.platform, config_path)
+
+        # If no CLI, use JSON as primary
+        if primary is None:
+            return (fallback, None)
+
+        return (primary, fallback)
+
+    def validate_installation(self) -> bool:
+        """Validate Claude Code is available.
+
+        Checks for config file existence or CLI availability.
+
+        Returns:
+            True if Claude Code appears to be installed
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> if strategy.validate_installation():
+            ...     print("Claude Code is available")
+        """
+        # Check for any config file
+        global_config = Path.home() / ".config" / "claude" / "mcp.json"
+        legacy_config = Path.home() / ".claude.json"
+        project_config = Path(".claude.json")
+
+        has_config = (
+            global_config.exists() or legacy_config.exists() or project_config.exists()
+        )
+
+        # Check for CLI
+        has_cli = resolve_command_path("claude") is not None
+
+        return has_config or has_cli
+
+    def build_server_config(
+        self,
+        package: str,
+        install_method: InstallMethod | None = None,
+        env: dict[str, str] | None = None,
+        description: str = "",
+    ) -> MCPServerConfig:
+        """Build server configuration for Claude Code.
+
+        Uses CommandBuilder to auto-detect best installation method.
+
+        Args:
+            package: Package name (e.g., "mcp-ticketer")
+            install_method: Installation method (auto-detected if None)
+            env: Environment variables
+            description: Server description
+
+        Returns:
+            Complete server configuration
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> config = strategy.build_server_config(
+            ...     "mcp-ticketer",
+            ...     env={"LINEAR_API_KEY": "..."}
+            ... )
+            >>> print(f"{config.command} {' '.join(config.args)}")
+            uv run mcp-ticketer mcp
+        """
+        builder = CommandBuilder(self.platform)
+        return builder.to_server_config(
+            package=package,
+            install_method=install_method,
+            env=env,
+            description=description,
+        )
+
+    def get_platform_info(self) -> dict[str, str]:
+        """Get platform information.
+
+        Returns:
+            Dict with platform details
+
+        Example:
+            >>> strategy = ClaudeCodeStrategy()
+            >>> info = strategy.get_platform_info()
+            >>> print(info["name"])
+            Claude Code
+        """
+        return {
+            "name": "Claude Code",
+            "platform": self.platform.value,
+            "config_format": "json",
+            "scope_support": "both",
+            "cli_available": str(resolve_command_path("claude") is not None),
+            "config_key": "mcpServers",
+        }