code-index-mcp

Instructions

Implementation Reference

• src/code_index_mcp/server.py:139-144 (handler)

  The primary MCP tool handler and registration for 'set_project_path'. This function is decorated with @mcp.tool() and delegates the logic to ProjectManagementService.initialize_project(path).

  @mcp.tool()
  @handle_mcp_tool_errors(return_type='str')
  def set_project_path(path: str, ctx: Context) -> str:
      """Set the base project path for indexing."""
      return ProjectManagementService(ctx).initialize_project(path)

• src/code_index_mcp/services/project_management_service.py:76-365 (helper)

  Helper method in ProjectManagementService that orchestrates the full project initialization, including validation, cleanup, shallow index setup via _shallow_manager.set_project_path, file monitoring, and result formatting.

  def initialize_project(self, path: str) -> str:
      """
      Initialize a project with comprehensive business logic.
  
      This is the main business method that orchestrates the project
      initialization workflow, handling validation, cleanup, setup,
      and coordination of all project components.
  
      Args:
          path: Project directory path to initialize
  
      Returns:
          Success message with project information
  
      Raises:
          ValueError: If path is invalid or initialization fails
      """
      # Business validation
      self._validate_initialization_request(path)
  
      # Business workflow: Execute initialization
      result = self._execute_initialization_workflow(path)
  
      # Business result formatting
      return self._format_initialization_result(result)
  
  def _validate_initialization_request(self, path: str) -> None:
      """
      Validate the project initialization request according to business rules.
  
      Args:
          path: Project path to validate
  
      Raises:
          ValueError: If validation fails
      """
      # Business rule: Path must be valid
      error = self._config_tool.validate_project_path(path)
      if error:
          raise ValueError(error)
  
  def _execute_initialization_workflow(self, path: str) -> ProjectInitializationResult:
      """
      Execute the core project initialization business workflow.
  
      Args:
          path: Project path to initialize
  
      Returns:
          ProjectInitializationResult with initialization data
      """
      # Business step 1: Initialize config tool
      self._config_tool.initialize_settings(path)
  
      # Normalize path for consistent processing
      normalized_path = self._config_tool.normalize_project_path(path)
  
      # Business step 2: Cleanup existing project state
      self._cleanup_existing_project()
  
      # Business step 3: Initialize shallow index by default (fast path)
      index_result = self._initialize_shallow_index_manager(normalized_path)
  
      # Business step 3.1: Store index manager in context for other services
      self.helper.update_index_manager(self._index_manager)
  
      # Business step 4: Setup file monitoring
      monitoring_result = self._setup_file_monitoring(normalized_path)
  
      # Business step 4: Update system state
      self._update_project_state(normalized_path, index_result['file_count'])
  
      # Business step 6: Get search capabilities info
      search_info = self._get_search_capabilities_info()
  
      return ProjectInitializationResult(
          project_path=normalized_path,
          file_count=index_result['file_count'],
          index_source=index_result['source'],
          search_capabilities=search_info,
          monitoring_status=monitoring_result,
          message=f"Project initialized: {normalized_path}"
      )
  
  def _cleanup_existing_project(self) -> None:
      """Business logic to cleanup existing project state."""
      with self._noop_operation():
          # Stop existing file monitoring
          self._watcher_tool.stop_existing_watcher()
  
          # Clear existing index cache
          self.helper.clear_index_cache()
  
          # Clear any existing index state
          pass
  
  def _initialize_shallow_index_manager(self, project_path: str) -> Dict[str, Any]:
      """
      Business logic to initialize the shallow index manager by default.
  
      Args:
          project_path: Project path
  
      Returns:
          Dictionary with initialization results
      """
      # Get user-configured exclude patterns
      excludes = self._get_exclude_patterns()
  
      # Set project path in shallow manager with exclusions
      if not self._shallow_manager.set_project_path(project_path, excludes):
          raise RuntimeError(f"Failed to set project path (shallow): {project_path}")
  
      # Update context
      self.helper.update_base_path(project_path)
  
      # Try to load existing shallow index or build new one
      if self._shallow_manager.load_index():
          source = "loaded_existing"
      else:
          if not self._shallow_manager.build_index():
              raise RuntimeError("Failed to build shallow index")
          source = "built_new"
  
      # Determine file count from shallow list
      try:
          files = self._shallow_manager.get_file_list()
          file_count = len(files)
      except Exception:  # noqa: BLE001 - safe fallback
          file_count = 0
  
      return {
          'file_count': file_count,
          'source': source,
          'total_symbols': 0,
          'languages': []
      }
  
  
  def _is_valid_existing_index(self, index_data: Dict[str, Any]) -> bool:
      """
      Business rule to determine if existing index is valid and usable.
  
      Args:
          index_data: Index data to validate
  
      Returns:
          True if index is valid and usable, False otherwise
      """
      if not index_data or not isinstance(index_data, dict):
          return False
  
      # Business rule: Must have new format metadata
      if 'index_metadata' not in index_data:
          return False
  
      # Business rule: Must be compatible version
      version = index_data.get('index_metadata', {}).get('version', '')
      return version >= '3.0'
  
  def _load_existing_index(self, index_data: Dict[str, Any]) -> Dict[str, Any]:
      """
      Business logic to load and use existing index.
  
      Args:
          index_data: Existing index data
  
      Returns:
          Dictionary with loading results
      """
  
  
      # Note: Legacy index loading is now handled by UnifiedIndexManager
      # This method is kept for backward compatibility but functionality moved
  
      # Extract file count from metadata
      file_count = index_data.get('project_metadata', {}).get('total_files', 0)
  
  
  
      return {
          'file_count': file_count,
          'source': 'loaded_existing'
      }
  
  
  def _setup_file_monitoring(self, project_path: str) -> str:
      """
      Business logic to setup file monitoring for the project.
  
      Args:
          project_path: Project path to monitor
  
      Returns:
          String describing monitoring setup result
      """
  
  
      try:
          # Create rebuild callback that uses the JSON index manager
          def rebuild_callback():
              logger.info("File watcher triggered rebuild callback")
              try:
                  logger.debug(f"Starting shallow index rebuild for: {project_path}")
                  # Business logic: File changed, rebuild using SHALLOW index manager
                  try:
                      if not self._shallow_manager.set_project_path(project_path):
                          logger.warning("Shallow manager set_project_path failed")
                          return False
                      if self._shallow_manager.build_index():
                          files = self._shallow_manager.get_file_list()
                          logger.info(f"File watcher shallow rebuild completed successfully - files {len(files)}")
                          return True
                      else:
                          logger.warning("File watcher shallow rebuild failed")
                          return False
                  except Exception as e:
                      import traceback
                      logger.error(f"File watcher shallow rebuild failed: {e}")
                      logger.error(f"Traceback: {traceback.format_exc()}")
                      return False
              except Exception as e:
                  import traceback
                  logger.error(f"File watcher rebuild failed: {e}")
                  logger.error(f"Traceback: {traceback.format_exc()}")
                  return False
  
          # Start monitoring using watcher tool
          success = self._watcher_tool.start_monitoring(project_path, rebuild_callback)
  
          if success:
              # Store watcher in context for later access
              self._watcher_tool.store_in_context()
              # No logging
              return "monitoring_active"
          else:
              self._watcher_tool.record_error("Failed to start file monitoring")
              return "monitoring_failed"
  
      except Exception as e:
          error_msg = f"File monitoring setup failed: {e}"
          self._watcher_tool.record_error(error_msg)
          return "monitoring_error"
  
  def _update_project_state(self, project_path: str, file_count: int) -> None:
      """Business logic to update system state after project initialization."""
  
  
      # Update context with file count
      self.helper.update_file_count(file_count)
  
      # No logging
  
  def _get_search_capabilities_info(self) -> str:
      """Business logic to get search capabilities information."""
      search_info = self._config_tool.get_search_tool_info()
  
      if search_info['available']:
          return f"Advanced search enabled ({search_info['name']})"
      else:
          return "Basic search available"
  
  def _format_initialization_result(self, result: ProjectInitializationResult) -> str:
      """
      Format the initialization result according to business requirements.
  
      Args:
          result: Initialization result data
  
      Returns:
          Formatted result string for MCP response
      """
      if result.index_source == 'unified_manager':
          message = (f"Project path set to: {result.project_path}. "
                    f"Initialized unified index with {result.file_count} files. "
                    f"{result.search_capabilities}.")
      elif result.index_source == 'failed':
          message = (f"Project path set to: {result.project_path}. "
                    f"Index initialization failed. Some features may be limited. "
                    f"{result.search_capabilities}.")
      else:
          message = (f"Project path set to: {result.project_path}. "
                    f"Indexed {result.file_count} files. "
                    f"{result.search_capabilities}.")
  
      if result.monitoring_status != "monitoring_active":
          message += " (File monitoring unavailable - use manual refresh)"
  
      return message

