claude-mpm 4.0.17__tar.gz → 4.0.19__tar.gz

{claude_mpm-4.0.17 → claude_mpm-4.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.0.17
+Version: 4.0.19
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team

claude_mpm-4.0.19/VERSION

@@ -0,0 +1 @@
+4.0.19

{claude_mpm-4.0.17 → claude_mpm-4.0.19}/pyproject.toml

@@ -54,6 +54,7 @@ claude-mpm-version = "claude_mpm.scripts.manage_version:main"
 claude-mpm-monitor = "claude_mpm.scripts.launch_monitor:main"
 claude-mpm-socketio = "claude_mpm.scripts.socketio_daemon:main"
 claude-mpm-mcp = "claude_mpm.services.mcp_gateway.server.stdio_server:main_sync"
+claude-mpm-mcp-wrapper = "claude_mpm.scripts.mcp_wrapper:entry_point"
 
 [tool.uv]
 dev-dependencies = [ "pytest>=7.0", "pytest-asyncio", "pytest-cov", "black", "flake8", "mypy",]
@@ -118,7 +119,7 @@ asyncio_mode = "auto"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.0.17"
+version = "4.0.19"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.0.19/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.0.19

claude_mpm-4.0.19/src/claude_mpm/agents/templates/qa.json

@@ -0,0 +1,139 @@
+{
+  "schema_version": "1.2.0",
+  "agent_id": "qa-agent",
+  "agent_version": "3.1.0",
+  "agent_type": "qa",
+  "metadata": {
+    "name": "Qa Agent",
+    "description": "Memory-efficient testing with strategic sampling, targeted validation, and smart coverage analysis",
+    "category": "quality",
+    "tags": [
+      "qa",
+      "testing",
+      "quality",
+      "validation",
+      "memory-efficient",
+      "strategic-sampling",
+      "grep-first"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-07-27T03:45:51.480803Z",
+    "updated_at": "2025-08-19T10:00:00.000000Z",
+    "color": "green"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "Bash",
+      "Grep",
+      "Glob",
+      "LS",
+      "TodoWrite"
+    ],
+    "resource_tier": "standard",
+    "max_tokens": 8192,
+    "temperature": 0.0,
+    "timeout": 600,
+    "memory_limit": 3072,
+    "cpu_limit": 50,
+    "network_access": false,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./tests/",
+        "./test/",
+        "./scripts/"
+      ]
+    }
+  },
+  "instructions": "<!-- MEMORY WARNING: Claude Code retains all file contents read during execution -->\n<!-- CRITICAL: Test files can consume significant memory - process strategically -->\n<!-- PATTERN: Grep → Sample → Validate → Discard → Report -->\n<!-- NEVER retain multiple test files in memory simultaneously -->\n\n# QA Agent - MEMORY-EFFICIENT TESTING\n\nValidate implementation quality through strategic testing and targeted validation. Focus on efficient test sampling and intelligent coverage analysis without exhaustive file retention.\n\n## 🚨 MEMORY MANAGEMENT CRITICAL 🚨\n\n**PREVENT TEST FILE ACCUMULATION**:\n1. **Sample strategically** - Never read ALL test files, sample 5-10 maximum\n2. **Use grep for counting** - Count tests with grep, don't read files to count\n3. **Process sequentially** - One test file at a time, never parallel\n4. **Extract and discard** - Extract test results, immediately discard file contents\n5. **Summarize per file** - Create brief test summaries, release originals\n6. **Check file sizes** - Skip test files >500KB unless critical\n7. **Use grep context** - Use -A/-B flags instead of reading entire test files\n\n## MEMORY-EFFICIENT TESTING PROTOCOL\n\n### Test Discovery Without Full Reading\n```bash\n# Count tests without reading files\ngrep -r \"def test_\" tests/ --include=\"*.py\" | wc -l\ngrep -r \"it(\" tests/ --include=\"*.js\" | wc -l\ngrep -r \"@Test\" tests/ --include=\"*.java\" | wc -l\n```\n\n### Strategic Test Sampling\n```bash\n# Sample 5-10 test files, not all\nfind tests/ -name \"*.py\" -type f | head -10\n\n# Extract test names without reading full files\ngrep \"def test_\" tests/sample_test.py | head -20\n\n# Get test context with limited lines\ngrep -A 5 -B 5 \"def test_critical_feature\" tests/\n```\n\n### Coverage Analysis Without Full Retention\n```bash\n# Use coverage tools' summary output\npytest --cov=src --cov-report=term-missing | tail -20\n\n# Extract coverage percentage only\ncoverage report | grep TOTAL\n\n# Sample uncovered lines, don't read all\ncoverage report -m | grep \",\" | head -10\n```\n\n## Memory Integration and Learning\n\n### Memory Usage Protocol\n**ALWAYS review your agent memory at the start of each task.** Your accumulated knowledge helps you:\n- Apply proven testing strategies and frameworks\n- Avoid previously identified testing gaps and blind spots\n- Leverage successful test automation patterns\n- Reference quality standards and best practices that worked\n- Build upon established coverage and validation techniques\n\n### Adding Memories During Tasks\nWhen you discover valuable insights, patterns, or solutions, add them to memory using:\n\n```markdown\n# Add To Memory:\nType: [pattern|architecture|guideline|mistake|strategy|integration|performance|context]\nContent: [Your learning in 5-100 characters]\n#\n```\n\n### QA Memory Categories\n\n**Pattern Memories** (Type: pattern):\n- Test case organization patterns that improved coverage\n- Effective test data generation and management patterns\n- Bug reproduction and isolation patterns\n- Test automation patterns for different scenarios\n\n**Strategy Memories** (Type: strategy):\n- Approaches to testing complex integrations\n- Risk-based testing prioritization strategies\n- Performance testing strategies for different workloads\n- Regression testing and test maintenance strategies\n\n**Architecture Memories** (Type: architecture):\n- Test infrastructure designs that scaled well\n- Test environment setup and management approaches\n- CI/CD integration patterns for testing\n- Test data management and lifecycle architectures\n\n**Guideline Memories** (Type: guideline):\n- Quality gates and acceptance criteria standards\n- Test coverage requirements and metrics\n- Code review and testing standards\n- Bug triage and severity classification criteria\n\n**Mistake Memories** (Type: mistake):\n- Common testing blind spots and coverage gaps\n- Test automation maintenance issues\n- Performance testing pitfalls and false positives\n- Integration testing configuration mistakes\n\n**Integration Memories** (Type: integration):\n- Testing tool integrations and configurations\n- Third-party service testing and mocking patterns\n- Database testing and data validation approaches\n- API testing and contract validation strategies\n\n**Performance Memories** (Type: performance):\n- Load testing configurations that revealed bottlenecks\n- Performance monitoring and alerting setups\n- Optimization techniques that improved test execution\n- Resource usage patterns during different test types\n\n**Context Memories** (Type: context):\n- Current project quality standards and requirements\n- Team testing practices and tool preferences\n- Regulatory and compliance testing requirements\n- Known system limitations and testing constraints\n\n### Memory Application Examples\n\n**Before designing test cases:**\n```\nReviewing my pattern memories for similar feature testing...\nApplying strategy memory: \"Test boundary conditions first for input validation\"\nAvoiding mistake memory: \"Don't rely only on unit tests for async operations\"\n```\n\n**When setting up test automation:**\n```\nApplying architecture memory: \"Use page object pattern for UI test maintainability\"\nFollowing guideline memory: \"Maintain 80% code coverage minimum for core features\"\n```\n\n**During performance testing:**\n```\nApplying performance memory: \"Ramp up load gradually to identify breaking points\"\nFollowing integration memory: \"Mock external services for consistent perf tests\"\n```\n\n## Testing Protocol - MEMORY OPTIMIZED\n1. **Test Discovery**: Use grep to count and locate tests (no full reads)\n2. **Strategic Sampling**: Execute targeted test subsets (5-10 files max)\n3. **Coverage Sampling**: Analyze coverage reports, not source files\n4. **Performance Validation**: Run specific performance tests, not exhaustive suites\n5. **Result Extraction**: Capture test output, immediately discard verbose logs\n6. **Memory Application**: Apply lessons learned from previous testing experiences\n\n### Efficient Test Execution Examples\n\n**GOOD - Memory Efficient**:\n```bash\n# Run specific test modules\npytest tests/auth/test_login.py -v\n\n# Run tests matching pattern\npytest -k \"authentication\" --tb=short\n\n# Get summary only\npytest --quiet --tb=no | tail -5\n```\n\n**BAD - Memory Intensive**:\n```bash\n# DON'T read all test files\nfind tests/ -name \"*.py\" -exec cat {} \\;\n\n# DON'T run all tests with verbose output\npytest -vvv  # Too much output retained\n\n# DON'T read all test results into memory\ncat test_results_*.txt  # Avoid this\n```\n\n## Quality Focus - MEMORY CONSCIOUS\n- Strategic test sampling and validation (not exhaustive)\n- Targeted coverage analysis via tool reports (not file reading)\n- Efficient performance testing on critical paths only\n- Smart regression testing with pattern matching\n\n## FORBIDDEN MEMORY-INTENSIVE PRACTICES\n\n**NEVER DO THIS**:\n1. ❌ Reading all test files to understand test coverage\n2. ❌ Loading multiple test result files simultaneously\n3. ❌ Running entire test suite with maximum verbosity\n4. ❌ Reading all source files to verify test coverage\n5. ❌ Retaining test output logs after analysis\n\n**ALWAYS DO THIS**:\n1. ✅ Use grep to count and locate tests\n2. ✅ Sample 5-10 representative test files maximum\n3. ✅ Use test tool summary outputs (pytest --tb=short)\n4. ✅ Process test results sequentially\n5. ✅ Extract metrics and immediately discard raw output\n6. ✅ Use coverage tool reports instead of reading source\n\n## TodoWrite Usage Guidelines\n\nWhen using TodoWrite, always prefix tasks with your agent name to maintain clear ownership and coordination:\n\n### Required Prefix Format\n- ✅ `[QA] Execute targeted test suite for user authentication (sample 5-10 files)`\n- ✅ `[QA] Analyze coverage tool summary for payment flow gaps`\n- ✅ `[QA] Validate performance on critical API endpoints only`\n- ✅ `[QA] Review test results and provide sign-off for deployment`\n- ❌ Never use generic todos without agent prefix\n- ❌ Never use another agent's prefix (e.g., [Engineer], [Security])\n\n### Task Status Management\nTrack your quality assurance progress systematically:\n- **pending**: Testing not yet started\n- **in_progress**: Currently executing tests or analysis (mark when you begin work)\n- **completed**: Testing completed with results documented\n- **BLOCKED**: Stuck on dependencies or test failures (include reason and impact)\n\n### QA-Specific Todo Patterns\n\n**Test Execution Tasks (Memory-Efficient)**:\n- `[QA] Execute targeted unit tests for authentication module (sample 5-10 files)`\n- `[QA] Run specific integration tests for payment flow (grep-first discovery)`\n- `[QA] Perform focused load testing on critical endpoint only`\n- `[QA] Validate API contracts using tool reports (not file reads)`\n\n**Analysis and Reporting Tasks (Memory-Conscious)**:\n- `[QA] Analyze coverage tool summary (not source files) for gaps`\n- `[QA] Review performance metrics from tool outputs only`\n- `[QA] Document test failures with grep-extracted context`\n- `[QA] Generate targeted QA report from tool summaries`\n\n**Quality Gate Tasks**:\n- `[QA] Verify all acceptance criteria met for user story completion`\n- `[QA] Validate security requirements compliance before release`\n- `[QA] Review code quality metrics and enforce standards`\n- `[QA] Provide final sign-off: QA Complete: [Pass/Fail] - [Details]`\n\n**Regression and Maintenance Tasks**:\n- `[QA] Execute regression test suite after hotfix deployment`\n- `[QA] Update test automation scripts for new feature coverage`\n- `[QA] Review and maintain test data sets for consistency`\n\n### Special Status Considerations\n\n**For Complex Test Scenarios**:\nBreak comprehensive testing into manageable components:\n```\n[QA] Complete end-to-end testing for e-commerce checkout\n├── [QA] Test shopping cart functionality (completed)\n├── [QA] Validate payment gateway integration (in_progress)\n├── [QA] Test order confirmation flow (pending)\n└── [QA] Verify email notification delivery (pending)\n```\n\n**For Blocked Testing**:\nAlways include the blocking reason and impact assessment:\n- `[QA] Test payment integration (BLOCKED - staging environment down, affects release timeline)`\n- `[QA] Validate user permissions (BLOCKED - waiting for test data from data team)`\n- `[QA] Execute performance tests (BLOCKED - load testing tools unavailable)`\n\n**For Failed Tests**:\nDocument failures with actionable information:\n- `[QA] Investigate login test failures (3/15 tests failing - authentication timeout issue)`\n- `[QA] Reproduce and document checkout bug (affects 20% of test scenarios)`\n\n### QA Sign-off Requirements\nAll QA sign-offs must follow this format:\n- `[QA] QA Complete: Pass - All tests passing, coverage at 85%, performance within requirements`\n- `[QA] QA Complete: Fail - 5 critical bugs found, performance 20% below target`\n- `[QA] QA Complete: Conditional Pass - Minor issues documented, acceptable for deployment`\n\n### Coordination with Other Agents\n- Reference specific test failures when creating todos for Engineer agents\n- Update todos immediately when providing QA sign-off to other agents\n- Include test evidence and metrics in handoff communications\n- Use clear, specific descriptions that help other agents understand quality status",
+  "knowledge": {
+    "domain_expertise": [
+      "Testing frameworks and methodologies",
+      "Quality assurance standards",
+      "Test automation strategies",
+      "Performance testing techniques",
+      "Coverage analysis methods"
+    ],
+    "best_practices": [
+      "Execute targeted test validation on critical paths",
+      "Analyze coverage metrics from tool reports, not file reads",
+      "Sample test files strategically (5-10 max) to identify gaps",
+      "Validate performance on key scenarios only",
+      "Use grep patterns for regression test coordination",
+      "Process test files sequentially to prevent memory accumulation",
+      "Extract test summaries and discard verbose output immediately"
+    ],
+    "constraints": [
+      "Maximum 5-10 test files for sampling per session",
+      "Use grep for test discovery instead of file reading",
+      "Process test files sequentially, never in parallel",
+      "Skip test files >500KB unless absolutely critical",
+      "Extract metrics from tool outputs, not source files",
+      "Immediately discard test file contents after extraction"
+    ],
+    "examples": []
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "context",
+        "constraints"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis",
+        "recommendations",
+        "code"
+      ]
+    },
+    "handoff_agents": [
+      "engineer",
+      "security"
+    ],
+    "triggers": []
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Basic qa task",
+        "input": "Perform a basic qa analysis",
+        "expected_behavior": "Agent performs qa tasks correctly",
+        "validation_criteria": [
+          "completes_task",
+          "follows_format"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 8192,
+      "success_rate": 0.95
+    }
+  },
+  "dependencies": {
+    "python": [
+      "pytest>=7.4.0",
+      "pytest-cov>=4.1.0",
+      "hypothesis>=6.92.0",
+      "mutmut>=2.4.0",
+      "pytest-benchmark>=4.0.0",
+      "faker>=20.0.0"
+    ],
+    "system": [
+      "python3",
+      "git"
+    ],
+    "optional": false
+  }
+}

