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

mcp_ticketer/cli/main.py

@@ -5,7 +5,7 @@ import json
 import os
 from enum import Enum
 from pathlib import Path
-from typing import Optional
+from typing import Any
 
 import typer
 from dotenv import load_dotenv
@@ -24,9 +24,11 @@ from ..queue.ticket_registry import TicketRegistry
 from .configure import configure_wizard, set_adapter_config, show_current_config
 from .diagnostics import run_diagnostics
 from .discover import app as discover_app
-from .linear_commands import app as linear_app
+from .instruction_commands import app as instruction_app
 from .migrate_config import migrate_config_command
+from .platform_commands import app as platform_app
 from .queue_commands import app as queue_app
+from .ticket_commands import app as ticket_app
 
 # Load environment variables from .env files
 # Priority: .env.local (highest) > .env (base)
@@ -48,11 +50,11 @@ app = typer.Typer(
 console = Console()
 
 
-def version_callback(value: bool):
+def version_callback(value: bool) -> None:
     """Print version and exit."""
     if value:
         console.print(f"mcp-ticketer version {__version__}")
-        raise typer.Exit()
+        raise typer.Exit() from None
 
 
 @app.callback()
@@ -65,7 +67,7 @@ def main_callback(
         is_eager=True,
         help="Show version and exit",
     ),
-):
+) -> None:
     """MCP Ticketer - Universal ticket management interface."""
     pass
 
@@ -83,7 +85,7 @@ class AdapterType(str, Enum):
     GITHUB = "github"
 
 
-def load_config(project_dir: Optional[Path] = None) -> dict:
+def load_config(project_dir: Path | None = None) -> dict:
     """Load configuration from project-local config file ONLY.
 
     SECURITY: This method ONLY reads from the current project directory
@@ -145,7 +147,7 @@ def load_config(project_dir: Optional[Path] = None) -> dict:
     return {"adapter": "aitrackdown", "config": {"base_path": ".aitrackdown"}}
 
 
-def _discover_from_env_files() -> Optional[str]:
+def _discover_from_env_files() -> str | None:
     """Discover adapter configuration from .env or .env.local files.
 
     Returns:
@@ -269,8 +271,8 @@ def merge_config(updates: dict) -> dict:
 
 
 def get_adapter(
-    override_adapter: Optional[str] = None, override_config: Optional[dict] = None
-):
+    override_adapter: str | None = None, override_config: dict | None = None
+) -> Any:
     """Get configured adapter instance.
 
     Args:
@@ -318,6 +320,416 @@ def get_adapter(
     return AdapterRegistry.get_adapter(adapter_type, adapter_config)
 
 
+async def _validate_adapter_credentials(
+    adapter_type: str, config_file_path: Path
+) -> list[str]:
+    """Validate adapter credentials by performing real connectivity tests.
+
+    Args:
+        adapter_type: Type of adapter to validate
+        config_file_path: Path to config file
+
+    Returns:
+        List of validation issues (empty if valid)
+
+    """
+    import json
+
+    issues = []
+
+    try:
+        # Load config
+        with open(config_file_path) as f:
+            config = json.load(f)
+
+        adapter_config = config.get("adapters", {}).get(adapter_type, {})
+
+        if not adapter_config:
+            issues.append(f"No configuration found for {adapter_type}")
+            return issues
+
+        # Validate based on adapter type
+        if adapter_type == "linear":
+            api_key = adapter_config.get("api_key")
+
+            # Check API key format
+            if not api_key:
+                issues.append("Linear API key is missing")
+                return issues
+
+            if not api_key.startswith("lin_api_"):
+                issues.append(
+                    "Invalid Linear API key format (should start with 'lin_api_')"
+                )
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.linear import LinearAdapter
+
+                adapter = LinearAdapter(adapter_config)
+                # Try to list one ticket to verify connectivity
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if "401" in error_msg or "Unauthorized" in error_msg:
+                    issues.append(
+                        "Failed to authenticate with Linear API - invalid API key"
+                    )
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("Linear API key lacks required permissions")
+                elif "team" in error_msg.lower():
+                    issues.append(f"Linear team configuration error: {error_msg}")
+                else:
+                    issues.append(f"Failed to connect to Linear API: {error_msg}")
+
+        elif adapter_type == "jira":
+            server = adapter_config.get("server")
+            email = adapter_config.get("email")
+            api_token = adapter_config.get("api_token")
+
+            # Check required fields
+            if not server:
+                issues.append("JIRA server URL is missing")
+            if not email:
+                issues.append("JIRA email is missing")
+            if not api_token:
+                issues.append("JIRA API token is missing")
+
+            if issues:
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.jira import JiraAdapter
+
+                adapter = JiraAdapter(adapter_config)
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if "401" in error_msg or "Unauthorized" in error_msg:
+                    issues.append(
+                        "Failed to authenticate with JIRA - invalid credentials"
+                    )
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("JIRA credentials lack required permissions")
+                else:
+                    issues.append(f"Failed to connect to JIRA: {error_msg}")
+
+        elif adapter_type == "github":
+            token = adapter_config.get("token") or adapter_config.get("api_key")
+            owner = adapter_config.get("owner")
+            repo = adapter_config.get("repo")
+
+            # Check required fields
+            if not token:
+                issues.append("GitHub token is missing")
+            if not owner:
+                issues.append("GitHub owner is missing")
+            if not repo:
+                issues.append("GitHub repo is missing")
+
+            if issues:
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.github import GitHubAdapter
+
+                adapter = GitHubAdapter(adapter_config)
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if (
+                    "401" in error_msg
+                    or "Unauthorized" in error_msg
+                    or "Bad credentials" in error_msg
+                ):
+                    issues.append("Failed to authenticate with GitHub - invalid token")
+                elif "404" in error_msg or "Not Found" in error_msg:
+                    issues.append(f"GitHub repository not found: {owner}/{repo}")
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("GitHub token lacks required permissions")
+                else:
+                    issues.append(f"Failed to connect to GitHub: {error_msg}")
+
+        elif adapter_type == "aitrackdown":
+            # AITrackdown doesn't require credentials, just check base_path is set
+            base_path = adapter_config.get("base_path")
+            if not base_path:
+                issues.append("AITrackdown base_path is missing")
+
+    except Exception as e:
+        issues.append(f"Validation error: {str(e)}")
+
+    return issues
+
+
+async def _validate_configuration_with_retry(
+    console: Console, adapter_type: str, config_file_path: Path, proj_path: Path
+) -> bool:
+    """Validate configuration with retry loop for corrections.
+
+    Args:
+        console: Rich console for output
+        adapter_type: Type of adapter configured
+        config_file_path: Path to config file
+        proj_path: Project path
+
+    Returns:
+        True if validation passed or user chose to continue, False if user chose to exit
+
+    """
+    max_retries = 3
+    retry_count = 0
+
+    while retry_count < max_retries:
+        console.print("\n[cyan]🔍 Validating configuration...[/cyan]")
+
+        # Run real adapter validation (suppress verbose output)
+        import io
+        import sys
+
+        # Capture output to suppress verbose diagnostics output
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+        sys.stdout = io.StringIO()
+        sys.stderr = io.StringIO()
+
+        try:
+            # Perform real adapter validation using diagnostics
+            validation_issues = await _validate_adapter_credentials(
+                adapter_type, config_file_path
+            )
+        finally:
+            # Restore stdout/stderr
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+        # Check if there are issues
+        if not validation_issues:
+            console.print("[green]✓ Configuration validated successfully![/green]")
+            return True
+
+        # Display issues found
+        console.print("[yellow]⚠️  Configuration validation found issues:[/yellow]")
+        for issue in validation_issues:
+            console.print(f"  [red]❌[/red] {issue}")
+
+        # Offer user options
+        console.print("\n[bold]What would you like to do?[/bold]")
+        console.print("1. [cyan]Re-enter configuration values[/cyan] (fix issues)")
+        console.print("2. [yellow]Continue anyway[/yellow] (skip validation)")
+        console.print("3. [red]Exit[/red] (fix manually later)")
+
+        try:
+            choice = typer.prompt("\nSelect option (1-3)", type=int, default=1)
+        except typer.Abort:
+            console.print("[yellow]Cancelled.[/yellow]")
+            return False
+
+        if choice == 1:
+            # Re-enter configuration
+            # Check BEFORE increment to fix off-by-one error
+            if retry_count >= max_retries:
+                console.print(
+                    f"[red]Maximum retry attempts ({max_retries}) reached.[/red]"
+                )
+                console.print(
+                    "[yellow]Please fix configuration manually and run 'mcp-ticketer doctor'[/yellow]"
+                )
+                return False
+            retry_count += 1
+
+            console.print(
+                f"\n[cyan]Retry {retry_count}/{max_retries} - Re-entering configuration...[/cyan]"
+            )
+
+            # Reload current config to get values
+            import json
+
+            with open(config_file_path) as f:
+                current_config = json.load(f)
+
+            # Re-prompt for adapter-specific configuration
+            if adapter_type == "linear":
+                console.print("\n[bold]Linear Configuration[/bold]")
+                console.print(
+                    "[dim]Get your API key at: https://linear.app/settings/api[/dim]\n"
+                )
+
+                linear_api_key = typer.prompt(
+                    "Enter your Linear API key", hide_input=True
+                )
+
+                console.print("\n[bold]Linear Team Configuration[/bold]")
+                console.print("You can provide either:")
+                console.print(
+                    "  1. Team URL (e.g., https://linear.app/workspace/team/TEAMKEY/active)"
+                )
+                console.print("  2. Team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
+                console.print("  3. Team ID (UUID)")
+                console.print(
+                    "[dim]Find team URL or key in: Linear → Your Team → Team Issues Page[/dim]\n"
+                )
+
+                team_input = typer.prompt("Team URL, key, or ID")
+
+                # Check if input is a URL
+                linear_team_id = None
+                linear_team_key = None
+
+                if team_input.startswith("https://linear.app/"):
+                    console.print("[cyan]Detected team URL, deriving team ID...[/cyan]")
+                    from .linear_commands import derive_team_from_url
+
+                    derived_team_id, error = await derive_team_from_url(
+                        linear_api_key, team_input
+                    )
+
+                    if derived_team_id:
+                        linear_team_id = derived_team_id
+                        console.print(
+                            "[green]✓[/green] Successfully derived team ID from URL"
+                        )
+                    else:
+                        console.print(f"[red]Error:[/red] {error}")
+                        console.print("Please provide team key or ID manually instead.")
+                        team_input = typer.prompt("Team key or ID")
+
+                        if len(team_input) > 20:  # Likely a UUID
+                            linear_team_id = team_input
+                        else:
+                            linear_team_key = team_input
+                else:
+                    # Input is team key or ID
+                    if len(team_input) > 20:  # Likely a UUID
+                        linear_team_id = team_input
+                    else:
+                        linear_team_key = team_input
+
+                # Update config
+                linear_config = {
+                    "api_key": linear_api_key,
+                    "type": "linear",
+                }
+                if linear_team_key:
+                    linear_config["team_key"] = linear_team_key
+                if linear_team_id:
+                    linear_config["team_id"] = linear_team_id
+
+                current_config["adapters"]["linear"] = linear_config
+
+            elif adapter_type == "jira":
+                console.print("\n[bold]JIRA Configuration[/bold]")
+                console.print("Enter your JIRA server details.\n")
+
+                server = typer.prompt(
+                    "JIRA server URL (e.g., https://company.atlassian.net)"
+                )
+                email = typer.prompt("Your JIRA email address")
+
+                console.print("\nYou need a JIRA API token.")
+                console.print(
+                    "[dim]Generate one at: https://id.atlassian.com/manage/api-tokens[/dim]\n"
+                )
+
+                token = typer.prompt("Enter your JIRA API token", hide_input=True)
+
+                project = typer.prompt(
+                    "Default JIRA project key (optional, press Enter to skip)",
+                    default="",
+                    show_default=False,
+                )
+
+                # Update config
+                jira_config = {
+                    "server": server,
+                    "email": email,
+                    "api_token": token,
+                    "type": "jira",
+                }
+                if project:
+                    jira_config["project_key"] = project
+
+                current_config["adapters"]["jira"] = jira_config
+
+            elif adapter_type == "github":
+                console.print("\n[bold]GitHub Configuration[/bold]")
+                console.print("Enter your GitHub repository details.\n")
+
+                owner = typer.prompt(
+                    "GitHub repository owner (username or organization)"
+                )
+                repo = typer.prompt("GitHub repository name")
+
+                console.print("\nYou need a GitHub Personal Access Token.")
+                console.print(
+                    "[dim]Create one at: https://github.com/settings/tokens/new[/dim]"
+                )
+                console.print(
+                    "[dim]Required scopes: repo (for private repos) or public_repo (for public repos)[/dim]\n"
+                )
+
+                token = typer.prompt(
+                    "Enter your GitHub Personal Access Token", hide_input=True
+                )
+
+                # Update config
+                current_config["adapters"]["github"] = {
+                    "owner": owner,
+                    "repo": repo,
+                    "token": token,
+                    "type": "github",
+                }
+
+            elif adapter_type == "aitrackdown":
+                # AITrackdown doesn't need credentials, but save config before returning
+                # Save updated configuration
+                with open(config_file_path, "w") as f:
+                    json.dump(current_config, f, indent=2)
+
+                console.print(
+                    "[yellow]AITrackdown doesn't require credentials. Continuing...[/yellow]"
+                )
+                console.print("[dim]✓ Configuration updated[/dim]")
+                return True
+
+            else:
+                console.print(f"[red]Unknown adapter type: {adapter_type}[/red]")
+                return False
+
+            # Save updated configuration
+            with open(config_file_path, "w") as f:
+                json.dump(current_config, f, indent=2)
+
+            console.print("[dim]✓ Configuration updated[/dim]")
+            # Loop will retry validation
+
+        elif choice == 2:
+            # Continue anyway
+            console.print(
+                "[yellow]⚠️  Continuing with potentially invalid configuration.[/yellow]"
+            )
+            console.print("[dim]You can validate later with: mcp-ticketer doctor[/dim]")
+            return True
+
+        elif choice == 3:
+            # Exit
+            console.print(
+                "[yellow]Configuration saved but not validated. Run 'mcp-ticketer doctor' to test.[/yellow]"
+            )
+            return False
+
+        else:
+            console.print(
+                f"[red]Invalid choice: {choice}. Please enter 1, 2, or 3.[/red]"
+            )
+            # Continue loop to ask again
+
+    return True
+
+
 def _prompt_for_adapter_selection(console: Console) -> str:
     """Interactive prompt for adapter selection.
 
