claude-mpm 4.0.29__py3-none-any.whl → 4.0.31__py3-none-any.whl

claude_mpm/core/interactive_session.py

@@ -206,7 +206,7 @@ class InteractiveSession:
             return self._attempt_fallback_launch(environment)
 
     def process_interactive_command(self, prompt: str) -> Optional[bool]:
-        """Process special interactive commands like /agents.
+        """Process special interactive commands like /agents and /mpm-doctor.
 
         Args:
             prompt: User input command
@@ -214,9 +214,19 @@ class InteractiveSession:
         Returns:
             Optional[bool]: True if handled, False if error, None if not a special command
         """
+        # Parse command and arguments
+        parts = prompt.strip().split()
+        if not parts:
+            return None
+            
+        command = parts[0]
+        args = parts[1:]
+        
         # Check for special commands
-        if prompt.strip() == "/agents":
+        if command == "/agents":
             return self._show_available_agents()
+        elif command == "/mpm-doctor":
+            return self._run_doctor_diagnostics(args)
 
         # Not a special command
         return None
@@ -310,7 +320,13 @@ class InteractiveSession:
             print(f"\033[32m│\033[0m   {output_style_info:<49}\033[32m│\033[0m")
         print("\033[32m│                                                   │\033[0m")
         print(
-            "\033[32m│\033[0m   Type '/agents' to see available agents          \033[32m│\033[0m"
+            "\033[32m│\033[0m   Commands:                                       \033[32m│\033[0m"
+        )
+        print(
+            "\033[32m│\033[0m     /agents      - Show available agents          \033[32m│\033[0m"
+        )
+        print(
+            "\033[32m│\033[0m     /mpm-doctor  - Run diagnostic checks          \033[32m│\033[0m"
         )
         print("\033[32m╰───────────────────────────────────────────────────╯\033[0m")
         print("")  # Add blank line after box
@@ -552,3 +568,66 @@ class InteractiveSession:
         except Exception as e:
             print(f"Error getting agent versions: {e}")
             return False
+
+    def _run_doctor_diagnostics(self, args: list) -> bool:
+        """Run doctor diagnostics from interactive mode.
+        
+        Args:
+            args: Command arguments (e.g., ['--verbose'])
+            
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            from claude_mpm.services.diagnostics import DiagnosticRunner, DoctorReporter
+            
+            # Parse arguments
+            verbose = "--verbose" in args or "-v" in args
+            no_color = "--no-color" in args
+            
+            # Print header
+            print("\n" + "="*60)
+            print("Claude MPM Doctor Report")
+            print("="*60)
+            
+            # Create diagnostic runner
+            runner = DiagnosticRunner(verbose=verbose)
+            
+            # Run diagnostics
+            try:
+                summary = runner.run_diagnostics()
+            except KeyboardInterrupt:
+                print("\nDiagnostics interrupted by user")
+                return False
+            except Exception as e:
+                print(f"\n❌ Diagnostic failed: {str(e)}")
+                if verbose:
+                    import traceback
+                    traceback.print_exc()
+                return False
+            
+            # Create reporter
+            reporter = DoctorReporter(
+                use_color=not no_color,
+                verbose=verbose
+            )
+            
+            # Display results in terminal format
+            reporter.report(summary, format="terminal")
+            
+            # Return based on status
+            if summary.error_count > 0:
+                return False
+            
+            return True
+            
+        except ImportError as e:
+            print(f"Error: Diagnostics module not available: {e}")
+            print("Please ensure claude-mpm is properly installed")
+            return False
+        except Exception as e:
+            print(f"Error running diagnostics: {e}")
+            if "--verbose" in args or "-v" in args:
+                import traceback
+                traceback.print_exc()
+            return False

claude_mpm/core/output_style_manager.py

@@ -3,7 +3,7 @@
 This module handles:
 1. Claude version detection
 2. Output style extraction from framework instructions  
-3. One-time deployment to Claude Desktop >= 1.0.83 at startup
+3. One-time deployment to Claude Code >= 1.0.83 at startup
 4. Fallback injection for older versions
 
 The output style is set once at startup and not monitored or enforced after that.
