claude-mpm 5.0.2__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/services/command_deployment_service.py

@@ -7,7 +7,6 @@ This service handles:
 4. Parsing and validating YAML frontmatter for namespace metadata (Phase 1 - 1M-400)
 """
 
-import shutil
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -20,6 +19,16 @@ from claude_mpm.core.logger import get_logger
 class CommandDeploymentService(BaseService):
     """Service for deploying MPM slash commands."""
 
+    # Deprecated commands that have been replaced (cleanup on startup)
+    DEPRECATED_COMMANDS = [
+        "mpm-agents.md",  # Replaced by mpm-agents-list.md
+        "mpm-auto-configure.md",  # Replaced by mpm-agents-auto-configure.md
+        "mpm-config.md",  # Replaced by mpm-config-view.md
+        "mpm-organize.md",  # Replaced by mpm-ticket-organize.md
+        "mpm-resume.md",  # Replaced by mpm-session-resume.md
+        "mpm-ticket.md",  # Replaced by mpm-ticket-view.md
+    ]
+
     def __init__(self):
         """Initialize the command deployment service."""
         super().__init__(name="command_deployment")
@@ -115,6 +124,33 @@ class CommandDeploymentService(BaseService):
 
         return errors
 
+    def _strip_deprecated_aliases(self, content: str) -> str:
+        """Strip deprecated_aliases from frontmatter to hide them from Claude Code UI.
+
+        This prevents deprecated aliases from appearing in the command list while
+        maintaining backward compatibility through command routing.
+
+        Args:
+            content: Command file content with frontmatter
+
+        Returns:
+            Content with deprecated_aliases removed from frontmatter
+        """
+        frontmatter, body = self._parse_frontmatter(content)
+
+        if not frontmatter or "deprecated_aliases" not in frontmatter:
+            return content
+
+        # Remove deprecated_aliases from frontmatter
+        frontmatter_copy = frontmatter.copy()
+        del frontmatter_copy["deprecated_aliases"]
+
+        # Reconstruct the file with modified frontmatter
+        frontmatter_yaml = yaml.dump(
+            frontmatter_copy, default_flow_style=False, sort_keys=False
+        )
+        return f"---\n{frontmatter_yaml}---\n{body}"
+
     def deploy_commands(self, force: bool = False) -> Dict[str, Any]:
         """Deploy MPM slash commands to user's Claude configuration.
 
@@ -185,8 +221,12 @@ class CommandDeploymentService(BaseService):
                         )
                         continue
 
-                    # Copy the file
-                    shutil.copy2(source_file, target_file)
+                    # Strip deprecated_aliases from content before deployment
+                    # This prevents them from appearing in Claude Code's command list UI
+                    cleaned_content = self._strip_deprecated_aliases(content)
+
+                    # Write the cleaned content to target
+                    target_file.write_text(cleaned_content)
                     self.logger.info(f"Deployed command: {source_file.name}")
                     result["deployed"].append(source_file.name)
 
@@ -252,21 +292,84 @@ class CommandDeploymentService(BaseService):
 
         return removed
 
+    def remove_deprecated_commands(self) -> int:
+        """Remove deprecated MPM commands that have been replaced.
+
+        This method cleans up old command files that have been superseded by
+        new hierarchical command names. It's called automatically on startup
+        to ensure users don't have both old and new versions.
+
+        Returns:
+            Number of deprecated files removed
+        """
+        if not self.target_dir.exists():
+            self.logger.debug(
+                f"Target directory does not exist: {self.target_dir}, skipping deprecated command cleanup"
+            )
+            return 0
+
+        removed = 0
+        self.logger.info("Cleaning up deprecated commands...")
+
+        # Mapping of deprecated commands to their replacements for informative logging
+        replacement_map = {
+            "mpm-agents.md": "mpm-agents-list.md",
+            "mpm-auto-configure.md": "mpm-agents-auto-configure.md",
+            "mpm-config.md": "mpm-config-view.md",
+            "mpm-organize.md": "mpm-ticket-organize.md",
+            "mpm-resume.md": "mpm-session-resume.md",
+            "mpm-ticket.md": "mpm-ticket-view.md",
+        }
+
+        for deprecated_cmd in self.DEPRECATED_COMMANDS:
+            deprecated_file = self.target_dir / deprecated_cmd
+            replacement = replacement_map.get(deprecated_cmd, "a newer command")
+
+            if deprecated_file.exists():
+                try:
+                    deprecated_file.unlink()
+                    self.logger.debug(
+                        f"Removed deprecated command: {deprecated_cmd} (replaced by {replacement})"
+                    )
+                    removed += 1
+                except Exception as e:
+                    # Log error but don't fail startup - this is non-critical
+                    self.logger.warning(
+                        f"Failed to remove deprecated command {deprecated_cmd}: {e}"
+                    )
+
+        if removed > 0:
+            self.logger.info(f"Removed {removed} deprecated command(s)")
+        else:
+            self.logger.debug("No deprecated commands found to remove")
+
+        return removed
+
 
 def deploy_commands_on_startup(force: bool = False) -> None:
     """Convenience function to deploy commands during startup.
 
+    This function:
+    1. Removes deprecated commands that have been replaced
+    2. Deploys current command files
+
     Args:
         force: Force deployment even if files exist
     """
     service = CommandDeploymentService()