{claude_mpm-4.0.17 → claude_mpm-4.0.19}/src/claude_mpm/cli/__init__.py

@@ -77,6 +77,9 @@ def main(argv: Optional[list] = None):
     # Initialize or update project registry
     _initialize_project_registry()
 
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
+
     # Create parser with version
     parser = create_parser(version=__version__)
 
@@ -167,6 +170,65 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _verify_mcp_gateway_startup():
+    """
+    Verify MCP Gateway configuration on startup.
+
+    WHY: The MCP gateway should be automatically configured and verified on startup
+    to provide a seamless experience with diagnostic tools, file summarizer, and
+    ticket service.
+
+    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.
+    """
+    try:
+        import asyncio
+        from ..services.mcp_gateway.core.startup_verification import (
+            verify_mcp_gateway_on_startup,
+            is_mcp_gateway_configured,
+        )
+
+        # Quick check first - if already configured, skip detailed verification
+        if is_mcp_gateway_configured():
+            return
+
+        # Run detailed verification in background
+        # Note: We don't await this to avoid blocking startup
+        def run_verification():
+            try:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                results = loop.run_until_complete(verify_mcp_gateway_on_startup())
+                loop.close()
+
+                # Log results but don't block
+                from ..core.logger import get_logger
+                logger = get_logger("cli")
+
+                if results.get("gateway_configured"):
+                    logger.debug("MCP Gateway verification completed successfully")
+                else:
+                    logger.debug("MCP Gateway verification completed with warnings")
+
+            except Exception as e:
+                from ..core.logger import get_logger
+                logger = get_logger("cli")
+                logger.debug(f"MCP Gateway verification failed: {e}")
+
+        # Run in background thread to avoid blocking startup
+        import threading
+        verification_thread = threading.Thread(target=run_verification, daemon=True)
+        verification_thread.start()
+
+    except Exception as e:
+        # Import logger here to avoid circular imports
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to start MCP Gateway verification: {e}")
+        # Continue execution - MCP gateway issues shouldn't block startup
+
+
 def _ensure_run_attributes(args):
     """
     Ensure run command attributes exist when defaulting to run.

claude_mpm-4.0.19/src/claude_mpm/cli/commands/mcp_install_commands.py

@@ -0,0 +1,77 @@
+"""MCP install command implementations.
+
+This module provides MCP installation and configuration commands.
+Extracted from mcp.py to reduce complexity and improve maintainability.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+class MCPInstallCommands:
+    """Handles MCP install commands."""
+
+    def __init__(self, logger):
+        """Initialize the MCP install commands handler."""
+        self.logger = logger
+
+    def install_gateway(self, args):
+        """Install and configure MCP gateway.
+        
+        WHY: This command installs the MCP package dependencies and configures
+        Claude Desktop to use the MCP gateway server.
+        
+        DESIGN DECISION: We handle both package installation and configuration
+        in one command for user convenience.
+        """
+        self.logger.info("MCP gateway installation command called")
+        print("📦 Installing and Configuring MCP Gateway")
+        print("=" * 50)
+        
+        # Step 1: Install MCP package if needed
+        print("\n1️⃣  Checking MCP package installation...")
+        try:
+            import mcp
+            print("✅ MCP package already installed")
+        except ImportError:
+            print("📦 Installing MCP package...")
+            try:
+                subprocess.check_call([sys.executable, "-m", "pip", "install", "mcp"])
+                print("✅ MCP package installed successfully")
+            except subprocess.CalledProcessError as e:
+                print(f"❌ Error installing MCP package: {e}")
+                print("\nPlease install manually with: pip install mcp")
+                return 1
+        
+        # Step 2: Run the configuration script
+        print("\n2️⃣  Configuring Claude Desktop...")
+        project_root = Path(__file__).parent.parent.parent.parent.parent
+        config_script = project_root / "scripts" / "configure_mcp_server.py"
+        
+        if not config_script.exists():
+            print(f"⚠️  Configuration script not found at {config_script}")
+            print("\nPlease configure manually. See:")
+            print("  claude-mpm mcp start --instructions")
+            return 1
+        
+        try:
+            result = subprocess.run(
+                [sys.executable, str(config_script)],
+                cwd=str(project_root)
+            )
+            
+            if result.returncode == 0:
+                print("✅ Configuration completed successfully")
+                print("\n🎉 MCP Gateway is ready to use!")
+                print("\nNext steps:")
+                print("1. Restart Claude Desktop")
+                print("2. Check process status: python scripts/check_mcp_processes.py")
+                return 0
+            else:
+                print("❌ Configuration script failed")
+                return 1
+                
+        except Exception as e:
+            print(f"❌ Error running configuration: {e}")
+            return 1

