feat: enhance file_summary functionality with comprehensive index-based analysis

This commit significantly improves the file_summary MCP tool by refactoring it to provide comprehensive analysis data directly from the project index, eliminating real-time file analysis overhead.

**Core File Summary Improvements:**
- Refactor FileService.analyze_file() to rely exclusively on indexed data for faster, consistent results
- Add comprehensive index entry validation with _validate_index_entry() method
- Return complete relationship data including function calls, class inheritance, and import dependencies
- Improve error handling with detailed validation of index data structure integrity
- Remove dependency on AnalyzerFactory for better separation of concerns and performance

**Enhanced Data Quality and Validation:**
- Add robust validation for functions, classes, and imports data structures in index entries
- Support both legacy string format and enhanced object format for backward compatibility
- Validate function metadata including parameters, decorators, async status, and call relationships
- Validate class inheritance chains and instantiation relationships
- Ensure import statements include complete module and type information

**Path Handling Improvements:**
- Enhance normalize_file_path() function to handle edge cases and provide consistent path normalization
- Update scanner.py and search/base.py to use centralized path normalization
- Improve cross-platform path handling with os.path.normpath() integration
- Fix path separator consistency throughout the indexing and search systems

**Fallback Strategy Enhancements:**
- Implement intelligent project-aware fallback directories (project → home → system temp)
- Replace hardcoded current directory fallbacks with context-aware alternatives
- Improve error handling for directory access issues in restricted environments
- Enhanced ProjectSettings robustness for various deployment scenarios

**Response Format Improvements:**
- Enhanced ResponseFormatter to handle complex index data structures
- Better error reporting and validation feedback for malformed index entries
- Improved utilities for file operation validation and path handling

The file_summary tool now provides rich, structured analysis data including complete function signatures, class relationships, import dependencies, and language-specific metadata, all sourced from the optimized project index for maximum performance and consistency.

Author: johnhuang316

src/code_index_mcp/indexing/qualified_names.py

@@ -90,15 +90,24 @@ def validate_qualified_name(qualified_name: str) -> bool:
 
 def normalize_file_path(file_path: str) -> str:
     """
-    Normalize file path for consistent qualified name generation.
+    Normalize file path for consistent use throughout the codebase.
+    
+    This function provides a unified way to normalize file paths by:
+    1. Converting all path separators to forward slashes
+    2. Normalizing the path structure (removing redundant separators, etc.)
     
     Args:
         file_path: File path to normalize
     
     Returns:
         Normalized file path with forward slashes
     """
-    return file_path.replace(os.sep, '/')
+    if not file_path:
+        return file_path
+    
+    # First normalize the path structure, then convert separators
+    normalized = os.path.normpath(file_path)
+    return normalized.replace(os.sep, '/')
 
 
 def get_file_path_from_qualified_name(qualified_name: str) -> str:

src/code_index_mcp/indexing/scanner.py

@@ -11,6 +11,7 @@
 from datetime import datetime
 from typing import Dict, List, Any
 from .models import FileInfo, ProjectScanResult, SpecialFiles
+from .qualified_names import normalize_file_path
 from code_index_mcp.constants import SUPPORTED_EXTENSIONS
 
 
@@ -115,7 +116,7 @@ def _discover_files(self) -> List[str]:
                     file_path = os.path.join(root, filename)
                     # Convert to relative path from base_path
                     rel_path = os.path.relpath(file_path, self.base_path)
-                    files.append(rel_path.replace('\\', '/'))  # Normalize path separators
+                    files.append(normalize_file_path(rel_path))  # Normalize path separators
 
         return files
 

src/code_index_mcp/project_settings.py

@@ -74,15 +74,25 @@ def __init__(self, base_path, skip_load=False):
             # Check if the system temporary directory exists and is writable
             if not os.path.exists(system_temp):
                 print(f"Warning: System temporary directory does not exist: {system_temp}")