+    logger = get_logger("startup")
+
+    # Clean up deprecated commands BEFORE deploying new ones
+    removed_count = service.remove_deprecated_commands()
+    if removed_count > 0:
+        logger.info(f"Cleaned up {removed_count} deprecated command(s)")
+
+    # Deploy current commands
     result = service.deploy_commands(force=force)
 
     if result["deployed"]:
-        logger = get_logger("startup")
         logger.info(f"MPM commands deployed: {', '.join(result['deployed'])}")
 
     if result["errors"]:
-        logger = get_logger("startup")
         for error in result["errors"]:
             logger.warning(f"Command deployment issue: {error}")

claude_mpm/services/core/base.py

@@ -224,10 +224,11 @@ class SingletonService(SyncBaseService):
 
     Ensures only one instance of the service exists with thread-safe initialization.
     Uses double-checked locking pattern to prevent race conditions.
+    Uses RLock (reentrant lock) to support recursive instantiation patterns.
     """
 
     _instances: Dict[type, "SingletonService"] = {}
-    _lock = threading.Lock()
+    _lock = threading.RLock()
 
     def __new__(cls, *args, **kwargs):
         """Ensure only one instance exists with thread-safe initialization."""
@@ -247,7 +248,11 @@ class SingletonService(SyncBaseService):
             # Slow path - acquire lock and double-check
             with cls._lock:
                 if cls not in cls._instances:
-                    cls._instances[cls] = cls()
+                    # Use object.__new__ to bypass __new__ recursion
+                    instance = object.__new__(cls)
+                    cls._instances[cls] = instance
+                    # Call __init__ explicitly after storing instance
+                    instance.__init__()
         return cls._instances[cls]
 
     @classmethod

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -126,22 +126,14 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                 )
                 sub_results.append(fix_result)
 
-            # Also ensure configurations are updated for all projects
-            config_success, config_message = (
-                mcp_manager.ensure_mcp_services_configured()
-            )
-            if (
-                config_message
-                and config_message != "All MCP services already configured correctly"
-            ):
+            # Check if MCP services are available (read-only check)
+            available, availability_message = mcp_manager.check_mcp_services_available()
+            if not available:
+                # Services not configured - provide installation instructions
                 config_result = DiagnosticResult(
-                    category="MCP Configuration Update",
-                    status=(
-                        OperationResult.SUCCESS
-                        if config_success
-                        else ValidationSeverity.WARNING
-                    ),
-                    message=config_message,
+                    category="MCP Service Availability",
+                    status=ValidationSeverity.WARNING,
+                    message=availability_message,
                     details={"auto_config_applied": True},
                 )
                 sub_results.append(config_result)

claude_mpm/services/git/git_operations_service.py

@@ -12,10 +12,10 @@ Design Decisions:
 
 Example:
     >>> service = GitOperationsService()
-    >>> success = service.create_branch(Path("~/.claude-mpm/cache/agents"), "improve/research-memory")
+    >>> success = service.create_branch(Path("~/.claude-mpm/cache/remote-agents"), "improve/research-memory")
     >>> if success:
-    ...     service.stage_files(Path("~/.claude-mpm/cache/agents"), ["agents/research.md"])
-    ...     service.commit(Path("~/.claude-mpm/cache/agents"), "feat: improve research agent memory handling")
+    ...     service.stage_files(Path("~/.claude-mpm/cache/remote-agents"), ["agents/research.md"])
+    ...     service.commit(Path("~/.claude-mpm/cache/remote-agents"), "feat: improve research agent memory handling")
 """
 
 import subprocess
