claude-mpm 4.9.0__py3-none-any.whl → 4.10.0__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.9.0
+4.10.0

claude_mpm/agents/templates/research.json

@@ -87,28 +87,35 @@
     ],
     "best_practices": [
       "CRITICAL: Claude Code permanently retains ALL file contents - no memory release possible",
-      "TOP PRIORITY: Use mcp__mcp-vector-search__search_code for semantic pattern discovery",
-      "FIRST PRIORITY: Use mcp__claude-mpm-gateway__document_summarizer for ALL files >20KB",
-      "SECOND PRIORITY: Use mcp__mcp-vector-search__search_similar to find related code patterns",
-      "THIRD PRIORITY: Use mcp__mcp-vector-search__search_context for understanding functionality",
-      "LAST RESORT: Read tool ONLY for files <20KB when other tools unavailable",
-      "Always index project first with mcp__mcp-vector-search__index_project if not indexed",
-      "Use mcp__mcp-vector-search__get_project_status to check indexing status",
-      "Extract key patterns from 3-5 representative files ABSOLUTE MAXIMUM",
-      "NEVER exceed 5 files even if task requests 'thorough' or 'complete' analysis",
-      "Leverage vector search for finding similar implementations and patterns",
-      "Use grep with line numbers (-n) only when vector search unavailable",
-      "MANDATORY: Leverage MCP summarizer tool for files exceeding 20KB thresholds",
-      "Trigger summarization at 20KB or 200 lines for single files",
-      "Apply batch summarization after 3 files or 50KB cumulative content",
-      "Use file type-specific thresholds for optimal processing",
-      "Process files sequentially to prevent memory accumulation",
-      "Check file sizes BEFORE reading - NEVER read files >1MB, use vector search instead",
-      "Reset cumulative counters after batch summarization",
-      "Extract and summarize patterns immediately (behavioral guidance only - memory persists)",
-      "Review file commit history before modifications: git log --oneline -5 <file_path>",
-      "Write succinct commit messages explaining WHAT changed and WHY",
-      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
+      "TOOL AVAILABILITY: Check if mcp-vector-search tools are available before use",
+      "IF VECTOR SEARCH AVAILABLE:",
+      "  - TOP PRIORITY: Use mcp__mcp-vector-search__search_code for semantic pattern discovery",
+      "  - SECOND PRIORITY: Use mcp__mcp-vector-search__search_similar to find related code patterns",
+      "  - THIRD PRIORITY: Use mcp__mcp-vector-search__search_context for understanding functionality",
+      "  - Always index project first with mcp__mcp-vector-search__index_project if not indexed",
+      "  - Use mcp__mcp-vector-search__get_project_status to check indexing status",
+      "  - Leverage vector search for finding similar implementations and patterns",
+      "IF VECTOR SEARCH UNAVAILABLE:",
+      "  - PRIMARY: Use Grep tool with pattern matching for code search",
+      "  - SECONDARY: Use Glob tool for file discovery by pattern",
+      "  - CONTEXT: Use grep with -A/-B flags for contextual code understanding",
+      "  - ADAPTIVE: Adjust grep context based on matches (>50: -A 2 -B 2, <20: -A 10 -B 10)",
+      "UNIVERSAL BEST PRACTICES (always apply):",
+      "  - FIRST PRIORITY: Use mcp__claude-mpm-gateway__document_summarizer for ALL files >20KB",
+      "  - LAST RESORT: Read tool ONLY for files <20KB when other tools unavailable",
+      "  - Extract key patterns from 3-5 representative files ABSOLUTE MAXIMUM",
+      "  - NEVER exceed 5 files even if task requests 'thorough' or 'complete' analysis",
+      "  - MANDATORY: Leverage MCP summarizer tool for files exceeding 20KB thresholds",
+      "  - Trigger summarization at 20KB or 200 lines for single files",
+      "  - Apply batch summarization after 3 files or 50KB cumulative content",
+      "  - Use file type-specific thresholds for optimal processing",
+      "  - Process files sequentially to prevent memory accumulation",
+      "  - Check file sizes BEFORE reading - NEVER read files >1MB",
+      "  - Reset cumulative counters after batch summarization",
+      "  - Extract and summarize patterns immediately (behavioral guidance only - memory persists)",
+      "  - Review file commit history before modifications: git log --oneline -5 <file_path>",
+      "  - Write succinct commit messages explaining WHAT changed and WHY",
+      "  - Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
     ],
     "constraints": [
       "PERMANENT MEMORY: Claude Code retains ALL file contents permanently - no release mechanism exists",
@@ -128,7 +135,7 @@
       "PREFER mcp__claude-mpm-gateway__document_summarizer over Read tool in ALL cases >20KB"
     ]
   },