-                # Try using current directory as fallback
-                system_temp = os.getcwd()
-                print(f"Using current directory as fallback: {system_temp}")
+                # Try using project directory as fallback if available
+                if base_path and os.path.exists(base_path):
+                    system_temp = base_path
+                    print(f"Using project directory as fallback: {system_temp}")
+                else:
+                    # Use user's home directory as last resort
+                    system_temp = os.path.expanduser("~")
+                    print(f"Using home directory as fallback: {system_temp}")
 
             if not os.access(system_temp, os.W_OK):
                 print(f"Warning: No write access to system temporary directory: {system_temp}")
-                # Try using current directory as fallback
-                system_temp = os.getcwd()
-                print(f"Using current directory as fallback: {system_temp}")
+                # Try using project directory as fallback if available
+                if base_path and os.path.exists(base_path) and os.access(base_path, os.W_OK):
+                    system_temp = base_path
+                    print(f"Using project directory as fallback: {system_temp}")
+                else:
+                    # Use user's home directory as last resort
+                    system_temp = os.path.expanduser("~")
+                    print(f"Using home directory as fallback: {system_temp}")
 
             # Create code_indexer directory
             temp_base_dir = os.path.join(system_temp, SETTINGS_DIR)
@@ -96,9 +106,14 @@ def __init__(self, base_path, skip_load=False):
                 print(f"Code indexer directory already exists: {temp_base_dir}")
         except Exception as e:
             print(f"Error setting up temporary directory: {e}")
-            # If unable to create temporary directory, use .code_indexer in current directory
-            temp_base_dir = os.path.join(os.getcwd(), ".code_indexer")
-            print(f"Using fallback directory: {temp_base_dir}")
+            # If unable to create temporary directory, use .code_indexer in project directory if available
+            if base_path and os.path.exists(base_path):
+                temp_base_dir = os.path.join(base_path, ".code_indexer")
+                print(f"Using project fallback directory: {temp_base_dir}")
+            else:
+                # Use home directory as last resort
+                temp_base_dir = os.path.join(os.path.expanduser("~"), ".code_indexer")
+                print(f"Using home fallback directory: {temp_base_dir}")
             if not os.path.exists(temp_base_dir):
                 os.makedirs(temp_base_dir, exist_ok=True)
 
@@ -117,9 +132,13 @@ def __init__(self, base_path, skip_load=False):
             self.ensure_settings_dir()
         except Exception as e:
             print(f"Error setting up project settings: {e}")
-            # If error occurs, use .code_indexer in current directory as fallback
-            fallback_dir = os.path.join(os.getcwd(), ".code_indexer",
-                                      "default" if not base_path else hashlib.md5(base_path.encode()).hexdigest())
+            # If error occurs, use .code_indexer in project or home directory as fallback
+            if base_path and os.path.exists(base_path):
+                fallback_dir = os.path.join(base_path, ".code_indexer",
+                                          hashlib.md5(base_path.encode()).hexdigest())
+            else:
+                fallback_dir = os.path.join(os.path.expanduser("~"), ".code_indexer",
+                                          "default" if not base_path else hashlib.md5(base_path.encode()).hexdigest())
             print(f"Using fallback directory: {fallback_dir}")
             self.settings_path = fallback_dir
             if not os.path.exists(fallback_dir):
@@ -141,18 +160,26 @@ def ensure_settings_dir(self):
             # Check if directory is writable
             if not os.access(self.settings_path, os.W_OK):
                 print(f"Warning: No write access to project settings directory: {self.settings_path}")
-                # If directory is not writable, use .code_indexer in current directory as fallback
-                fallback_dir = os.path.join(os.getcwd(), ".code_indexer",
-                                          os.path.basename(self.settings_path))
+                # If directory is not writable, use .code_indexer in project or home directory as fallback
+                if self.base_path and os.path.exists(self.base_path) and os.access(self.base_path, os.W_OK):
+                    fallback_dir = os.path.join(self.base_path, ".code_indexer",
+                                              os.path.basename(self.settings_path))
+                else:
+                    fallback_dir = os.path.join(os.path.expanduser("~"), ".code_indexer",
+                                              os.path.basename(self.settings_path))
                 print(f"Using fallback directory: {fallback_dir}")
                 self.settings_path = fallback_dir
                 if not os.path.exists(fallback_dir):
                     os.makedirs(fallback_dir, exist_ok=True)
         except Exception as e:
             print(f"Error ensuring settings directory: {e}")