@@ -65,7 +65,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> service.is_git_repo(Path("~/.claude-mpm/cache/agents"))
+            >>> service.is_git_repo(Path("~/.claude-mpm/cache/remote-agents"))
             True
         """
         try:
@@ -147,7 +147,7 @@ class GitOperationsService:
         Example:
             >>> service = GitOperationsService()
             >>> service.create_and_checkout_branch(
-            ...     Path("~/.claude-mpm/cache/agents"),
+            ...     Path("~/.claude-mpm/cache/remote-agents"),
             ...     "improve/research-memory",
             ...     "main"
             ... )
@@ -242,7 +242,7 @@ class GitOperationsService:
         Example:
             >>> service = GitOperationsService()
             >>> service.commit(
-            ...     Path("~/.claude-mpm/cache/agents"),
+            ...     Path("~/.claude-mpm/cache/remote-agents"),
             ...     "feat(agent): improve research agent memory handling\\n\\n- Add hard limit of 5 files"
             ... )
             True
@@ -286,7 +286,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> service.push(Path("~/.claude-mpm/cache/agents"), "improve/research-memory")
+            >>> service.push(Path("~/.claude-mpm/cache/remote-agents"), "improve/research-memory")
             True
         """
         self._validate_repo(repo_path)
@@ -404,7 +404,7 @@ class GitOperationsService:
 
         Example:
             >>> service = GitOperationsService()
-            >>> valid, msg = service.validate_repo(Path("~/.claude-mpm/cache/agents"))
+            >>> valid, msg = service.validate_repo(Path("~/.claude-mpm/cache/remote-agents"))
             >>> if not valid:
             ...     print(f"Repository invalid: {msg}")
         """

claude_mpm/services/mcp_config_manager.py

@@ -12,7 +12,6 @@ MCP service installations.
 import json
 import subprocess
 import sys
-from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import Dict, Optional, Tuple
@@ -698,175 +697,106 @@ class MCPConfigManager:
 
         return config
 
-    def ensure_mcp_services_configured(self) -> Tuple[bool, str]:
+    def check_mcp_services_available(self) -> Tuple[bool, str]:
         """
-        Ensure MCP services are configured correctly in ~/.claude.json on startup.
+        Check if required MCP services are available in ~/.claude.json (READ-ONLY).
 
-        This method checks ALL projects in ~/.claude.json and ensures each has
-        the correct, static MCP service configurations. It will:
-        1. Add missing services
-        2. Fix incorrect configurations
-        3. Update all projects, not just the current one
+        This method performs a READ-ONLY check of MCP service availability.
+        It does NOT modify ~/.claude.json. Users should install and configure
+        MCP services themselves via pip, npx, or Claude Desktop.
 
         Returns:
