Instructions

Implementation Reference

• src/xray/mcp_server.py:69-147 (handler)

  MCP tool handler for 'explore_repo'. Registers the tool with FastMCP, handles parameter conversion for LLM compatibility, retrieves or creates XRayIndexer instance, and calls its explore_repo method to generate the repository tree.
  @mcp.tool def explore_repo( root_path: str, max_depth: Optional[Union[int, str]] = None, include_symbols: Union[bool, str] = False, focus_dirs: Optional[List[str]] = None, max_symbols_per_file: Union[int, str] = 5 ) -> str: """ 🗺️ STEP 1: Map the codebase structure - start simple, then zoom in! PROGRESSIVE DISCOVERY WORKFLOW: 1. First call: explore_repo("/path/to/project") - See directory structure only 2. Zoom in: explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True) 3. Go deeper: explore_repo("/path/to/project", max_depth=3, include_symbols=True) INPUTS: - root_path: The ABSOLUTE path to the project (e.g., "/Users/john/myproject") NOT relative paths like "./myproject" or "~/myproject" - max_depth: How deep to traverse directories (None = unlimited, accepts int or string) - include_symbols: Show function/class signatures with docs (False = dirs only, accepts bool or string) - focus_dirs: List of top-level directories to focus on (e.g., ["src", "lib"]) - max_symbols_per_file: Max symbols to show per file when include_symbols=True (accepts int or string) EXAMPLE 1 - Initial exploration (directory only): explore_repo("/Users/john/project") # Returns: # /Users/john/project/ # ├── src/ # ├── tests/ # ├── docs/ # └── README.md EXAMPLE 2 - Zoom into src/ with symbols: explore_repo("/Users/john/project", focus_dirs=["src"], include_symbols=True) # Returns: # /Users/john/project/ # └── src/ # ├── auth.py # │ ├── class AuthService: # Handles user authentication # │ ├── def authenticate(username, password): # Validates credentials # │ └── def logout(session_id): # Ends user session # └── models.py # ├── class User(BaseModel): # User account model # └── ... and 3 more EXAMPLE 3 - Limited depth exploration: explore_repo("/Users/john/project", max_depth=1, include_symbols=True) # Shows only top-level dirs and files with their symbols 💡 PRO TIP: Start with include_symbols=False to see structure, then set it to True for areas you want to examine in detail. This prevents information overload! ⚡ PERFORMANCE: Symbol extraction is cached per git commit - subsequent calls are instant! WHAT TO DO NEXT: - If you found interesting directories, zoom in with focus_dirs - If you see relevant files, use find_symbol() to locate specific functions """ try: # Convert string inputs to proper types (for LLMs that pass strings) if max_depth is not None and isinstance(max_depth, str): max_depth = int(max_depth) if isinstance(max_symbols_per_file, str): max_symbols_per_file = int(max_symbols_per_file) if isinstance(include_symbols, str): include_symbols = include_symbols.lower() in ('true', '1', 'yes') indexer = get_indexer(root_path) tree = indexer.explore_repo( max_depth=max_depth, include_symbols=include_symbols, focus_dirs=focus_dirs, max_symbols_per_file=max_symbols_per_file ) return tree except Exception as e: return f"Error exploring repository: {str(e)}"
• src/xray/mcp_server.py:69-69 (registration)

  The @mcp.tool decorator registers the explore_repo function as an MCP tool with FastMCP.
  @mcp.tool
• src/xray/mcp_server.py:70-77 (schema)

  Function signature and docstring define the input schema (parameters with types/defaults) and output (str tree representation) for the MCP tool, used by FastMCP for validation.
  def explore_repo( root_path: str, max_depth: Optional[Union[int, str]] = None, include_symbols: Union[bool, str] = False, focus_dirs: Optional[List[str]] = None, max_symbols_per_file: Union[int, str] = 5 ) -> str: """
• src/xray/core/indexer.py:102-144 (helper)

  Core helper method in XRayIndexer class that implements the repository exploration logic: parses gitignore, builds recursive tree with optional symbols using _build_tree_recursive_enhanced, handles caching.
  def explore_repo( self, max_depth: Optional[int] = None, include_symbols: bool = False, focus_dirs: Optional[List[str]] = None, max_symbols_per_file: int = 5 ) -> str: """ Build a visual file tree with optional symbol skeletons. Args: max_depth: Limit directory traversal depth include_symbols: Include symbol skeletons in output focus_dirs: Only include these top-level directories max_symbols_per_file: Max symbols to show per file Returns: Formatted tree string """ # Get gitignore patterns if available gitignore_patterns = self._parse_gitignore() # Build the tree tree_lines = [] self._build_tree_recursive_enhanced( self.root_path, tree_lines, "", gitignore_patterns, current_depth=0, max_depth=max_depth, include_symbols=include_symbols, focus_dirs=focus_dirs, max_symbols_per_file=max_symbols_per_file, is_last=True ) # Save cache after building tree if include_symbols: self._save_cache() return "\n".join(tree_lines)