• src/code_index_mcp/indexing/shallow_index_manager.py:37-70 (helper)

  Core helper implementation in ShallowIndexManager that validates the project path, sets up the JSONIndexBuilder with excludes, configures temp directory and index path for shallow indexing.

  def set_project_path(self, project_path: str, additional_excludes: Optional[List[str]] = None) -> bool:
      """Configure project path for shallow indexing.
  
      Args:
          project_path: Path to the project directory to index
          additional_excludes: Optional list of additional directory/file
              patterns to exclude from indexing (e.g., ['vendor', 'custom_deps'])
  
      Returns:
          True if configuration succeeded, False otherwise
      """
      with self._lock:
          try:
              if not isinstance(project_path, str) or not project_path.strip():
                  logger.error("Invalid project path for shallow index")
                  return False
              project_path = project_path.strip()
              if not os.path.isdir(project_path):
                  logger.error(f"Project path does not exist: {project_path}")
                  return False
  
              self.project_path = project_path
              self.index_builder = JSONIndexBuilder(project_path, additional_excludes)
  
              project_hash = hashlib.md5(project_path.encode()).hexdigest()[:12]
              self.temp_dir = os.path.join(tempfile.gettempdir(), SETTINGS_DIR, project_hash)
              os.makedirs(self.temp_dir, exist_ok=True)
              self.index_path = os.path.join(self.temp_dir, INDEX_FILE_SHALLOW)
              if additional_excludes:
                  logger.info("Shallow index additional excludes: %s", additional_excludes)
              return True
          except Exception as e:  # noqa: BLE001 - centralized logging
              logger.error(f"Failed to set project path (shallow): {e}")
              return False

• src/code_index_mcp/server.py:351-353 (registration)

  CLI argument registration that allows setting project path on server startup, equivalent to the set_project_path tool.

  "--project-path",
  dest="project_path",
  help="Set the project path on startup (equivalent to calling set_project_path)."