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)