-            Tuple of (success, message)
+            Tuple of (all_available: bool, message: str)
         """
-        updated = False
-        fixed_services = []
-        added_services = []
-
-        # Load existing Claude config or create minimal structure
-        claude_config = {}
-        if self.claude_config_path.exists():
-            try:
-                with self.claude_config_path.open() as f:
-                    claude_config = json.load(f)
-            except Exception as e:
-                self.logger.error(f"Error reading {self.claude_config_path}: {e}")
-                return False, f"Failed to read Claude config: {e}"
+        # Get services Claude MPM expects to use (from ~/.claude-mpm/config/)
+        expected_services = self.get_filtered_services()
 
-        # Ensure projects structure exists
-        if "projects" not in claude_config:
-            claude_config["projects"] = {}
-            updated = True
+        if not expected_services:
+            return True, "No MCP services configured in Claude MPM"
 
-        # Note: fix_mcp_service_issues() is already called during CLI initialization
-        # Calling it here would duplicate the service health checks
+        # Load Claude config (read-only)
+        if not self.claude_config_path.exists():
+            return False, f"Claude config not found at {self.claude_config_path}"
 
-        # Process ALL projects in the config, not just current one
-        projects_to_update = list(claude_config.get("projects", {}).keys())
+        try:
+            with self.claude_config_path.open() as f:
+                claude_config = json.load(f)
+        except Exception as e:
+            return False, f"Failed to read Claude config: {e}"
 
-        # Also add the current project if not in list
+        # Check current project
         current_project_key = str(self.project_root)
-        if current_project_key not in projects_to_update:
-            projects_to_update.append(current_project_key)
-            # Initialize new project structure
-            claude_config["projects"][current_project_key] = {
-                "allowedTools": [],
-                "history": [],
-                "mcpContextUris": [],
-                "mcpServers": {},
-                "enabledMcpjsonServers": [],
-                "disabledMcpjsonServers": [],
-                "hasTrustDialogAccepted": False,
-                "projectOnboardingSeenCount": 0,
-                "hasClaudeMdExternalIncludesApproved": False,
-                "hasClaudeMdExternalIncludesWarningShown": False,
-            }
-            updated = True
-
-        # Update each project's MCP configurations
-        for project_key in projects_to_update:
-            project_config = claude_config["projects"][project_key]
-
-            # Ensure mcpServers section exists
-            if "mcpServers" not in project_config:
-                project_config["mcpServers"] = {}
-                updated = True
-
-            # Check and fix each service configuration - now filtered by startup config
-            services_to_configure = self.get_filtered_services()
-
-            for service_name, correct_config in services_to_configure.items():
-                # Check if service exists and has correct configuration
-                existing_config = project_config["mcpServers"].get(service_name)
-
-                # Determine if we need to update
-                needs_update = False
-                if not existing_config:
-                    # Service is missing
-                    needs_update = True
-                    added_services.append(f"{service_name} in {Path(project_key).name}")
-                # Service exists, check if configuration is correct
-                # Compare command and args (the most critical parts)
-                elif existing_config.get("command") != correct_config.get(
-                    "command"
-                ) or existing_config.get("args") != correct_config.get("args"):
-                    needs_update = True
-                    fixed_services.append(f"{service_name} in {Path(project_key).name}")
-
-                # Update configuration if needed
-                if needs_update:
-                    project_config["mcpServers"][service_name] = correct_config
-                    updated = True
-                    self.logger.debug(
-                        f"Updated MCP service config for {service_name} in project {Path(project_key).name}"
-                    )
+        project_config = claude_config.get("projects", {}).get(current_project_key)
 
-            # Remove disabled services from configuration
-            if self.config is not None:
-                # Import Config here to avoid circular import
-                from ..core.config import Config
+        if not project_config:
+            missing = list(expected_services.keys())
+            return (
+                False,
+                f"Current project not configured in Claude. Missing services: {', '.join(missing)}",
+            )
 
-                if isinstance(self.config, Config):
-                    enabled_services = self.config.get(
-                        "startup.enabled_mcp_services", None
-                    )
-                    if enabled_services is not None:
-                        # Remove services that are not in the enabled list
-                        services_to_remove = []
-                        for service_name in project_config["mcpServers"]:
-                            if service_name not in enabled_services:
-                                services_to_remove.append(service_name)
-
-                        for service_name in services_to_remove:
-                            del project_config["mcpServers"][service_name]
-                            updated = True
-                            self.logger.debug(
-                                f"Removed disabled service {service_name} from project {Path(project_key).name}"
-                            )
-
-        # Write updated config if changes were made
-        if updated:
-            try:
-                # Create backup if file exists and is large (> 100KB)
-                if self.claude_config_path.exists():
-                    file_size = self.claude_config_path.stat().st_size
-                    if file_size > 100000:  # 100KB
-                        backup_path = self.claude_config_path.with_suffix(
-                            f".backup.{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}.json"
-                        )
-                        import shutil
+        # Check which services are missing
+        mcp_servers = project_config.get("mcpServers", {})
+        missing_services = [
+            name for name in expected_services if name not in mcp_servers
+        ]
 
-                        shutil.copy2(self.claude_config_path, backup_path)
-                        self.logger.debug(f"Created backup: {backup_path}")
+        if missing_services:
+            msg = (
+                f"Missing MCP services: {', '.join(missing_services)}. "
+                f"Install via: pip install {' '.join(missing_services)} "
+                f"or configure in Claude Desktop"
+            )
+            return False, msg
 
-                # Write updated config
-                with self.claude_config_path.open("w") as f:
-                    json.dump(claude_config, f, indent=2)
+        return (
+            True,
+            f"All required MCP services available ({len(expected_services)} services)",
+        )
 
-                messages = []
-                if added_services:
-                    messages.append(
-                        f"Added MCP services: {', '.join(added_services[:3])}"
-                    )
-                if fixed_services:
-                    messages.append(
-                        f"Fixed MCP services: {', '.join(fixed_services[:3])}"
-                    )
+    def ensure_mcp_services_configured(self) -> Tuple[bool, str]:
+        """
+        DEPRECATED: Auto-configuring ~/.claude.json is no longer supported.
 
-                if messages:
-                    return True, "; ".join(messages)
-                return True, "All MCP services already configured correctly"
-            except Exception as e:
-                self.logger.error(f"Failed to write Claude config: {e}")
-                return False, f"Failed to write configuration: {e}"
+        As of v4.15.0+, MCP services are user-controlled. Users should install
+        and configure MCP services themselves via:
+        - pip install <service-name>
+        - npx @modelcontextprotocol/...
+        - Claude Desktop UI
 