-  "instructions": "You are an expert research analyst with deep expertise in codebase investigation, architectural analysis, and system understanding. Your approach combines systematic methodology with efficient resource management to deliver comprehensive insights while maintaining strict memory discipline.\n\n**Core Responsibilities:**\n\nYou will investigate and analyze systems with focus on:\n- Comprehensive codebase exploration and pattern identification\n- Architectural analysis and system boundary mapping\n- Technology stack assessment and dependency analysis\n- Security posture evaluation and vulnerability identification\n- Performance characteristics and bottleneck analysis\n- Code quality metrics and technical debt assessment\n\n**Research Methodology:**\n\nWhen conducting analysis, you will:\n\n1. **Plan Investigation Strategy**: Systematically approach research by:\n   - Checking project indexing status with mcp__mcp-vector-search__get_project_status\n   - Running mcp__mcp-vector-search__index_project if needed for initial indexing\n   - Defining clear research objectives and scope boundaries\n   - Prioritizing critical components and high-impact areas\n   - Selecting appropriate tools and techniques for discovery\n   - Establishing memory-efficient sampling strategies\n\n2. **Execute Strategic Discovery**: Conduct analysis using:\n   - Semantic search with mcp__mcp-vector-search__search_code for pattern discovery\n   - Similarity analysis with mcp__mcp-vector-search__search_similar for related code\n   - Context search with mcp__mcp-vector-search__search_context for functionality understanding\n   - Pattern-based search techniques to identify key components\n   - Architectural mapping through dependency analysis\n   - Representative sampling of critical system components\n   - Progressive refinement of understanding through iterations\n\n3. **Analyze Findings**: Process discovered information by:\n   - Extracting meaningful patterns from code structures\n   - Identifying architectural decisions and design principles\n   - Documenting system boundaries and interaction patterns\n   - Assessing technical debt and improvement opportunities\n\n4. **Synthesize Insights**: Create comprehensive understanding through:\n   - Connecting disparate findings into coherent system view\n   - Identifying risks, opportunities, and recommendations\n   - Documenting key insights and architectural decisions\n   - Providing actionable recommendations for improvement\n\n**Memory Management Excellence:**\n\nYou will maintain strict memory discipline through:\n- Prioritizing mcp-vector-search tools to avoid loading files into memory\n- Strategic sampling of representative components (maximum 3-5 files per session)\n- Preference for semantic search over traditional file reading\n- Mandatory use of document summarization for files exceeding 20KB\n- Sequential processing to prevent memory accumulation\n- Immediate extraction and summarization of key insights\n\n**Research Focus Areas:**\n\n**Architectural Analysis:**\n- System design patterns and architectural decisions\n- Service boundaries and interaction mechanisms\n- Data flow patterns and processing pipelines\n- Integration points and external dependencies\n\n**Code Quality Assessment:**\n- Design pattern usage and code organization\n- Technical debt identification and quantification\n- Security vulnerability assessment\n- Performance bottleneck identification\n\n**Technology Evaluation:**\n- Framework and library usage patterns\n- Configuration management approaches\n- Development and deployment practices\n- Tooling and automation strategies\n\n**Communication Style:**\n\nWhen presenting research findings, you will:\n- Provide clear, structured analysis with supporting evidence\n- Highlight key insights and their implications\n- Recommend specific actions based on discovered patterns\n- Document assumptions and limitations of the analysis\n- Present findings in actionable, prioritized format\n\n**Research Standards:**\n\nYou will maintain high standards through:\n- Systematic approach to investigation and analysis\n- Evidence-based conclusions with clear supporting data\n- Comprehensive documentation of methodology and findings\n- Regular validation of assumptions against discovered evidence\n- Clear separation of facts, inferences, and recommendations\n\nYour goal is to provide comprehensive, accurate, and actionable insights that enable informed decision-making about system architecture, code quality, and technical strategy while maintaining exceptional memory efficiency throughout the research process.",
+  "instructions": "You are an expert research analyst with deep expertise in codebase investigation, architectural analysis, and system understanding. Your approach combines systematic methodology with efficient resource management to deliver comprehensive insights while maintaining strict memory discipline.\n\n**Core Responsibilities:**\n\nYou will investigate and analyze systems with focus on:\n- Comprehensive codebase exploration and pattern identification\n- Architectural analysis and system boundary mapping\n- Technology stack assessment and dependency analysis\n- Security posture evaluation and vulnerability identification\n- Performance characteristics and bottleneck analysis\n- Code quality metrics and technical debt assessment\n\n**Research Methodology:**\n\nWhen conducting analysis, you will:\n\n1. **Plan Investigation Strategy**: Systematically approach research by:\n   - Checking tool availability (vector search vs grep/glob fallback)\n   - IF vector search available: Check indexing status with mcp__mcp-vector-search__get_project_status\n   - IF vector search available AND not indexed: Run mcp__mcp-vector-search__index_project\n   - IF vector search unavailable: Plan grep/glob pattern-based search strategy\n   - Defining clear research objectives and scope boundaries\n   - Prioritizing critical components and high-impact areas\n   - Selecting appropriate tools based on availability\n   - Establishing memory-efficient sampling strategies\n\n2. **Execute Strategic Discovery**: Conduct analysis using available tools:\n\n   **WITH VECTOR SEARCH (preferred when available):**\n   - Semantic search with mcp__mcp-vector-search__search_code for pattern discovery\n   - Similarity analysis with mcp__mcp-vector-search__search_similar for related code\n   - Context search with mcp__mcp-vector-search__search_context for functionality understanding\n\n   **WITHOUT VECTOR SEARCH (graceful fallback):**\n   - Pattern-based search with Grep tool for code discovery\n   - File discovery with Glob tool using patterns like \"**/*.py\" or \"src/**/*.ts\"\n   - Contextual understanding with grep -A/-B flags for surrounding code\n   - Adaptive context: >50 matches use -A 2 -B 2, <20 matches use -A 10 -B 10\n\n   **UNIVERSAL TECHNIQUES (always available):**\n   - Pattern-based search techniques to identify key components\n   - Architectural mapping through dependency analysis\n   - Representative sampling of critical system components (3-5 files maximum)\n   - Progressive refinement of understanding through iterations\n   - MCP document summarizer for files >20KB\n\n3. **Analyze Findings**: Process discovered information by:\n   - Extracting meaningful patterns from code structures\n   - Identifying architectural decisions and design principles\n   - Documenting system boundaries and interaction patterns\n   - Assessing technical debt and improvement opportunities\n\n4. **Synthesize Insights**: Create comprehensive understanding through:\n   - Connecting disparate findings into coherent system view\n   - Identifying risks, opportunities, and recommendations\n   - Documenting key insights and architectural decisions\n   - Providing actionable recommendations for improvement\n\n**Memory Management Excellence:**\n\nYou will maintain strict memory discipline through:\n- Prioritizing search tools (vector search OR grep/glob) to avoid loading files into memory\n- Using vector search when available for semantic understanding without file loading\n- Using grep/glob as fallback when vector search is unavailable\n- Strategic sampling of representative components (maximum 3-5 files per session)\n- Preference for search tools over direct file reading\n- Mandatory use of document summarization for files exceeding 20KB\n- Sequential processing to prevent memory accumulation\n- Immediate extraction and summarization of key insights\n\n**Tool Availability and Graceful Degradation:**\n\nYou will adapt your approach based on available tools:\n- Check if mcp-vector-search tools are available in your tool set\n- If available: Use semantic search capabilities for efficient pattern discovery\n- If unavailable: Gracefully fall back to grep/glob for pattern-based search\n- Never fail a task due to missing optional tools - adapt your strategy\n- Inform the user if falling back to alternative search methods\n- Maintain same quality of analysis regardless of tool availability\n\n**Research Focus Areas:**\n\n**Architectural Analysis:**\n- System design patterns and architectural decisions\n- Service boundaries and interaction mechanisms\n- Data flow patterns and processing pipelines\n- Integration points and external dependencies\n\n**Code Quality Assessment:**\n- Design pattern usage and code organization\n- Technical debt identification and quantification\n- Security vulnerability assessment\n- Performance bottleneck identification\n\n**Technology Evaluation:**\n- Framework and library usage patterns\n- Configuration management approaches\n- Development and deployment practices\n- Tooling and automation strategies\n\n**Communication Style:**\n\nWhen presenting research findings, you will:\n- Provide clear, structured analysis with supporting evidence\n- Highlight key insights and their implications\n- Recommend specific actions based on discovered patterns\n- Document assumptions and limitations of the analysis\n- Present findings in actionable, prioritized format\n\n**Research Standards:**\n\nYou will maintain high standards through:\n- Systematic approach to investigation and analysis\n- Evidence-based conclusions with clear supporting data\n- Comprehensive documentation of methodology and findings\n- Regular validation of assumptions against discovered evidence\n- Clear separation of facts, inferences, and recommendations\n\nYour goal is to provide comprehensive, accurate, and actionable insights that enable informed decision-making about system architecture, code quality, and technical strategy while maintaining exceptional memory efficiency throughout the research process.",
   "memory_routing": {
     "description": "Stores analysis findings, domain knowledge, and architectural decisions",
     "categories": [

claude_mpm/cli/commands/search.py

@@ -16,8 +16,7 @@ from rich.panel import Panel
 from rich.syntax import Syntax
 from rich.table import Table
 
-from claude_mpm.cli.utils import handle_async_errors
-from claude_mpm.services.service_container import get_service_container
+from claude_mpm.services.core.service_container import get_global_container
 
 console = Console()
 
@@ -27,8 +26,9 @@ class MCPSearchInterface:
 
     def __init__(self):
         """Initialize the search interface."""
-        self.container = get_service_container()
+        self.container = get_global_container()
         self.mcp_gateway = None
+        self.vector_search_available = False
 
     async def initialize(self):
         """Initialize the MCP gateway connection."""
@@ -39,10 +39,127 @@ class MCPSearchInterface:
             if not self.mcp_gateway:
                 self.mcp_gateway = MCPGatewayService()
                 await self.mcp_gateway.initialize()
+
+            # Check if vector search is available
+            self.vector_search_available = await self._check_vector_search_available()
+
         except Exception as e:
             console.print(f"[red]Failed to initialize MCP gateway: {e}[/red]")
             raise
 
+    async def _check_vector_search_available(self) -> bool:
+        """Check if mcp-vector-search is available and offer installation if not."""
+        import importlib.util
+
+        # Check if package is installed
+        spec = importlib.util.find_spec("mcp_vector_search")
+        if spec is not None:
+            return True
+
+        # Package not found - offer installation
+        console.print("\n[yellow]⚠️  mcp-vector-search not found[/yellow]")
+        console.print("This package enables semantic code search (optional feature).")
+        console.print("\nInstallation options:")
+        console.print("  1. Install via pip (recommended for this project)")
+        console.print("  2. Install via pipx (isolated, system-wide)")
+        console.print("  3. Skip (use traditional grep/glob instead)")
+
+        try:
+            choice = input("\nChoose option (1/2/3) [3]: ").strip() or "3"
+
+            if choice == "1":
+                return await self._install_via_pip()
+            if choice == "2":
+                return await self._install_via_pipx()
+            console.print(
+                "[dim]Continuing with fallback search methods (grep/glob)[/dim]"
+            )
+            return False
+
+        except (EOFError, KeyboardInterrupt):
+            console.print("\n[dim]Installation cancelled, using fallback methods[/dim]")
+            return False
+
+    async def _install_via_pip(self) -> bool:
+        """Install mcp-vector-search via pip."""
+        import subprocess
+
+        try:
+            console.print("\n[cyan]📦 Installing mcp-vector-search via pip...[/cyan]")
+            result = subprocess.run(
+                [sys.executable, "-m", "pip", "install", "mcp-vector-search"],
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                console.print(
+                    "[green]✓ Successfully installed mcp-vector-search[/green]"
+                )
+                return True
+
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            console.print(f"[red]✗ Installation failed: {error_msg}[/red]")
+            return False
+
+        except subprocess.TimeoutExpired:
+            console.print("[red]✗ Installation timed out[/red]")
+            return False
+        except Exception as e:
+            console.print(f"[red]✗ Installation error: {e}[/red]")
+            return False
+
+    async def _install_via_pipx(self) -> bool:
+        """Install mcp-vector-search via pipx."""
+        import subprocess
+
+        try:
+            # Check if pipx is available
+            pipx_check = subprocess.run(
+                ["pipx", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+
+            if pipx_check.returncode != 0:
+                console.print("[red]✗ pipx is not installed[/red]")
+                console.print("Install pipx first: python -m pip install pipx")
+                return False
+
+            console.print("\n[cyan]📦 Installing mcp-vector-search via pipx...[/cyan]")
+            result = subprocess.run(
+                ["pipx", "install", "mcp-vector-search"],
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                console.print(
+                    "[green]✓ Successfully installed mcp-vector-search[/green]"
+                )
+                return True
+
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            console.print(f"[red]✗ Installation failed: {error_msg}[/red]")
+            return False
+
+        except FileNotFoundError:
+            console.print("[red]✗ pipx command not found[/red]")
+            console.print("Install pipx first: python -m pip install pipx")
+            return False
+        except subprocess.TimeoutExpired:
+            console.print("[red]✗ Installation timed out[/red]")
+            return False
+        except Exception as e:
+            console.print(f"[red]✗ Installation error: {e}[/red]")
+            return False
+
     async def search_code(
         self,
         query: str,
@@ -125,6 +242,12 @@ class MCPSearchInterface:
         if not self.mcp_gateway:
             await self.initialize()
 
+        # Check if vector search is available
+        if not self.vector_search_available:
+            return {
+                "error": "mcp-vector-search is not available. Use traditional grep/glob tools instead, or run command again to install."
+            }
+
         try:
             return await self.mcp_gateway.call_tool(tool_name, params)
         except Exception as e:
@@ -196,7 +319,6 @@ def display_search_results(results: Dict[str, Any], output_format: str = "rich")
 @click.option("--focus", multiple=True, help="Focus areas (with --context)")
 @click.option("--force", is_flag=True, help="Force reindexing (with --index)")
 @click.option("--json", "output_json", is_flag=True, help="Output results as JSON")
-@handle_async_errors
 async def search_command(
     query: Optional[str],
     similar: Optional[str],
@@ -228,8 +350,24 @@ async def search_command(
     output_format = "json" if output_json else "rich"
 
     try:
+        # Show first-time usage tips if vector search is available
+        if search.vector_search_available and not (index or status):
+            console.print(
+                "\n[dim]💡 Tip: Vector search provides semantic code understanding.[/dim]"
+            )
+            console.print(
+                "[dim]   Run with --index first to index your project.[/dim]\n"
+            )
+
         # Handle different operation modes
         if index:
+            if not search.vector_search_available:
+                console.print("[red]✗ mcp-vector-search is required for indexing[/red]")
+                console.print(
+                    "[dim]Install it or use traditional grep/glob for search[/dim]"
+                )
+                sys.exit(1)
+
             console.print("[cyan]Indexing project...[/cyan]")
             result = await search.index_project(
                 force=force, file_extensions=list(extensions) if extensions else None
@@ -239,10 +377,23 @@ async def search_command(
             display_search_results(result, output_format)
 
         elif status:
+            if not search.vector_search_available:
+                console.print(
+                    "[red]✗ mcp-vector-search is required for status check[/red]"
+                )
+                console.print("[dim]Install it to use vector search features[/dim]")
+                sys.exit(1)
+
             result = await search.get_status()
             display_search_results(result, output_format)
 
         elif similar:
+            if not search.vector_search_available:
+                console.print("[yellow]⚠️  Vector search not available[/yellow]")
+                console.print("[dim]Similarity search requires mcp-vector-search[/dim]")
+                console.print("[dim]Falling back to basic file search...[/dim]")
+                sys.exit(1)
+
             result = await search.search_similar(
                 file_path=similar,
                 function_name=function,
@@ -252,6 +403,12 @@ async def search_command(
             display_search_results(result, output_format)
 
         elif context:
+            if not search.vector_search_available:
+                console.print("[yellow]⚠️  Vector search not available[/yellow]")
+                console.print("[dim]Context search requires mcp-vector-search[/dim]")
+                console.print("[dim]Try using grep for text-based search instead[/dim]")
+                sys.exit(1)
+
             result = await search.search_context(
                 description=context,
                 focus_areas=list(focus) if focus else None,
@@ -260,6 +417,15 @@ async def search_command(
             display_search_results(result, output_format)
 
         elif query:
+            if not search.vector_search_available:
+                console.print("[yellow]⚠️  Vector search not available[/yellow]")
+                console.print("[dim]Code search requires mcp-vector-search[/dim]")
+                console.print(
+                    "\n[cyan]Alternative: Use grep for pattern matching:[/cyan]"
+                )
+                console.print(f"  grep -r '{query}' .")
+                sys.exit(1)
+
             result = await search.search_code(
                 query=query,
                 limit=limit,

claude_mpm/services/mcp_gateway/main.py

@@ -323,6 +323,27 @@ class MCPGatewayOrchestrator:
         except Exception as e:
             self.logger.warning(f"Could not load KuzuMemoryService: {e}")
 
+        # MCP Vector Search Service (optional - will auto-install on first use)
+        try:
+            from .tools.external_mcp_services import MCPVectorSearchService
+
+            vector_search = MCPVectorSearchService()
+            # Try to initialize without interactive prompts during gateway startup
+            # This will only succeed if already installed
+            init_success = await vector_search.initialize(
+                auto_install=False, interactive=False
+            )
+
+            if init_success:
+                tools.append(vector_search)
+                self.logger.info("MCPVectorSearchService added to built-in tools")
+            else:
+                self.logger.debug(
+                    "mcp-vector-search not installed - will be available via auto-install on first use"
+                )
+        except Exception as e:
+            self.logger.debug(f"Could not load MCPVectorSearchService: {e}")
+
         # Ticket tools removed - mcp-ticketer provides ticket functionality
 
         if not tools:

claude_mpm/services/mcp_gateway/tools/external_mcp_services.py

@@ -64,21 +64,28 @@ class ExternalMCPService(BaseToolAdapter):
             execution_time=0.0,
         )
 
-    async def initialize(self) -> bool:
-        """Initialize the external service."""
+    async def initialize(
+        self, auto_install: bool = True, interactive: bool = True
+    ) -> bool:
+        """Initialize the external service.
+
+        Args:
+            auto_install: Whether to automatically install if not found
+            interactive: Whether to prompt user for installation preferences
+        """
         try:
             # Check if package is installed
             self._is_installed = await self._check_installation()
 
-            if not self._is_installed:
-                self.logger.debug(
-                    f"{self.package_name} not installed - will attempt automatic installation if needed"
+            if not self._is_installed and auto_install:
+                self.logger.info(
+                    f"{self.package_name} not installed - attempting installation"
                 )
-                await self._install_package()
+                await self._install_package(interactive=interactive)
                 self._is_installed = await self._check_installation()
 
             if not self._is_installed:
-                self.logger.error(f"Failed to install {self.package_name}")
+                self.logger.warning(f"{self.package_name} is not available")
                 return False
 
             self.logger.info(f"{self.package_name} is available")
@@ -90,9 +97,21 @@ class ExternalMCPService(BaseToolAdapter):
 
     async def _check_installation(self) -> bool:
         """Check if the package is installed."""
+        # First check if importable (faster and more reliable)
+        import_name = self.package_name.replace("-", "_")
+        try:
+            import importlib.util
+
+            spec = importlib.util.find_spec(import_name)
+            if spec is not None:
+                return True
+        except (ImportError, ModuleNotFoundError, ValueError):
+            pass
+
+        # Fallback: try running as module
         try:
             result = subprocess.run(
-                [sys.executable, "-m", self.package_name.replace("-", "_"), "--help"],
+                [sys.executable, "-m", import_name, "--help"],
                 capture_output=True,
                 text=True,
                 timeout=5,
@@ -106,25 +125,133 @@ class ExternalMCPService(BaseToolAdapter):
         ):
             return False
 
-    async def _install_package(self) -> bool:
-        """Install the package using pip."""
+    async def _install_package(self, interactive: bool = True) -> bool:
+        """Install the package using pip or pipx.
+
+        Args:
+            interactive: Whether to prompt user for installation method choice
+        """
         try:
-            self.logger.info(f"Installing {self.package_name}...")
+            install_method = None
+
+            if interactive:
+                # Show user-friendly installation prompt
+                print(f"\n⚠️  {self.package_name} not found")
+                print("This package enables enhanced functionality (optional).")
+                print("\nInstallation options:")
+                print("1. Install via pip (recommended for this project)")
+                print("2. Install via pipx (isolated, system-wide)")
+                print("3. Skip (continue without this package)")
+
+                try:
+                    choice = input("\nChoose option (1/2/3) [1]: ").strip() or "1"
+                    if choice == "1":
+                        install_method = "pip"
+                    elif choice == "2":
+                        install_method = "pipx"
+                    else:
+                        self.logger.info(
+                            f"Skipping installation of {self.package_name}"
+                        )
+                        return False
+                except (EOFError, KeyboardInterrupt):
+                    print("\nInstallation cancelled")
+                    return False
+            else:
+                # Non-interactive: default to pip
+                install_method = "pip"
+
+            # Install using selected method
+            if install_method == "pip":
+                return await self._install_via_pip()
+            if install_method == "pipx":
+                return await self._install_via_pipx()
+
+            return False
+
+        except Exception as e:
+            self.logger.error(f"Error installing {self.package_name}: {e}")
+            return False
+
+    async def _install_via_pip(self) -> bool:
+        """Install package via pip."""
+        try:
+            print(f"\n📦 Installing {self.package_name} via pip...")
             result = subprocess.run(
                 [sys.executable, "-m", "pip", "install", self.package_name],
                 capture_output=True,
                 text=True,
-                timeout=30,
+                timeout=120,
                 check=False,
             )
 
             if result.returncode == 0:
-                self.logger.info(f"Successfully installed {self.package_name}")
+                print(f"✓ Successfully installed {self.package_name}")
+                self.logger.info(f"Successfully installed {self.package_name} via pip")
                 return True
-            self.logger.error(f"Failed to install {self.package_name}: {result.stderr}")
+
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            print(f"✗ Installation failed: {error_msg}")
+            self.logger.error(f"Failed to install {self.package_name}: {error_msg}")
             return False
 
+        except subprocess.TimeoutExpired:
+            print("✗ Installation timed out")
+            self.logger.error(f"Installation of {self.package_name} timed out")
+            return False
+        except Exception as e:
+            print(f"✗ Installation error: {e}")
+            self.logger.error(f"Error installing {self.package_name}: {e}")
+            return False
+
+    async def _install_via_pipx(self) -> bool:
+        """Install package via pipx."""
+        try:
+            # Check if pipx is available
+            pipx_check = subprocess.run(
+                ["pipx", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+
+            if pipx_check.returncode != 0:
+                print("✗ pipx is not installed")
+                print("Install pipx first: python -m pip install pipx")
+                self.logger.error("pipx not available for installation")
+                return False
+
+            print(f"\n📦 Installing {self.package_name} via pipx...")
+            result = subprocess.run(
+                ["pipx", "install", self.package_name],
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                print(f"✓ Successfully installed {self.package_name}")
+                self.logger.info(f"Successfully installed {self.package_name} via pipx")
+                return True
+
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            print(f"✗ Installation failed: {error_msg}")
+            self.logger.error(f"Failed to install {self.package_name}: {error_msg}")
+            return False
+
+        except FileNotFoundError:
+            print("✗ pipx command not found")
+            print("Install pipx first: python -m pip install pipx")
+            self.logger.error("pipx command not found")
+            return False
+        except subprocess.TimeoutExpired:
+            print("✗ Installation timed out")
+            self.logger.error(f"Installation of {self.package_name} timed out")
+            return False
         except Exception as e:
+            print(f"✗ Installation error: {e}")
             self.logger.error(f"Error installing {self.package_name}: {e}")
             return False
 

{claude_mpm-4.9.0.dist-info → claude_mpm-4.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.9.0
+Version: 4.10.0
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -160,7 +160,8 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 - 🧠 **Persistent Knowledge System**: Project-specific kuzu-memory integration for intelligent context retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume`
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
-- 🔌 **Optional MCP Services**: mcp-vector-search and kuzu-memory with automatic fallback installation
+- 🔌 **Smart MCP Services**: Interactive auto-install for mcp-vector-search on first use (pip/pipx choice)
+- 🔍 **Semantic Code Search**: Optional vector search with graceful fallback to grep/glob
 - 📁 **Multi-Project Support**: Per-session working directories with persistent knowledge graphs
 - 🔍 **Git Integration**: View diffs and track changes across projects
 - 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
@@ -197,7 +198,8 @@ claude-mpm mcp-pipx-config
 - `[monitor]` - Full monitoring dashboard with Socket.IO and async web server components
 - **Combine both**: Use `"claude-mpm[mcp,monitor]"` to install all features
 - **Note**: kuzu-memory is now a required dependency, always included with Claude MPM
-- Without optional MCP dependencies, other MCP services auto-install on first use via pipx
+- **Auto-Install**: mcp-vector-search offers interactive installation on first use (pip/pipx choice)
+- Without pre-installed MCP dependencies, services install on-demand with user confirmation
 
 **🎉 Pipx Support Now Fully Functional!** Recent improvements ensure complete compatibility:
 - ✅ Socket.IO daemon script path resolution (fixed)
@@ -216,6 +218,11 @@ claude-mpm
 # Start with monitoring dashboard
 claude-mpm run --monitor
 
+# Use semantic code search (auto-installs mcp-vector-search on first use)
+claude-mpm search "authentication logic"
+# or inside Claude Code session:
+/mpm-search "authentication logic"
+
 # Use MCP Gateway for external tool integration
 claude-mpm mcp
 

{claude_mpm-4.9.0.dist-info → claude_mpm-4.10.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 claude_mpm/BUILD_NUMBER,sha256=9JfxhnDtr-8l3kCP2U5TVXSErptHoga8m7XA8zqgGOc,4
-claude_mpm/VERSION,sha256=ucY14U7h_QVbv4d5sg77hbXv8X1m3zQsRzVoMpc3MXY,6
+claude_mpm/VERSION,sha256=9StPgaDGDNmI-MzJoDM-IGtffkHdD1KGxqtfe_LVM18,7
 claude_mpm/__init__.py,sha256=UCw6j9e_tZQ3kJtTqmdfNv7MHyw9nD1jkj80WurwM2g,2064
 claude_mpm/__main__.py,sha256=Ro5UBWBoQaSAIoSqWAr7zkbLyvi4sSy28WShqAhKJG0,723
 claude_mpm/constants.py,sha256=sLjJF6Kw7H4V9WWeaEYltM-77TgXqzEMX5vx4ukM5-0,5977
@@ -54,7 +54,7 @@ claude_mpm/agents/templates/python_engineer.json,sha256=SeTvI1EXS-RTIJzVHX0zu0FS
 claude_mpm/agents/templates/qa.json,sha256=bccjpuC93a7msGei3LKsCe88UiFMQzk1W40TvEYIHOg,10661
 claude_mpm/agents/templates/react_engineer.json,sha256=ihmqRAgiU81UVpw3ToSHvUigEZ7MMpoPhUbyXSmfbAo,13151
 claude_mpm/agents/templates/refactoring_engineer.json,sha256=qmhZdl4aXNyQEjZ-yieSa2NfEaPPi7Z4bYUZ4ohWJiI,12130
-claude_mpm/agents/templates/research.json,sha256=0i0FsMT13cQvynOXdtcWuVMrpFtV560Grr2N3mXUOvI,12406
+claude_mpm/agents/templates/research.json,sha256=-U7cDwH0kiffMSvrAuIe_AiA6OmWQbI5MLNjgvUhmhc,14336
 claude_mpm/agents/templates/ruby-engineer.json,sha256=FDdEGTbXzzAwbeucXH9Ve91mCnD9fGh3J26zbrKi9qs,12412
 claude_mpm/agents/templates/rust_engineer.json,sha256=0HKDrRGJxyvO5GWqby8d45Trw9IaAoJkeX5ZIkN10xE,12317
 claude_mpm/agents/templates/security.json,sha256=ekwiFj-TzVDTEj70QfV5Oix1x7zAeCdl-zZ8-QGJIXg,24556
@@ -103,7 +103,7 @@ claude_mpm/cli/commands/monitor.py,sha256=Fjb68hf3dEwTFek2LV8Nh6iU0qEkY7qYlOn32I
 claude_mpm/cli/commands/mpm_init.py,sha256=OtdJMsFn7E9Ck56wWPrCvqw6j5dsN_VI098C3bteitc,63888
 claude_mpm/cli/commands/mpm_init_handler.py,sha256=b1CSwZYJ89wMorKzPOKS-RVxOKR2kT9yv9KQLvKkd2U,3532
 claude_mpm/cli/commands/run.py,sha256=PB2H55piOPTy4yo4OBgbUCjMlcz9K79wbwpxQVc9m5Q,48225
-claude_mpm/cli/commands/search.py,sha256=_0qbUnop8v758MHsB0fAop8FVxwygD59tec_-iN7pLE,9806
+claude_mpm/cli/commands/search.py,sha256=alv6udvKcn-xkqeBlLuPRvfSDV1yxEX4n9mjjRT5uLM,16581
 claude_mpm/cli/commands/tickets.py,sha256=kl2dklTBnG3Y4jUUJ_PcEVsTx4CtVJfkGWboWBx_mQM,21234
 claude_mpm/cli/commands/uninstall.py,sha256=KGlVG6veEs1efLVjrZ3wSty7e1zVR9wpt-VXQA1RzWw,5945
 claude_mpm/cli/commands/upgrade.py,sha256=NYMVONNlj78WHoQ6eyVInroE95AeQxUY2_TpjYFTdYE,5409
@@ -632,7 +632,7 @@ claude_mpm/services/infrastructure/monitoring/resources.py,sha256=7Mt9zvNAYGf7OT
 claude_mpm/services/infrastructure/monitoring/service.py,sha256=guYB6rJtU18T2kPhZbKKg85l96lm2f7XVtPnBt1O3So,12613
 claude_mpm/services/mcp_gateway/__init__.py,sha256=4fiMsd7i2QzZpEXCUeo0Vk_CXRi35TE94gPvwyuz2es,5099
 claude_mpm/services/mcp_gateway/auto_configure.py,sha256=JNos01nGb2qXACXNHC-UkLccqQ-p8GFUElXqBLUQl7A,12163
-claude_mpm/services/mcp_gateway/main.py,sha256=lczjLqieS5eHhwWO5VXlqURDLAgXgOg6i-724oa590A,18189
+claude_mpm/services/mcp_gateway/main.py,sha256=1e_-NGwVNr8cFtwWC_2NhZS-EYwC--MSfiZTx15x3ao,19121
 claude_mpm/services/mcp_gateway/config/__init__.py,sha256=MpFgHfaT3dQz5QyEdpfbulD6tXUOY325LkovAYsdkAg,386
 claude_mpm/services/mcp_gateway/config/config_loader.py,sha256=jM0LCQGnyAezQHLqfLWtPn5P3GpGMxGltKlTIKCL24M,9427
 claude_mpm/services/mcp_gateway/config/config_schema.py,sha256=eSPyHmYJWBpGxJ8l0vBjEGod_PEnbGyHi3fcNLS4mH0,9475
@@ -654,7 +654,7 @@ claude_mpm/services/mcp_gateway/server/stdio_server.py,sha256=k_VHLZ17zdZzP6XOg6
 claude_mpm/services/mcp_gateway/tools/__init__.py,sha256=Ga0kbvNOi8peBRZk5MUnO5bo3jWDCpHFko7mO21Vix4,754
 claude_mpm/services/mcp_gateway/tools/base_adapter.py,sha256=na1MdyBCtVmKzgIcFJ5MuAUJ1LJrtA4yxkuqLnejiD8,16029
 claude_mpm/services/mcp_gateway/tools/document_summarizer.py,sha256=F86qgDIFW2UXljGV8Tx9CapypqnXFNu3qFvi8XHlcZg,28223
-claude_mpm/services/mcp_gateway/tools/external_mcp_services.py,sha256=PCw6egI7Vy7I-2l9ya9BZGusOdnQ3bY0uIJVSVnY_YA,18614
+claude_mpm/services/mcp_gateway/tools/external_mcp_services.py,sha256=PSnes4mVOyAdqJ5o_YU9lmyTiXeXwXzE_x1pQeadpbs,23635
 claude_mpm/services/mcp_gateway/tools/health_check_tool.py,sha256=SIrGt2uZGR4EGsH2_0UgkmHUV895M8zq9suNkRSteRA,16457
 claude_mpm/services/mcp_gateway/tools/hello_world.py,sha256=L45ph8b0iLPpksrkf0ELrfl6CwVD3W3YLigwUKjIOoY,20291
 claude_mpm/services/mcp_gateway/tools/kuzu_memory_service.py,sha256=qc9vYJtN3OYXqb-aXZpkx3FtkM9ivUm9AcWKUgeGdG4,17745
@@ -797,9 +797,9 @@ claude_mpm/utils/subprocess_utils.py,sha256=D0izRT8anjiUb_JG72zlJR_JAw1cDkb7kalN
 claude_mpm/validation/__init__.py,sha256=YZhwE3mhit-lslvRLuwfX82xJ_k4haZeKmh4IWaVwtk,156
 claude_mpm/validation/agent_validator.py,sha256=GprtAvu80VyMXcKGsK_VhYiXWA6BjKHv7O6HKx0AB9w,20917
 claude_mpm/validation/frontmatter_validator.py,sha256=YpJlYNNYcV8u6hIOi3_jaRsDnzhbcQpjCBE6eyBKaFY,7076
-claude_mpm-4.9.0.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
-claude_mpm-4.9.0.dist-info/METADATA,sha256=spXmDr3uBGSclzDSE5Clu2uTb4tQJ1bsMHcOpcf8r3Q,17584
-claude_mpm-4.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-4.9.0.dist-info/entry_points.txt,sha256=Vlw3GNi-OtTpKSrez04iNrPmxNxYDpIWxmJCxiZ5Tx8,526
-claude_mpm-4.9.0.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-4.9.0.dist-info/RECORD,,
+claude_mpm-4.10.0.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
+claude_mpm-4.10.0.dist-info/METADATA,sha256=k0Zv4w5f9JRyt9zBPKr0C1Np9CetMfRascM9u-26Tgo,17967
+claude_mpm-4.10.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-4.10.0.dist-info/entry_points.txt,sha256=Vlw3GNi-OtTpKSrez04iNrPmxNxYDpIWxmJCxiZ5Tx8,526
+claude_mpm-4.10.0.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-4.10.0.dist-info/RECORD,,