claude-mpm 4.0.34__py3-none-any.whl → 4.1.1__py3-none-any.whl

claude_mpm/cli/__init__.py

@@ -83,15 +83,26 @@ def main(argv: Optional[list] = None):
     # Initialize or update project registry
     _initialize_project_registry()
 
-    # Verify MCP Gateway configuration on startup (non-blocking)
-    _verify_mcp_gateway_startup()
-
-    # Create parser with version
+    # Parse args early to check if we should skip auto-configuration
+    # (for commands like --version, --help, etc.)
     parser = create_parser(version=__version__)
-
-    # Preprocess and parse arguments
     processed_argv = preprocess_args(argv)
     args = parser.parse_args(processed_argv)
+    
+    # Skip auto-configuration for certain commands
+    skip_auto_config_commands = ["--version", "-v", "--help", "-h"]
+    # sys is already imported at module level (line 16), use it directly
+    should_skip_auto_config = (
+        any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_auto_config_commands)
+        or (hasattr(args, 'command') and args.command in ["info", "doctor", "config", "mcp"])  # Info, diagnostic, and MCP commands
+    )
+    
+    if not should_skip_auto_config:
+        # Check for MCP auto-configuration (pipx installations)
+        _check_mcp_auto_configuration()
+
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
 
     # Set up logging
     # Special case: For MCP start command, we need minimal logging to avoid stdout interference
@@ -101,7 +112,7 @@ def main(argv: Optional[list] = None):
     ):
         # For MCP server, configure minimal stderr-only logging
         import logging