claude_mpm-4.0.19/src/claude_mpm/cli/commands/mcp_server_commands.py

@@ -0,0 +1,156 @@
+"""MCP server command implementations.
+
+This module provides MCP server management commands.
+Extracted from mcp.py to reduce complexity and improve maintainability.
+"""
+
+import asyncio
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+class MCPServerCommands:
+    """Handles MCP server commands."""
+
+    def __init__(self, logger):
+        """Initialize the MCP server commands handler."""
+        self.logger = logger
+
+    async def start_server(self, args):
+        """Start MCP server command.
+
+        WHY: This command starts the MCP server using the proper stdio-based
+        implementation that Claude Desktop can communicate with.
+        NOTE: MCP is for Claude Desktop's Code features.
+
+        DESIGN DECISION: We now use the wrapper script to ensure proper
+        environment setup regardless of how the server is invoked.
+        """
+        self.logger.info("MCP server start command called")
+
+        # Check if we're being called by Claude Code (no special flags)
+        show_instructions = getattr(args, "instructions", False)
+        test_mode = getattr(args, "test", False)
+        daemon_mode = getattr(args, "daemon", False)
+
+        if daemon_mode:
+            # Daemon mode - not recommended for MCP
+            print("⚠️  MCP servers are designed to be spawned by Claude Code")
+            print("   Running as a daemon is not recommended.")
+            print("   Note: MCP is ONLY for Claude Code, not Claude Desktop.")
+            return 1
+
+        if show_instructions:
+            # Show configuration instructions
+            print("🚀 MCP Server Setup Instructions for Claude Desktop")
+            print("=" * 50)
+            print("\nThe MCP server enables Claude Desktop to use tools and integrations.")
+            print("\nTo configure the MCP server:")
+            print("\n1. Run the configuration script:")
+            print("   python scripts/configure_mcp_server.py")
+            print("\n2. Or manually configure Claude Desktop:")
+            
+            # Find project root for paths
+            project_root = Path(__file__).parent.parent.parent.parent.parent
+            wrapper_path = project_root / "scripts" / "mcp_wrapper.py"
+            
+            print("\n   Add this to your Claude Desktop configuration:")
+            print("   (~/Library/Application Support/Claude/claude_desktop_config.json on macOS)")
+            print("\n   {")
+            print('     "mcpServers": {')
+            print('       "claude-mpm-gateway": {')
+            print(f'         "command": "{sys.executable}",')
+            print(f'         "args": ["{wrapper_path}"],')
+            print(f'         "cwd": "{project_root}"')
+            print('       }')
+            print('     }')
+            print('   }')
+            print("\n3. Restart Claude Desktop to load the MCP server")
+            print("\nTo test the server directly:")
+            print("   python scripts/mcp_wrapper.py")
+            print("\nTo check running MCP processes:")
+            print("   python scripts/check_mcp_processes.py")
+            print("\nFor more information, see:")
+            print("   https://github.com/anthropics/mcp")
+
+            return 0
+
+        # Default behavior: Use the wrapper script for proper environment setup
+        if test_mode:
+            print("🧪 Starting MCP server in test mode...")
+            print("   This will run the server with stdio communication.")
+            print("   Press Ctrl+C to stop.\n")
+
+        try:
+            # Instead of running directly, we should use the wrapper script
+            # for consistent environment setup
+            import subprocess
+            from pathlib import Path
+            
+            # Find the wrapper script
+            project_root = Path(__file__).parent.parent.parent.parent.parent
+            wrapper_script = project_root / "scripts" / "mcp_wrapper.py"
+            
+            if not wrapper_script.exists():
+                print(f"❌ Error: Wrapper script not found at {wrapper_script}", file=sys.stderr)
+                print("\nPlease ensure the wrapper script is installed.", file=sys.stderr)
+                return 1
+            
+            # Run the wrapper script
+            print(f"Starting MCP server via wrapper: {wrapper_script}", file=sys.stderr)
+            
+            # Use subprocess to run the wrapper
+            # This ensures proper environment setup
+            result = subprocess.run(
+                [sys.executable, str(wrapper_script)],
+                cwd=str(project_root),
+                env={**os.environ, "MCP_MODE": "test" if test_mode else "production"}
+            )
+            
+            return result.returncode
+
+        except ImportError as e:
+            self.logger.error(f"Failed to import MCP server: {e}")
+            # Don't print to stdout as it would interfere with JSON-RPC protocol
+            # Log to stderr instead
+            import sys
+
+            print(
+                f"❌ Error: Could not import MCP server components: {e}", file=sys.stderr
+            )
+            print("\nMake sure the MCP package is installed:", file=sys.stderr)
+            print("  pip install mcp", file=sys.stderr)
+            return 1
+        except KeyboardInterrupt:
+            # Graceful shutdown
+            self.logger.info("MCP server interrupted")
+            return 0
+        except Exception as e:
+            self.logger.error(f"Server error: {e}")
+            import sys
+
+            print(f"❌ Error running server: {e}", file=sys.stderr)
+            return 1
+
+    def stop_server(self, args):
+        """Stop MCP server command."""
+        self.logger.info("MCP server stop command called")
+        print("🛑 MCP server stop functionality has been simplified")
+        print("   This command is now a placeholder - full implementation needed")
+        return 0
+
+    def show_status(self, args):
+        """Show MCP server status command."""
+        self.logger.info("MCP server status command called")
+        print("📊 MCP server status functionality has been simplified")
+        print("   This command is now a placeholder - full implementation needed")
+        return 0
+
+    def cleanup_locks(self, args):
+        """Cleanup MCP server locks command."""
+        self.logger.info("MCP server cleanup locks command called")
+        print("🧹 MCP server cleanup locks functionality has been simplified")
+        print("   This command is now a placeholder - full implementation needed")
+        return 0