@@ -41,7 +41,7 @@ class OutputStyleManager:
 
     def _detect_claude_version(self) -> Optional[str]:
         """
-        Detect Claude Desktop version by running 'claude --version'.
+        Detect Claude Code version by running 'claude --version'.
         
         Returns:
             Version string (e.g., "1.0.82") or None if Claude not found
@@ -73,7 +73,7 @@ class OutputStyleManager:
                 return None
                 
         except FileNotFoundError:
-            self.logger.info("Claude Desktop not found in PATH")
+            self.logger.info("Claude Code not found in PATH")
             return None
         except subprocess.TimeoutExpired:
             self.logger.warning("Claude version check timed out")
@@ -116,7 +116,7 @@ class OutputStyleManager:
 
     def supports_output_styles(self) -> bool:
         """
-        Check if Claude Desktop supports output styles (>= 1.0.83).
+        Check if Claude Code supports output styles (>= 1.0.83).
         
         Returns:
             True if Claude version >= 1.0.83, False otherwise
@@ -324,7 +324,7 @@ class OutputStyleManager:
 
     def deploy_output_style(self, content: str) -> bool:
         """
-        Deploy output style to Claude Desktop if version >= 1.0.83.
+        Deploy output style to Claude Code if version >= 1.0.83.
         Deploys the style file and activates it once.
         
         Args:
@@ -356,7 +356,7 @@ class OutputStyleManager:
 
     def _activate_output_style(self) -> bool:
         """
-        Update Claude Desktop settings to activate the claude-mpm output style.
+        Update Claude Code settings to activate the claude-mpm output style.
         Sets activeOutputStyle to "claude-mpm" once at startup.
         
         Returns:

claude_mpm/core/unified_paths.py

@@ -641,6 +641,128 @@ class UnifiedPathManager:
         if src_dir.exists() and str(src_dir) not in sys.path:
             sys.path.insert(0, str(src_dir))
 
+    def get_executable_path(self) -> Optional[Path]:
+        """Get the path to the claude-mpm executable for the current deployment context.
+        
+        This method provides deployment-context-aware executable path detection,
+        particularly useful for MCP server configuration.
+        
+        Returns:
+            Path to executable or None if not found
+        """
+        import shutil
+        
+        # Try standard which first
+        which_result = shutil.which("claude-mpm")
+        if which_result:
+            return Path(which_result)
+        
+        # Enhanced detection based on deployment context
+        if self._deployment_context == DeploymentContext.PIPX_INSTALL:
+            return self._find_pipx_executable()
+        elif self._deployment_context in (DeploymentContext.DEVELOPMENT, DeploymentContext.EDITABLE_INSTALL):
+            return self._find_development_executable()
+        elif self._deployment_context == DeploymentContext.PIP_INSTALL:
+            return self._find_pip_executable()
+        
+        return None
+    
+    def _find_pipx_executable(self) -> Optional[Path]:
+        """Find claude-mpm executable in pipx installation."""
+        try:
+            import claude_mpm
+            module_path = Path(claude_mpm.__file__).parent
+            
+            if "pipx" not in str(module_path):
+                return None
+            
+            # Common pipx executable locations
+            home = Path.home()
+            pipx_paths = [
+                home / ".local" / "bin" / "claude-mpm",
+                home / ".local" / "share" / "pipx" / "venvs" / "claude-mpm" / "bin" / "claude-mpm",
+            ]
+            
+            # Windows paths
+            if sys.platform == "win32":
+                pipx_paths.extend([
+                    home / "AppData" / "Local" / "pipx" / "bin" / "claude-mpm.exe",
+                    home / ".local" / "bin" / "claude-mpm.exe",
+                ])
+            
+            for path in pipx_paths:
+                if path.exists():
+                    logger.debug(f"Found pipx executable: {path}")
+                    return path
+            
+            # Try to derive from module path
+            # Navigate up from module to find venv, then to bin
+            venv_path = module_path
+            for _ in range(5):  # Prevent infinite loops
+                if venv_path.name == "claude-mpm" and (venv_path / "pyvenv.cfg").exists():
+                    # Found the venv directory
+                    bin_dir = venv_path / ("Scripts" if sys.platform == "win32" else "bin")
+                    exe_name = "claude-mpm.exe" if sys.platform == "win32" else "claude-mpm"
+                    exe_path = bin_dir / exe_name
+                    
+                    if exe_path.exists():
+                        logger.debug(f"Found pipx executable via module path: {exe_path}")
+                        return exe_path
+                    break
+                
+                if venv_path == venv_path.parent:
+                    break
+                venv_path = venv_path.parent
+                
+        except Exception as e:
+            logger.debug(f"Error finding pipx executable: {e}")
+        
+        return None
+    
+    def _find_development_executable(self) -> Optional[Path]:
+        """Find claude-mpm executable in development installation."""
+        # For development, prefer the script in the project
+        scripts_dir = self.get_scripts_dir()
+        dev_executable = scripts_dir / "claude-mpm"
+        
+        if dev_executable.exists():
+            return dev_executable
+        
+        # Check if we're in a development venv
+        if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
+            venv_bin = Path(sys.prefix) / ("Scripts" if sys.platform == "win32" else "bin")
+            venv_executable = venv_bin / "claude-mpm"
+            if venv_executable.exists():
+                return venv_executable
+        
+        return None
+    
+    def _find_pip_executable(self) -> Optional[Path]:
+        """Find claude-mpm executable in pip installation."""
+        # For pip installs, check the current Python environment
+        if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
+            # In a virtual environment
+            venv_bin = Path(sys.prefix) / ("Scripts" if sys.platform == "win32" else "bin")
+            venv_executable = venv_bin / "claude-mpm"
+            if venv_executable.exists():
+                return venv_executable
+        
+        # Check system-wide installation
+        try:
+            import site
+            for site_dir in site.getsitepackages():
+                # Look for installed scripts
+                site_path = Path(site_dir)
+                scripts_dir = site_path.parent / ("Scripts" if sys.platform == "win32" else "bin")
+                if scripts_dir.exists():
+                    exe_path = scripts_dir / "claude-mpm"
+                    if exe_path.exists():
+                        return exe_path
+        except Exception as e:
+            logger.debug(f"Error finding pip executable: {e}")
+        
+        return None
+
 
 # ============================================================================
 # Singleton Instance and Convenience Functions