-        import sys
+        # sys is already imported at module level
 
         # Only log errors to stderr for MCP server
         if not getattr(args, "test", False) and not getattr(
@@ -176,6 +187,36 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _check_mcp_auto_configuration():
+    """
+    Check and potentially auto-configure MCP for pipx installations.
+    
+    WHY: Users installing via pipx should have MCP work out-of-the-box with
+    minimal friction. This function offers one-time auto-configuration with
+    user consent.
+    
+    DESIGN DECISION: This is blocking but quick - it only runs once and has
+    a 10-second timeout. We want to catch users on first run for the best
+    experience.
+    """
+    try:
+        from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
+        
+        # This function handles all the logic:
+        # - Checks if already configured
+        # - Checks if pipx installation
+        # - Checks if already asked before
+        # - Prompts user if needed
+        # - Configures if user agrees
+        check_and_configure_mcp()
+        
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+        logger = get_logger("cli")
+        logger.debug(f"MCP auto-configuration check failed: {e}")
+
+
 def _verify_mcp_gateway_startup():
     """
     Verify MCP Gateway configuration on startup and pre-warm MCP services.

claude_mpm/cli/commands/agents.py

@@ -71,6 +71,7 @@ class AgentsCommand(AgentCommand):
                 "deps-install": self._install_agent_dependencies,
                 "deps-list": self._list_agent_dependencies,
                 "deps-fix": self._fix_agent_dependencies,
+                "cleanup-orphaned": self._cleanup_orphaned_agents,
             }
 
             if args.agents_command in command_map:
@@ -469,6 +470,87 @@ class AgentsCommand(AgentCommand):
         except Exception as e:
             self.logger.error(f"Error fixing dependencies: {e}", exc_info=True)
             return CommandResult.error_result(f"Error fixing dependencies: {e}")
+    
+    def _cleanup_orphaned_agents(self, args) -> CommandResult:
+        """Clean up orphaned agents that don't have templates."""
+        try:
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService
+            )
+            
+            # Determine agents directory
+            if hasattr(args, 'agents_dir') and args.agents_dir:
+                agents_dir = args.agents_dir
+            else:
+                # Check for project-level .claude/agents first
+                project_agents_dir = Path.cwd() / ".claude" / "agents"
+                if project_agents_dir.exists():
+                    agents_dir = project_agents_dir
+                else:
+                    # Fall back to user home directory
+                    agents_dir = Path.home() / ".claude" / "agents"
+            
+            if not agents_dir.exists():
+                return CommandResult.success_result(f"Agents directory not found: {agents_dir}")
+            
+            # Initialize service
+            service = MultiSourceAgentDeploymentService()
+            
+            # Determine if we're doing a dry run
+            dry_run = getattr(args, 'dry_run', True)
+            if hasattr(args, 'force') and args.force:
+                dry_run = False
+            
+            # Perform cleanup
+            results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+            
+            output_format = getattr(args, 'format', 'text')
+            quiet = getattr(args, 'quiet', False)
+            
+            if output_format in ['json', 'yaml']:
+                return CommandResult.success_result(
+                    f"Found {len(results.get('orphaned', []))} orphaned agents",
+                    data=results
+                )
+            else:
+                # Text output
+                if not results.get("orphaned"):
+                    print("✅ No orphaned agents found")
+                    return CommandResult.success_result("No orphaned agents found")
+                
+                if not quiet:
+                    print(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+                    for orphan in results["orphaned"]:
+                        print(f"  - {orphan['name']} v{orphan['version']}")
+                
+                if dry_run:
+                    print(
+                        f"\n📝 This was a dry run. Use --force to actually remove "
+                        f"{len(results['orphaned'])} orphaned agent(s)"
+                    )
+                else:
+                    if results.get("removed"):
+                        print(
+                            f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                        )
+                    
+                    if results.get("errors"):
+                        print(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                        for error in results["errors"]:
+                            print(f"  - {error}")
+                        return CommandResult.error_result(
+                            f"Cleanup completed with {len(results['errors'])} errors",
+                            data=results
+                        )
+                
+                return CommandResult.success_result(
+                    f"Cleanup {'preview' if dry_run else 'completed'}",
+                    data=results
+                )
+                
+        except Exception as e:
+            self.logger.error(f"Error during cleanup: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error during cleanup: {e}")
 
 
 def manage_agents(args):

claude_mpm/cli/commands/cleanup_orphaned_agents.py

@@ -0,0 +1,150 @@
+"""CLI command to clean up orphaned agents without templates.
+
+This command helps manage deployed agents that no longer have corresponding
+templates, which can happen when agents are removed from the system or when
+switching between different agent sources.
+"""
+
+import argparse
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_config import get_logger
+from claude_mpm.services.agents.deployment.multi_source_deployment_service import (
+    MultiSourceAgentDeploymentService
+)
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the cleanup-orphaned-agents command parser.
+    
+    Args:
+        subparsers: The subparsers object from argparse
+    """
+    parser = subparsers.add_parser(
+        "cleanup-orphaned-agents",
+        help="Clean up orphaned agents that don't have templates",
+        description=(
+            "Detect and optionally remove deployed agents that no longer have "
+            "corresponding templates. This can happen when agents are removed "
+            "from the system or when switching between agent sources."
+        ),
+    )
+    
+    parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        help="Directory containing deployed agents (default: .claude/agents/)",
+    )
+    
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        help="Only show what would be removed without actually removing (default)",
+    )
+    
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Actually remove orphaned agents (disables dry-run)",
+    )
+    
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only show summary, not individual agents",
+    )
+    
+    parser.set_defaults(func=cleanup_orphaned_agents)
+
+
+def cleanup_orphaned_agents(args: argparse.Namespace) -> int:
+    """Clean up orphaned agents.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    logger = get_logger(__name__)
+    
+    # Determine agents directory
+    if args.agents_dir:
+        agents_dir = args.agents_dir
+    else:
+        # Check for project-level .claude/agents first
+        project_agents_dir = Path.cwd() / ".claude" / "agents"
+        if project_agents_dir.exists():
+            agents_dir = project_agents_dir
+        else:
+            # Fall back to user home directory
+            agents_dir = Path.home() / ".claude" / "agents"
+    
+    if not agents_dir.exists():
+        logger.info(f"Agents directory not found: {agents_dir}")
+        return 0
+    
+    logger.info(f"Checking for orphaned agents in: {agents_dir}")
+    
+    # Initialize service
+    service = MultiSourceAgentDeploymentService()
+    
+    # Determine if we're doing a dry run
+    dry_run = args.dry_run and not args.force
+    
+    try:
+        # Perform cleanup
+        results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+        
+        # Handle results
+        if not results["orphaned"]:
+            logger.info("✅ No orphaned agents found")
+            return 0
+        
+        if not args.quiet:
+            logger.info(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+            for orphan in results["orphaned"]:
+                logger.info(f"  - {orphan['name']} v{orphan['version']}")
+        
+        if dry_run:
+            logger.info(
+                f"\n📝 This was a dry run. Use --force to actually remove "
+                f"{len(results['orphaned'])} orphaned agent(s)"
+            )
+        else:
+            if results["removed"]:
+                logger.info(
+                    f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                )
+            
+            if results["errors"]:
+                logger.error(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                for error in results["errors"]:
+                    logger.error(f"  - {error}")
+                return 1
+        
+        return 0
+        
+    except Exception as e:
+        logger.error(f"Error during cleanup: {e}")
+        return 1
+
+
+# For backward compatibility
+def main(args: Optional[argparse.Namespace] = None) -> int:
+    """Main entry point for the command.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code
+    """
+    if args is None:
+        parser = argparse.ArgumentParser()
+        add_parser(parser.add_subparsers())
+        args = parser.parse_args()
+    
+    return cleanup_orphaned_agents(args)

claude_mpm/cli/commands/mcp_pipx_config.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+MCP configuration command for pipx installations.
+
+This module provides a CLI command to configure MCP for users who installed
+claude-mpm via pipx.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def find_claude_config_path() -> Path:
+    """Find the Claude Code configuration file path."""
+    system = platform.system()
+    
+    if system == "Darwin":  # macOS
+        config_path = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif system == "Windows":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            config_path = Path(appdata) / "Claude" / "claude_desktop_config.json"
+        else:
+            config_path = Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    else:  # Linux and others
+        config_path = Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+    
+    return config_path
+
+
+def check_pipx_installation() -> bool:
+    """Check if claude-mpm is installed via pipx."""
+    try:
+        # Check if running from pipx
+        if "pipx" in sys.executable.lower():
+            return True
+        
+        # Check pipx list
+        result = subprocess.run(
+            ["pipx", "list", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode == 0:
+            pipx_data = json.loads(result.stdout)
+            return "claude-mpm" in pipx_data.get("venvs", {})
+    except Exception:
+        pass
+    
+    return False
+
+
+def create_mcp_config() -> Dict[str, Any]:
+    """Create MCP configuration for pipx installation."""
+    return {
+        "mcpServers": {
+            "claude-mpm-gateway": {
+                "command": "claude-mpm-mcp"
+            }
+        }
+    }
+
+
+def configure_mcp_for_pipx(args) -> int:
+    """
+    Configure MCP for pipx installation.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    print("Claude MPM - MCP Configuration for pipx")
+    print("=" * 40)
+    
+    # Check if this is a pipx installation
+    if not check_pipx_installation():
+        print("\n⚠️  This doesn't appear to be a pipx installation")
+        print("This command is specifically for pipx users.")
+        print("\nFor other installation methods, see:")
+        print("  docs/MCP_SETUP.md")
+        
+        if not args.force:
+            return 1
+        print("\n--force flag detected, continuing anyway...")
+    
+    # Find Claude config
+    config_path = find_claude_config_path()
+    print(f"\n📁 Claude config path: {config_path}")
+    
+    # Load existing config
+    existing_config = {}
+    if config_path.exists():
+        try:
+            with open(config_path, 'r') as f:
+                existing_config = json.load(f)
+            print("✅ Existing config loaded")
+        except json.JSONDecodeError:
+            print("⚠️  Config exists but is invalid JSON")
+            if not args.force:
+                print("Use --force to overwrite")
+                return 1
+    else:
+        print("📝 Config will be created")
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Check for existing MCP config
+    if "mcpServers" in existing_config and "claude-mpm-gateway" in existing_config["mcpServers"]:
+        print("\n⚠️  claude-mpm-gateway is already configured")
+        if not args.force:
+            print("Use --force to overwrite")
+            return 0
+        print("Overwriting existing configuration...")
+    
+    # Create and merge config
+    mcp_config = create_mcp_config()
+    existing_config.update(mcp_config)
+    
+    # Show what will be written
+    if not args.quiet:
+        print("\n📝 Configuration to write:")
+        print(json.dumps(mcp_config, indent=2))
+    
+    # Write config
+    if not args.dry_run:
+        try:
+            with open(config_path, 'w') as f:
+                json.dump(existing_config, f, indent=2)
+            print(f"\n✅ Configuration written to: {config_path}")
+        except Exception as e:
+            print(f"\n❌ Failed to write config: {e}")
+            return 1
+    else:
+        print("\n--dry-run: Configuration not written")
+    
+    # Test the command
+    print("\n🧪 Testing claude-mpm-mcp command...")
+    try:
+        result = subprocess.run(
+            ["which", "claude-mpm-mcp"],
+            capture_output=True,
+            text=True,
+            timeout=2
+        )
+        if result.returncode == 0:
+            print(f"✅ Command found: {result.stdout.strip()}")
+        else:
+            print("⚠️  Command not found in PATH")
+            print("   Ensure pipx bin directory is in your PATH")
+    except Exception as e:
+        print(f"⚠️  Could not test command: {e}")
+    
+    print("\n✨ Next steps:")
+    print("1. Restart Claude Code")
+    print("2. Look for the MCP icon in the interface")
+    print("3. Try using @claude-mpm-gateway in a conversation")
+    print("\nFor more help, see: docs/MCP_PIPX_SETUP.md")
+    
+    return 0
+
+
+def add_parser(subparsers):
+    """Add the mcp-pipx-config command parser."""
+    parser = subparsers.add_parser(
+        'mcp-pipx-config',
+        help='Configure MCP for pipx installation',
+        description='Configure MCP Gateway for Claude Code when installed via pipx'
+    )
+    
+    parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force configuration even if not pipx or already configured'
+    )
+    
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Show what would be done without making changes'
+    )
+    
+    parser.add_argument(
+        '--quiet',
+        action='store_true',
+        help='Suppress non-essential output'
+    )
+    
+    parser.set_defaults(func=configure_mcp_for_pipx)

claude_mpm/cli/parsers/agents_parser.py

@@ -132,5 +132,32 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         default=3,
         help="Maximum retry attempts per package (default: 3)",
     )
+    
+    # Cleanup orphaned agents
+    cleanup_orphaned_parser = agents_subparsers.add_parser(
+        "cleanup-orphaned",
+        help="Clean up orphaned agents that don't have templates"
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        help="Directory containing deployed agents (default: .claude/agents/)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        help="Only show what would be removed without actually removing (default)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Actually remove orphaned agents (disables dry-run)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only show summary, not individual agents",
+    )
 
     return agents_parser

claude_mpm/cli/parsers/base_parser.py

@@ -338,6 +338,12 @@ def create_parser(
         from ..commands.cleanup import add_cleanup_parser
 
         add_cleanup_parser(subparsers)
+
+        # MCP pipx configuration command
+        if hasattr(CLICommands, "MCP_PIPX_CONFIG") or True:  # Always add for now
+            from ..commands.mcp_pipx_config import add_parser as add_mcp_pipx_parser
+            
+            add_mcp_pipx_parser(subparsers)
         
         from ..commands.doctor import add_doctor_parser
         

claude_mpm/cli/startup_logging.py

@@ -66,8 +66,10 @@ class StartupStatusLogger:
                     self.logger.info(f"MCP Server: {config_status['servers_count']} server(s) configured")
                 else:
                     self.logger.info("MCP Server: No servers configured")
+                    self._log_mcp_setup_hint()
             else:
                 self.logger.info("MCP Server: No configuration found in ~/.claude.json")
+                self._log_mcp_setup_hint()
             
             # Check for claude-mpm MCP gateway status
             gateway_status = self._check_mcp_gateway_status()
@@ -75,6 +77,9 @@ class StartupStatusLogger:
                 self.logger.info("MCP Gateway: Claude MPM gateway configured")
             else:
                 self.logger.info("MCP Gateway: Claude MPM gateway not configured")
+                # Check if this is a pipx installation that could benefit from auto-config
+                if self._is_pipx_installation() and not self._has_auto_config_preference():
+                    self.logger.info("MCP Gateway: Auto-configuration available for pipx users")
                 
         except Exception as e:
             self.logger.warning(f"MCP Server: Status check failed - {e}")
@@ -293,6 +298,76 @@ class StartupStatusLogger:
             result["error"] = str(e)
         
         return result
+    
+    def _is_pipx_installation(self) -> bool:
+        """Check if this is a pipx installation."""
+        try:
+            # Check if running from pipx
+            if "pipx" in sys.executable.lower():
+                return True
+            
+            # Check module path
+            import claude_mpm
+            module_path = Path(claude_mpm.__file__).parent
+            if "pipx" in str(module_path):
+                return True
+        except Exception:
+            pass
+        
+        return False
+    
+    def _has_auto_config_preference(self) -> bool:
+        """Check if user has already been asked about auto-configuration."""
+        try:
+            from ..config.paths import paths
+            preference_file = paths.claude_mpm_dir_hidden / "mcp_auto_config_preference.json"
+            return preference_file.exists()
+        except Exception:
+            return False
+    
+    def _log_mcp_setup_hint(self) -> None:
+        """Log helpful hints for MCP setup."""
+        # Check if installed via pipx
+        is_pipx = self._check_pipx_installation()
+        
+        if is_pipx:
+            self.logger.info("💡 TIP: It looks like you installed claude-mpm via pipx")
+            self.logger.info("   To configure MCP for Claude Code with pipx:")
+            self.logger.info("   1. Run: python3 scripts/configure_mcp_pipx.py")
+            self.logger.info("   2. Or see: docs/MCP_PIPX_SETUP.md for manual setup")
+            self.logger.info("   3. Restart Claude Code after configuration")
+        else:
+            self.logger.info("💡 TIP: To enable MCP integration with Claude Code:")
+            self.logger.info("   1. See docs/MCP_SETUP.md for setup instructions")
+            self.logger.info("   2. Run: claude-mpm doctor --check mcp to verify")
+            self.logger.info("   3. Restart Claude Code after configuration")
+    
+    def _check_pipx_installation(self) -> bool:
+        """Check if claude-mpm was installed via pipx."""
+        try:
+            # Check if running from a pipx venv
+            if "pipx" in sys.executable.lower():
+                return True
+            
+            # Check if claude-mpm-mcp command exists and is from pipx
+            mcp_cmd = shutil.which("claude-mpm-mcp")
+            if mcp_cmd and "pipx" in mcp_cmd.lower():
+                return True
+            
+            # Try to check pipx list
+            result = subprocess.run(
+                ["pipx", "list"],
+                capture_output=True,
+                text=True,
+                timeout=2
+            )
+            if result.returncode == 0 and "claude-mpm" in result.stdout:
+                return True
+                
+        except Exception:
+            pass
+        
+        return False
 
 
 def setup_startup_logging(project_root: Optional[Path] = None) -> Path: