mcp-ticketer 0.4.4__tar.gz → 0.4.5__tar.gz

{mcp_ticketer-0.4.4/src/mcp_ticketer.egg-info → mcp_ticketer-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.4.4
+Version: 0.4.5
 Summary: Universal ticket management interface for AI agents with MCP support
 Author-email: MCP Ticketer Team <support@mcp-ticketer.io>
 Maintainer-email: MCP Ticketer Team <support@mcp-ticketer.io>
@@ -282,16 +282,25 @@ mcp-ticketer uninstall auggie        # Alias for remove
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/path/to/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/absolute/path/to/project"],
       "env": {
-        "MCP_TICKETER_ADAPTER": "aitrackdown"
+        "MCP_TICKETER_ADAPTER": "aitrackdown",
+        "PYTHONPATH": "/absolute/path/to/project"
       }
     }
   }
 }
 ```
 
+**Why this pattern?**
+- **More Reliable**: Uses venv Python directly instead of binary wrapper
+- **Consistent**: Matches proven mcp-vector-search pattern
+- **Universal**: Works across pipx, pip, and uv installations
+- **Better Errors**: Python module invocation provides clearer error messages
+
+**Automatic Detection**: The `mcp-ticketer install` commands automatically detect your venv Python and generate the correct configuration.
+
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for client-specific details.**
 
 ## ⚙️ Configuration

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/README.md

@@ -197,16 +197,25 @@ mcp-ticketer uninstall auggie        # Alias for remove
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/path/to/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/absolute/path/to/project"],
       "env": {
-        "MCP_TICKETER_ADAPTER": "aitrackdown"
+        "MCP_TICKETER_ADAPTER": "aitrackdown",
+        "PYTHONPATH": "/absolute/path/to/project"
       }
     }
   }
 }
 ```
 
+**Why this pattern?**
+- **More Reliable**: Uses venv Python directly instead of binary wrapper
+- **Consistent**: Matches proven mcp-vector-search pattern
+- **Universal**: Works across pipx, pip, and uv installations
+- **Better Errors**: Python module invocation provides clearer error messages
+
+**Automatic Detection**: The `mcp-ticketer install` commands automatically detect your venv Python and generate the correct configuration.
+
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for client-specific details.**
 
 ## ⚙️ Configuration

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/docs/AI_CLIENT_INTEGRATION.md

@@ -28,6 +28,33 @@ Complete guide to integrating MCP Ticketer with AI clients via the Model Context
 
 The **Model Context Protocol (MCP)** is a standardized protocol that enables AI assistants to interact with external tools and services. MCP Ticketer implements MCP to provide universal ticket management capabilities to AI clients.
 
+### MCP Server Configuration Pattern
+
+**MCP Ticketer uses a reliable venv Python + module invocation pattern:**
+
+```json
+{
+  "command": "/path/to/venv/bin/python",
+  "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"],
+  "env": {
+    "PYTHONPATH": "/project/path"
+  }
+}
+```
+
+**Why this pattern?**
+1. **Reliability**: Direct venv Python invocation avoids binary wrapper issues
+2. **Consistency**: Matches proven mcp-vector-search approach
+3. **Compatibility**: Works across pipx, pip, and uv installations
+4. **Error Clarity**: Python module errors are more informative
+5. **Automatic**: `mcp-ticketer install <platform>` detects paths automatically
+
+**How it works:**
+- The `install` commands automatically detect your mcp-ticketer venv Python
+- Module invocation (`-m mcp_ticketer.mcp.server`) is more reliable than binary paths
+- Project path argument enables project-specific configurations
+- PYTHONPATH ensures proper module resolution
+
 ### Supported AI Clients
 
 MCP Ticketer supports **4 major AI clients** with varying levels of integration:
