claude-mpm 4.4.6__py3-none-any.whl → 4.4.8__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.4.6
+4.4.8

claude_mpm/agents/templates/local_ops_agent.json

@@ -0,0 +1,273 @@
+{
+  "name": "local-ops",
+  "display_name": "Local Operations Agent",
+  "description": "Specialized agent for managing local development deployments with authority over PM2, Docker, and native processes",
+  "version": "1.0.0",
+  "author": "Claude MPM",
+  "authority": {
+    "level": "deployment_manager",
+    "domains": [
+      "local_deployments",
+      "process_management",
+      "port_allocation",
+      "resource_monitoring",
+      "log_management"
+    ]
+  },
+  "capabilities": {
+    "frameworks": {
+      "javascript": ["next.js", "react", "vue", "angular", "svelte", "nuxt", "gatsby", "vite"],
+      "python": ["django", "flask", "fastapi", "streamlit", "gradio"],
+      "ruby": ["rails", "sinatra"],
+      "php": ["laravel", "symfony"],
+      "static": ["hugo", "jekyll", "eleventy"]
+    },
+    "deployment_methods": {
+      "pm2": {
+        "description": "Node.js process manager for production deployments",
+        "commands": ["start", "stop", "restart", "status", "logs", "monit"],
+        "features": ["auto-restart", "clustering", "log-rotation", "monitoring"]
+      },
+      "docker": {
+        "description": "Container-based deployment for isolation",
+        "commands": ["build", "run", "stop", "logs", "exec"],
+        "features": ["isolation", "reproducibility", "multi-service"]
+      },
+      "native": {
+        "description": "Direct process management for simple cases",
+        "commands": ["start", "stop", "status"],
+        "features": ["lightweight", "direct-control"]
+      },
+      "systemd": {
+        "description": "Linux system service management",
+        "commands": ["start", "stop", "enable", "status"],
+        "features": ["boot-persistence", "system-integration"]
+      }
+    },
+    "monitoring": {
+      "health_checks": ["http", "tcp", "process"],
+      "metrics": ["cpu", "memory", "response_time", "error_rate"],
+      "alerts": ["crash", "high_memory", "port_conflict", "unhealthy"]
+    }
+  },
+  "metadata": {
+    "category": "operations",
+    "tags": ["deployment", "devops", "local", "process-management", "monitoring"],
+    "requirements": {
+      "optional": ["pm2", "docker", "nginx"],
+      "auto_install": ["pm2"]
+    }
+  },
+  "configuration": {
+    "default_port_range": [3000, 9999],
+    "deployment_directory": ".claude-mpm/deployments",
+    "log_directory": ".claude-mpm/logs",
+    "state_file": ".claude-mpm/deployment-state.json",
+    "health_check_interval": 30,
+    "auto_restart_attempts": 3,
+    "cleanup_on_exit": false
+  },
+  "commands": {
+    "deploy": {
+      "description": "Deploy application with optimal method",
+      "examples": [
+        "Deploy this Next.js app in production mode",
+        "Start the development server with hot reload",
+        "Deploy with PM2 for stability"
+      ],
+      "workflow": [
+        "detect_framework",
+        "check_existing_deployments",
+        "allocate_port",
+        "build_if_needed",
+        "start_process",
+        "monitor_health",
+        "report_status"
+      ]
+    },
+    "status": {
+      "description": "Check deployment status",
+      "provides": ["process_info", "port_mapping", "health_status", "resource_usage"]
+    },
+    "logs": {
+      "description": "Stream or fetch deployment logs",
+      "options": ["tail", "follow", "filter", "since"]
+    },
+    "stop": {
+      "description": "Gracefully stop deployments",
+      "options": ["force", "timeout", "cleanup"]
+    },
+    "scale": {
+      "description": "Scale deployments (PM2 cluster mode)",
+      "options": ["instances", "auto"]
+    }
+  },
+  "detection_patterns": {
+    "nextjs": {
+      "files": ["next.config.js", "next.config.mjs", "next.config.ts"],
+      "package_json": ["next"],
+      "commands": {
+        "dev": "next dev",
+        "build": "next build",
+        "start": "next start",
+        "export": "next export"
+      }
+    },
+    "react": {
+      "files": ["react-scripts", "vite.config.js", "webpack.config.js"],
+      "package_json": ["react", "react-dom"],
+      "commands": {
+        "dev": "npm start",
+        "build": "npm run build",
+        "serve": "serve -s build"
+      }
+    },
+    "vue": {
+      "files": ["vue.config.js", "vite.config.js"],
+      "package_json": ["vue", "@vue/cli-service"],
+      "commands": {
+        "dev": "npm run serve",
+        "build": "npm run build",
+        "preview": "npm run preview"
+      }
+    },
+    "python_django": {
+      "files": ["manage.py", "wsgi.py"],
+      "requirements": ["django"],
+      "commands": {
+        "dev": "python manage.py runserver",
+        "prod": "gunicorn wsgi:application"
+      }
+    },
+    "python_flask": {
+      "files": ["app.py", "wsgi.py"],
+      "requirements": ["flask"],
+      "commands": {
+        "dev": "flask run",
+        "prod": "gunicorn app:app"
+      }
+    }
+  },
+  "deployment_strategies": {
+    "production": {
+      "nextjs": {
+        "method": "pm2",
+        "steps": [
+          "npm install --production",
+          "npm run build",
+          "pm2 start npm --name '{app_name}' -- start"
+        ],
+        "health_check": "http://localhost:{port}",
+        "environment": {
+          "NODE_ENV": "production"
+        }
+      },
+      "react": {
+        "method": "static",
+        "steps": [
+          "npm install",
+          "npm run build",
+          "pm2 serve build {port} --name '{app_name}'"
+        ],
+        "health_check": "http://localhost:{port}"
+      },
+      "python": {
+        "method": "pm2",
+        "steps": [
+          "pip install -r requirements.txt",
+          "pm2 start gunicorn --name '{app_name}' -- app:app --bind 0.0.0.0:{port}"
+        ],
+        "health_check": "http://localhost:{port}/health"
+      }
+    },
+    "development": {
+      "nextjs": {
+        "method": "pm2",
+        "steps": [
+          "npm install",
+          "pm2 start npm --name '{app_name}-dev' -- run dev"
+        ],
+        "environment": {
+          "NODE_ENV": "development"
+        }
+      },
+      "react": {
+        "method": "pm2",
+        "steps": [
+          "npm install",
+          "pm2 start npm --name '{app_name}-dev' -- start"
+        ]
+      }
+    },
+    "docker": {
+      "default": {
+        "method": "docker",
+        "steps": [
+          "docker build -t {app_name} .",
+          "docker run -d -p {port}:{container_port} --name {app_name} {app_name}"
+        ],
+        "health_check": "docker exec {app_name} echo 'OK'"
+      }
+    }
+  },
+  "error_recovery": {
+    "port_conflict": {
+      "detection": "EADDRINUSE",
+      "action": "allocate_next_available_port"
+    },
+    "build_failure": {
+      "detection": "npm ERR!|ERROR|Failed",
+      "action": "report_error_and_suggest_fixes"
+    },
+    "crash_loop": {
+      "detection": "restart_count > 5",
+      "action": "stop_and_investigate_logs"
+    },
+    "out_of_memory": {
+      "detection": "JavaScript heap out of memory",
+      "action": "increase_memory_limit"
+    }
+  },
+  "security": {
+    "port_exposure": "localhost_only",
+    "process_isolation": "user_level",
+    "log_sanitization": true,
+    "secrets_handling": "environment_variables"
+  },
+  "integration": {
+    "hooks": {
+      "pre_deploy": "validate_requirements",
+      "post_deploy": "notify_status",
+      "pre_stop": "graceful_shutdown",
+      "on_crash": "auto_restart_with_backoff"
+    },
+    "monitoring": {
+      "export_metrics": true,
+      "prometheus_endpoint": "/metrics",
+      "health_endpoint": "/health"
+    }
+  },
+  "tools": [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit"
+  ],
+  "examples": [
+    {
+      "user": "Deploy my Next.js app",
+      "response": "I'll deploy your Next.js application using PM2 for stability. Let me detect your configuration and set it up...",
+      "actions": ["detect_framework", "build_production", "deploy_with_pm2", "monitor_health"]
+    },
+    {
+      "user": "Show me the status of all deployments",
+      "response": "Here's the status of all active deployments...",
+      "actions": ["list_pm2_processes", "check_docker_containers", "aggregate_status"]
+    },
+    {
+      "user": "The app keeps crashing, help me debug",
+      "response": "Let me check the logs and identify the issue...",
+      "actions": ["fetch_error_logs", "analyze_crash_pattern", "suggest_fixes"]
+    }
+  ]
+}