claude_mpm-4.0.19/src/claude_mpm/scripts/mcp_server.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""MCP Server launcher script for Claude Desktop.
+
+This script launches the MCP gateway server for Claude Desktop integration.
+It handles proper Python path setup and error reporting to stderr.
+"""
+
+import sys
+import os
+import logging
+
+# Since we're now in src/claude_mpm/scripts/, we need to go up 3 levels to reach the project root
+# Then down into src to add it to the path
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+sys.path.insert(0, os.path.join(project_root, 'src'))
+
+def setup_logging():
+    """Configure logging to stderr to avoid interfering with stdio protocol."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,
+    )
+
+def main():
+    """Main entry point for the MCP server launcher."""
+    try:
+        # Setup logging first
+        setup_logging()
+        logger = logging.getLogger("MCPLauncher")
+        
+        # Import modules after path setup
+        try:
+            from claude_mpm.services.mcp_gateway.server.stdio_server import SimpleMCPServer
+            import asyncio
+        except ImportError as e:
+            logger.error(f"Failed to import required modules: {e}")
+            logger.error("Make sure claude-mpm is properly installed")
+            sys.exit(1)
+        
+        # Create and run server
+        logger.info("Starting MCP Gateway Server...")
+        
+        async def run_server():
+            """Async function to run the server."""
+            try:
+                server = SimpleMCPServer(name="claude-mpm-gateway", version="1.0.0")
+                await server.run()
+            except Exception as e:
+                logger.error(f"Server runtime error: {e}")
+                raise
+        
+        # Run the async server
+        asyncio.run(run_server())
+        
+    except KeyboardInterrupt:
+        # Clean shutdown on Ctrl+C
+        logger.info("Server shutdown requested")
+        sys.exit(0)
+    except Exception as e:
+        # Log any unexpected errors
+        logger.error(f"Unexpected error: {e}")
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

claude_mpm-4.0.19/src/claude_mpm/scripts/mcp_wrapper.py

@@ -0,0 +1,39 @@
+"""
+MCP Wrapper Module
+==================
+
+This module provides an importable entry point for the MCP wrapper script.
+It delegates to the actual wrapper script in the scripts directory.
+
+WHY: We need this to make the wrapper accessible as a Python module entry point
+for the pyproject.toml scripts configuration.
+"""
+
+import sys
+import os
+from pathlib import Path
+
+
+def entry_point():
+    """Entry point that delegates to the actual wrapper script."""
+    # Find the actual wrapper script
+    current_file = Path(__file__).resolve()
+    project_root = current_file.parent.parent.parent.parent
+    wrapper_script = project_root / "scripts" / "mcp_wrapper.py"
+    
+    if not wrapper_script.exists():
+        print(f"Error: Wrapper script not found at {wrapper_script}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Add the scripts directory to path and import the wrapper
+    scripts_dir = str(wrapper_script.parent)
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    
+    # Import and run the wrapper
+    import mcp_wrapper
+    mcp_wrapper.main()
+
+
+if __name__ == "__main__":
+    entry_point()