mcp-ticketer 0.4.4__py3-none-any.whl → 0.4.8__py3-none-any.whl

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,7 +1,8 @@
 """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__ = [

mcp_ticketer/mcp/__init__.py

@@ -1,5 +1,33 @@
 """MCP server implementation for ticket management."""
 
-from .server import MCPTicketServer
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .server.main import MCPTicketServer
 
 __all__ = ["MCPTicketServer"]
+
+
+def __dir__():
+    """Return list of available names for dir().
+
+    This ensures that MCPTicketServer appears in dir() results
+    even though it's lazily imported.
+    """
+    return __all__
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid premature module loading.
+
+    This prevents the RuntimeWarning when running:
+        python -m mcp_ticketer.mcp.server
+
+    The warning occurred because __init__.py imported server before
+    runpy could execute it as __main__.
+    """
+    if name == "MCPTicketServer":
+        from .server.main import MCPTicketServer
+
+        return MCPTicketServer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mcp_ticketer/mcp/__main__.py

@@ -0,0 +1,60 @@
+"""Main entry point for MCP server module invocation.
+
+This module enables running the MCP server via:
+    python -m mcp_ticketer.mcp.server [project_path]
+
+This is the preferred invocation method for MCP configurations as it:
+- Works reliably across installation methods (pipx, pip, uv)
+- Doesn't depend on binary path detection
+- Follows the proven mcp-vector-search pattern
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from .server import main
+
+
+def run_server() -> None:
+    """Run the MCP server with optional project path argument.
+
+    Usage:
+        python -m mcp_ticketer.mcp.server
+        python -m mcp_ticketer.mcp.server /path/to/project
+
+    Arguments:
+        project_path (optional): Path to project directory for context
+
+    """
+    # Check for project path argument
+    if len(sys.argv) > 1:
+        project_path = Path(sys.argv[1])
+
+        # Validate project path exists
+        if not project_path.exists():
+            sys.stderr.write(f"Error: Project path does not exist: {project_path}\n")
+            sys.exit(1)
+
+        # Change to project directory for context
+        try:
+            import os
+
+            os.chdir(project_path)
+            sys.stderr.write(f"[MCP Server] Working directory: {project_path}\n")
+        except OSError as e:
+            sys.stderr.write(f"Warning: Could not change to project directory: {e}\n")
+
+    # Run the async main function
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.stderr.write("\n[MCP Server] Interrupted by user\n")
+        sys.exit(0)
+    except Exception as e:
+        sys.stderr.write(f"[MCP Server] Fatal error: {e}\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_server()

mcp_ticketer/mcp/server/__init__.py

@@ -0,0 +1,21 @@
+"""MCP Server package for mcp-ticketer.
+
+This package provides the FastMCP server implementation for ticket management
+operations via the Model Context Protocol (MCP).
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .main import main
+
+__all__ = ["main"]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid premature module loading."""
+    if name == "main":
+        from .main import main
+
+        return main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mcp_ticketer/mcp/server/__main__.py

@@ -0,0 +1,60 @@
+"""Main entry point for MCP server module invocation.
+
+This module enables running the MCP server via:
+    python -m mcp_ticketer.mcp.server [project_path]
+
+This is the preferred invocation method for MCP configurations as it:
+- Works reliably across installation methods (pipx, pip, uv)
+- Doesn't depend on binary path detection
+- Follows the proven mcp-vector-search pattern
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+from .main import main
+
+
+def run_server() -> None:
+    """Run the MCP server with optional project path argument.
+
+    Usage:
+        python -m mcp_ticketer.mcp.server
+        python -m mcp_ticketer.mcp.server /path/to/project
+
+    Arguments:
+        project_path (optional): Path to project directory for context
+
+    """
+    # Check for project path argument
+    if len(sys.argv) > 1:
+        project_path = Path(sys.argv[1])
+
+        # Validate project path exists
+        if not project_path.exists():
+            sys.stderr.write(f"Error: Project path does not exist: {project_path}\n")
+            sys.exit(1)
+
+        # Change to project directory for context
+        try:
+            import os
+
+            os.chdir(project_path)
+            sys.stderr.write(f"[MCP Server] Working directory: {project_path}\n")
+        except OSError as e:
+            sys.stderr.write(f"Warning: Could not change to project directory: {e}\n")
+
+    # Run the async main function
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.stderr.write("\n[MCP Server] Interrupted by user\n")
+        sys.exit(0)
+    except Exception as e:
+        sys.stderr.write(f"[MCP Server] Fatal error: {e}\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_server()

mcp_ticketer/mcp/{server.py → server/main.py}

@@ -11,41 +11,21 @@ from dotenv import load_dotenv
 # Import adapters module to trigger registration
 import mcp_ticketer.adapters  # noqa: F401
 
-from ..core import AdapterRegistry
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
-from .constants import (
-    DEFAULT_BASE_PATH,
-    DEFAULT_LIMIT,
-    DEFAULT_MAX_DEPTH,
-    DEFAULT_OFFSET,
-    ERROR_INTERNAL,
-    ERROR_METHOD_NOT_FOUND,
-    ERROR_PARSE,
-    JSONRPC_VERSION,
-    MCP_PROTOCOL_VERSION,
-    MSG_EPIC_NOT_FOUND,
-    MSG_INTERNAL_ERROR,
-    MSG_MISSING_TICKET_ID,
-    MSG_MISSING_TITLE,
-    MSG_NO_TICKETS_PROVIDED,
-    MSG_NO_UPDATES_PROVIDED,
-    MSG_TICKET_NOT_FOUND,
-    MSG_TRANSITION_FAILED,
-    MSG_UNKNOWN_METHOD,
-    MSG_UNKNOWN_OPERATION,
-    MSG_UPDATE_FAILED,
-    SERVER_NAME,
-    SERVER_VERSION,
-    STATUS_COMPLETED,
-    STATUS_ERROR,
-)
-from .dto import (
-    CreateEpicRequest,
-    CreateIssueRequest,
-    CreateTaskRequest,
-    CreateTicketRequest,
-    ReadTicketRequest,
-)
+from ...core import AdapterRegistry
+from ...core.models import (Comment, Epic, Priority, SearchQuery, Task,
+                            TicketState)
+from .constants import (DEFAULT_BASE_PATH, DEFAULT_LIMIT, DEFAULT_MAX_DEPTH,
+                        DEFAULT_OFFSET, ERROR_INTERNAL, ERROR_METHOD_NOT_FOUND,
+                        ERROR_PARSE, JSONRPC_VERSION, MCP_PROTOCOL_VERSION,
+                        MSG_EPIC_NOT_FOUND, MSG_INTERNAL_ERROR,
+                        MSG_MISSING_TICKET_ID, MSG_MISSING_TITLE,
+                        MSG_NO_TICKETS_PROVIDED, MSG_NO_UPDATES_PROVIDED,
+                        MSG_TICKET_NOT_FOUND, MSG_TRANSITION_FAILED,
+                        MSG_UNKNOWN_METHOD, MSG_UNKNOWN_OPERATION,
+                        MSG_UPDATE_FAILED, SERVER_NAME, SERVER_VERSION,
+                        STATUS_COMPLETED, STATUS_ERROR)
+from .dto import (CreateEpicRequest, CreateIssueRequest, CreateTaskRequest,
+                  CreateTicketRequest, ReadTicketRequest)
 from .response_builder import ResponseBuilder
 
 # Load environment variables early (prioritize .env.local)

mcp_ticketer/mcp/{tools → server/tools}/__init__.py

@@ -17,15 +17,13 @@ Modules:
 
 # Import all tool modules to register them with FastMCP
 # Order matters - import core functionality first
-from . import (
-    attachment_tools,  # noqa: F401
-    bulk_tools,  # noqa: F401
-    comment_tools,  # noqa: F401
-    hierarchy_tools,  # noqa: F401
-    pr_tools,  # noqa: F401
-    search_tools,  # noqa: F401
-    ticket_tools,  # noqa: F401
-)
+from . import attachment_tools  # noqa: F401
+from . import bulk_tools  # noqa: F401
+from . import comment_tools  # noqa: F401
+from . import hierarchy_tools  # noqa: F401
+from . import pr_tools  # noqa: F401
+from . import search_tools  # noqa: F401
+from . import ticket_tools  # noqa: F401
 
 __all__ = [
     "ticket_tools",