claude_mpm/cli/__init__.py

@@ -234,6 +234,19 @@ def _verify_mcp_gateway_startup():
     DESIGN DECISION: This is non-blocking - failures are logged but don't prevent
     startup to ensure claude-mpm remains functional even if MCP gateway has issues.
     """
+    # Quick verification of MCP services installation
+    try:
+        from ..services.mcp_service_verifier import verify_mcp_services_on_startup
+        from ..core.logger import get_logger
+
+        logger = get_logger("mcp_verify")
+        all_ok, message = verify_mcp_services_on_startup()
+        if not all_ok:
+            logger.warning(message)
+    except Exception:
+        # Non-critical - continue with startup
+        pass
+
     try:
         import asyncio
         import time
@@ -449,6 +462,14 @@ def _execute_command(command: str, args) -> int:
         # Convert CommandResult to exit code
         return result.exit_code if result else 0
 
+    # Handle verify command with lazy import
+    if command == "verify":
+        # Lazy import to avoid loading unless needed
+        from .commands.verify import handle_verify
+
+        result = handle_verify(args)
+        return result if result is not None else 0
+
     # Map stable commands to their implementations
     command_map = {
         CLICommands.RUN.value: run_session,

claude_mpm/cli/commands/verify.py

@@ -0,0 +1,118 @@
+"""
+Verify command for MCP service health checks.
+"""
+
+import argparse
+import sys
+
+from ...core.logger import get_logger
+from ...services.mcp_service_verifier import MCPServiceVerifier, ServiceStatus
+
+
+def add_parser(subparsers) -> None:
+    """Add the verify command parser."""
+    parser = subparsers.add_parser(
+        "verify",
+        help="Verify MCP services installation and configuration",
+        description="Performs comprehensive health checks on MCP services",
+    )
+
+    parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Attempt to automatically fix detected issues",
+    )
+
+    parser.add_argument(
+        "--service",
+        type=str,
+        help="Verify a specific service only",
+        choices=["mcp-vector-search", "mcp-browser", "mcp-ticketer", "kuzu-memory"],
+    )
+
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results in JSON format",
+    )
+
+    parser.set_defaults(func=handle_verify)
+
+
+def handle_verify(args: argparse.Namespace) -> int:
+    """
+    Handle the verify command.
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        Exit code (0 for success, non-zero for issues found)
+    """
+    logger = get_logger(__name__)
+    verifier = MCPServiceVerifier()
+
+    try:
+        # Run verification
+        if args.service:
+            # Verify single service
+            logger.info(f"Verifying {args.service}...")
+            diagnostic = verifier._verify_service(args.service)
+            diagnostics = {args.service: diagnostic}
+
+            # Auto-fix if requested
+            if args.fix and diagnostic.fix_command and diagnostic.status != ServiceStatus.WORKING:
+                logger.info(f"Attempting to fix {args.service}...")
+                if verifier._attempt_auto_fix(args.service, diagnostic):
+                    # Re-verify after fix
+                    diagnostic = verifier._verify_service(args.service)
+                    diagnostics = {args.service: diagnostic}
+        else:
+            # Verify all services
+            logger.info("Verifying all MCP services...")
+            diagnostics = verifier.verify_all_services(auto_fix=args.fix)
+
+        # Output results
+        if args.json:
+            import json
+
+            # Convert to JSON-serializable format
+            json_output = {}
+            for name, diag in diagnostics.items():
+                json_output[name] = {
+                    "status": diag.status.value,
+                    "message": diag.message,
+                    "installed_path": diag.installed_path,
+                    "configured_command": diag.configured_command,
+                    "fix_command": diag.fix_command,
+                    "details": diag.details,
+                }
+            print(json.dumps(json_output, indent=2))
+        else:
+            verifier.print_diagnostics(diagnostics)
+
+        # Determine exit code
+        all_working = all(
+            d.status == ServiceStatus.WORKING
+            for d in diagnostics.values()
+        )
+
+        if all_working:
+            logger.info("✅ All verified services are fully operational")
+            return 0
+        else:
+            issues_count = sum(
+                1 for d in diagnostics.values()
+                if d.status != ServiceStatus.WORKING
+            )
+            logger.warning(f"⚠️ {issues_count} service(s) have issues")
+            return 1
+
+    except Exception as e:
+        logger.error(f"Verification failed: {e}")
+        if args.json:
+            import json
+            print(json.dumps({"error": str(e)}, indent=2))
+        else:
+            print(f"\n❌ Verification failed: {e}")
+        return 2

claude_mpm/cli/parsers/base_parser.py

@@ -422,6 +422,11 @@ def create_parser(
         from ..commands.doctor import add_doctor_parser
 
         add_doctor_parser(subparsers)
+
+        # Add verify command for MCP service verification
+        from ..commands.verify import add_parser as add_verify_parser
+
+        add_verify_parser(subparsers)
     except ImportError:
         # Commands module may not be available during testing or refactoring
         pass

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -369,12 +369,18 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                     else "single"
                 )
 
+                # When using multi-source deployment, we've already determined which
+                # agents need updates. Don't re-check versions in single_agent_deployer.
+                # This prevents the issue where multi-source says "deploying 9 agents"
+                # but then all get skipped due to redundant version checks.
+                skip_version_check = use_multi_source and not force_rebuild
+
                 self.single_agent_deployer.deploy_single_agent(
                     template_file=template_file_path,
                     agents_dir=agents_dir,
                     base_agent_data=base_agent_data,
                     base_agent_version=base_agent_version,
-                    force_rebuild=force_rebuild,
+                    force_rebuild=force_rebuild or skip_version_check,
                     deployment_mode=deployment_mode,
                     results=results,
                     source_info=source_info,
@@ -817,11 +823,9 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
 
                 agents_to_deploy = filtered_agents
 
-                if agents_to_deploy:
-                    self.logger.info(
-                        f"Deploying {len(agents_to_deploy)} agents that need updates"
-                    )
-                else:
+                # Don't log this redundant message - we already logged the upgrades above
+                # The "Deploying X agent upgrade(s)" message is sufficient
+                if not agents_to_deploy:
                     self.logger.debug(
                         f"All {len(comparison_results.get('up_to_date', []))} agents are up to date"
                     )

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -10,6 +10,7 @@ import subprocess
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
+from claude_mpm.core.logger import get_logger
 from ..models import DiagnosticResult, DiagnosticStatus
 from .base_check import BaseDiagnosticCheck
 
@@ -17,6 +18,11 @@ from .base_check import BaseDiagnosticCheck
 class MCPServicesCheck(BaseDiagnosticCheck):
     """Check MCP external services installation and health."""
 
+    def __init__(self, verbose: bool = False):
+        """Initialize the MCP services check."""
+        super().__init__(verbose)
+        self.logger = get_logger(self.__class__.__name__)
+
     # Define MCP services to check
     MCP_SERVICES = {
         "mcp-vector-search": {
@@ -71,6 +77,11 @@ class MCPServicesCheck(BaseDiagnosticCheck):
             sub_results = []
             services_status = {}
 
+            # Check for kuzu-memory configuration issues and offer auto-fix
+            kuzu_config_result = self._check_and_fix_kuzu_memory_config()
+            if kuzu_config_result:
+                sub_results.append(kuzu_config_result)
+
             # Check each MCP service
             for service_name, service_config in self.MCP_SERVICES.items():
                 service_result = self._check_service(service_name, service_config)
@@ -391,6 +402,117 @@ class MCPServicesCheck(BaseDiagnosticCheck):
 
         return None
 
+    def _check_and_fix_kuzu_memory_config(self) -> Optional[DiagnosticResult]:
+        """Check for incorrect kuzu-memory configuration in .claude.json and offer auto-fix."""
+        claude_config_path = Path.home() / ".claude.json"
+
+        if not claude_config_path.exists():
+            return None
+
+        try:
+            with open(claude_config_path) as f:
+                config = json.load(f)
+
+            mcp_servers = config.get("mcpServers", {})
+            kuzu_config = mcp_servers.get("kuzu-memory")
+
+            if not kuzu_config:
+                return None
+
+            # Check if kuzu-memory has incorrect args
+            args = kuzu_config.get("args", [])
+            needs_fix = False
+            fix_reason = ""
+            new_args = None
+
+            # Check for outdated configurations
+            if args == ["claude", "mcp-server"]:
+                needs_fix = True
+                fix_reason = "Outdated 'claude mcp-server' format"
+                new_args = ["mcp", "serve"]
+            elif args == ["serve"]:
+                needs_fix = True
+                fix_reason = "Legacy 'serve' format"
+                new_args = ["mcp", "serve"]
+            elif args == ["mcp-server"]:
+                needs_fix = True
+                fix_reason = "Incorrect 'mcp-server' format"
+                new_args = ["mcp", "serve"]
+
+            if needs_fix:
+                # Offer to auto-fix
+                self.logger.warning(
+                    f"Found incorrect kuzu-memory configuration: {fix_reason}. "
+                    f"Current args: {args}"
+                )
+
+                # Auto-fix the configuration
+                fixed = self._fix_kuzu_memory_args(claude_config_path, config, new_args)
+
+                if fixed:
+                    return DiagnosticResult(
+                        category="kuzu-memory Configuration Fix",
+                        status=DiagnosticStatus.OK,
+                        message="Fixed kuzu-memory configuration",
+                        details={
+                            "old_args": args,
+                            "new_args": new_args,
+                            "reason": fix_reason,
+                            "auto_fixed": True,
+                        },
+                    )
+                else:
+                    return DiagnosticResult(
+                        category="kuzu-memory Configuration",
+                        status=DiagnosticStatus.WARNING,
+                        message="kuzu-memory has incorrect configuration",
+                        details={
+                            "current_args": args,
+                            "correct_args": new_args,
+                            "reason": fix_reason,
+                            "auto_fix_failed": True,
+                        },
+                        fix_command="claude-mpm configure --mcp --fix-kuzu",
+                        fix_description="Fix kuzu-memory configuration manually",
+                    )
+
+            # Configuration is correct
+            return None
+
+        except (json.JSONDecodeError, Exception) as e:
+            self.logger.debug(f"Could not check kuzu-memory config: {e}")
+            return None
+
+    def _fix_kuzu_memory_args(self, config_path: Path, config: Dict, new_args: List[str]) -> bool:
+        """Fix kuzu-memory args in the configuration."""
+        try:
+            # Save old args before updating
+            old_args = config["mcpServers"]["kuzu-memory"].get("args", [])
+
+            # Create backup
+            backup_path = config_path.with_suffix(".json.backup")
+            with open(backup_path, "w") as f:
+                json.dump(config, f, indent=2)
+
+            # Update the configuration
+            config["mcpServers"]["kuzu-memory"]["args"] = new_args
+
+            # Write updated configuration
+            with open(config_path, "w") as f:
+                json.dump(config, f, indent=2)
+
+            self.logger.info(
+                f"✅ Fixed kuzu-memory configuration in {config_path}\n"
+                f"   Changed args from {old_args} to {new_args}\n"
+                f"   Backup saved to {backup_path}"
+            )
+
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Failed to fix kuzu-memory configuration: {e}")
+            return False
+
     def _check_gateway_configuration(self) -> DiagnosticResult:
         """Check if MCP services are configured in the gateway."""
         try:

claude_mpm/services/diagnostics/diagnostic_runner.py

@@ -214,6 +214,9 @@ class DiagnosticRunner:
             "agents": AgentCheck,
             "agent": AgentCheck,
             "mcp": MCPCheck,
+            "mcp_services": MCPServicesCheck,
+            "mcp-services": MCPServicesCheck,
+            "external": MCPServicesCheck,
             "monitor": MonitorCheck,
             "monitoring": MonitorCheck,
             "common": CommonIssuesCheck,