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

claude_mpm/cli/parsers/mcp_parser.py

@@ -172,7 +172,7 @@ def add_mcp_subparser(subparsers) -> argparse.ArgumentParser:
         "--test", action="store_true", help="Run in test mode with debug output"
     )
     server_mcp_parser.add_argument(
-        "--instructions", action="store_true", help="Show setup instructions for Claude Desktop"
+        "--instructions", action="store_true", help="Show setup instructions for Claude Code"
     )
 
     return mcp_parser

claude_mpm/cli/parsers/run_parser.py

@@ -78,7 +78,7 @@ def add_run_arguments(parser: argparse.ArgumentParser) -> None:
     run_group.add_argument(
         "--resume",
         action="store_true",
-        help="Pass --resume flag to Claude Desktop to resume the last conversation",
+        help="Pass --resume flag to Claude Code to resume the last conversation",
     )
 
     # Dependency checking options

claude_mpm/cli/startup_logging.py

@@ -0,0 +1,463 @@
+"""
+Startup logging utilities for MCP server and monitor setup status.
+
+WHY: This module provides detailed startup logging for better debugging
+visibility. It logs MCP server installation/configuration status and
+monitor service initialization status during the startup sequence.
+
+DESIGN DECISIONS:
+- Use consistent INFO log format with existing startup messages
+- Gracefully handle missing dependencies or services
+- Provide informative but concise status messages
+- Include helpful context for debugging
+- Ensure logging works in all deployment contexts (dev, pipx, pip)
+- Capture all startup logs to timestamped files for analysis
+"""
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from ..core.logger import get_logger
+
+
+class StartupStatusLogger:
+    """Logs MCP server and monitor setup status during startup."""
+    
+    def __init__(self, logger_name: str = "startup_status"):
+        """Initialize the startup status logger."""
+        self.logger = get_logger(logger_name)
+    
+    def log_mcp_server_status(self) -> None:
+        """
+        Log MCP server installation and configuration status.
+        
+        Checks:
+        - MCP server executable availability
+        - MCP server version if available
+        - MCP configuration in ~/.claude.json
+        - MCP-related errors or warnings
+        """
+        try:
+            # Check if MCP server executable is available
+            mcp_executable = self._find_mcp_executable()
+            if mcp_executable:
+                self.logger.info(f"MCP Server: Installed at {mcp_executable}")
+                
+                # Try to get version
+                version = self._get_mcp_version(mcp_executable)
+                if version:
+                    self.logger.info(f"MCP Server: Version {version}")
+                else:
+                    self.logger.info("MCP Server: Version unknown")
+            else:
+                self.logger.info("MCP Server: Not found in PATH")
+            
+            # Check MCP configuration in ~/.claude.json
+            config_status = self._check_mcp_configuration()
+            if config_status["found"]:
+                self.logger.info("MCP Server: Configuration found in ~/.claude.json")
+                if config_status["servers_count"] > 0:
+                    self.logger.info(f"MCP Server: {config_status['servers_count']} server(s) configured")
+                else:
+                    self.logger.info("MCP Server: No servers configured")
+            else:
+                self.logger.info("MCP Server: No configuration found in ~/.claude.json")
+            
+            # Check for claude-mpm MCP gateway status
+            gateway_status = self._check_mcp_gateway_status()
+            if gateway_status["configured"]:
+                self.logger.info("MCP Gateway: Claude MPM gateway configured")
+            else:
+                self.logger.info("MCP Gateway: Claude MPM gateway not configured")
+                
+        except Exception as e:
+            self.logger.warning(f"MCP Server: Status check failed - {e}")
+    
+    def log_monitor_setup_status(self, monitor_mode: bool = False, websocket_port: int = 8765) -> None:
+        """
+        Log monitor service initialization status.
+        
+        Args:
+            monitor_mode: Whether monitor mode is enabled
+            websocket_port: WebSocket port for monitoring
+            
+        Checks:
+        - Monitor service initialization status
+        - Which monitors are enabled/disabled
+        - Monitor configuration details
+        - Monitor-related errors or warnings
+        """
+        try:
+            if monitor_mode:
+                self.logger.info("Monitor: Mode enabled")
+                
+                # Check SocketIO dependencies
+                socketio_status = self._check_socketio_dependencies()
+                if socketio_status["available"]:
+                    self.logger.info("Monitor: Socket.IO dependencies available")
+                else:
+                    self.logger.info(f"Monitor: Socket.IO dependencies missing - {socketio_status['error']}")
+                
+                # Check if server is running
+                server_running = self._check_socketio_server_running(websocket_port)
+                if server_running:
+                    self.logger.info(f"Monitor: Socket.IO server running on port {websocket_port}")
+                else:
+                    self.logger.info(f"Monitor: Socket.IO server will start on port {websocket_port}")
+                
+                # Check response logging configuration
+                logging_config = self._check_response_logging_config()
+                if logging_config["enabled"]:
+                    self.logger.info(f"Monitor: Response logging enabled to {logging_config['directory']}")
+                else:
+                    self.logger.info("Monitor: Response logging disabled")
+                    
+            else:
+                self.logger.info("Monitor: Mode disabled")
+                
+                # Still check if there's an existing server running
+                server_running = self._check_socketio_server_running(websocket_port)
+                if server_running:
+                    self.logger.info(f"Monitor: Background Socket.IO server detected on port {websocket_port}")
+                    
+        except Exception as e:
+            self.logger.warning(f"Monitor: Status check failed - {e}")
+    
+    def _find_mcp_executable(self) -> Optional[str]:
+        """Find MCP server executable in PATH."""
+        # Common MCP executable names
+        executables = ["claude-mpm-mcp", "mcp", "claude-mcp"]
+        
+        for exe_name in executables:
+            exe_path = shutil.which(exe_name)
+            if exe_path:
+                return exe_path
+        
+        # Check if it's installed as a Python package
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "claude_mpm.scripts.mcp_server", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode == 0:
+                return f"{sys.executable} -m claude_mpm.scripts.mcp_server"
+        except Exception:
+            pass
+        
+        return None
+    
+    def _get_mcp_version(self, executable: str) -> Optional[str]:
+        """Get MCP server version."""
+        try:
+            # Try --version flag
+            result = subprocess.run(
+                executable.split() + ["--version"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode == 0:
+                # Extract version from output
+                output = result.stdout.strip()
+                if output:
+                    return output
+            
+            # Try version command
+            result = subprocess.run(
+                executable.split() + ["version"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode == 0:
+                output = result.stdout.strip()
+                if output:
+                    return output
+                    
+        except Exception:
+            pass
+        
+        return None
+    
+    def _check_mcp_configuration(self) -> Dict[str, Any]:
+        """Check MCP configuration in ~/.claude.json."""
+        claude_json_path = Path.home() / ".claude.json"
+        
+        result = {
+            "found": False,
+            "servers_count": 0,
+            "error": None
+        }
+        
+        try:
+            if not claude_json_path.exists():
+                return result
+            
+            import json
+            with open(claude_json_path, 'r') as f:
+                config = json.load(f)
+            
+            result["found"] = True
+            
+            # Check for MCP servers configuration
+            mcp_config = config.get("mcpServers", {})
+            result["servers_count"] = len(mcp_config)
+            
+        except Exception as e:
+            result["error"] = str(e)
+        
+        return result
+    
+    def _check_mcp_gateway_status(self) -> Dict[str, Any]:
+        """Check Claude MPM MCP gateway configuration status."""
+        result = {
+            "configured": False,
+            "error": None
+        }
+        
+        try:
+            # Check if MCP gateway startup verification is available
+            from ..services.mcp_gateway.core.startup_verification import is_mcp_gateway_configured
+            result["configured"] = is_mcp_gateway_configured()
+        except ImportError:
+            # MCP gateway not available
+            pass
+        except Exception as e:
+            result["error"] = str(e)
+        
+        return result
+    
+    def _check_socketio_dependencies(self) -> Dict[str, Any]:
+        """Check if Socket.IO dependencies are available."""
+        result = {
+            "available": False,
+            "error": None
+        }
+        
+        try:
+            import socketio
+            import aiohttp
+            import engineio
+            result["available"] = True
+        except ImportError as e:
+            result["error"] = f"Missing dependencies: {e}"
+        except Exception as e:
+            result["error"] = str(e)
+        
+        return result
+    
+    def _check_socketio_server_running(self, port: int) -> bool:
+        """Check if Socket.IO server is running on specified port."""
+        try:
+            import socket
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.settimeout(1)
+                result = s.connect_ex(('localhost', port))
+                return result == 0
+        except Exception:
+            return False
+    
+    def _check_response_logging_config(self) -> Dict[str, Any]:
+        """Check response logging configuration."""
+        result = {
+            "enabled": False,
+            "directory": None,
+            "error": None
+        }
+        
+        try:
+            from ..core.shared.config_loader import ConfigLoader
+            
+            config_loader = ConfigLoader()
+            config = config_loader.load_main_config()
+            
+            # Check response logging configuration
+            response_logging = config.get("response_logging", {})
+            result["enabled"] = response_logging.get("enabled", False)
+            
+            if result["enabled"]:
+                log_dir = response_logging.get("session_directory", ".claude-mpm/responses")
+                if not Path(log_dir).is_absolute():
+                    log_dir = Path.cwd() / log_dir
+                result["directory"] = str(log_dir)
+            
+        except Exception as e:
+            result["error"] = str(e)
+        
+        return result
+
+
+def setup_startup_logging(project_root: Optional[Path] = None) -> Path:
+    """
+    Set up logging to both console and file for startup.
+    
+    WHY: Capture all startup logs (INFO, WARNING, ERROR, DEBUG) to timestamped
+    files for later analysis by the doctor command. This helps diagnose
+    startup issues that users may not notice in the console output.
+    
+    DESIGN DECISIONS:
+    - Use ISO-like timestamp format for easy sorting and reading
+    - Store in .claude-mpm/logs/startup/ directory
+    - Keep all historical startup logs for pattern analysis
+    - Add file handler to root logger to capture ALL module logs
+    
+    Args:
+        project_root: Root directory for the project (defaults to cwd)
+        
+    Returns:
+        Path to the created log file
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    
+    # Create log directory
+    log_dir = project_root / ".claude-mpm" / "logs" / "startup"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Generate timestamp for log file
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+    log_file = log_dir / f"startup-{timestamp}.log"
+    
+    # Create file handler with detailed formatting
+    file_handler = logging.FileHandler(log_file, encoding='utf-8')
+    file_handler.setLevel(logging.DEBUG)  # Capture all levels to file
+    
+    # Format with timestamp, logger name, level, and message
+    formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    file_handler.setFormatter(formatter)
+    
+    # Add to claude_mpm logger to capture all our logs
+    # (Don't add to root logger to avoid duplicates from propagation)
+    claude_logger = logging.getLogger("claude_mpm")
+    claude_logger.addHandler(file_handler)
+    claude_logger.setLevel(logging.DEBUG)  # Ensure all levels are captured
+    
+    # Log startup header
+    logger = get_logger("startup")
+    logger.info("="*60)
+    logger.info(f"Claude MPM Startup - {datetime.now().isoformat()}")
+    logger.info(f"Log file: {log_file}")
+    logger.info("="*60)
+    
+    # Log system information
+    logger.info(f"Python: {sys.version}")
+    logger.info(f"Platform: {sys.platform}")
+    logger.info(f"CWD: {Path.cwd()}")
+    logger.info(f"Project root: {project_root}")
+    
+    return log_file
+
+
+def cleanup_old_startup_logs(project_root: Optional[Path] = None, 
+                            keep_days: int = 7,
+                            keep_min_count: int = 10) -> int:
+    """
+    Clean up old startup log files.
+    
+    WHY: Prevent unbounded growth of startup logs while keeping enough
+    history for debugging patterns.
+    
+    DESIGN DECISIONS:
+    - Keep logs from last N days
+    - Always keep minimum count regardless of age
+    - Return count of deleted files for reporting
+    
+    Args:
+        project_root: Root directory for the project
+        keep_days: Number of days to keep logs
+        keep_min_count: Minimum number of logs to keep regardless of age
+        
+    Returns:
+        Number of log files deleted
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    
+    log_dir = project_root / ".claude-mpm" / "logs" / "startup"
+    
+    if not log_dir.exists():
+        return 0
+    
+    # Get all startup log files
+    log_files = sorted(log_dir.glob("startup-*.log"), 
+                      key=lambda p: p.stat().st_mtime,
+                      reverse=True)  # Newest first
+    
+    if len(log_files) <= keep_min_count:
+        return 0  # Keep minimum count
+    
+    # Calculate cutoff time
+    cutoff_time = datetime.now().timestamp() - (keep_days * 24 * 60 * 60)
+    
+    deleted_count = 0
+    for log_file in log_files[keep_min_count:]:  # Skip minimum count
+        if log_file.stat().st_mtime < cutoff_time:
+            try:
+                log_file.unlink()
+                deleted_count += 1
+            except Exception:
+                pass  # Ignore deletion errors
+    
+    return deleted_count
+
+
+def get_latest_startup_log(project_root: Optional[Path] = None) -> Optional[Path]:
+    """
+    Get the path to the most recent startup log file.
+    
+    Args:
+        project_root: Root directory for the project
+        
+    Returns:
+        Path to latest log file or None if no logs exist
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    
+    log_dir = project_root / ".claude-mpm" / "logs" / "startup"
+    
+    if not log_dir.exists():
+        return None
+    
+    log_files = sorted(log_dir.glob("startup-*.log"),
+                      key=lambda p: p.stat().st_mtime,
+                      reverse=True)
+    
+    return log_files[0] if log_files else None
+
+
+def log_startup_status(monitor_mode: bool = False, websocket_port: int = 8765) -> None:
+    """
+    Log comprehensive startup status for MCP server and monitor setup.
+    
+    This function should be called during application startup to provide
+    detailed information about MCP and monitor setup status.
+    
+    Args:
+        monitor_mode: Whether monitor mode is enabled
+        websocket_port: WebSocket port for monitoring
+    """
+    try:
+        status_logger = StartupStatusLogger("cli")
+        
+        # Log MCP server status
+        status_logger.log_mcp_server_status()
+        
+        # Log monitor setup status
+        status_logger.log_monitor_setup_status(monitor_mode, websocket_port)
+        
+    except Exception as e:
+        # Don't let logging failures prevent startup
+        logger = get_logger("cli")
+        logger.debug(f"Startup status logging failed: {e}")

claude_mpm/constants.py

@@ -40,6 +40,7 @@ class CLICommands(str, Enum):
     AGGREGATE = "aggregate"
     CLEANUP = "cleanup-memory"
     MCP = "mcp"
+    DOCTOR = "doctor"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""

claude_mpm/core/claude_runner.py

@@ -210,6 +210,10 @@ class ClaudeRunner:
         else:
             self.system_instructions = self._load_system_instructions()
 
+        # Deploy output style early (before Claude Code launches)
+        # This ensures the "Claude MPM" output style is active on startup
+        self._deploy_output_style()
+        
         # Create session log file using configuration service
         self.session_log_file = self.configuration_service.create_session_log_file(
             self.project_logger, self.log_level, config_data
@@ -732,6 +736,80 @@ Use these agents to delegate specialized work via the Task tool.
             # Fallback if service not available
             return "v0.0.0"
 
+    def _deploy_output_style(self) -> None:
+        """Deploy the Claude MPM output style before Claude Code launches.
+        
+        This method ensures the output style is set to "Claude MPM" on startup
+        by deploying the style file and updating Claude Code settings.
+        Only works for Claude Code >= 1.0.83.
+        """
+        try:
+            from claude_mpm.core.output_style_manager import OutputStyleManager
+            
+            # Create OutputStyleManager instance
+            output_style_manager = OutputStyleManager()
+            
+            # Check if Claude Code supports output styles
+            if not output_style_manager.supports_output_styles():
+                self.logger.debug(
+                    f"Claude Code version {output_style_manager.claude_version or 'unknown'} "
+                    "does not support output styles (requires >= 1.0.83)"
+                )
+                return
+            
+            # Check if output style is already deployed and active
+            settings_file = Path.home() / ".claude" / "settings.json"
+            if settings_file.exists():
+                try:
+                    import json
+                    settings = json.loads(settings_file.read_text())
+                    if settings.get("activeOutputStyle") == "claude-mpm":
+                        # Already active, check if file exists
+                        output_style_file = Path.home() / ".claude" / "output-styles" / "claude-mpm.md"
+                        if output_style_file.exists():
+                            self.logger.debug("Output style 'Claude MPM' already deployed and active")
+                            return
+                except Exception:
+                    pass  # Continue with deployment if we can't read settings
+            
+            # Read the OUTPUT_STYLE.md content if it exists
+            output_style_path = Path(__file__).parent.parent / "agents" / "OUTPUT_STYLE.md"
+            
+            if output_style_path.exists():
+                # Use existing OUTPUT_STYLE.md content
+                output_style_content = output_style_path.read_text()
+                self.logger.debug("Using existing OUTPUT_STYLE.md content")
+            else:
+                # Extract output style content from framework instructions
+                output_style_content = output_style_manager.extract_output_style_content()
+                self.logger.debug("Extracted output style from framework instructions")
+            
+            # Deploy the output style
+            deployed = output_style_manager.deploy_output_style(output_style_content)
+            
+            if deployed:
+                self.logger.info("✅ Output style 'Claude MPM' deployed and activated on startup")
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        "Output style 'Claude MPM' deployed and activated on startup",
+                        level="INFO",
+                        component="output_style"
+                    )
+            else:
+                self.logger.warning("Failed to deploy output style")
+                
+        except ImportError as e:
+            self.logger.warning(f"Could not import OutputStyleManager: {e}")
+        except Exception as e:
+            # Don't fail startup if output style deployment fails
+            self.logger.warning(f"Error deploying output style: {e}")
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Output style deployment error: {e}",
+                    level="WARNING", 
+                    component="output_style"
+                )
+
     def _launch_subprocess_interactive(self, cmd: list, env: dict):
         """Launch Claude as a subprocess with PTY for interactive mode.
 

claude_mpm/core/framework_loader.py

@@ -77,11 +77,11 @@ class FrameworkLoader:
             output_style_content = self.output_style_manager.extract_output_style_content(framework_loader=self)
             output_style_path = self.output_style_manager.save_output_style(output_style_content)
             
-            # Deploy to Claude Desktop if supported
+            # Deploy to Claude Code if supported
             deployed = self.output_style_manager.deploy_output_style(output_style_content)
             
             if deployed:
-                self.logger.info("✅ Output style deployed to Claude Desktop >= 1.0.83")
+                self.logger.info("✅ Output style deployed to Claude Code >= 1.0.83")
             else:
                 self.logger.info("📝 Output style will be injected into instructions for older Claude versions")
                 
@@ -97,11 +97,11 @@ class FrameworkLoader:
         # Claude version detection
         claude_version = self.output_style_manager.claude_version
         if claude_version:
-            self.logger.info(f"Claude Desktop version detected: {claude_version}")
+            self.logger.info(f"Claude Code version detected: {claude_version}")
             
             # Check if version supports output styles
             if self.output_style_manager.supports_output_styles():
-                self.logger.info("✅ Claude Desktop supports output styles (>= 1.0.83)")
+                self.logger.info("✅ Claude Code supports output styles (>= 1.0.83)")
                 
                 # Check deployment status
                 output_style_path = self.output_style_manager.output_style_path
@@ -111,10 +111,10 @@ class FrameworkLoader:
                     self.logger.info(f"📝 Output style will be created at: {output_style_path}")
                     
             else:
-                self.logger.info(f"⚠️ Claude Desktop {claude_version} does not support output styles (< 1.0.83)")
+                self.logger.info(f"⚠️ Claude Code {claude_version} does not support output styles (< 1.0.83)")
                 self.logger.info("📝 Output style content will be injected into framework instructions")
         else:
-            self.logger.info("⚠️ Claude Desktop not detected or version unknown")
+            self.logger.info("⚠️ Claude Code not detected or version unknown")
             self.logger.info("📝 Output style content will be injected into framework instructions as fallback")
 
     def _detect_framework_path(self) -> Optional[Path]:
@@ -311,17 +311,41 @@ class FrameworkLoader:
 
     def _load_instructions_file(self, content: Dict[str, Any]) -> None:
         """
-        Load INSTRUCTIONS.md or legacy CLAUDE.md from working directory.
+        Load custom INSTRUCTIONS.md from .claude-mpm directories.
 
-        NOTE: We no longer load CLAUDE.md since Claude Code already picks it up automatically.
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/INSTRUCTIONS.md
+        2. User-specific: ~/.claude-mpm/INSTRUCTIONS.md
+        
+        NOTE: We do NOT load CLAUDE.md files since Claude Code already picks them up automatically.
         This prevents duplication of instructions.
 
         Args:
             content: Dictionary to update with loaded instructions
         """
-        # Disabled - Claude Code already reads CLAUDE.md automatically
-        # We don't need to duplicate it in the PM instructions
-        pass
+        # Check for project-specific INSTRUCTIONS.md first
+        project_instructions_path = Path.cwd() / ".claude-mpm" / "INSTRUCTIONS.md"
+        if project_instructions_path.exists():
+            loaded_content = self._try_load_file(
+                project_instructions_path, "project-specific INSTRUCTIONS.md"
+            )
+            if loaded_content:
+                content["custom_instructions"] = loaded_content
+                content["custom_instructions_level"] = "project"
+                self.logger.info("Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md")
+                return
+        
+        # Check for user-specific INSTRUCTIONS.md
+        user_instructions_path = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
+        if user_instructions_path.exists():
+            loaded_content = self._try_load_file(
+                user_instructions_path, "user-specific INSTRUCTIONS.md"
+            )
+            if loaded_content:
+                content["custom_instructions"] = loaded_content
+                content["custom_instructions_level"] = "user"
+                self.logger.info("Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md")
+                return
 
     def _load_workflow_instructions(self, content: Dict[str, Any]) -> None:
         """
@@ -1101,6 +1125,16 @@ class FrameworkLoader:
 
             # Note: We don't add working directory CLAUDE.md here since Claude Code
             # already picks it up automatically. This prevents duplication.
+            
+            # Add custom INSTRUCTIONS.md if present (overrides or extends framework instructions)
+            if self.framework_content.get("custom_instructions"):
+                level = self.framework_content.get("custom_instructions_level", "unknown")
+                instructions += f"\n\n## Custom PM Instructions ({level} level)\n\n"
+                instructions += "**The following custom instructions override or extend the framework defaults:**\n\n"
+                instructions += self._strip_metadata_comments(
+                    self.framework_content["custom_instructions"]
+                )
+                instructions += "\n"
 
             # Add WORKFLOW.md after instructions
             if self.framework_content.get("workflow_instructions"):