@@ -164,18 +191,24 @@ mcp-ticketer install claude-code --dry-run
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/usr/local/bin/mcp-ticketer",
-      "args": ["serve"],
-      "cwd": "/Users/username/projects/my-project",
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/Users/username/projects/my-project"],
       "env": {
         "MCP_TICKETER_ADAPTER": "aitrackdown",
-        "MCP_TICKETER_BASE_PATH": "/Users/username/projects/my-project/.aitrackdown"
+        "MCP_TICKETER_BASE_PATH": "/Users/username/projects/my-project/.aitrackdown",
+        "PYTHONPATH": "/Users/username/projects/my-project"
       }
     }
   }
 }
 ```
 
+**Configuration Pattern Explained:**
+- **command**: Path to Python in your mcp-ticketer venv (auto-detected by `install` command)
+- **args**: `["-m", "mcp_ticketer.mcp.server", "<project_path>"]` - module invocation pattern
+- **PYTHONPATH**: Project path for proper module resolution
+- **Benefits**: More reliable, better error messages, works across all installation methods
+
 #### Step 5: Use in Claude Code
 
 1. Open Claude Code
@@ -193,13 +226,14 @@ mcp-ticketer install claude-code --dry-run
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/path/to/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"],
       "env": {
         "MCP_TICKETER_ADAPTER": "linear",
         "LINEAR_API_KEY": "your-api-key",
         "LINEAR_TEAM_ID": "your-team-id",
-        "MCP_TICKETER_LOG_LEVEL": "DEBUG"
+        "MCP_TICKETER_LOG_LEVEL": "DEBUG",
+        "PYTHONPATH": "/project/path"
       }
     }
   }
@@ -212,19 +246,21 @@ mcp-ticketer install claude-code --dry-run
 {
   "mcpServers": {
     "mcp-ticketer-jira": {
-      "command": "/path/to/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"],
       "env": {
         "MCP_TICKETER_ADAPTER": "jira",
-        "JIRA_SERVER": "https://company.atlassian.net"
+        "JIRA_SERVER": "https://company.atlassian.net",
+        "PYTHONPATH": "/project/path"
       }
     },
     "mcp-ticketer-github": {
-      "command": "/path/to/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"],
       "env": {
         "MCP_TICKETER_ADAPTER": "github",
-        "GITHUB_REPO": "owner/repo"
+        "GITHUB_REPO": "owner/repo",
+        "PYTHONPATH": "/project/path"
       }
     }
   }
@@ -300,10 +336,10 @@ mcp-ticketer install gemini --dry-run
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/usr/local/bin/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server", "/Users/username/projects/my-project"],
       "env": {
-        "PYTHONPATH": "/Users/username/projects/my-project/src",
+        "PYTHONPATH": "/Users/username/projects/my-project",
         "MCP_TICKETER_ADAPTER": "aitrackdown",
         "MCP_TICKETER_BASE_PATH": "/Users/username/projects/my-project/.aitrackdown"
       },
@@ -314,6 +350,8 @@ mcp-ticketer install gemini --dry-run
 }
 ```
 
+**Note**: The venv Python path is automatically detected by `mcp-ticketer install gemini`.
+
 #### Step 5: Use in Gemini CLI
 
 1. Navigate to your project directory
@@ -424,15 +462,17 @@ mcp-ticketer install codex --dry-run
 
 ```toml
 [mcp_servers.mcp-ticketer]
-command = "/usr/local/bin/mcp-ticketer"
-args = ["serve"]
+command = "/path/to/venv/bin/python"
+args = ["-m", "mcp_ticketer.mcp.server", "/Users/username/projects/my-project"]
 
 [mcp_servers.mcp-ticketer.env]
-PYTHONPATH = "/Users/username/projects/my-project/src"
+PYTHONPATH = "/Users/username/projects/my-project"
 MCP_TICKETER_ADAPTER = "aitrackdown"
 MCP_TICKETER_BASE_PATH = "/Users/username/projects/my-project/.aitrackdown"
 ```
 
+**Note**: The venv Python path is automatically detected and configured by `mcp-ticketer install codex`.
+
 #### Step 6: Use in Codex CLI
 
 1. Run `codex` from any directory