-            # If unable to create settings directory, use .code_indexer in current directory
-            fallback_dir = os.path.join(os.getcwd(), ".code_indexer",
-                                      "default" if not self.base_path else hashlib.md5(self.base_path.encode()).hexdigest())
+            # If unable to create settings directory, use .code_indexer in project or home directory
+            if self.base_path and os.path.exists(self.base_path):
+                fallback_dir = os.path.join(self.base_path, ".code_indexer",
+                                          hashlib.md5(self.base_path.encode()).hexdigest())
+            else:
+                fallback_dir = os.path.join(os.path.expanduser("~"), ".code_indexer",
+                                          "default" if not self.base_path else hashlib.md5(self.base_path.encode()).hexdigest())
             print(f"Using fallback directory: {fallback_dir}")
             self.settings_path = fallback_dir
             if not os.path.exists(fallback_dir):
@@ -167,8 +194,11 @@ def get_config_path(self):
             return path
         except Exception as e:
             print(f"Error getting config path: {e}")
-            # If error occurs, use file in current directory as fallback
-            return os.path.join(os.getcwd(), CONFIG_FILE)
+            # If error occurs, use file in project or home directory as fallback
+            if self.base_path and os.path.exists(self.base_path):
+                return os.path.join(self.base_path, CONFIG_FILE)
+            else:
+                return os.path.join(os.path.expanduser("~"), CONFIG_FILE)
 
     def get_index_path(self):
         """Get the path to the index file"""
@@ -179,8 +209,11 @@ def get_index_path(self):
             return path
         except Exception as e:
             print(f"Error getting index path: {e}")
-            # If error occurs, use file in current directory as fallback
-            return os.path.join(os.getcwd(), INDEX_FILE)
+            # If error occurs, use file in project or home directory as fallback
+            if self.base_path and os.path.exists(self.base_path):
+                return os.path.join(self.base_path, INDEX_FILE)
+            else:
+                return os.path.join(os.path.expanduser("~"), INDEX_FILE)
 
     # get_cache_path method removed - no longer needed with new indexing system
 
@@ -259,8 +292,11 @@ def save_index(self, index_data):
             # Check if directory is writable
             if not os.access(dir_path, os.W_OK):
                 print(f"Warning: Directory is not writable: {dir_path}")
-                # Use current directory as fallback
-                index_path = os.path.join(os.getcwd(), INDEX_FILE)
+                # Use project or home directory as fallback
+                if self.base_path and os.path.exists(self.base_path):
+                    index_path = os.path.join(self.base_path, INDEX_FILE)
+                else:
+                    index_path = os.path.join(os.path.expanduser("~"), INDEX_FILE)
                 print(f"Using fallback path: {index_path}")
 
             # Convert to JSON string if it's a CodeIndex object
@@ -278,9 +314,12 @@ def save_index(self, index_data):
             print(f"Index saved successfully to: {index_path}")
         except Exception as e:
             print(f"Error saving index: {e}")
-            # Try saving to current directory
+            # Try saving to project or home directory
             try:
-                fallback_path = os.path.join(os.getcwd(), INDEX_FILE)
+                if self.base_path and os.path.exists(self.base_path):
+                    fallback_path = os.path.join(self.base_path, INDEX_FILE)
+                else:
+                    fallback_path = os.path.join(os.path.expanduser("~"), INDEX_FILE)
                 print(f"Trying fallback path: {fallback_path}")
 
                 # Convert to JSON string if it's a CodeIndex object
@@ -324,8 +363,11 @@ def load_index(self):
                     print(f"Unexpected error loading index: {e}")
                     return None
             else:
-                # Try loading from current directory
-                fallback_path = os.path.join(os.getcwd(), INDEX_FILE)
+                # Try loading from project or home directory
+                if self.base_path and os.path.exists(self.base_path):
+                    fallback_path = os.path.join(self.base_path, INDEX_FILE)
+                else:
+                    fallback_path = os.path.join(os.path.expanduser("~"), INDEX_FILE)
                 if os.path.exists(fallback_path):
                     print(f"Trying fallback path: {fallback_path}")
                     try:
