mcp-ticketer 0.4.3__py3-none-any.whl → 0.4.5__py3-none-any.whl

mcp_ticketer/cli/main.py

@@ -20,8 +20,7 @@ from ..core.models import Comment, SearchQuery
 from ..queue import Queue, QueueStatus, WorkerManager
 from ..queue.health_monitor import HealthStatus, QueueHealthMonitor
 from ..queue.ticket_registry import TicketRegistry
-from .configure import (configure_wizard, set_adapter_config,
-                        show_current_config)
+from .configure import configure_wizard, set_adapter_config, show_current_config
 from .diagnostics import run_diagnostics
 from .discover import app as discover_app
 from .migrate_config import migrate_config_command
@@ -679,7 +678,9 @@ def init(
             if not linear_team_key and not linear_team_id and not discovered:
                 console.print("\n[bold]Linear Team Configuration[/bold]")
                 console.print("Enter your team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
-                console.print("[dim]Find it in: Linear Settings → Teams → Your Team → Key field[/dim]\n")
+                console.print(
+                    "[dim]Find it in: Linear Settings → Teams → Your Team → Key field[/dim]\n"
+                )
 
                 linear_team_key = typer.prompt("Team key")
 
@@ -893,10 +894,11 @@ def _show_next_steps(
         console.print("\n3. [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("\n4. [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]")
@@ -1871,6 +1873,10 @@ mcp_app = typer.Typer(
 
 @app.command()
 def install(
+    platform: str | None = typer.Argument(
+        None,
+        help="Platform to install (claude-code, claude-desktop, gemini, codex, auggie)",
+    ),
     adapter: str | None = typer.Option(
         None,
         "--adapter",
@@ -1918,41 +1924,31 @@ def install(
     github_token: str | None = typer.Option(
         None, "--github-token", help="GitHub Personal Access Token"
     ),
-    platform: str | None = typer.Option(
-        None,
-        "--platform",
-        help="Platform to configure MCP for (claude-code, claude-desktop, auggie, gemini, codex)",
-    ),
     dry_run: bool = typer.Option(
         False,
         "--dry-run",
         help="Show what would be done without making changes (for platform installation)",
     ),
 ) -> None:
-    """Install and initialize mcp-ticketer (synonymous with 'init' and 'setup').
+    """Install MCP for AI platforms OR initialize adapter setup.
 
-    Without arguments, runs interactive setup wizard to configure your ticket adapter.
-    With --platform, installs MCP configuration for AI platforms.
+    With platform argument (new syntax): Install MCP configuration for AI platforms
+    Without platform argument (legacy): Run adapter setup wizard (same as 'init' and 'setup')
 
-    This command serves two purposes:
-    1. Adapter initialization (same as 'init' and 'setup')
-    2. Platform MCP configuration (when using --platform flag)
-
-    Examples:
-        # Interactive setup (same as 'init' and 'setup')
-        mcp-ticketer install
+    New Command Structure:
+        # Install MCP for AI platforms
+        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
 
-        # Setup with specific adapter
+    Legacy Adapter Setup (still supported):
+        mcp-ticketer install                 # Interactive setup wizard
         mcp-ticketer install --adapter linear
 
-        # Install MCP for Claude Code
-        mcp-ticketer install --platform claude-code
-
-        # Install MCP for Claude Desktop
-        mcp-ticketer install --platform claude-desktop
-
     """
-    # If platform flag is provided, handle MCP platform installation
+    # If platform argument is provided, handle MCP platform installation (NEW SYNTAX)
     if platform is not None:
         # Import configuration functions
         from .auggie_configure import configure_auggie_mcp
@@ -2004,8 +2000,8 @@ def install(
             raise typer.Exit(1)
         return
 
-    # Otherwise, delegate to init for adapter initialization
-    # This makes 'install' and 'init' synonymous when called without --platform
+    # 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,
@@ -2429,6 +2425,125 @@ def mcp_auggie(
         raise typer.Exit(1)
 
 
+@mcp_app.command(name="status")
+def mcp_status():
+    """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():
+    """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(mcp_app, name="mcp")
 

mcp_ticketer/cli/mcp_configure.py

@@ -2,65 +2,43 @@
 
 import json
 import os
-import shutil
 import sys
 from pathlib import Path
 
 from rich.console import Console
 
+from .python_detection import get_mcp_ticketer_python
+
 console = Console()
 
 
-def find_mcp_ticketer_binary() -> str:
-    """Find the mcp-ticketer binary path.
+def load_env_file(env_path: Path) -> dict[str, str]:
+    """Load environment variables from .env file.
 
-    Returns:
-        Path to mcp-ticketer binary (prefers simple 'mcp-ticketer' if in PATH)
+    Args:
+        env_path: Path to .env file
 
-    Raises:
-        FileNotFoundError: If binary not found
+    Returns:
+        Dict of environment variable key-value pairs
 
     """
-    # PRIORITY 1: Check PATH first (like kuzu-memory)
-    # This allows the system to resolve the binary location
-    which_result = shutil.which("mcp-ticketer")
-    if which_result:
-        # Return just "mcp-ticketer" for PATH-based installations
-        # This is more portable and matches kuzu-memory's approach
-        return "mcp-ticketer"
-
-    # FALLBACK: Check development environment
-    import mcp_ticketer
-
-    package_path = Path(mcp_ticketer.__file__).parent.parent.parent
-
-    # Check for virtual environment bin
-    possible_paths = [
-        # Development paths
-        package_path / "venv" / "bin" / "mcp-ticketer",
-        package_path / ".venv" / "bin" / "mcp-ticketer",
-        package_path / "test_venv" / "bin" / "mcp-ticketer",
-        # System installation
-        Path.home() / ".local" / "bin" / "mcp-ticketer",
-        # pipx installation
-        Path.home()
-        / ".local"
-        / "pipx"
-        / "venvs"
-        / "mcp-ticketer"
-        / "bin"
-        / "mcp-ticketer",
-    ]
-
-    # Check possible paths
-    for path in possible_paths:
-        if path.exists():
-            return str(path.resolve())
-
-    raise FileNotFoundError(
-        "Could not find mcp-ticketer binary. Please ensure mcp-ticketer is installed.\n"
-        "Install with: pip install mcp-ticketer"
-    )
+    env_vars = {}
+    if not env_path.exists():
+        return env_vars
+
+    with open(env_path) as f:
+        for line in f:
+            line = line.strip()
+            # Skip comments and empty lines
+            if not line or line.startswith("#"):
+                continue
+
+            # Parse KEY=VALUE format
+            if "=" in line:
+                key, value = line.split("=", 1)
+                env_vars[key.strip()] = value.strip()
+
+    return env_vars
 
 
 def load_project_config() -> dict:
@@ -129,8 +107,8 @@ def find_claude_mcp_config(global_config: bool = False) -> Path:
                 Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
             )
     else:
-        # Project-level configuration
-        config_path = Path.cwd() / ".mcp" / "config.json"
+        # Project-level configuration for Claude Code
+        config_path = Path.cwd() / ".claude" / "settings.local.json"
 
     return config_path
 
@@ -149,7 +127,7 @@ def load_claude_mcp_config(config_path: Path) -> dict:
         with open(config_path) as f:
             return json.load(f)
 
-    # Return empty structure
+    # Return empty structure (Claude Code uses mcpServers key)
     return {"mcpServers": {}}
 
 
@@ -170,28 +148,37 @@ def save_claude_mcp_config(config_path: Path, config: dict) -> None:
 
 
 def create_mcp_server_config(
-    binary_path: str, project_config: dict, cwd: str | None = None
+    python_path: str, project_config: dict, project_path: str | None = None
 ) -> dict:
     """Create MCP server configuration for mcp-ticketer.
 
     Args:
-        binary_path: Path to mcp-ticketer binary
+        python_path: Path to Python executable in mcp-ticketer venv
         project_config: Project configuration from .mcp-ticketer/config.json
-        cwd: Working directory for server (optional)
+        project_path: Project directory path (optional)
 
     Returns:
-        MCP server configuration dict
+        MCP server configuration dict matching Claude Code stdio pattern
 
     """
+    # Ensure python3 is used (not python)
+    if python_path.endswith("/python"):
+        python_path = python_path.replace("/python", "/python3")
+
+    # Use module invocation pattern: python -m mcp_ticketer.mcp.server
+    args = ["-m", "mcp_ticketer.mcp.server"]
+
+    # Add project path if provided
+    if project_path:
+        args.append(project_path)
+
+    # REQUIRED: Add "type": "stdio" for Claude Code compatibility
     config = {
-        "command": binary_path,
-        "args": ["mcp", "serve"],  # Use 'mcp serve' command to start MCP server
+        "type": "stdio",
+        "command": python_path,
+        "args": args,
     }
 
-    # Add working directory if provided
-    if cwd:
-        config["cwd"] = cwd
-
     # Add environment variables based on adapter
     adapter = project_config.get("default_adapter", "aitrackdown")
     adapters_config = project_config.get("adapters", {})
@@ -199,15 +186,49 @@ def create_mcp_server_config(
 
     env_vars = {}
 
-    # Add adapter-specific environment variables
+    # Add PYTHONPATH for project context
+    if project_path:
+        env_vars["PYTHONPATH"] = project_path
+
+    # Add MCP_TICKETER_ADAPTER to identify which adapter to use
+    env_vars["MCP_TICKETER_ADAPTER"] = adapter
+
+    # Load environment variables from .env.local if it exists
+    if project_path:
+        env_file_path = Path(project_path) / ".env.local"
+        env_file_vars = load_env_file(env_file_path)
+
+        # Add relevant adapter-specific vars from .env.local
+        adapter_env_keys = {
+            "linear": ["LINEAR_API_KEY", "LINEAR_TEAM_ID", "LINEAR_TEAM_KEY"],
+            "github": ["GITHUB_TOKEN", "GITHUB_OWNER", "GITHUB_REPO"],
+            "jira": [
+                "JIRA_ACCESS_USER",
+                "JIRA_ACCESS_TOKEN",
+                "JIRA_ORGANIZATION_ID",
+                "JIRA_URL",
+                "JIRA_EMAIL",
+                "JIRA_API_TOKEN",
+            ],
+            "aitrackdown": [],  # No specific env vars needed
+        }
+
+        # Include adapter-specific env vars from .env.local
+        for key in adapter_env_keys.get(adapter, []):
+            if key in env_file_vars:
+                env_vars[key] = env_file_vars[key]
+
+    # Fallback: Add adapter-specific environment variables from project config
     if adapter == "linear" and "api_key" in adapter_config:
-        env_vars["LINEAR_API_KEY"] = adapter_config["api_key"]
+        if "LINEAR_API_KEY" not in env_vars:
+            env_vars["LINEAR_API_KEY"] = adapter_config["api_key"]
     elif adapter == "github" and "token" in adapter_config:
-        env_vars["GITHUB_TOKEN"] = adapter_config["token"]
+        if "GITHUB_TOKEN" not in env_vars:
+            env_vars["GITHUB_TOKEN"] = adapter_config["token"]
     elif adapter == "jira":
-        if "api_token" in adapter_config:
+        if "api_token" in adapter_config and "JIRA_API_TOKEN" not in env_vars:
             env_vars["JIRA_API_TOKEN"] = adapter_config["api_token"]
-        if "email" in adapter_config:
+        if "email" in adapter_config and "JIRA_EMAIL" not in env_vars:
             env_vars["JIRA_EMAIL"] = adapter_config["email"]
 
     if env_vars:
@@ -284,18 +305,31 @@ def configure_claude_mcp(global_config: bool = False, force: bool = False) -> No
         force: Overwrite existing configuration
 
     Raises:
-        FileNotFoundError: If binary or project config not found
+        FileNotFoundError: If Python executable or project config not found
         ValueError: If configuration is invalid
 
     """
-    # Step 1: Find mcp-ticketer binary
-    console.print("[cyan]🔍 Finding mcp-ticketer binary...[/cyan]")
+    # Determine project path for venv detection
+    project_path = Path.cwd() if not global_config else None
+
+    # Step 1: Find Python executable (project-specific if available)
+    console.print("[cyan]🔍 Finding mcp-ticketer Python executable...[/cyan]")
     try:
-        binary_path = find_mcp_ticketer_binary()
-        console.print(f"[green]✓[/green] Found: {binary_path}")
-    except FileNotFoundError as e:
-        console.print(f"[red]✗[/red] {e}")
-        raise
+        python_path = get_mcp_ticketer_python(project_path=project_path)
+        console.print(f"[green]✓[/green] Found: {python_path}")
+
+        # Show if using project venv or fallback
+        if project_path and str(project_path / ".venv") in python_path:
+            console.print("[dim]Using project-specific venv[/dim]")
+        else:
+            console.print("[dim]Using pipx/system Python[/dim]")
+    except Exception as e:
+        console.print(f"[red]✗[/red] Could not find Python executable: {e}")
+        raise FileNotFoundError(
+            "Could not find mcp-ticketer Python executable. "
+            "Please ensure mcp-ticketer is installed.\n"
+            "Install with: pip install mcp-ticketer or pipx install mcp-ticketer"
+        )
 
     # Step 2: Load project configuration
     console.print("\n[cyan]📖 Reading project configuration...[/cyan]")
@@ -327,9 +361,11 @@ def configure_claude_mcp(global_config: bool = False, force: bool = False) -> No
             console.print("[yellow]⚠ Overwriting existing configuration[/yellow]")
 
     # Step 6: Create mcp-ticketer server config
-    cwd = str(Path.cwd()) if not global_config else None
+    project_path = str(Path.cwd()) if not global_config else None
     server_config = create_mcp_server_config(
-        binary_path=binary_path, project_config=project_config, cwd=cwd
+        python_path=python_path,
+        project_config=project_config,
+        project_path=project_path,
     )
 
     # Step 7: Update MCP configuration
@@ -348,9 +384,10 @@ def configure_claude_mcp(global_config: bool = False, force: bool = False) -> No
         console.print("\n[bold]Configuration Details:[/bold]")
         console.print("  Server name: mcp-ticketer")
         console.print(f"  Adapter: {adapter}")
-        console.print(f"  Binary: {binary_path}")
-        if cwd:
-            console.print(f"  Working directory: {cwd}")
+        console.print(f"  Python: {python_path}")
+        console.print("  Command: python -m mcp_ticketer.mcp.server")
+        if project_path:
+            console.print(f"  Project path: {project_path}")
         if "env" in server_config:
             console.print(
                 f"  Environment variables: {list(server_config['env'].keys())}"

mcp_ticketer/cli/python_detection.py

@@ -0,0 +1,126 @@
+"""Reliable Python executable detection for mcp-ticketer.
+
+This module provides reliable detection of the Python executable for mcp-ticketer
+across different installation methods (pipx, pip, uv, direct venv).
+
+The module follows the proven pattern from mcp-vector-search:
+- Detect venv Python path reliably
+- Use `python -m mcp_ticketer.mcp.server` instead of binary paths
+- Support multiple installation methods transparently
+"""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def get_mcp_ticketer_python(project_path: Path | None = None) -> str:
+    """Get the correct Python executable for mcp-ticketer MCP server.
+
+    This function follows the mcp-vector-search pattern of using project-specific
+    venv Python for proper project isolation and dependency management.
+
+    Detection priority:
+    1. Project-local venv (.venv/bin/python) if project_path provided
+    2. Current Python executable if in pipx venv
+    3. Python from mcp-ticketer binary shebang
+    4. Current Python executable (fallback)
+
+    Args:
+        project_path: Optional project directory path to check for local venv
+
+    Returns:
+        Path to Python executable
+
+    Examples:
+        >>> # With project venv
+        >>> python_path = get_mcp_ticketer_python(Path("/home/user/my-project"))
+        >>> # Returns: "/home/user/my-project/.venv/bin/python"
+
+        >>> # Without project path (fallback to pipx)
+        >>> python_path = get_mcp_ticketer_python()
+        >>> # Returns: "/Users/user/.local/pipx/venvs/mcp-ticketer/bin/python"
+
+    """
+    # Priority 1: Check for project-local venv
+    if project_path:
+        project_venv_python = project_path / ".venv" / "bin" / "python"
+        if project_venv_python.exists():
+            return str(project_venv_python)
+
+    current_executable = sys.executable
+
+    # Priority 2: Check if we're in a pipx venv
+    if "/pipx/venvs/" in current_executable:
+        return current_executable
+
+    # Priority 3: Check mcp-ticketer binary shebang
+    mcp_ticketer_path = shutil.which("mcp-ticketer")
+    if mcp_ticketer_path:
+        try:
+            with open(mcp_ticketer_path) as f:
+                first_line = f.readline().strip()
+                if first_line.startswith("#!") and "python" in first_line:
+                    python_path = first_line[2:].strip()
+                    if os.path.exists(python_path):
+                        return python_path
+        except OSError:
+            pass
+
+    # Priority 4: Fallback to current Python
+    return current_executable
+
+
+def get_mcp_server_command(project_path: str | None = None) -> tuple[str, list[str]]:
+    """Get the complete command to run the MCP server.
+
+    Args:
+        project_path: Optional project path to pass as argument and check for venv
+
+    Returns:
+        Tuple of (python_executable, args_list)
+        Example: ("/path/to/python", ["-m", "mcp_ticketer.mcp.server", "/project/path"])
+
+    Examples:
+        >>> python, args = get_mcp_server_command("/home/user/project")
+        >>> # python: "/home/user/project/.venv/bin/python" (if .venv exists)
+        >>> # args: ["-m", "mcp_ticketer.mcp.server", "/home/user/project"]
+
+    """
+    # Convert project_path to Path object for venv detection
+    project_path_obj = Path(project_path) if project_path else None
+    python_path = get_mcp_ticketer_python(project_path=project_path_obj)
+    args = ["-m", "mcp_ticketer.mcp.server"]
+
+    if project_path:
+        args.append(str(project_path))
+
+    return python_path, args
+
+
+def validate_python_executable(python_path: str) -> bool:
+    """Validate that a Python executable can import mcp_ticketer.
+
+    Args:
+        python_path: Path to Python executable to validate
+
+    Returns:
+        True if Python can import mcp_ticketer, False otherwise
+
+    Examples:
+        >>> is_valid = validate_python_executable("/usr/bin/python3")
+        >>> # Returns: False (system Python doesn't have mcp_ticketer)
+
+    """
+    try:
+        import subprocess
+
+        result = subprocess.run(
+            [python_path, "-c", "import mcp_ticketer.mcp.server"],
+            capture_output=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False

mcp_ticketer/core/__init__.py

@@ -1,8 +1,7 @@
 """Core models and abstractions for MCP Ticketer."""
 
 from .adapter import BaseAdapter
-from .models import (Attachment, Comment, Epic, Priority, Task, TicketState,
-                     TicketType)
+from .models import Attachment, Comment, Epic, Priority, Task, TicketState, TicketType
 from .registry import AdapterRegistry
 
 __all__ = [