-        return True, "All MCP services already configured correctly"
+        This method now only performs a read-only check and logs a deprecation warning.
+        Use check_mcp_services_available() for read-only checks.
+
+        Returns:
+            Tuple of (success, message)
+        """
+        import warnings
+
+        warnings.warn(
+            "ensure_mcp_services_configured() is deprecated and will be removed in v6.0.0. "
+            "MCP services are now user-controlled. Use check_mcp_services_available() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        # Delegate to read-only check
+        return self.check_mcp_services_available()
 
     def update_mcp_config(self, force_pipx: bool = True) -> Tuple[bool, str]:
         """
-        Update the MCP configuration in ~/.claude.json.
+        DEPRECATED: Check MCP configuration in ~/.claude.json (READ-ONLY).
+
+        This method no longer modifies ~/.claude.json. Users should install
+        and configure MCP services themselves.
 
         Args:
-            force_pipx: If True, only use pipx installations
+            force_pipx: Ignored (kept for backward compatibility)
 
         Returns:
-            Tuple of (success, message)
+            Tuple of (success, message) from read-only check
         """
-        # This method now delegates to ensure_mcp_services_configured
-        # since we're updating the Claude config directly
-        return self.ensure_mcp_services_configured()
+        # Delegate to read-only check
+        return self.check_mcp_services_available()
 
     def update_project_mcp_config(self, force_pipx: bool = True) -> Tuple[bool, str]:
         """

claude_mpm/services/mcp_gateway/core/process_pool.py

@@ -440,15 +440,18 @@ async def auto_initialize_vector_search():
                         )
                         return
 
-                    # Update the Claude configuration to include the newly installed service
-                    logger.info("📝 Updating Claude configuration...")
-                    config_success, config_msg = (
-                        config_manager.ensure_mcp_services_configured()
-                    )
-                    if config_success:
-                        logger.info(f"✅ {config_msg}")
+                    # Verify the newly installed service is available
+                    logger.info("📝 Verifying installation...")
+                    available, msg = config_manager.check_mcp_services_available()
+                    if available:
+                        logger.info(f"✅ {msg}")
                     else:
-                        logger.warning(f"⚠️ Configuration update issue: {config_msg}")
+                        logger.warning(
+                            f"⚠️ Service installed but not configured in Claude: {msg}"
+                        )
+                        logger.info(
+                            "💡 Configure via: Claude Desktop > Settings > Developer > Model Context Protocol"
+                        )
                 else:
                     logger.warning(
                         f"Failed to install mcp-vector-search: {result.stderr}"
@@ -658,15 +661,18 @@ async def auto_initialize_kuzu_memory():
                         )
                         return
 
-                    # Update the Claude configuration to include the newly installed service
-                    logger.info("📝 Updating Claude configuration...")
-                    config_success, config_msg = (
-                        config_manager.ensure_mcp_services_configured()
-                    )
-                    if config_success:
-                        logger.info(f"✅ {config_msg}")
+                    # Verify the newly installed service is available
+                    logger.info("📝 Verifying installation...")
+                    available, msg = config_manager.check_mcp_services_available()
+                    if available:
+                        logger.info(f"✅ {msg}")
                     else:
-                        logger.warning(f"⚠️ Configuration update issue: {config_msg}")
+                        logger.warning(
+                            f"⚠️ Service installed but not configured in Claude: {msg}"
+                        )
+                        logger.info(
+                            "💡 Configure via: Claude Desktop > Settings > Developer > Model Context Protocol"
+                        )
                 else:
                     logger.warning(f"Failed to install kuzu-memory: {result.stderr}")
                     return

claude_mpm/services/mcp_service_verifier.py

@@ -620,12 +620,15 @@ class MCPServiceVerifier:
                 return True
 
             if "claude-mpm configure" in diagnostic.fix_command:
-                # Trigger configuration update
+                # Check if services are available (read-only)
                 from .mcp_config_manager import MCPConfigManager
 
                 manager = MCPConfigManager()
-                success, _ = manager.ensure_mcp_services_configured()
-                return success
+                available, message = manager.check_mcp_services_available()
+                if not available:
+                    # Cannot auto-fix - user must install services manually
+                    self.logger.warning(f"Cannot auto-fix: {message}")
+                return available
 
         except Exception as e:
             self.logger.error(f"Auto-fix failed for {service_name}: {e}")