@@ -376,8 +418,12 @@ def detect_index_version(self):
                 return 'legacy'
 
             # Check fallback locations
-            fallback_json = os.path.join(os.getcwd(), INDEX_FILE)
-            fallback_pickle = os.path.join(os.getcwd(), "file_index.pickle")
+            if self.base_path and os.path.exists(self.base_path):
+                fallback_json = os.path.join(self.base_path, INDEX_FILE)
+                fallback_pickle = os.path.join(self.base_path, "file_index.pickle")
+            else:
+                fallback_json = os.path.join(os.path.expanduser("~"), INDEX_FILE)
+                fallback_pickle = os.path.join(os.path.expanduser("~"), "file_index.pickle")
 
             if os.path.exists(fallback_json):
                 try:
@@ -427,11 +473,21 @@ def migrate_legacy_index(self):
                 # Clean up legacy files
                 legacy_files = [
                     os.path.join(self.settings_path, "file_index.pickle"),
-                    os.path.join(self.settings_path, "content_cache.pickle"),
-                    os.path.join(os.getcwd(), "file_index.pickle"),
-                    os.path.join(os.getcwd(), "content_cache.pickle")
+                    os.path.join(self.settings_path, "content_cache.pickle")
                 ]
 
+                # Add fallback locations
+                if self.base_path and os.path.exists(self.base_path):
+                    legacy_files.extend([
+                        os.path.join(self.base_path, "file_index.pickle"),
+                        os.path.join(self.base_path, "content_cache.pickle")
+                    ])
+                else:
+                    legacy_files.extend([
+                        os.path.join(os.path.expanduser("~"), "file_index.pickle"),
+                        os.path.join(os.path.expanduser("~"), "content_cache.pickle")
+                    ])
+                
                 for legacy_file in legacy_files:
                     if os.path.exists(legacy_file):
                         try:
@@ -493,7 +549,7 @@ def get_stats(self):
                 'writable': os.access(self.settings_path, os.W_OK) if os.path.exists(self.settings_path) else False,
                 'files': {},
                 'temp_dir': tempfile.gettempdir(),
-                'current_dir': os.getcwd()
+                'base_path': self.base_path
             }
 
             if stats['exists'] and stats['is_directory']:
@@ -524,7 +580,10 @@ def get_stats(self):
                     stats['list_error'] = str(e)
 
             # Check fallback path
-            fallback_dir = os.path.join(os.getcwd(), ".code_indexer")
+            if self.base_path and os.path.exists(self.base_path):
+                fallback_dir = os.path.join(self.base_path, ".code_indexer")
+            else:
+                fallback_dir = os.path.join(os.path.expanduser("~"), ".code_indexer")
             stats['fallback_path'] = fallback_dir
             stats['fallback_exists'] = os.path.exists(fallback_dir)
             stats['fallback_is_directory'] = os.path.isdir(fallback_dir) if os.path.exists(fallback_dir) else False
@@ -536,7 +595,7 @@ def get_stats(self):
                 'error': str(e),
                 'settings_path': self.settings_path,
                 'temp_dir': tempfile.gettempdir(),
-                'current_dir': os.getcwd()
+                'base_path': self.base_path
             }
 
     def get_search_tools_config(self):

src/code_index_mcp/search/base.py

@@ -12,6 +12,8 @@
 from abc import ABC, abstractmethod
 from typing import Dict, List, Optional, Tuple, Any
 
+from ..indexing.qualified_names import normalize_file_path
+
 def parse_search_output(output: str, base_path: str) -> Dict[str, List[Tuple[int, str]]]:
     """
     Parse the output of command-line search tools (grep, ag, rg).
@@ -49,7 +51,7 @@ def parse_search_output(output: str, base_path: str) -> Dict[str, List[Tuple[int
             relative_path = os.path.relpath(file_path_abs, normalized_base_path)
 
             # Normalize path separators for consistency
-            relative_path = relative_path.replace('\\', '/')
+            relative_path = normalize_file_path(relative_path)
 
             if relative_path not in results:
                 results[relative_path] = []