@@ -701,6 +823,11 @@ def get_package_resource_path(resource_path: str) -> Path:
     return get_path_manager().get_package_resource_path(resource_path)
 
 
+def get_executable_path() -> Optional[Path]:
+    """Get the claude-mpm executable path for the current deployment context."""
+    return get_path_manager().get_executable_path()
+
+
 # ============================================================================
 # Export All Public Symbols
 # ============================================================================
@@ -719,4 +846,5 @@ __all__ = [
     "get_config_dir",
     "find_file_upwards",
     "get_package_resource_path",
+    "get_executable_path",
 ]

claude_mpm/scripts/mcp_server.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""MCP Server launcher script for Claude Desktop.
+"""MCP Server launcher script for Claude Code.
 
-This script launches the MCP gateway server for Claude Desktop integration.
+This script launches the MCP gateway server for Claude Code integration.
 It handles proper Python path setup and error reporting to stderr.
 """
 

claude_mpm/services/agents/deployment/agent_validator.py

@@ -324,6 +324,7 @@ class AgentValidator:
         agent_info = {
             "file": agent_file.name,
             "name": agent_file.stem,
+            "path": str(agent_file),
             "description": "No description",
             "version": "unknown",
         }

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -363,6 +363,10 @@ class MultiSourceAgentDeploymentService:
                     source_match = re.search(r'^source:\s*(.+)$', deployed_content, re.MULTILINE)
                     if source_match:
                         deployed_source = source_match.group(1).strip()
+                
+                # If source is still unknown, try to infer it from deployment context
+                if deployed_source == "unknown":
+                    deployed_source = self._infer_agent_source_from_context(agent_name, deployed_agents_dir)
             except Exception as e:
                 self.logger.warning(f"Error reading deployed agent '{agent_name}': {e}")
                 comparison_results["needs_update"].append(agent_name)
@@ -438,4 +442,68 @@ class MultiSourceAgentDeploymentService:
                     f"{downgrade['template_version']}"
                 )
         