@@ -381,172 +793,442 @@ def _prompt_for_adapter_selection(console: Console) -> str:
                 )
         except (ValueError, typer.Abort):
             console.print("[yellow]Setup cancelled.[/yellow]")
-            raise typer.Exit(0)
+            raise typer.Exit(0) from None
 
 
 @app.command()
 def setup(
-    adapter: Optional[str] = typer.Option(
-        None,
-        "--adapter",
-        "-a",
-        help="Adapter type to use (interactive prompt if not specified)",
-    ),
-    project_path: Optional[str] = typer.Option(
+    project_path: str | None = typer.Option(
         None, "--path", help="Project path (default: current directory)"
     ),
-    global_config: bool = typer.Option(
+    skip_platforms: bool = typer.Option(
         False,
-        "--global",
-        "-g",
-        help="Save to global config instead of project-specific",
-    ),
-    base_path: Optional[str] = typer.Option(
-        None,
-        "--base-path",
-        "-p",
-        help="Base path for ticket storage (AITrackdown only)",
-    ),
-    api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for Linear or API token for JIRA"
-    ),
-    team_id: Optional[str] = typer.Option(
-        None, "--team-id", help="Linear team ID (required for Linear adapter)"
-    ),
-    jira_server: Optional[str] = typer.Option(
-        None,
-        "--jira-server",
-        help="JIRA server URL (e.g., https://company.atlassian.net)",
-    ),
-    jira_email: Optional[str] = typer.Option(
-        None, "--jira-email", help="JIRA user email for authentication"
-    ),
-    jira_project: Optional[str] = typer.Option(
-        None, "--jira-project", help="Default JIRA project key"
-    ),
-    github_owner: Optional[str] = typer.Option(
-        None, "--github-owner", help="GitHub repository owner"
-    ),
-    github_repo: Optional[str] = typer.Option(
-        None, "--github-repo", help="GitHub repository name"
+        "--skip-platforms",
+        help="Skip platform installation (only initialize adapter)",
     ),
-    github_token: Optional[str] = typer.Option(
-        None, "--github-token", help="GitHub Personal Access Token"
+    force_reinit: bool = typer.Option(
+        False,
+        "--force-reinit",
+        help="Force re-initialization even if config exists",
     ),
 ) -> None:
-    """Interactive setup wizard for MCP Ticketer (alias for init).
+    """Smart setup command - combines init + platform installation.
+
+    This command intelligently detects your current setup state and only
+    performs necessary configuration. It's the recommended way to get started.
 
-    This command provides a user-friendly setup experience with prompts
-    to guide you through configuring MCP Ticketer for your preferred
-    ticket management system. It's identical to 'init' and 'install'.
+    Detection & Smart Actions:
+    - First run: Full setup (init + platform installation)
+    - Existing config: Skip init, offer platform installation
+    - Detects changes: Offers to update configurations
+    - Respects existing: Won't overwrite without confirmation
 
     Examples:
-        # Run interactive setup
+        # Smart setup (recommended for first-time setup)
         mcp-ticketer setup
 
-        # Setup with specific adapter
-        mcp-ticketer setup --adapter linear
-
         # Setup for different project
         mcp-ticketer setup --path /path/to/project
 
-    """
-    # Call init with all parameters
-    init(
-        adapter=adapter,
-        project_path=project_path,
-        global_config=global_config,
-        base_path=base_path,
-        api_key=api_key,
-        team_id=team_id,
-        jira_server=jira_server,
-        jira_email=jira_email,
-        jira_project=jira_project,
-        github_owner=github_owner,
-        github_repo=github_repo,
-        github_token=github_token,
-    )
+        # Re-initialize configuration
+        mcp-ticketer setup --force-reinit
 
+        # Only init adapter, skip platform installation
+        mcp-ticketer setup --skip-platforms
 
-@app.command()
-def init(
-    adapter: Optional[str] = typer.Option(
-        None,
-        "--adapter",
-        "-a",
-        help="Adapter type to use (interactive prompt if not specified)",
-    ),
-    project_path: Optional[str] = typer.Option(
-        None, "--path", help="Project path (default: current directory)"
-    ),
-    global_config: bool = typer.Option(
-        False,
-        "--global",
-        "-g",
-        help="Save to global config instead of project-specific",
-    ),
-    base_path: Optional[str] = typer.Option(
-        None,
-        "--base-path",
-        "-p",
-        help="Base path for ticket storage (AITrackdown only)",
-    ),
-    api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for Linear or API token for JIRA"
-    ),
-    team_id: Optional[str] = typer.Option(
-        None, "--team-id", help="Linear team ID (required for Linear adapter)"
-    ),
-    jira_server: Optional[str] = typer.Option(
-        None,
-        "--jira-server",
-        help="JIRA server URL (e.g., https://company.atlassian.net)",
-    ),
-    jira_email: Optional[str] = typer.Option(
-        None, "--jira-email", help="JIRA user email for authentication"
-    ),
-    jira_project: Optional[str] = typer.Option(
-        None, "--jira-project", help="Default JIRA project key"
-    ),
-    github_owner: Optional[str] = typer.Option(
-        None, "--github-owner", help="GitHub repository owner"
-    ),
-    github_repo: Optional[str] = typer.Option(
-        None, "--github-repo", help="GitHub repository name"
-    ),
-    github_token: Optional[str] = typer.Option(
-        None, "--github-token", help="GitHub Personal Access Token"
-    ),
-) -> None:
-    """Initialize mcp-ticketer for the current project.
+    Note: For advanced configuration, use 'init' and 'install' separately.
 
-    This command sets up MCP Ticketer configuration with interactive prompts
-    to guide you through the process. It auto-detects adapter configuration
-    from .env files or prompts for interactive setup if no configuration is found.
+    """
+    from .platform_detection import PlatformDetector
 
-    Creates .mcp-ticketer/config.json in the current directory with
-    auto-detected or specified adapter configuration.
+    proj_path = Path(project_path) if project_path else Path.cwd()
+    config_path = proj_path / ".mcp-ticketer" / "config.json"
 
-    Note: 'setup' and 'install' are synonyms for this command.
+    console.print("[bold cyan]🚀 MCP Ticketer Smart Setup[/bold cyan]\n")
 
-    Examples:
-        # Interactive setup (same as 'setup' and 'install')
-        mcp-ticketer init
+    # Step 1: Detect existing configuration
+    config_exists = config_path.exists()
+    config_valid = False
+    current_adapter = None
 
-        # Force specific adapter
+    if config_exists and not force_reinit:
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+                current_adapter = config.get("default_adapter")
+                config_valid = bool(current_adapter and config.get("adapters"))
+        except (json.JSONDecodeError, OSError):
+            config_valid = False
+
+    if config_valid:
+        console.print("[green]✓[/green] Configuration detected")
+        console.print(f"[dim]  Adapter: {current_adapter}[/dim]")
+        console.print(f"[dim]  Location: {config_path}[/dim]\n")
+
+        # Offer to reconfigure
+        if not typer.confirm(
+            "Configuration already exists. Keep existing settings?", default=True
+        ):
+            console.print("[cyan]Re-initializing configuration...[/cyan]\n")
+            force_reinit = True
+            config_valid = False
+    else:
+        if config_exists:
+            console.print(
+                "[yellow]⚠[/yellow]  Configuration file exists but is invalid\n"
+            )
+        else:
+            console.print("[yellow]⚠[/yellow]  No configuration found\n")
+
+    # Step 2: Initialize adapter configuration if needed
+    if not config_valid or force_reinit:
+        console.print("[bold]Step 1/2: Adapter Configuration[/bold]\n")
+
+        # Run init command non-interactively through function call
+        # We'll use the discover and prompt flow from init
+        from ..core.env_discovery import discover_config
+
+        discovered = discover_config(proj_path)
+        adapter_type = None
+
+        # Try auto-discovery
+        if discovered and discovered.adapters:
+            primary = discovered.get_primary_adapter()
+            if primary:
+                adapter_type = primary.adapter_type
+                console.print(f"[green]✓ Auto-detected {adapter_type} adapter[/green]")
+                console.print(f"[dim]  Source: {primary.found_in}[/dim]")
+                console.print(f"[dim]  Confidence: {primary.confidence:.0%}[/dim]\n")
+
+                if not typer.confirm(
+                    f"Use detected {adapter_type} adapter?", default=True
+                ):
+                    adapter_type = None
+
+        # If no adapter detected, prompt for selection
+        if not adapter_type:
+            adapter_type = _prompt_for_adapter_selection(console)
+
+        # Now run the full init with the selected adapter
+        console.print(f"\n[cyan]Initializing {adapter_type} adapter...[/cyan]\n")
+
+        # Call init programmatically
+        init(
+            adapter=adapter_type,
+            project_path=str(proj_path),
+            global_config=False,
+        )
+
+        console.print("\n[green]✓ Adapter configuration complete[/green]\n")
+    else:
+        console.print("[green]✓ Step 1/2: Adapter already configured[/green]\n")
+
+    # Step 3: Platform installation
+    if skip_platforms:
+        console.print(
+            "[yellow]⚠[/yellow]  Skipping platform installation (--skip-platforms)\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    console.print("[bold]Step 2/2: Platform Installation[/bold]\n")
+
+    # Detect available platforms
+    detector = PlatformDetector()
+    detected = detector.detect_all(project_path=proj_path)
+
+    if not detected:
+        console.print("[yellow]No AI platforms detected on this system.[/yellow]")
+        console.print(
+            "\n[dim]Supported platforms: Claude Code, Claude Desktop, Gemini, Codex, Auggie[/dim]"
+        )
+        console.print(
+            "[dim]Install these platforms to use them with mcp-ticketer.[/dim]\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Filter to only installed platforms
+    installed = [p for p in detected if p.is_installed]
+
+    if not installed:
+        console.print(
+            "[yellow]AI platforms detected but have configuration issues.[/yellow]"
+        )
+        console.print(
+            "\n[dim]Run 'mcp-ticketer install --auto-detect' for details.[/dim]\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Show detected platforms
+    console.print(f"[green]✓[/green] Detected {len(installed)} platform(s):\n")
+    for plat in installed:
+        console.print(f"  • {plat.display_name} ({plat.scope})")
+
+    console.print()
+
+    # Check if mcp-ticketer is already configured for these platforms
+    already_configured = _check_existing_platform_configs(installed, proj_path)
+
+    if already_configured:
+        console.print(
+            f"[green]✓[/green] mcp-ticketer already configured for {len(already_configured)} platform(s)\n"
+        )
+        for plat_name in already_configured:
+            console.print(f"  • {plat_name}")
+        console.print()
+
+        if not typer.confirm("Update platform configurations anyway?", default=False):
+            console.print("[yellow]Skipping platform installation[/yellow]\n")
+            _show_setup_complete_message(console, proj_path)
+            return
+
+    # Offer to install for all or select specific
+    console.print("[bold]Platform Installation Options:[/bold]")
+    console.print("1. Install for all detected platforms")
+    console.print("2. Select specific platform")
+    console.print("3. Skip platform installation")
+
+    try:
+        choice = typer.prompt("\nSelect option (1-3)", type=int, default=1)
+    except typer.Abort:
+        console.print("[yellow]Setup cancelled[/yellow]")
+        raise typer.Exit(0) from None
+
+    if choice == 3:
+        console.print("[yellow]Skipping platform installation[/yellow]\n")
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Import configuration functions
+    from .auggie_configure import configure_auggie_mcp
+    from .codex_configure import configure_codex_mcp
+    from .gemini_configure import configure_gemini_mcp
+    from .mcp_configure import configure_claude_mcp
+
+    platform_mapping = {
+        "claude-code": lambda: configure_claude_mcp(global_config=False, force=True),
+        "claude-desktop": lambda: configure_claude_mcp(global_config=True, force=True),
+        "auggie": lambda: configure_auggie_mcp(force=True),
+        "gemini": lambda: configure_gemini_mcp(scope="project", force=True),
+        "codex": lambda: configure_codex_mcp(force=True),
+    }
+
+    platforms_to_install = []
+
+    if choice == 1:
+        # Install for all
+        platforms_to_install = installed
+    elif choice == 2:
+        # Select specific platform
+        console.print("\n[bold]Select platform:[/bold]")
+        for idx, plat in enumerate(installed, 1):
+            console.print(f"  {idx}. {plat.display_name} ({plat.scope})")
+
+        try:
+            plat_choice = typer.prompt("\nSelect platform number", type=int)
+            if 1 <= plat_choice <= len(installed):
+                platforms_to_install = [installed[plat_choice - 1]]
+            else:
+                console.print("[red]Invalid selection[/red]")
+                raise typer.Exit(1) from None
+        except typer.Abort:
+            console.print("[yellow]Setup cancelled[/yellow]")
+            raise typer.Exit(0) from None
+
+    # Install for selected platforms
+    console.print()
+    success_count = 0
+    failed = []
+
+    for plat in platforms_to_install:
+        config_func = platform_mapping.get(plat.name)
+        if not config_func:
+            console.print(f"[yellow]⚠[/yellow]  No installer for {plat.display_name}")
+            continue
+
+        try:
+            console.print(f"[cyan]Installing for {plat.display_name}...[/cyan]")
+            config_func()
+            console.print(f"[green]✓[/green] {plat.display_name} configured\n")
+            success_count += 1
+        except Exception as e:
+            console.print(
+                f"[red]✗[/red] Failed to configure {plat.display_name}: {e}\n"
+            )
+            failed.append(plat.display_name)
+
+    # Summary
+    console.print(
+        f"[bold]Platform Installation:[/bold] {success_count}/{len(platforms_to_install)} succeeded"
+    )
+    if failed:
+        console.print(f"[red]Failed:[/red] {', '.join(failed)}")
+
+    console.print()
+    _show_setup_complete_message(console, proj_path)
+
+
+def _check_existing_platform_configs(platforms: list, proj_path: Path) -> list[str]:
+    """Check if mcp-ticketer is already configured for given platforms.
+
+    Args:
+        platforms: List of DetectedPlatform objects
+        proj_path: Project path
+
+    Returns:
+        List of platform display names that are already configured
+
+    """
+    configured = []
+
+    for plat in platforms:
+        try:
+            if plat.name == "claude-code":
+                config_path = Path.home() / ".claude.json"
+                if config_path.exists():
+                    with open(config_path) as f:
+                        config = json.load(f)
+                        projects = config.get("projects", {})
+                        proj_key = str(proj_path)
+                        if proj_key in projects:
+                            mcp_servers = projects[proj_key].get("mcpServers", {})
+                            if "mcp-ticketer" in mcp_servers:
+                                configured.append(plat.display_name)
+
+            elif plat.name == "claude-desktop":
+                if plat.config_path.exists():
+                    with open(plat.config_path) as f:
+                        config = json.load(f)
+                        if "mcp-ticketer" in config.get("mcpServers", {}):
+                            configured.append(plat.display_name)
+
+            elif plat.name in ["auggie", "codex", "gemini"]:
+                if plat.config_path.exists():
+                    # Check if mcp-ticketer is configured
+                    # Implementation depends on each platform's config format
+                    # For now, just check if config exists (simplified)
+                    pass
+
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return configured
+
+
+def _show_setup_complete_message(console: Console, proj_path: Path) -> None:
+    """Show setup complete message with next steps.
+
+    Args:
+        console: Rich console for output
+        proj_path: Project path
+
+    """
+    console.print("[bold green]🎉 Setup Complete![/bold green]\n")
+
+    console.print("[bold]Quick Start:[/bold]")
+    console.print("1. Create a test ticket:")
+    console.print("   [cyan]mcp-ticketer create 'My first ticket'[/cyan]\n")
+
+    console.print("2. List tickets:")
+    console.print("   [cyan]mcp-ticketer list[/cyan]\n")
+
+    console.print("[bold]Useful Commands:[/bold]")
+    console.print("  [cyan]mcp-ticketer doctor[/cyan]        - Validate configuration")
+    console.print("  [cyan]mcp-ticketer install <platform>[/cyan] - Add more platforms")
+    console.print("  [cyan]mcp-ticketer --help[/cyan]        - See all commands\n")
+
+    console.print(
+        f"[dim]Configuration: {proj_path / '.mcp-ticketer' / 'config.json'}[/dim]"
+    )
+
+
+@app.command()
+def init(
+    adapter: str | None = typer.Option(
+        None,
+        "--adapter",
+        "-a",
+        help="Adapter type to use (interactive prompt if not specified)",
+    ),
+    project_path: str | None = typer.Option(
+        None, "--path", help="Project path (default: current directory)"
+    ),
+    global_config: bool = typer.Option(
+        False,
+        "--global",
+        "-g",
+        help="Save to global config instead of project-specific",
+    ),
+    base_path: str | None = typer.Option(
+        None,
+        "--base-path",
+        "-p",
+        help="Base path for ticket storage (AITrackdown only)",
+    ),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="API key for Linear or API token for JIRA"
+    ),
+    team_id: str | None = typer.Option(
+        None, "--team-id", help="Linear team ID (required for Linear adapter)"
+    ),
+    jira_server: str | None = typer.Option(
+        None,
+        "--jira-server",
+        help="JIRA server URL (e.g., https://company.atlassian.net)",
+    ),
+    jira_email: str | None = typer.Option(
+        None, "--jira-email", help="JIRA user email for authentication"
+    ),
+    jira_project: str | None = typer.Option(
+        None, "--jira-project", help="Default JIRA project key"
+    ),
+    github_owner: str | None = typer.Option(
+        None, "--github-owner", help="GitHub repository owner"
+    ),
+    github_repo: str | None = typer.Option(
+        None, "--github-repo", help="GitHub repository name"
+    ),
+    github_token: str | None = typer.Option(
+        None, "--github-token", help="GitHub Personal Access Token"
+    ),
+) -> None:
+    """Initialize adapter configuration only (without platform installation).
+
+    This command sets up adapter configuration with interactive prompts.
+    It auto-detects adapter configuration from .env files or prompts for
+    interactive setup if no configuration is found.
+
+    Creates .mcp-ticketer/config.json in the current directory.
+
+    RECOMMENDED: Use 'mcp-ticketer setup' instead for a complete setup
+    experience that includes both adapter configuration and platform
+    installation in one command.
+
+    The init command automatically validates your configuration after setup:
+    - If validation passes, setup completes
+    - If issues are detected, you can re-enter credentials, continue anyway, or exit
+    - You get up to 3 retry attempts to fix configuration issues
+    - You can always re-validate later with 'mcp-ticketer doctor'
+
+    Examples:
+        # For first-time setup, use 'setup' instead (recommended)
+        mcp-ticketer setup
+
+        # Initialize adapter only (advanced usage)
+        mcp-ticketer init
+
+        # Force specific adapter
         mcp-ticketer init --adapter linear
 
         # Initialize for different project
         mcp-ticketer init --path /path/to/project
 
-        # Save globally (not recommended)
-        mcp-ticketer init --global
-
     """
     from pathlib import Path
 
     from ..core.env_discovery import discover_config
-    from ..core.project_config import ConfigResolver
 
     # Determine project path
     proj_path = Path(project_path) if project_path else Path.cwd()
@@ -561,7 +1243,7 @@ def init(
                 default=False,
             ):
                 console.print("[yellow]Initialization cancelled.[/yellow]")
-                raise typer.Exit(0)
+                raise typer.Exit(0) from None
 
     # 1. Try auto-discovery if no adapter specified
     discovered = None
@@ -573,7 +1255,7 @@ def init(
         )
 
         # First try our improved .env configuration loader
-        from ..mcp.server import _load_env_configuration
+        from ..mcp.server.main import _load_env_configuration
 
         env_config = _load_env_configuration()
 
@@ -650,11 +1332,9 @@ def init(
     elif adapter_type == "linear":
         # If not auto-discovered, build from CLI params or prompt
         if adapter_type not in config["adapters"]:
-            linear_config = {}
-
             # API Key
             linear_api_key = api_key or os.getenv("LINEAR_API_KEY")
-            if not linear_api_key and not discovered:
+            if not linear_api_key:
                 console.print("\n[bold]Linear Configuration[/bold]")
                 console.print("You need a Linear API key to connect to Linear.")
                 console.print(
@@ -665,30 +1345,81 @@ def init(
                     "Enter your Linear API key", hide_input=True
                 )
 
-            if linear_api_key:
-                linear_config["api_key"] = linear_api_key
-
-            # Team ID
+            # Team ID or Team Key or Team URL
+            # Try environment variables first
+            linear_team_key = os.getenv("LINEAR_TEAM_KEY")
             linear_team_id = team_id or os.getenv("LINEAR_TEAM_ID")
-            if not linear_team_id and not discovered:
-                console.print("\nYou need your Linear team ID.")
-                console.print("[dim]Find it in Linear settings or team URL[/dim]\n")
-
-                linear_team_id = typer.prompt("Enter your Linear team ID")
-
-            if linear_team_id:
-                linear_config["team_id"] = linear_team_id
 
-            if not linear_config.get("api_key") or not linear_config.get("team_id"):
+            if not linear_team_key and not linear_team_id:
+                console.print("\n[bold]Linear Team Configuration[/bold]")
+                console.print("You can provide either:")
+                console.print(
+                    "  1. Team URL (e.g., https://linear.app/workspace/team/TEAMKEY/active)"
+                )
+                console.print("  2. Team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
+                console.print("  3. Team ID (UUID)")
                 console.print(
-                    "[red]Error:[/red] Linear requires both API key and team ID"
+                    "[dim]Find team URL or key in: Linear → Your Team → Team Issues Page[/dim]\n"
                 )
+
+                team_input = typer.prompt("Team URL, key, or ID")
+
+                # Check if input is a URL
+                if team_input.startswith("https://linear.app/"):
+                    console.print("[cyan]Detected team URL, deriving team ID...[/cyan]")
+                    import asyncio
+
+                    from .linear_commands import derive_team_from_url
+
+                    derived_team_id, error = asyncio.run(
+                        derive_team_from_url(linear_api_key, team_input)
+                    )
+
+                    if derived_team_id:
+                        linear_team_id = derived_team_id
+                        console.print(
+                            "[green]✓[/green] Successfully derived team ID from URL"
+                        )
+                    else:
+                        console.print(f"[red]Error:[/red] {error}")
+                        console.print("Please provide team key or ID manually instead.")
+                        team_input = typer.prompt("Team key or ID")
+
+                        # Store as either team_key or team_id based on format
+                        if len(team_input) > 20:  # Likely a UUID
+                            linear_team_id = team_input
+                        else:
+                            linear_team_key = team_input
+                else:
+                    # Input is team key or ID
+                    if len(team_input) > 20:  # Likely a UUID
+                        linear_team_id = team_input
+                    else:
+                        linear_team_key = team_input
+
+            # Validate required fields (following JIRA pattern)
+            if not linear_api_key:
+                console.print("[red]Error:[/red] Linear API key is required")
+                raise typer.Exit(1) from None
+
+            if not linear_team_id and not linear_team_key:
                 console.print(
-                    "Run 'mcp-ticketer init --adapter linear' with proper credentials"
+                    "[red]Error:[/red] Linear requires either team ID or team key"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
+
+            # Build configuration
+            linear_config = {
+                "api_key": linear_api_key,
+                "type": "linear",
+            }
+
+            # Save whichever was provided
+            if linear_team_key:
+                linear_config["team_key"] = linear_team_key
+            if linear_team_id:
+                linear_config["team_id"] = linear_team_id
 
-            linear_config["type"] = "linear"
             config["adapters"]["linear"] = linear_config
 
     elif adapter_type == "jira":
@@ -700,7 +1431,7 @@ def init(
             project = jira_project or os.getenv("JIRA_PROJECT_KEY")
 
             # Interactive prompts for missing values
-            if not server and not discovered:
+            if not server:
                 console.print("\n[bold]JIRA Configuration[/bold]")
                 console.print("Enter your JIRA server details.\n")
 
@@ -708,10 +1439,10 @@ def init(
                     "JIRA server URL (e.g., https://company.atlassian.net)"
                 )
 
-            if not email and not discovered:
+            if not email:
                 email = typer.prompt("Your JIRA email address")
 
-            if not token and not discovered:
+            if not token:
                 console.print("\nYou need a JIRA API token.")
                 console.print(
                     "[dim]Generate one at: https://id.atlassian.com/manage/api-tokens[/dim]\n"
@@ -719,7 +1450,7 @@ def init(
 
                 token = typer.prompt("Enter your JIRA API token", hide_input=True)
 
-            if not project and not discovered:
+            if not project:
                 project = typer.prompt(
                     "Default JIRA project key (optional, press Enter to skip)",
                     default="",
@@ -729,15 +1460,15 @@ def init(
             # Validate required fields
             if not server:
                 console.print("[red]Error:[/red] JIRA server URL is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not email:
                 console.print("[red]Error:[/red] JIRA email is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not token:
                 console.print("[red]Error:[/red] JIRA API token is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             jira_config = {
                 "server": server,
@@ -759,7 +1490,7 @@ def init(
             token = github_token or os.getenv("GITHUB_TOKEN")
 
             # Interactive prompts for missing values
-            if not owner and not discovered:
+            if not owner:
                 console.print("\n[bold]GitHub Configuration[/bold]")
                 console.print("Enter your GitHub repository details.\n")
 
@@ -767,10 +1498,10 @@ def init(
                     "GitHub repository owner (username or organization)"
                 )
 
-            if not repo and not discovered:
+            if not repo:
                 repo = typer.prompt("GitHub repository name")
 
-            if not token and not discovered:
+            if not token:
                 console.print("\nYou need a GitHub Personal Access Token.")
                 console.print(
                     "[dim]Create one at: https://github.com/settings/tokens/new[/dim]"
@@ -786,17 +1517,17 @@ def init(
             # Validate required fields
             if not owner:
                 console.print("[red]Error:[/red] GitHub repository owner is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not repo:
                 console.print("[red]Error:[/red] GitHub repository name is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not token:
                 console.print(
                     "[red]Error:[/red] GitHub Personal Access Token is required"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             config["adapters"]["github"] = {
                 "owner": owner,
@@ -805,42 +1536,46 @@ def init(
                 "type": "github",
             }
 
-    # 5. Save to appropriate location
-    if global_config:
-        # Save to ~/.mcp-ticketer/config.json
-        resolver = ConfigResolver(project_path=proj_path)
-        config_file_path = resolver.GLOBAL_CONFIG_PATH
-        config_file_path.parent.mkdir(parents=True, exist_ok=True)
+    # 5. Save to project-local config (global config deprecated for security)
+    # Always save to ./.mcp-ticketer/config.json (PROJECT-SPECIFIC)
+    config_file_path = proj_path / ".mcp-ticketer" / "config.json"
+    config_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(config_file_path, "w") as f:
+        json.dump(config, f, indent=2)
 
-        with open(config_file_path, "w") as f:
-            json.dump(config, f, indent=2)
+    if global_config:
+        console.print(
+            "[yellow]Note: Global config deprecated for security. Saved to project config instead.[/yellow]"
+        )
 
-        console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
-        console.print(f"[dim]Global configuration saved to {config_file_path}[/dim]")
+    console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
+    console.print(f"[dim]Project configuration saved to {config_file_path}[/dim]")
+
+    # Add .mcp-ticketer to .gitignore if not already there
+    gitignore_path = proj_path / ".gitignore"
+    if gitignore_path.exists():
+        gitignore_content = gitignore_path.read_text()
+        if ".mcp-ticketer" not in gitignore_content:
+            with open(gitignore_path, "a") as f:
+                f.write("\n# MCP Ticketer\n.mcp-ticketer/\n")
+            console.print("[dim]✓ Added .mcp-ticketer/ to .gitignore[/dim]")
     else:
-        # Save to ./.mcp-ticketer/config.json (PROJECT-SPECIFIC)
-        config_file_path = proj_path / ".mcp-ticketer" / "config.json"
-        config_file_path.parent.mkdir(parents=True, exist_ok=True)
-
-        with open(config_file_path, "w") as f:
-            json.dump(config, f, indent=2)
-
-        console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
-        console.print(f"[dim]Project configuration saved to {config_file_path}[/dim]")
-
-        # Add .mcp-ticketer to .gitignore if not already there
-        gitignore_path = proj_path / ".gitignore"
-        if gitignore_path.exists():
-            gitignore_content = gitignore_path.read_text()
-            if ".mcp-ticketer" not in gitignore_content:
-                with open(gitignore_path, "a") as f:
-                    f.write("\n# MCP Ticketer\n.mcp-ticketer/\n")
-                console.print("[dim]✓ Added .mcp-ticketer/ to .gitignore[/dim]")
-        else:
-            # Create .gitignore if it doesn't exist
-            with open(gitignore_path, "w") as f:
-                f.write("# MCP Ticketer\n.mcp-ticketer/\n")
-            console.print("[dim]✓ Created .gitignore with .mcp-ticketer/[/dim]")
+        # Create .gitignore if it doesn't exist
+        with open(gitignore_path, "w") as f:
+            f.write("# MCP Ticketer\n.mcp-ticketer/\n")
+        console.print("[dim]✓ Created .gitignore with .mcp-ticketer/[/dim]")
+
+    # Validate configuration with loop for corrections
+    import asyncio
+
+    if not asyncio.run(
+        _validate_configuration_with_retry(
+            console, adapter_type, config_file_path, proj_path
+        )
+    ):
+        # User chose to exit without valid configuration
+        raise typer.Exit(1) from None
 
     # Show next steps
     _show_next_steps(console, adapter_type, config_file_path)
@@ -861,16 +1596,13 @@ def _show_next_steps(
     console.print(f"MCP Ticketer is now configured to use {adapter_type.title()}.\n")
 
     console.print("[bold]Next Steps:[/bold]")
-    console.print("1. [cyan]Test your configuration:[/cyan]")
-    console.print("   mcp-ticketer diagnose")
-    console.print("\n2. [cyan]Create a test ticket:[/cyan]")
+    console.print("1. [cyan]Create a test ticket:[/cyan]")
     console.print("   mcp-ticketer create 'Test ticket from MCP Ticketer'")
 
     if adapter_type != "aitrackdown":
         console.print(
-            f"\n3. [cyan]Verify the ticket appears in {adapter_type.title()}[/cyan]"
+            f"\n2. [cyan]Verify the ticket appears in {adapter_type.title()}[/cyan]"
         )
-
         if adapter_type == "linear":
             console.print("   Check your Linear workspace for the new ticket")
         elif adapter_type == "github":
@@ -878,121 +1610,36 @@ def _show_next_steps(
         elif adapter_type == "jira":
             console.print("   Check your JIRA project for the new ticket")
     else:
-        console.print("\n3. [cyan]Check local ticket storage:[/cyan]")
+        console.print("\n2. [cyan]Check local ticket storage:[/cyan]")
         console.print("   ls .aitrackdown/")
 
-    console.print("\n4. [cyan]Configure MCP clients (optional):[/cyan]")
-    console.print("   mcp-ticketer mcp claude    # For Claude Code")
-    console.print("   mcp-ticketer mcp auggie    # For Auggie")
-    console.print("   mcp-ticketer mcp gemini    # For Gemini CLI")
+    console.print("\n3. [cyan]Install MCP for AI clients (optional):[/cyan]")
+    console.print("   mcp-ticketer install claude-code     # For Claude Code")
+    console.print("   mcp-ticketer install claude-desktop  # For Claude Desktop")
+    console.print("   mcp-ticketer install auggie          # For Auggie")
+    console.print("   mcp-ticketer install gemini          # For Gemini CLI")
 
     console.print(f"\n[dim]Configuration saved to: {config_file_path}[/dim]")
-    console.print("[dim]Run 'mcp-ticketer --help' for more commands[/dim]")
-
-
-@app.command()
-def install(
-    adapter: Optional[str] = typer.Option(
-        None,
-        "--adapter",
-        "-a",
-        help="Adapter type to use (auto-detected from .env if not specified)",
-    ),
-    project_path: Optional[str] = typer.Option(
-        None, "--path", help="Project path (default: current directory)"
-    ),
-    global_config: bool = typer.Option(
-        False,
-        "--global",
-        "-g",
-        help="Save to global config instead of project-specific",
-    ),
-    base_path: Optional[str] = typer.Option(
-        None,
-        "--base-path",
-        "-p",
-        help="Base path for ticket storage (AITrackdown only)",
-    ),
-    api_key: Optional[str] = typer.Option(
-        None, "--api-key", help="API key for Linear or API token for JIRA"
-    ),
-    team_id: Optional[str] = typer.Option(
-        None, "--team-id", help="Linear team ID (required for Linear adapter)"
-    ),
-    jira_server: Optional[str] = typer.Option(
-        None,
-        "--jira-server",
-        help="JIRA server URL (e.g., https://company.atlassian.net)",
-    ),
-    jira_email: Optional[str] = typer.Option(
-        None, "--jira-email", help="JIRA user email for authentication"
-    ),
-    jira_project: Optional[str] = typer.Option(
-        None, "--jira-project", help="Default JIRA project key"
-    ),
-    github_owner: Optional[str] = typer.Option(
-        None, "--github-owner", help="GitHub repository owner"
-    ),
-    github_repo: Optional[str] = typer.Option(
-        None, "--github-repo", help="GitHub repository name"
-    ),
-    github_token: Optional[str] = typer.Option(
-        None, "--github-token", help="GitHub Personal Access Token"
-    ),
-) -> None:
-    """Initialize mcp-ticketer for the current project (alias for init).
-
-    This command is synonymous with 'init' and 'setup' - all three provide
-    identical functionality with interactive prompts to guide you through
-    configuring MCP Ticketer for your preferred ticket management system.
-
-    Examples:
-        # Interactive setup (same as 'init' and 'setup')
-        mcp-ticketer install
-
-        # Force specific adapter
-        mcp-ticketer install --adapter linear
-
-        # Initialize for different project
-        mcp-ticketer install --path /path/to/project
-
-        # Save globally (not recommended)
-        mcp-ticketer install --global
-
-    """
-    # Call init with all parameters
-    init(
-        adapter=adapter,
-        project_path=project_path,
-        global_config=global_config,
-        base_path=base_path,
-        api_key=api_key,
-        team_id=team_id,
-        jira_server=jira_server,
-        jira_email=jira_email,
-        jira_project=jira_project,
-        github_owner=github_owner,
-        github_repo=github_repo,
-        github_token=github_token,
+    console.print(
+        "[dim]Run 'mcp-ticketer doctor' to re-validate configuration anytime[/dim]"
     )
+    console.print("[dim]Run 'mcp-ticketer --help' for more commands[/dim]")
 
 
 @app.command("set")
 def set_config(
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", "-a", help="Set default adapter"
     ),
-    team_key: Optional[str] = typer.Option(
+    team_key: str | None = typer.Option(
         None, "--team-key", help="Linear team key (e.g., BTA)"
     ),
-    team_id: Optional[str] = typer.Option(None, "--team-id", help="Linear team ID"),
-    owner: Optional[str] = typer.Option(
-        None, "--owner", help="GitHub repository owner"
-    ),
-    repo: Optional[str] = typer.Option(None, "--repo", help="GitHub repository name"),
-    server: Optional[str] = typer.Option(None, "--server", help="JIRA server URL"),
-    project: Optional[str] = typer.Option(None, "--project", help="JIRA project key"),
-    base_path: Optional[str] = typer.Option(
+    team_id: str | None = typer.Option(None, "--team-id", help="Linear team ID"),
+    owner: str | None = typer.Option(None, "--owner", help="GitHub repository owner"),
+    repo: str | None = typer.Option(None, "--repo", help="GitHub repository name"),
+    server: str | None = typer.Option(None, "--server", help="JIRA server URL"),
+    project: str | None = typer.Option(None, "--project", help="JIRA project key"),
+    base_path: str | None = typer.Option(
         None, "--base-path", help="AITrackdown base path"
     ),
 ) -> None:
@@ -1082,16 +1729,12 @@ def set_config(
 @app.command("configure")
 def configure_command(
     show: bool = typer.Option(False, "--show", help="Show current configuration"),
-    adapter: Optional[str] = typer.Option(
+    adapter: str | None = typer.Option(
         None, "--adapter", help="Set default adapter type"
     ),
-    api_key: Optional[str] = typer.Option(None, "--api-key", help="Set API key/token"),
-    project_id: Optional[str] = typer.Option(
-        None, "--project-id", help="Set project ID"
-    ),
-    team_id: Optional[str] = typer.Option(
-        None, "--team-id", help="Set team ID (Linear)"
-    ),
+    api_key: str | None = typer.Option(None, "--api-key", help="Set API key/token"),
+    project_id: str | None = typer.Option(None, "--project-id", help="Set project ID"),
+    team_id: str | None = typer.Option(None, "--team-id", help="Set team ID (Linear)"),
     global_scope: bool = typer.Option(
         False,
         "--global",
@@ -1142,9 +1785,16 @@ def migrate_config(
     migrate_config_command(dry_run=dry_run)
 
 
-@app.command("status")
-def status_command():
-    """Show queue and worker status."""
+@app.command("queue-status", deprecated=True, hidden=True)
+def old_queue_status_command() -> None:
+    """Show queue and worker status.
+
+    DEPRECATED: Use 'mcp-ticketer queue status' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer queue status' instead.[/yellow]\n"
+    )
+
     queue = Queue()
     manager = WorkerManager()
 
@@ -1169,12 +1819,12 @@ def status_command():
         console.print("\n[red]○ Worker is not running[/red]")
         if pending > 0:
             console.print(
-                "[yellow]Note: There are pending items. Start worker with 'mcp-ticketer worker start'[/yellow]"
+                "[yellow]Note: There are pending items. Start worker with 'mcp-ticketer queue worker start'[/yellow]"
             )
 
 
-@app.command()
-def health(
+@app.command("queue-health", deprecated=True, hidden=True)
+def old_queue_health_command(
     auto_repair: bool = typer.Option(
         False, "--auto-repair", help="Attempt automatic repair of issues"
     ),
@@ -1182,7 +1832,13 @@ def health(
         False, "--verbose", "-v", help="Show detailed health information"
     ),
 ) -> None:
-    """Check queue system health and detect issues immediately."""
+    """Check queue system health and detect issues immediately.
+
+    DEPRECATED: Use 'mcp-ticketer queue health' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer queue health' instead.[/yellow]\n"
+    )
     health_monitor = QueueHealthMonitor()
     health = health_monitor.check_health()
 
@@ -1246,41 +1902,48 @@ def health(
 
     # Exit with appropriate code
     if health["status"] == HealthStatus.CRITICAL:
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
     elif health["status"] == HealthStatus.WARNING:
-        raise typer.Exit(2)
+        raise typer.Exit(2) from None
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def create(
     title: str = typer.Argument(..., help="Ticket title"),
-    description: Optional[str] = typer.Option(
+    description: str | None = typer.Option(
         None, "--description", "-d", help="Ticket description"
     ),
     priority: Priority = typer.Option(
         Priority.MEDIUM, "--priority", "-p", help="Priority level"
     ),
-    tags: Optional[list[str]] = typer.Option(
+    tags: list[str] | None = typer.Option(
         None, "--tag", "-t", help="Tags (can be specified multiple times)"
     ),
-    assignee: Optional[str] = typer.Option(
+    assignee: str | None = typer.Option(
         None, "--assignee", "-a", help="Assignee username"
     ),
-    project: Optional[str] = typer.Option(
+    project: str | None = typer.Option(
         None,
         "--project",
         help="Parent project/epic ID (synonym for --epic)",
     ),
-    epic: Optional[str] = typer.Option(
+    epic: str | None = typer.Option(
         None,
         "--epic",
         help="Parent epic/project ID (synonym for --project)",
     ),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Create a new ticket with comprehensive health checks."""
+    """Create a new ticket with comprehensive health checks.
+
+    DEPRECATED: Use 'mcp-ticketer ticket create' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket create' instead.[/yellow]\n"
+    )
+
     # IMMEDIATE HEALTH CHECK - Critical for reliability
     health_monitor = QueueHealthMonitor()
     health = health_monitor.check_health()
@@ -1309,7 +1972,7 @@ def create(
                 console.print(
                     "[red]Cannot safely create ticket. Please check system status.[/red]"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
             else:
                 console.print(
                     "[green]✓ Auto-repair successful. Proceeding with ticket creation.[/green]"
@@ -1318,7 +1981,7 @@ def create(
             console.print(
                 "[red]❌ No repair actions available. Manual intervention required.[/red]"
             )
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
     elif health["status"] == HealthStatus.WARNING:
         console.print("[yellow]⚠️  Warning: Queue system has minor issues[/yellow]")
@@ -1476,22 +2139,28 @@ def create(
             )
 
 
-@app.command("list")
+@app.command("list", deprecated=True, hidden=True)
 def list_tickets(
-    state: Optional[TicketState] = typer.Option(
+    state: TicketState | None = typer.Option(
         None, "--state", "-s", help="Filter by state"
     ),
-    priority: Optional[Priority] = typer.Option(
+    priority: Priority | None = typer.Option(
         None, "--priority", "-p", help="Filter by priority"
     ),
     limit: int = typer.Option(10, "--limit", "-l", help="Maximum number of tickets"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """List tickets with optional filters."""
+    """List tickets with optional filters.
 
-    async def _list():
+    DEPRECATED: Use 'mcp-ticketer ticket list' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket list' instead.[/yellow]\n"
+    )
+
+    async def _list() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1531,17 +2200,23 @@ def list_tickets(
     console.print(table)
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def show(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
     comments: bool = typer.Option(False, "--comments", "-c", help="Show comments"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Show detailed ticket information."""
+    """Show detailed ticket information.
 
-    async def _show():
+    DEPRECATED: Use 'mcp-ticketer ticket show' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket show' instead.[/yellow]\n"
+    )
+
+    async def _show() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1555,7 +2230,7 @@ def show(
 
     if not ticket:
         console.print(f"[red]✗[/red] Ticket not found: {ticket_id}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Display ticket details
     console.print(f"\n[bold]Ticket: {ticket.id}[/bold]")
@@ -1581,17 +2256,23 @@ def show(
             console.print(comment.content)
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def comment(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
     content: str = typer.Argument(..., help="Comment content"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Add a comment to a ticket."""
+    """Add a comment to a ticket.
+
+    DEPRECATED: Use 'mcp-ticketer ticket comment' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket comment' instead.[/yellow]\n"
+    )
 
-    async def _comment():
+    async def _comment() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1614,27 +2295,31 @@ def comment(
         console.print(f"Content: {content}")
     except Exception as e:
         console.print(f"[red]✗[/red] Failed to add comment: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def update(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
-    title: Optional[str] = typer.Option(None, "--title", help="New title"),
-    description: Optional[str] = typer.Option(
+    title: str | None = typer.Option(None, "--title", help="New title"),
+    description: str | None = typer.Option(
         None, "--description", "-d", help="New description"
     ),
-    priority: Optional[Priority] = typer.Option(
+    priority: Priority | None = typer.Option(
         None, "--priority", "-p", help="New priority"
     ),
-    assignee: Optional[str] = typer.Option(
-        None, "--assignee", "-a", help="New assignee"
-    ),
-    adapter: Optional[AdapterType] = typer.Option(
+    assignee: str | None = typer.Option(None, "--assignee", "-a", help="New assignee"),
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Update ticket fields."""
+    """Update ticket fields.
+
+    DEPRECATED: Use 'mcp-ticketer ticket update' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket update' instead.[/yellow]\n"
+    )
     updates = {}
     if title:
         updates["title"] = title
@@ -1649,7 +2334,7 @@ def update(
 
     if not updates:
         console.print("[yellow]No updates specified[/yellow]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Get the adapter name
     config = load_config()
@@ -1681,30 +2366,36 @@ def update(
         console.print("[dim]Worker started to process request[/dim]")
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def transition(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
-    state_positional: Optional[TicketState] = typer.Argument(
+    state_positional: TicketState | None = typer.Argument(
         None, help="Target state (positional - deprecated, use --state instead)"
     ),
-    state: Optional[TicketState] = typer.Option(
+    state: TicketState | None = typer.Option(
         None, "--state", "-s", help="Target state (recommended)"
     ),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """Change ticket state with validation.
 
+    DEPRECATED: Use 'mcp-ticketer ticket transition' instead.
+
     Examples:
         # Recommended syntax with flag:
-        mcp-ticketer transition BTA-215 --state done
-        mcp-ticketer transition BTA-215 -s in_progress
+        mcp-ticketer ticket transition BTA-215 --state done
+        mcp-ticketer ticket transition BTA-215 -s in_progress
 
         # Legacy positional syntax (still supported):
-        mcp-ticketer transition BTA-215 done
+        mcp-ticketer ticket transition BTA-215 done
 
     """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket transition' instead.[/yellow]\n"
+    )
+
     # Determine which state to use (prefer flag over positional)
     target_state = state if state is not None else state_positional
 
@@ -1715,7 +2406,7 @@ def transition(
             "  - Flag syntax (recommended): mcp-ticketer transition TICKET-ID --state STATE\n"
             "  - Positional syntax: mcp-ticketer transition TICKET-ID STATE"
         )
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Get the adapter name
     config = load_config()
@@ -1747,20 +2438,26 @@ def transition(
         console.print("[dim]Worker started to process request[/dim]")
 
 
-@app.command()
+@app.command(deprecated=True, hidden=True)
 def search(
-    query: Optional[str] = typer.Argument(None, help="Search query"),
-    state: Optional[TicketState] = typer.Option(None, "--state", "-s"),
-    priority: Optional[Priority] = typer.Option(None, "--priority", "-p"),
-    assignee: Optional[str] = typer.Option(None, "--assignee", "-a"),
+    query: str | None = typer.Argument(None, help="Search query"),
+    state: TicketState | None = typer.Option(None, "--state", "-s"),
+    priority: Priority | None = typer.Option(None, "--priority", "-p"),
+    assignee: str | None = typer.Option(None, "--assignee", "-a"),
     limit: int = typer.Option(10, "--limit", "-l"),
-    adapter: Optional[AdapterType] = typer.Option(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Search tickets with advanced query."""
+    """Search tickets with advanced query.
 
-    async def _search():
+    DEPRECATED: Use 'mcp-ticketer ticket search' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket search' instead.[/yellow]\n"
+    )
+
+    async def _search() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1790,17 +2487,26 @@ def search(
         console.print()
 
 
+# Add ticket command group to main app
+app.add_typer(ticket_app, name="ticket")
+
+# Add platform command group to main app
+app.add_typer(platform_app, name="platform")
+
 # Add queue command to main app
 app.add_typer(queue_app, name="queue")
 
 # Add discover command to main app
 app.add_typer(discover_app, name="discover")
 
+# Add instructions command to main app
+app.add_typer(instruction_app, name="instructions")
+
 
 # Add diagnostics command
-@app.command()
-def diagnose(
-    output_file: Optional[str] = typer.Option(
+@app.command("doctor")
+def doctor_command(
+    output_file: str | None = typer.Option(
         None, "--output", "-o", help="Save full report to file"
     ),
     json_output: bool = typer.Option(
@@ -1810,7 +2516,7 @@ def diagnose(
         False, "--simple", help="Use simple diagnostics (no heavy dependencies)"
     ),
 ) -> None:
-    """Run comprehensive system diagnostics and health check."""
+    """Run comprehensive system diagnostics and health check (alias: diagnose)."""
     if simple:
         from .simple_health import simple_diagnose
 
@@ -1826,7 +2532,7 @@ def diagnose(
 
             console.print("\n" + json.dumps(report, indent=2))
         if report["issues"]:
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
     else:
         try:
             asyncio.run(
@@ -1842,17 +2548,44 @@ def diagnose(
 
             report = simple_diagnose()
             if report["issues"]:
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
 
-@app.command()
-def health() -> None:
-    """Quick health check - shows system status summary."""
+@app.command("diagnose", hidden=True)
+def diagnose_alias(
+    output_file: str | None = typer.Option(
+        None, "--output", "-o", help="Save full report to file"
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Output report in JSON format"
+    ),
+    simple: bool = typer.Option(
+        False, "--simple", help="Use simple diagnostics (no heavy dependencies)"
+    ),
+) -> None:
+    """Run comprehensive system diagnostics and health check (alias for doctor)."""
+    # Call the doctor_command function with the same parameters
+    doctor_command(output_file=output_file, json_output=json_output, simple=simple)
+
+
+@app.command("status")
+def status_command() -> None:
+    """Quick health check - shows system status summary (alias: health)."""
+    from .simple_health import simple_health_check
+
+    result = simple_health_check()
+    if result != 0:
+        raise typer.Exit(result) from None
+
+
+@app.command("health")
+def health_alias() -> None:
+    """Quick health check - shows system status summary (alias for status)."""
     from .simple_health import simple_health_check
 
     result = simple_health_check()
     if result != 0:
-        raise typer.Exit(result)
+        raise typer.Exit(result) from None
 
 
 # Create MCP configuration command group
@@ -1860,18 +2593,554 @@ mcp_app = typer.Typer(
     name="mcp",
     help="Configure MCP integration for AI clients (Claude, Gemini, Codex, Auggie)",
     add_completion=False,
+    invoke_without_command=True,
 )
 
 
+@mcp_app.callback()
+def mcp_callback(
+    ctx: typer.Context,
+    project_path: str | None = typer.Option(
+        None, "--path", "-p", help="Project directory path (default: current directory)"
+    ),
+) -> None:
+    """MCP command group - runs MCP server if no subcommand provided.
+
+    Examples:
+        mcp-ticketer mcp              # Start server in current directory
+        mcp-ticketer mcp --path /dir  # Start server in specific directory
+        mcp-ticketer mcp -p /dir      # Start server (short form)
+        mcp-ticketer mcp status       # Check MCP status
+        mcp-ticketer mcp serve        # Explicitly start server
+
+    """
+    if ctx.invoked_subcommand is None:
+        # No subcommand provided, run the serve command
+        # Change to project directory if provided
+        if project_path:
+            import os
+
+            os.chdir(project_path)
+        # Invoke the serve command through context
+        ctx.invoke(mcp_serve, adapter=None, base_path=None)
+
+
 @app.command()
-def check(queue_id: str = typer.Argument(..., help="Queue ID to check")):
-    """Check status of a queued operation."""
+def install(
+    platform: str | None = typer.Argument(
+        None,
+        help="Platform to install (claude-code, claude-desktop, gemini, codex, auggie)",
+    ),
+    auto_detect: bool = typer.Option(
+        False,
+        "--auto-detect",
+        "-d",
+        help="Auto-detect and show all installed AI platforms",
+    ),
+    install_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Install for all detected platforms",
+    ),
+    adapter: str | None = typer.Option(
+        None,
+        "--adapter",
+        "-a",
+        help="Adapter type to use (interactive prompt if not specified)",
+    ),
+    project_path: str | None = typer.Option(
+        None, "--path", help="Project path (default: current directory)"
+    ),
+    global_config: bool = typer.Option(
+        False,
+        "--global",
+        "-g",
+        help="Save to global config instead of project-specific",
+    ),
+    base_path: str | None = typer.Option(
+        None,
+        "--base-path",
+        "-p",
+        help="Base path for ticket storage (AITrackdown only)",
+    ),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="API key for Linear or API token for JIRA"
+    ),
+    team_id: str | None = typer.Option(
+        None, "--team-id", help="Linear team ID (required for Linear adapter)"
+    ),
+    jira_server: str | None = typer.Option(
+        None,
+        "--jira-server",
+        help="JIRA server URL (e.g., https://company.atlassian.net)",
+    ),
+    jira_email: str | None = typer.Option(
+        None, "--jira-email", help="JIRA user email for authentication"
+    ),
+    jira_project: str | None = typer.Option(
+        None, "--jira-project", help="Default JIRA project key"
+    ),
+    github_owner: str | None = typer.Option(
+        None, "--github-owner", help="GitHub repository owner"
+    ),
+    github_repo: str | None = typer.Option(
+        None, "--github-repo", help="GitHub repository name"
+    ),
+    github_token: str | None = typer.Option(
+        None, "--github-token", help="GitHub Personal Access Token"
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be done without making changes (for platform installation)",
+    ),
+) -> None:
+    """Install MCP server configuration for AI platforms.
+
+    This command configures mcp-ticketer as an MCP server for various AI
+    platforms. It updates platform-specific configuration files to enable
+    mcp-ticketer integration.
+
+    RECOMMENDED: Use 'mcp-ticketer setup' for first-time setup, which
+    handles both adapter configuration and platform installation together.
+
+    Platform Installation:
+        # Auto-detect and prompt for platform selection
+        mcp-ticketer install
+
+        # Show all detected platforms
+        mcp-ticketer install --auto-detect
+
+        # Install for all detected platforms
+        mcp-ticketer install --all
+
+        # Install for specific platform
+        mcp-ticketer install claude-code     # Claude Code (project-level)
+        mcp-ticketer install claude-desktop  # Claude Desktop (global)
+        mcp-ticketer install gemini          # Gemini CLI
+        mcp-ticketer install codex           # Codex
+        mcp-ticketer install auggie          # Auggie
+
+    Legacy Usage (adapter setup, deprecated - use 'init' or 'setup' instead):
+        mcp-ticketer install --adapter linear  # Use 'init' or 'setup' instead
+
+    """
+    from .platform_detection import PlatformDetector, get_platform_by_name
+
+    detector = PlatformDetector()
+
+    # Handle auto-detect flag (just show detected platforms and exit)
+    if auto_detect:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if not detected:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print("\n[bold]Supported platforms:[/bold]")
+            console.print("  • Claude Code - Project-level configuration")
+            console.print("  • Claude Desktop - Global GUI application")
+            console.print("  • Auggie - CLI tool with global config")
+            console.print("  • Codex - CLI tool with global config")
+            console.print("  • Gemini - CLI tool with project/global config")
+            console.print(
+                "\n[dim]Install these platforms to use them with mcp-ticketer.[/dim]"
+            )
+            return
+
+        console.print("[bold]Detected AI platforms:[/bold]\n")
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Platform", style="green")
+        table.add_column("Status", style="yellow")
+        table.add_column("Scope", style="blue")
+        table.add_column("Config Path", style="dim")
+
+        for plat in detected:
+            status = "✓ Installed" if plat.is_installed else "⚠ Config Issue"
+            table.add_row(plat.display_name, status, plat.scope, str(plat.config_path))
+
+        console.print(table)
+        console.print(
+            "\n[dim]Run 'mcp-ticketer install <platform>' to configure a specific platform[/dim]"
+        )
+        console.print(
+            "[dim]Run 'mcp-ticketer install --all' to configure all detected platforms[/dim]"
+        )
+        return
+
+    # Handle --all flag (install for all detected platforms)
+    if install_all:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if not detected:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print(
+                "Run 'mcp-ticketer install --auto-detect' to see supported platforms."
+            )
+            return
+
+        # Handle dry-run mode - show what would be installed without actually installing
+        if dry_run:
+            console.print(
+                "\n[yellow]DRY RUN - The following platforms would be configured:[/yellow]\n"
+            )
+
+            installable_count = 0
+            for plat in detected:
+                if plat.is_installed:
+                    console.print(f"  ✓ {plat.display_name} ({plat.scope})")
+                    installable_count += 1
+                else:
+                    console.print(
+                        f"  ⚠ {plat.display_name} ({plat.scope}) - would be skipped (configuration issue)"
+                    )
+
+            console.print(
+                f"\n[dim]Would configure {installable_count} platform(s)[/dim]"
+            )
+            return
+
+        console.print(
+            f"[bold]Installing for {len(detected)} detected platform(s)...[/bold]\n"
+        )
+
+        # Import configuration functions
+        from .auggie_configure import configure_auggie_mcp
+        from .codex_configure import configure_codex_mcp
+        from .gemini_configure import configure_gemini_mcp
+        from .mcp_configure import configure_claude_mcp
+
+        # Map platform names to configuration functions
+        platform_mapping = {
+            "claude-code": lambda: configure_claude_mcp(
+                global_config=False, force=True
+            ),
+            "claude-desktop": lambda: configure_claude_mcp(
+                global_config=True, force=True
+            ),
+            "auggie": lambda: configure_auggie_mcp(force=True),
+            "gemini": lambda: configure_gemini_mcp(scope="project", force=True),
+            "codex": lambda: configure_codex_mcp(force=True),
+        }
+
+        success_count = 0
+        failed = []
+
+        for plat in detected:
+            if not plat.is_installed:
+                console.print(
+                    f"[yellow]⚠[/yellow]  Skipping {plat.display_name} (configuration issue)"
+                )
+                continue
+
+            config_func = platform_mapping.get(plat.name)
+            if not config_func:
+                console.print(
+                    f"[yellow]⚠[/yellow]  No installer for {plat.display_name}"
+                )
+                continue
+
+            try:
+                console.print(f"[cyan]Installing for {plat.display_name}...[/cyan]")
+                config_func()
+                success_count += 1
+            except Exception as e:
+                console.print(
+                    f"[red]✗[/red]  Failed to install for {plat.display_name}: {e}"
+                )
+                failed.append(plat.display_name)
+
+        console.print(
+            f"\n[bold]Installation complete:[/bold] {success_count} succeeded"
+        )
+        if failed:
+            console.print(f"[red]Failed:[/red] {', '.join(failed)}")
+        return
+
+    # If no platform argument and no adapter flag, auto-detect and prompt
+    if platform is None and adapter is None:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        # Filter to only installed platforms
+        installed = [p for p in detected if p.is_installed]
+
+        if not installed:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print("\n[bold]To see supported platforms:[/bold]")
+            console.print("  mcp-ticketer install --auto-detect")
+            console.print("\n[bold]Or run legacy adapter setup:[/bold]")
+            console.print("  mcp-ticketer install --adapter <adapter-type>")
+            return
+
+        # Show detected platforms and prompt for selection
+        console.print("[bold]Detected AI platforms:[/bold]\n")
+        for idx, plat in enumerate(installed, 1):
+            console.print(f"  {idx}. {plat.display_name} ({plat.scope})")
+
+        console.print(
+            "\n[dim]Enter the number of the platform to configure, or 'q' to quit:[/dim]"
+        )
+        choice = typer.prompt("Select platform")
+
+        if choice.lower() == "q":
+            console.print("Installation cancelled.")
+            return
+
+        try:
+            idx = int(choice) - 1
+            if idx < 0 or idx >= len(installed):
+                console.print("[red]Invalid selection.[/red]")
+                raise typer.Exit(1) from None
+            platform = installed[idx].name
+        except ValueError as e:
+            console.print("[red]Invalid input. Please enter a number.[/red]")
+            raise typer.Exit(1) from e
+
+    # If platform argument is provided, handle MCP platform installation (NEW SYNTAX)
+    if platform is not None:
+        # Validate that the platform is actually installed
+        platform_info = get_platform_by_name(
+            platform, project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if platform_info and not platform_info.is_installed:
+            console.print(
+                f"[yellow]⚠[/yellow]  {platform_info.display_name} was detected but has a configuration issue."
+            )
+            console.print(f"[dim]Config path: {platform_info.config_path}[/dim]\n")
+
+            proceed = typer.confirm(
+                "Do you want to proceed with installation anyway?", default=False
+            )
+            if not proceed:
+                console.print("Installation cancelled.")
+                return
+
+        elif not platform_info:
+            # Platform not detected at all - warn but allow proceeding
+            console.print(
+                f"[yellow]⚠[/yellow]  Platform '{platform}' not detected on this system."
+            )
+            console.print(
+                "[dim]Run 'mcp-ticketer install --auto-detect' to see detected platforms.[/dim]\n"
+            )
+
+            proceed = typer.confirm(
+                "Do you want to proceed with installation anyway?", default=False
+            )
+            if not proceed:
+                console.print("Installation cancelled.")
+                return
+
+        # Import configuration functions
+        from .auggie_configure import configure_auggie_mcp
+        from .codex_configure import configure_codex_mcp
+        from .gemini_configure import configure_gemini_mcp
+        from .mcp_configure import configure_claude_mcp
+
+        # Map platform names to configuration functions
+        platform_mapping = {
+            "claude-code": {
+                "func": lambda: configure_claude_mcp(global_config=False, force=True),
+                "name": "Claude Code",
+            },
+            "claude-desktop": {
+                "func": lambda: configure_claude_mcp(global_config=True, force=True),
+                "name": "Claude Desktop",
+            },
+            "auggie": {
+                "func": lambda: configure_auggie_mcp(force=True),
+                "name": "Auggie",
+            },
+            "gemini": {
+                "func": lambda: configure_gemini_mcp(scope="project", force=True),
+                "name": "Gemini CLI",
+            },
+            "codex": {
+                "func": lambda: configure_codex_mcp(force=True),
+                "name": "Codex",
+            },
+        }
+
+        if platform not in platform_mapping:
+            console.print(f"[red]Unknown platform: {platform}[/red]")
+            console.print("\n[bold]Available platforms:[/bold]")
+            for p in platform_mapping.keys():
+                console.print(f"  • {p}")
+            raise typer.Exit(1) from None
+
+        config = platform_mapping[platform]
+
+        if dry_run:
+            console.print(f"[cyan]DRY RUN - Would install for {config['name']}[/cyan]")
+            return
+
+        try:
+            config["func"]()
+        except Exception as e:
+            console.print(f"[red]Installation failed: {e}[/red]")
+            raise typer.Exit(1) from e
+        return
+
+    # Otherwise, delegate to init for adapter initialization (LEGACY BEHAVIOR)
+    # This makes 'install' and 'init' synonymous when called without platform argument
+    init(
+        adapter=adapter,
+        project_path=project_path,
+        global_config=global_config,
+        base_path=base_path,
+        api_key=api_key,
+        team_id=team_id,
+        jira_server=jira_server,
+        jira_email=jira_email,
+        jira_project=jira_project,
+        github_owner=github_owner,
+        github_repo=github_repo,
+        github_token=github_token,
+    )
+
+
+@app.command()
+def remove(
+    platform: str | None = typer.Argument(
+        None,
+        help="Platform to remove (claude-code, claude-desktop, auggie, gemini, codex)",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would be done without making changes"
+    ),
+) -> None:
+    """Remove mcp-ticketer from AI platforms.
+
+    Without arguments, shows help and available platforms.
+    With a platform argument, removes MCP configuration for that platform.
+
+    Examples:
+        # Remove from Claude Code (project-level)
+        mcp-ticketer remove claude-code
+
+        # Remove from Claude Desktop (global)
+        mcp-ticketer remove claude-desktop
+
+        # Remove from Auggie
+        mcp-ticketer remove auggie
+
+        # Dry run to preview changes
+        mcp-ticketer remove claude-code --dry-run
+
+    """
+    # If no platform specified, show help message
+    if platform is None:
+        console.print("[bold]Remove mcp-ticketer from AI platforms[/bold]\n")
+        console.print("Usage: mcp-ticketer remove <platform>\n")
+        console.print("[bold]Available platforms:[/bold]")
+        console.print("  • claude-code     - Claude Code (project-level)")
+        console.print("  • claude-desktop  - Claude Desktop (global)")
+        console.print("  • auggie          - Auggie (global)")
+        console.print("  • gemini          - Gemini CLI (project-level by default)")
+        console.print("  • codex           - Codex (global)")
+        return
+
+    # Import removal functions
+    from .auggie_configure import remove_auggie_mcp
+    from .codex_configure import remove_codex_mcp
+    from .gemini_configure import remove_gemini_mcp
+    from .mcp_configure import remove_claude_mcp
+
+    # Map platform names to removal functions
+    platform_mapping = {
+        "claude-code": {
+            "func": lambda: remove_claude_mcp(global_config=False, dry_run=dry_run),
+            "name": "Claude Code",
+        },
+        "claude-desktop": {
+            "func": lambda: remove_claude_mcp(global_config=True, dry_run=dry_run),
+            "name": "Claude Desktop",
+        },
+        "auggie": {
+            "func": lambda: remove_auggie_mcp(dry_run=dry_run),
+            "name": "Auggie",
+        },
+        "gemini": {
+            "func": lambda: remove_gemini_mcp(scope="project", dry_run=dry_run),
+            "name": "Gemini CLI",
+        },
+        "codex": {
+            "func": lambda: remove_codex_mcp(dry_run=dry_run),
+            "name": "Codex",
+        },
+    }
+
+    if platform not in platform_mapping:
+        console.print(f"[red]Unknown platform: {platform}[/red]")
+        console.print("\n[bold]Available platforms:[/bold]")
+        for p in platform_mapping.keys():
+            console.print(f"  • {p}")
+        raise typer.Exit(1) from None
+
+    config = platform_mapping[platform]
+
+    try:
+        config["func"]()
+    except Exception as e:
+        console.print(f"[red]Removal failed: {e}[/red]")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def uninstall(
+    platform: str | None = typer.Argument(
+        None,
+        help="Platform to uninstall (claude-code, claude-desktop, auggie, gemini, codex)",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would be done without making changes"
+    ),
+) -> None:
+    """Uninstall mcp-ticketer from AI platforms (alias for remove).
+
+    This is an alias for the 'remove' command.
+
+    Without arguments, shows help and available platforms.
+    With a platform argument, removes MCP configuration for that platform.
+
+    Examples:
+        # Uninstall from Claude Code (project-level)
+        mcp-ticketer uninstall claude-code
+
+        # Uninstall from Claude Desktop (global)
+        mcp-ticketer uninstall claude-desktop
+
+        # Uninstall from Auggie
+        mcp-ticketer uninstall auggie
+
+        # Dry run to preview changes
+        mcp-ticketer uninstall claude-code --dry-run
+
+    """
+    # Call the remove command with the same parameters
+    remove(platform=platform, dry_run=dry_run)
+
+
+@app.command(deprecated=True, hidden=True)
+def check(queue_id: str = typer.Argument(..., help="Queue ID to check")) -> None:
+    """Check status of a queued operation.
+
+    DEPRECATED: Use 'mcp-ticketer ticket check' instead.
+    """
+    console.print(
+        "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket check' instead.[/yellow]\n"
+    )
     queue = Queue()
     item = queue.get_item(queue_id)
 
     if not item:
         console.print(f"[red]Queue item not found: {queue_id}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Display status
     console.print(f"\n[bold]Queue Item: {item.id}[/bold]")
@@ -1905,19 +3174,19 @@ def check(queue_id: str = typer.Argument(..., help="Queue ID to check")):
         console.print(f"\nRetry Count: {item.retry_count}")
 
 
-@app.command()
-def serve(
-    adapter: Optional[AdapterType] = typer.Option(
+@mcp_app.command(name="serve")
+def mcp_serve(
+    adapter: AdapterType | None = typer.Option(
         None, "--adapter", "-a", help="Override default adapter type"
     ),
-    base_path: Optional[str] = typer.Option(
+    base_path: str | None = typer.Option(
         None, "--base-path", help="Base path for AITrackdown adapter"
     ),
-):
+) -> None:
     """Start MCP server for JSON-RPC communication over stdio.
 
     This command is used by Claude Code/Desktop when connecting to the MCP server.
-    You typically don't need to run this manually - use 'mcp-ticketer mcp' to configure.
+    You typically don't need to run this manually - use 'mcp-ticketer install add' to configure.
 
     Configuration Resolution:
     - When MCP server starts, it uses the current working directory (cwd)
@@ -1927,12 +3196,13 @@ def serve(
       2. Global: ~/.mcp-ticketer/config.json
       3. Default: aitrackdown adapter with .aitrackdown base path
     """
-    from ..mcp.server import MCPTicketServer
+    from ..mcp.server.server_sdk import configure_adapter
+    from ..mcp.server.server_sdk import main as sdk_main
 
     # Load configuration (respects project-specific config in cwd)
     config = load_config()
 
-    # Determine adapter type with priority: CLI arg > .env files > config > default
+    # Determine adapter type with priority: CLI arg > config > .env files > default
     if adapter:
         # Priority 1: Command line argument
         adapter_type = adapter.value
@@ -1940,18 +3210,24 @@ def serve(
         adapters_config = config.get("adapters", {})
         adapter_config = adapters_config.get(adapter_type, {})
     else:
-        # Priority 2: .env files
-        from ..mcp.server import _load_env_configuration
-
-        env_config = _load_env_configuration()
-        if env_config:
-            adapter_type = env_config["adapter_type"]
-            adapter_config = env_config["adapter_config"]
-        else:
-            # Priority 3: Configuration file
-            adapter_type = config.get("default_adapter", "aitrackdown")
+        # Priority 2: Configuration file (project-specific)
+        adapter_type = config.get("default_adapter")
+        if adapter_type:
             adapters_config = config.get("adapters", {})
             adapter_config = adapters_config.get(adapter_type, {})
+        else:
+            # Priority 3: .env files (auto-detection fallback)
+            from ..mcp.server.main import _load_env_configuration
+
+            env_config = _load_env_configuration()
+            if env_config:
+                adapter_type = env_config["adapter_type"]
+                adapter_config = env_config["adapter_config"]
+            else:
+                # Priority 4: Default fallback
+                adapter_type = "aitrackdown"
+                adapters_config = config.get("adapters", {})
+                adapter_config = adapters_config.get(adapter_type, {})
 
     # Override with command line options if provided (highest priority)
     if base_path and adapter_type == "aitrackdown":
@@ -1968,21 +3244,22 @@ def serve(
     if sys.stderr.isatty():
         # Only print if stderr is a terminal (not redirected)
         console.file = sys.stderr
-        console.print(f"[green]Starting MCP server[/green] with {adapter_type} adapter")
+        console.print(
+            f"[green]Starting MCP SDK server[/green] with {adapter_type} adapter"
+        )
         console.print(
             "[dim]Server running on stdio. Send JSON-RPC requests via stdin.[/dim]"
         )
 
-    # Create and run server
+    # Configure adapter and run SDK server
     try:
-        server = MCPTicketServer(adapter_type, adapter_config)
-        asyncio.run(server.run())
+        configure_adapter(adapter_type, adapter_config)
+        sdk_main()
     except KeyboardInterrupt:
-        # Also send this to stderr
+        # Send this to stderr
         if sys.stderr.isatty():
             console.print("\n[yellow]Server stopped by user[/yellow]")
-        if "server" in locals():
-            asyncio.run(server.stop())
+        sys.exit(0)
     except Exception as e:
         # Log error to stderr
         sys.stderr.write(f"MCP server error: {e}\n")
@@ -2000,7 +3277,7 @@ def mcp_claude(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Claude Code to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and updates
@@ -2026,7 +3303,7 @@ def mcp_claude(
         configure_claude_mcp(global_config=global_config, force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="gemini")
@@ -2040,7 +3317,7 @@ def mcp_gemini(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Gemini CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2067,13 +3344,13 @@ def mcp_gemini(
         console.print(
             f"[red]✗ Invalid scope:[/red] '{scope}'. Must be 'project' or 'user'"
         )
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     try:
         configure_gemini_mcp(scope=scope, force=force)  # type: ignore
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="codex")
@@ -2081,7 +3358,7 @@ def mcp_codex(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Codex CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2105,7 +3382,7 @@ def mcp_codex(
         configure_codex_mcp(force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="auggie")
@@ -2113,7 +3390,7 @@ def mcp_auggie(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Auggie CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2137,16 +3414,134 @@ def mcp_auggie(
         configure_auggie_mcp(force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
+
+
+@mcp_app.command(name="status")
+def mcp_status() -> None:
+    """Check MCP server status.
+
+    Shows whether the MCP server is configured and running for various platforms.
+
+    Examples:
+        mcp-ticketer mcp status
+
+    """
+    import json
+    from pathlib import Path
+
+    console.print("[bold]MCP Server Status[/bold]\n")
+
+    # Check project-level configuration
+    project_config = Path.cwd() / ".mcp-ticketer" / "config.json"
+    if project_config.exists():
+        console.print(f"[green]✓[/green] Project config found: {project_config}")
+        try:
+            with open(project_config) as f:
+                config = json.load(f)
+                adapter = config.get("default_adapter", "aitrackdown")
+                console.print(f"  Default adapter: [cyan]{adapter}[/cyan]")
+        except Exception as e:
+            console.print(f"  [yellow]Warning: Could not read config: {e}[/yellow]")
+    else:
+        console.print("[yellow]○[/yellow] No project config found")
+
+    # Check Claude Code configuration
+    claude_code_config = Path.cwd() / ".mcp" / "config.json"
+    if claude_code_config.exists():
+        console.print(
+            f"\n[green]✓[/green] Claude Code configured: {claude_code_config}"
+        )
+    else:
+        console.print("\n[yellow]○[/yellow] Claude Code not configured")
+
+    # Check Claude Desktop configuration
+    claude_desktop_config = (
+        Path.home()
+        / "Library"
+        / "Application Support"
+        / "Claude"
+        / "claude_desktop_config.json"
+    )
+    if claude_desktop_config.exists():
+        try:
+            with open(claude_desktop_config) as f:
+                config = json.load(f)
+                if "mcpServers" in config and "mcp-ticketer" in config["mcpServers"]:
+                    console.print(
+                        f"[green]✓[/green] Claude Desktop configured: {claude_desktop_config}"
+                    )
+                else:
+                    console.print(
+                        "[yellow]○[/yellow] Claude Desktop config exists but mcp-ticketer not found"
+                    )
+        except Exception:
+            console.print(
+                "[yellow]○[/yellow] Claude Desktop config exists but could not be read"
+            )
+    else:
+        console.print("[yellow]○[/yellow] Claude Desktop not configured")
+
+    # Check Gemini configuration
+    gemini_project_config = Path.cwd() / ".gemini" / "settings.json"
+    gemini_user_config = Path.home() / ".gemini" / "settings.json"
+    if gemini_project_config.exists():
+        console.print(
+            f"\n[green]✓[/green] Gemini (project) configured: {gemini_project_config}"
+        )
+    elif gemini_user_config.exists():
+        console.print(
+            f"\n[green]✓[/green] Gemini (user) configured: {gemini_user_config}"
+        )
+    else:
+        console.print("\n[yellow]○[/yellow] Gemini not configured")
+
+    # Check Codex configuration
+    codex_config = Path.home() / ".codex" / "config.toml"
+    if codex_config.exists():
+        console.print(f"[green]✓[/green] Codex configured: {codex_config}")
+    else:
+        console.print("[yellow]○[/yellow] Codex not configured")
+
+    # Check Auggie configuration
+    auggie_config = Path.home() / ".augment" / "settings.json"
+    if auggie_config.exists():
+        console.print(f"[green]✓[/green] Auggie configured: {auggie_config}")
+    else:
+        console.print("[yellow]○[/yellow] Auggie not configured")
+
+    console.print(
+        "\n[dim]Run 'mcp-ticketer install <platform>' to configure a platform[/dim]"
+    )
+
+
+@mcp_app.command(name="stop")
+def mcp_stop() -> None:
+    """Stop MCP server (placeholder - MCP runs on-demand via stdio).
+
+    Note: The MCP server runs on-demand when AI clients connect via stdio.
+    It doesn't run as a persistent background service, so there's nothing to stop.
+    This command is provided for consistency but has no effect.
+
+    Examples:
+        mcp-ticketer mcp stop
+
+    """
+    console.print(
+        "[yellow]ℹ[/yellow]  MCP server runs on-demand via stdio (not as a background service)"
+    )
+    console.print("There is no persistent server process to stop.")
+    console.print(
+        "\n[dim]The server starts automatically when AI clients connect and stops when they disconnect.[/dim]"
+    )
 
 
 # Add command groups to main app (must be after all subcommands are defined)
-app.add_typer(linear_app, name="linear")
 app.add_typer(mcp_app, name="mcp")
 
 
-def main():
-    """Main entry point."""
+def main() -> None:
+    """Execute the main CLI application entry point."""
     app()