@@ -525,8 +565,8 @@ mcp-ticketer install auggie --dry-run
 {
   "mcpServers": {
     "mcp-ticketer": {
-      "command": "/usr/local/bin/mcp-ticketer",
-      "args": ["serve"],
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "mcp_ticketer.mcp.server"],
       "env": {
         "MCP_TICKETER_ADAPTER": "aitrackdown",
         "MCP_TICKETER_BASE_PATH": "/Users/username/.mcp-ticketer/.aitrackdown"
@@ -536,6 +576,8 @@ mcp-ticketer install auggie --dry-run
 }
 ```
 
+**Note**: The venv Python path is automatically detected by `mcp-ticketer install auggie`. Since Auggie uses global configuration, project path arguments are typically omitted.
+
 #### Step 6: Use in Auggie
 
 1. Open Auggie

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/docs/MIGRATION_GUIDE.md

@@ -51,22 +51,81 @@ mcp-ticketer install
 
 #### New Features in v0.5.x
 
-##### 1. Installation Commands
+##### 1. Reliable venv Python Pattern
+
+Version 0.5.x introduces a new, more reliable MCP server configuration pattern:
+
+**Old Pattern (v0.4.x):**
+```json
+{
+  "command": "/usr/local/bin/mcp-ticketer",
+  "args": ["serve"],
+  "env": {
+    "MCP_TICKETER_ADAPTER": "aitrackdown"
+  }
+}
+```
+
+**New Pattern (v0.5.x):**
+```json
+{
+  "command": "/path/to/venv/bin/python",
+  "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"],
+  "env": {
+    "MCP_TICKETER_ADAPTER": "aitrackdown",
+    "PYTHONPATH": "/project/path"
+  }
+}
+```
+
+**Benefits:**
+- ✅ More reliable across installation methods (pipx, pip, uv)
+- ✅ Better error messages from Python module invocation
+- ✅ Consistent with proven mcp-vector-search approach
+- ✅ Automatic detection of venv Python path
+- ✅ Works across different Python versions
+
+**Migration:** The `install` commands automatically generate the new pattern. Old configurations continue to work but are deprecated.
+
+##### 2. Installation Commands
 
 The `install` command now handles MCP platform configuration:
 - Simplified syntax without the `mcp` subcommand
 - Clearer platform names (e.g., `claude-code` vs `claude-desktop`)
 - Dry-run support to preview changes
+- Automatic venv Python detection
 
 ```bash
 # Install with preview
 mcp-ticketer install claude-code --dry-run
 
-# Install normally
+# Install normally (automatically uses new pattern)
 mcp-ticketer install claude-code
 ```
 
-##### 2. Removal Commands
+##### 2. Automatic Python Path Detection
+
+The installer now automatically detects the correct Python executable:
+
+```python
+# Detection priority:
+# 1. Current Python if in pipx venv
+# 2. Python from mcp-ticketer binary shebang
+# 3. Current Python executable (fallback)
+```
+
+**Finding your venv Python manually:**
+```bash
+# For pipx installations
+ls ~/.local/pipx/venvs/mcp-ticketer/bin/python
+
+# For pip/uv in project venv
+ls .venv/bin/python
+
+# The install command detects this automatically
+```
+
+##### 3. Removal Commands
 
 New commands to remove MCP configurations:
 
@@ -83,7 +142,7 @@ mcp-ticketer uninstall codex
 mcp-ticketer remove gemini --dry-run
 ```
 
-##### 3. Platform Support
+##### 4. Platform Support
 
 **New platforms:**
 - `claude-code` - Project-level Claude Code configuration
@@ -124,16 +183,39 @@ Review and update any project documentation that references the old commands:
 - CI/CD pipelines
 - Developer onboarding docs
 
-##### Step 3: Reinstall Configurations (Optional)
+##### Step 3: Migrate to venv Python Pattern (Recommended)
 
-While old configurations continue to work, you may want to reinstall using the new commands:
+Update your configurations to use the new venv Python pattern:
 
 ```bash
-# Remove old configuration
+# Option 1: Automatic reinstall (recommended)
 mcp-ticketer remove claude-code
-
-# Install with new command
 mcp-ticketer install claude-code
+
+# Option 2: Manual update
+# Edit your configuration file directly:
+# Change: "command": "/usr/local/bin/mcp-ticketer"
+# To:     "command": "/path/to/venv/bin/python"
+# Change: "args": ["serve"]
+# To:     "args": ["-m", "mcp_ticketer.mcp.server", "/project/path"]
+# Add:    "PYTHONPATH": "/project/path" to env
+```
+
+**Why migrate?**
+- ✅ More reliable across different installation methods
+- ✅ Better error messages and debugging
+- ✅ Future-proof pattern matching industry standards
+- ✅ No RuntimeWarning about lazy imports
+
+**Verification:**
+```bash
+# Test the new configuration
+# For Claude Code/Desktop: Try creating a ticket in the AI client
+# The new pattern should work seamlessly
+
+# Check Python path manually
+which python
+# Should show your venv Python if installed with pipx/pip
 ```
 
 ##### Step 4: Test Integrations

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/docs/QUICK_START.md

@@ -453,6 +453,39 @@ mcp-ticketer serve
 # Press Ctrl+C to stop
 ```
 
+**Manual Configuration Pattern:**
+
+All AI clients use the same reliable venv Python + module invocation pattern:
+
+```json
+{
+  "command": "/path/to/venv/bin/python",
+  "args": ["-m", "mcp_ticketer.mcp.server", "/absolute/path/to/project"],
+  "env": {
+    "MCP_TICKETER_ADAPTER": "aitrackdown",
+    "PYTHONPATH": "/absolute/path/to/project"
+  }
+}
+```
+
+**Key Points:**
+- **command**: Path to Python in your mcp-ticketer venv (auto-detected by install commands)
+- **args**: Module invocation pattern `["-m", "mcp_ticketer.mcp.server", "<project_path>"]`
+- **PYTHONPATH**: Set to project root for proper module resolution
+- **Benefits**: More reliable than binary paths, works across all installation methods
+
+**Finding your venv Python:**
+```bash
+# For pipx installations
+ls ~/.local/pipx/venvs/mcp-ticketer/bin/python
+
+# For pip installations in venv
+ls .venv/bin/python
+
+# For uv installations
+ls .venv/bin/python
+```
+
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for detailed configuration.**
 
 ---

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/pyproject.toml

@@ -152,7 +152,7 @@ extend-exclude = '''
 '''
 
 [tool.ruff]
-target-version = "py311"
+target-version = "0.4.5"
 line-length = 88
 
 [tool.ruff.lint]

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/src/mcp_ticketer/__version__.py

@@ -1,6 +1,6 @@
 """Version information for mcp-ticketer package."""
 
-__version__ = "0.4.4"
+__version__ = "0.4.5"
 __version_info__ = tuple(int(part) for part in __version__.split("."))
 
 # Package metadata

{mcp_ticketer-0.4.4 → mcp_ticketer-0.4.5}/src/mcp_ticketer/cli/auggie_configure.py

@@ -10,7 +10,8 @@ from typing import Any
 
 from rich.console import Console
 
-from .mcp_configure import find_mcp_ticketer_binary, load_project_config
+from .mcp_configure import load_project_config
+from .python_detection import get_mcp_ticketer_python
 
 console = Console()
 
@@ -71,13 +72,14 @@ def save_auggie_config(config_path: Path, config: dict[str, Any]) -> None:
 
 
 def create_auggie_server_config(
-    binary_path: str, project_config: dict[str, Any]
+    python_path: str, project_config: dict[str, Any], project_path: str | None = None
 ) -> dict[str, Any]:
     """Create Auggie 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
+        project_path: Project directory path (optional)
 
     Returns:
         Auggie MCP server configuration dict
@@ -91,6 +93,10 @@ def create_auggie_server_config(
     # Build environment variables
     env_vars = {}
 
+    # Add PYTHONPATH for project context
+    if project_path:
+        env_vars["PYTHONPATH"] = project_path
+
     # Add adapter type
     env_vars["MCP_TICKETER_ADAPTER"] = adapter
 
@@ -128,10 +134,15 @@ def create_auggie_server_config(
         if "project_key" in adapter_config:
             env_vars["JIRA_PROJECT_KEY"] = adapter_config["project_key"]
 
+    # Use module invocation pattern: python -m mcp_ticketer.mcp.server
+    args = ["-m", "mcp_ticketer.mcp.server"]
+    if project_path:
+        args.append(project_path)
+
     # Create server configuration (simpler than Gemini - no timeout/trust)
     config = {
-        "command": binary_path,
-        "args": ["serve"],
+        "command": python_path,
+        "args": args,
         "env": env_vars,
     }
 
@@ -214,18 +225,22 @@ def configure_auggie_mcp(force: bool = False) -> None:
         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]")
+    # Step 1: Find Python executable
+    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()
+        console.print(f"[green]✓[/green] Found: {python_path}")
+    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]")
@@ -259,8 +274,11 @@ def configure_auggie_mcp(force: bool = False) -> None:
             console.print("[yellow]⚠ Overwriting existing configuration[/yellow]")
 
     # Step 6: Create mcp-ticketer server config
+    project_path = str(Path.cwd())
     server_config = create_auggie_server_config(
-        binary_path=binary_path, project_config=project_config
+        python_path=python_path,
+        project_config=project_config,
+        project_path=project_path,
     )
 
     # Step 7: Update Auggie configuration
@@ -279,8 +297,10 @@ def configure_auggie_mcp(force: bool = False) -> None:
         console.print("\n[bold]Configuration Details:[/bold]")
         console.print("  Server name: mcp-ticketer")
         console.print(f"  Adapter: {adapter}")
-        console.print(f"  Binary: {binary_path}")
+        console.print(f"  Python: {python_path}")
+        console.print("  Command: python -m mcp_ticketer.mcp.server")
         console.print("  Scope: Global (affects all projects)")
+        console.print(f"  Project path: {project_path}")
         if "env" in server_config:
             console.print(
                 f"  Environment variables: {list(server_config['env'].keys())}"