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

py_mcp_installer/src/py_mcp_installer/platforms/codex.py

@@ -0,0 +1,181 @@
+"""Codex platform implementation.
+
+This module provides platform-specific logic for Codex, including
+configuration paths, installation strategies, and validation.
+
+Codex supports:
+- Global config only: ~/.codex/config.toml
+- TOML format (not JSON)
+- TOML manipulation strategy
+"""
+
+from pathlib import Path
+
+from ..command_builder import CommandBuilder
+from ..installation_strategy import (
+    InstallationStrategy,
+    TOMLManipulationStrategy,
+)
+from ..types import InstallMethod, MCPServerConfig, Platform, Scope
+from ..utils import resolve_command_path
+
+
+class CodexStrategy:
+    """Codex platform implementation.
+
+    Provides configuration paths and installation strategies for Codex.
+
+    Note: Codex uses TOML format instead of JSON, and only supports
+    global-level configuration.
+
+    Example:
+        >>> strategy = CodexStrategy()
+        >>> config_path = strategy.get_config_path(Scope.GLOBAL)
+        >>> installer = strategy.get_strategy(Scope.GLOBAL)
+        >>> result = installer.install(server, Scope.GLOBAL)
+    """
+
+    def __init__(self) -> None:
+        """Initialize Codex strategy."""
+        self.platform = Platform.CODEX
+        self.config_format = "toml"
+
+    def get_config_path(self, scope: Scope) -> Path:
+        """Get configuration path for scope.
+
+        Codex only supports global configuration.
+
+        Args:
+            scope: Installation scope (only GLOBAL supported)
+
+        Returns:
+            Path to TOML configuration file
+
+        Example:
+            >>> strategy = CodexStrategy()
+            >>> path = strategy.get_config_path(Scope.GLOBAL)
+            >>> print(path)
+            /home/user/.codex/config.toml
+        """
+        # Codex only has global config
+        return Path.home() / ".codex" / "config.toml"
+
+    def get_strategy(self, scope: Scope) -> InstallationStrategy:
+        """Get appropriate installation strategy for scope.
+
+        Codex only supports TOML manipulation.
+
+        Args:
+            scope: Installation scope
+
+        Returns:
+            TOML manipulation strategy
+
+        Example:
+            >>> strategy = CodexStrategy()
+            >>> installer = strategy.get_strategy(Scope.GLOBAL)
+            >>> result = installer.install(server, Scope.GLOBAL)
+        """
+        config_path = self.get_config_path(scope)
+        return TOMLManipulationStrategy(self.platform, config_path)
+
+    def validate_installation(self) -> bool:
+        """Validate Codex is available.
+
+        Checks for config directory or codex CLI.
+
+        Returns:
+            True if Codex appears to be installed
+
+        Example:
+            >>> strategy = CodexStrategy()
+            >>> if strategy.validate_installation():
+            ...     print("Codex is available")
+        """
+        # Check for config directory
+        codex_dir = Path.home() / ".codex"
+        has_config_dir = codex_dir.exists() and codex_dir.is_dir()
+
+        # Check for codex CLI
+        has_cli = resolve_command_path("codex") is not None
+
+        return has_config_dir 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 Codex.
+
+        Uses CommandBuilder to auto-detect best installation method.
+
+        Note: Codex uses TOML format with snake_case keys.
+
+        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 = CodexStrategy()
+            >>> 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 = CodexStrategy()
+            >>> info = strategy.get_platform_info()
+            >>> print(info["name"])
+            Codex
+        """
+        return {
+            "name": "Codex",
+            "platform": self.platform.value,
+            "config_format": "toml",
+            "scope_support": "global_only",
+            "cli_available": str(resolve_command_path("codex") is not None),
+            "config_key": "mcp_servers",  # TOML uses snake_case
+        }
+
+    def get_toml_specific_notes(self) -> dict[str, str]:
+        """Get TOML-specific configuration notes.
+
+        Returns:
+            Dict with TOML-specific guidance
+
+        Example:
+            >>> strategy = CodexStrategy()
+            >>> notes = strategy.get_toml_specific_notes()
+            >>> print(notes["key_format"])
+            snake_case
+        """
+        return {
+            "key_format": "snake_case",
+            "section_name": "mcp_servers",
+            "env_handling": "May require special quoting for environment variables",
+            "config_location": str(Path.home() / ".codex" / "config.toml"),
+        }

py_mcp_installer/src/py_mcp_installer/platforms/cursor.py

@@ -0,0 +1,191 @@
+"""Cursor platform implementation.
+
+This module provides platform-specific logic for Cursor, including
+configuration paths, installation strategies, and validation.
+
+Cursor supports:
+- Project-level config: .cursor/mcp.json
+- Global config: ~/.cursor/mcp.json
+- JSON manipulation only (no native CLI for MCP)
+"""
+
+from pathlib import Path
+
+from ..command_builder import CommandBuilder
+from ..installation_strategy import (
+    InstallationStrategy,
+    JSONManipulationStrategy,
+)
+from ..types import InstallMethod, MCPServerConfig, Platform, Scope
+from ..utils import resolve_command_path
+
+
+class CursorStrategy:
+    """Cursor platform implementation.
+
+    Provides configuration paths and installation strategies for Cursor.
+
+    Note: Cursor does not have a native CLI for MCP configuration,
+    so only JSON manipulation strategy is available.
+
+    Example:
+        >>> strategy = CursorStrategy()
+        >>> 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 Cursor strategy."""
+        self.platform = Platform.CURSOR
+        self.config_format = "json"
+
+    def get_config_path(self, scope: Scope) -> Path:
+        """Get configuration path for scope.
+
+        Cursor config locations:
+        - Project: .cursor/mcp.json (if exists)
+        - Global: ~/.cursor/mcp.json
+
+        Args:
+            scope: Installation scope (PROJECT or GLOBAL)
+
+        Returns:
+            Path to configuration file
+
+        Example:
+            >>> strategy = CursorStrategy()
+            >>> path = strategy.get_config_path(Scope.GLOBAL)
+            >>> print(path)
+            /home/user/.cursor/mcp.json
+        """
+        if scope == Scope.PROJECT:
+            # Check for project-level config
+            project_config = Path(".cursor") / "mcp.json"
+            if project_config.exists():
+                return project_config
+
+            # Default to global if project config doesn't exist
+            return Path.home() / ".cursor" / "mcp.json"
+
+        else:  # Scope.GLOBAL
+            return Path.home() / ".cursor" / "mcp.json"
+
+    def get_strategy(self, scope: Scope) -> InstallationStrategy:
+        """Get appropriate installation strategy for scope.
+
+        Cursor only supports JSON manipulation (no native CLI).
+
+        Args:
+            scope: Installation scope
+
+        Returns:
+            JSON manipulation strategy
+
+        Example:
+            >>> strategy = CursorStrategy()
+            >>> installer = strategy.get_strategy(Scope.GLOBAL)
+            >>> result = installer.install(server, Scope.GLOBAL)
+        """
+        config_path = self.get_config_path(scope)
+        return JSONManipulationStrategy(self.platform, config_path)
+
+    def validate_installation(self) -> bool:
+        """Validate Cursor is available.
+
+        Checks for config directory or cursor CLI.
+
+        Returns:
+            True if Cursor appears to be installed
+
+        Example:
+            >>> strategy = CursorStrategy()
+            >>> if strategy.validate_installation():
+            ...     print("Cursor is available")
+        """
+        # Check for config directory
+        cursor_dir = Path.home() / ".cursor"
+        has_config_dir = cursor_dir.exists() and cursor_dir.is_dir()
+
+        # Check for cursor CLI
+        has_cli = resolve_command_path("cursor") is not None
+
+        return has_config_dir 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 Cursor.
+
+        Uses CommandBuilder to auto-detect best installation method.
+
+        Note: Cursor may require absolute paths for better reliability.
+
+        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 = CursorStrategy()
+            >>> 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 = CursorStrategy()
+            >>> info = strategy.get_platform_info()
+            >>> print(info["name"])
+            Cursor
+        """
+        return {
+            "name": "Cursor",
+            "platform": self.platform.value,
+            "config_format": "json",
+            "scope_support": "both",
+            "cli_available": "false",  # No MCP CLI support
+            "config_key": "mcp_servers",  # Cursor uses snake_case
+        }
+
+    def get_recommended_config(self) -> dict[str, str]:
+        """Get Cursor-specific configuration recommendations.
+
+        Returns:
+            Dict with recommended settings
+
+        Example:
+            >>> strategy = CursorStrategy()
+            >>> recs = strategy.get_recommended_config()
+            >>> print(recs["path_style"])
+            absolute
+        """
+        return {
+            "path_style": "absolute",  # Cursor prefers absolute paths
+            "restart_required": "yes",  # Must restart Cursor after config changes
+            "config_location": str(Path.home() / ".cursor" / "mcp.json"),
+        }