-        return comparison_results
+        return comparison_results
+    
+    def _infer_agent_source_from_context(self, agent_name: str, deployed_agents_dir: Path) -> str:
+        """Infer the source of a deployed agent when source metadata is missing.
+        
+        This method attempts to determine the agent source based on:
+        1. Deployment context (development vs pipx)
+        2. Agent naming patterns
+        3. Known system agents
+        
+        Args:
+            agent_name: Name of the agent
+            deployed_agents_dir: Directory where agent is deployed
+            
+        Returns:
+            Inferred source string (system/project/user)
+        """
+        # List of known system agents that ship with claude-mpm
+        system_agents = {
+            "pm", "engineer", "qa", "research", "documentation", "ops", 
+            "security", "web-ui", "api-qa", "version-control"
+        }
+        
+        # If this is a known system agent, it's from system
+        if agent_name in system_agents:
+            return "system"
+        
+        # Check deployment context
+        from ....core.unified_paths import get_path_manager
+        path_manager = get_path_manager()
+        
+        # If deployed_agents_dir is under user home/.claude/agents, check context
+        user_claude_dir = Path.home() / ".claude" / "agents"
+        if deployed_agents_dir == user_claude_dir:
+            # Check if we're in development mode
+            try:
+                from ....core.unified_paths import DeploymentContext, PathContext
+                deployment_context = PathContext.detect_deployment_context()
+                
+                if deployment_context in (DeploymentContext.DEVELOPMENT, DeploymentContext.EDITABLE_INSTALL):
+                    # In development mode, unknown agents are likely system agents being tested
+                    return "system"
+                elif deployment_context == DeploymentContext.PIPX_INSTALL:
+                    # In pipx mode, unknown agents could be system agents
+                    # Check if agent follows system naming patterns
+                    if agent_name.count('-') <= 2 and len(agent_name) <= 20:
+                        return "system"
+            except Exception:
+                pass
+        
+        # Check if deployed to project-specific directory
+        try:
+            project_root = path_manager.project_root
+            if str(deployed_agents_dir).startswith(str(project_root)):
+                return "project"
+        except Exception:
+            pass
+        
+        # Default inference based on naming patterns
+        # System agents typically have simple names
+        if '-' not in agent_name or agent_name.count('-') <= 1:
+            return "system"
+        
+        # Complex names are more likely to be user/project agents
+        return "user"

claude_mpm/services/agents/deployment/system_instructions_deployer.py

@@ -53,8 +53,8 @@ class SystemInstructionsDeployer:
             framework_files = [
                 (
                     "INSTRUCTIONS.md",
-                    "CLAUDE.md",
-                ),  # INSTRUCTIONS.md deploys as CLAUDE.md
+                    "INSTRUCTIONS.md",
+                ),  # Keep INSTRUCTIONS.md as is - NEVER rename to CLAUDE.md
                 ("WORKFLOW.md", "WORKFLOW.md"),
                 ("MEMORY.md", "MEMORY.md"),
             ]

claude_mpm/services/diagnostics/__init__.py

@@ -0,0 +1,18 @@
+"""
+Diagnostic service for claude-mpm health checks.
+
+WHY: Provide a comprehensive diagnostic tool to help users identify and fix
+common issues with their claude-mpm installation and configuration.
+
+DESIGN DECISIONS:
+- Modular check system for easy extension
+- Interface-based design for consistency
+- Clear status levels (ok, warning, error)
+- Actionable fix suggestions
+"""
+
+from .diagnostic_runner import DiagnosticRunner
+from .doctor_reporter import DoctorReporter
+from .models import DiagnosticResult, DiagnosticStatus
+
+__all__ = ["DiagnosticRunner", "DoctorReporter", "DiagnosticResult", "DiagnosticStatus"]

claude_mpm/services/diagnostics/checks/__init__.py

@@ -0,0 +1,30 @@
+"""
+Diagnostic checks for claude-mpm doctor command.
+
+WHY: Modular checks allow for easy extension and testing of individual
+diagnostic components.
+"""
+
+from .agent_check import AgentCheck
+from .base_check import BaseDiagnosticCheck
+from .claude_desktop_check import ClaudeDesktopCheck
+from .common_issues_check import CommonIssuesCheck
+from .configuration_check import ConfigurationCheck
+from .filesystem_check import FilesystemCheck
+from .installation_check import InstallationCheck
+from .mcp_check import MCPCheck
+from .monitor_check import MonitorCheck
+from .startup_log_check import StartupLogCheck
+
+__all__ = [
+    "BaseDiagnosticCheck",
+    "InstallationCheck",
+    "ConfigurationCheck",
+    "ClaudeDesktopCheck",
+    "AgentCheck",
+    "MCPCheck",
+    "MonitorCheck",
+    "FilesystemCheck",
+    "CommonIssuesCheck",
+    "StartupLogCheck",
+]