py_mcp_installer/src/py_mcp_installer/types.py

@@ -0,0 +1,222 @@
+"""Type definitions for py-mcp-installer-service.
+
+This module provides comprehensive type definitions for the entire library,
+including enums, dataclasses, and protocols for platform detection and
+installation strategies.
+
+Design Philosophy:
+- Use Python 3.10+ syntax (list[str], dict[str, Any], Path | None)
+- 100% type coverage for mypy --strict
+- Immutable dataclasses where possible (frozen=True)
+- Clear separation between public API and internal types
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+# ============================================================================
+# Core Enums
+# ============================================================================
+
+
+class Platform(str, Enum):
+    """Supported AI coding tool platforms.
+
+    Each platform has its own configuration format and installation method.
+    """
+
+    CLAUDE_CODE = "claude_code"
+    CLAUDE_DESKTOP = "claude_desktop"
+    CURSOR = "cursor"
+    AUGGIE = "auggie"
+    CODEX = "codex"
+    GEMINI_CLI = "gemini_cli"
+    WINDSURF = "windsurf"
+    ANTIGRAVITY = "antigravity"
+    UNKNOWN = "unknown"
+
+
+class InstallMethod(str, Enum):
+    """Installation methods for MCP servers.
+
+    Priority order (fastest to slowest):
+    1. UV_RUN: uv run mcp-ticketer mcp (recommended, fastest)
+    2. PIPX: mcp-ticketer (installed via pipx)
+    3. DIRECT: Direct binary in PATH
+    4. PYTHON_MODULE: python -m mcp_ticketer.mcp.server (fallback)
+    """
+
+    UV_RUN = "uv_run"
+    PIPX = "pipx"
+    DIRECT = "direct"
+    PYTHON_MODULE = "python_module"
+
+
+class Scope(str, Enum):
+    """Configuration scope for MCP server installation.
+
+    - PROJECT: Project-level configuration (.claude.json, .cursor/mcp.json)
+    - GLOBAL: User-level configuration (~/.config/claude/mcp.json)
+    - BOTH: Platform supports both scopes
+    """
+
+    PROJECT = "project"
+    GLOBAL = "global"
+    BOTH = "both"
+
+
+class ConfigFormat(str, Enum):
+    """Configuration file formats supported by platforms.
+
+    - JSON: Most platforms (Claude, Cursor, Auggie, Windsurf, Gemini)
+    - TOML: Codex uses TOML format
+    """
+
+    JSON = "json"
+    TOML = "toml"
+
+
+class InstallationStrategy(str, Enum):
+    """Installation strategies for different platforms.
+
+    - NATIVE_CLI: Use platform's native CLI (claude mcp add)
+    - JSON_MANIPULATION: Direct JSON config file modification
+    - TOML_MANIPULATION: Direct TOML config file modification
+    """
+
+    NATIVE_CLI = "native_cli"
+    JSON_MANIPULATION = "json_manipulation"
+    TOML_MANIPULATION = "toml_manipulation"
+
+
+# ============================================================================
+# Dataclasses
+# ============================================================================
+
+
+@dataclass(frozen=True)
+class MCPServerConfig:
+    """MCP server configuration for installation.
+
+    This represents the complete configuration needed to install an MCP server
+    on any supported platform.
+
+    Attributes:
+        name: Unique server identifier (e.g., "mcp-ticketer")
+        command: Executable command (e.g., "uv", "/usr/bin/mcp-ticketer")
+        args: Command arguments (e.g., ["run", "mcp-ticketer", "mcp"])
+        env: Environment variables (e.g., {"LINEAR_API_KEY": "..."})
+        description: Human-readable server description
+
+    Example:
+        >>> config = MCPServerConfig(
+        ...     name="mcp-ticketer",
+        ...     command="uv",
+        ...     args=["run", "mcp-ticketer", "mcp"],
+        ...     env={"LINEAR_API_KEY": "lin_api_..."}
+        ... )
+    """
+
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class PlatformInfo:
+    """Information about a detected platform.
+
+    Contains all information needed to work with a detected AI coding tool
+    platform, including confidence scoring for multi-platform environments.
+
+    Attributes:
+        platform: Detected platform enum
+        confidence: Detection confidence (0.0-1.0)
+            - 1.0: Config exists, valid, CLI available
+            - 0.8: Config exists, valid, no CLI needed
+            - 0.6: Config exists but invalid, CLI available
+            - 0.4: Config exists but invalid, no CLI
+            - 0.0: Platform not detected
+        config_path: Path to platform's config file (None if not found)
+        cli_available: Whether platform CLI is available in PATH
+        scope_support: Which configuration scopes the platform supports
+
+    Example:
+        >>> info = PlatformInfo(
+        ...     platform=Platform.CLAUDE_CODE,
+        ...     confidence=1.0,
+        ...     config_path=Path.home() / ".config/claude/mcp.json",
+        ...     cli_available=True,
+        ...     scope_support=Scope.BOTH
+        ... )
+    """
+
+    platform: Platform
+    confidence: float  # 0.0-1.0
+    config_path: Path | None = None
+    cli_available: bool = False
+    scope_support: Scope = Scope.BOTH
+
+
+@dataclass(frozen=True)
+class InstallationResult:
+    """Result of an MCP server installation operation.
+
+    Provides comprehensive information about installation success/failure,
+    including error details and recovery suggestions.
+
+    Attributes:
+        success: Whether installation succeeded
+        platform: Target platform
+        server_name: Name of installed server
+        method: Installation method used
+        message: Human-readable status message
+        config_path: Path to updated config file (None on failure)
+        error: Exception that caused failure (None on success)
+
+    Example (success):
+        >>> result = InstallationResult(
+        ...     success=True,
+        ...     platform=Platform.CLAUDE_CODE,
+        ...     server_name="mcp-ticketer",
+        ...     method=InstallMethod.UV_RUN,
+        ...     message="Successfully installed mcp-ticketer",
+        ...     config_path=Path.home() / ".config/claude/mcp.json"
+        ... )
+
+    Example (failure):
+        >>> result = InstallationResult(
+        ...     success=False,
+        ...     platform=Platform.CLAUDE_CODE,
+        ...     server_name="mcp-ticketer",
+        ...     method=InstallMethod.UV_RUN,
+        ...     message="Installation failed: config file not writable",
+        ...     error=PermissionError("Permission denied")
+        ... )
+    """
+
+    success: bool
+    platform: Platform
+    server_name: str
+    method: InstallMethod
+    message: str
+    config_path: Path | None = None
+    error: Exception | None = None
+
+
+# ============================================================================
+# Type Aliases
+# ============================================================================
+
+# JSON-serializable dictionary type
+JsonDict = dict[str, Any]
+
+# Environment variables dictionary
+EnvDict = dict[str, str]
+
+# Command arguments list
+ArgsList = list[str]