XRAY MCP

Instructions

Implementation Reference

• src/xray/mcp_server.py:149-198 (handler)

  MCP tool handler for 'find_symbol'. Retrieves the XRayIndexer for the given root_path and delegates to its find_symbol method, handling errors by returning an error dictionary.

  @mcp.tool
  def find_symbol(root_path: str, query: str) -> List[Dict[str, Any]]:
      """
      🔍 STEP 2: Find specific functions, classes, or methods in the codebase.
      
      USE THIS AFTER explore_repo() when you need to locate a specific piece of code.
      Uses fuzzy matching - you don't need the exact name!
      
      INPUTS:
      - root_path: Same ABSOLUTE path used in explore_repo
      - query: What you're looking for (fuzzy search works!)
               Examples: "auth", "user service", "validate", "parseJSON"
      
      EXAMPLE INPUTS:
      find_symbol("/Users/john/awesome-project", "authenticate")
      find_symbol("/Users/john/awesome-project", "user model")  # Fuzzy matches "UserModel"
      
      EXAMPLE OUTPUT:
      [
          {
              "name": "authenticate_user",
              "type": "function",
              "path": "/Users/john/awesome-project/src/auth.py",
              "start_line": 45,
              "end_line": 67
          },
          {
              "name": "AuthService",
              "type": "class", 
              "path": "/Users/john/awesome-project/src/services.py",
              "start_line": 12,
              "end_line": 89
          }
      ]
      
      RETURNS:
      List of symbol objects (dictionaries). Save these objects - you'll pass them to what_breaks()!
      Empty list if no matches found.
      
      WHAT TO DO NEXT:
      Pick a symbol from the results and pass THE ENTIRE SYMBOL OBJECT to what_breaks() 
      to see where it's used in the codebase.
      """
      try:
          indexer = get_indexer(root_path)
          results = indexer.find_symbol(query)
          return results
      except Exception as e:
          return [{"error": f"Error finding symbol: {str(e)}"}]

• src/xray/core/indexer.py:461-562 (helper)

  Core helper function implementing the symbol search logic. Uses multiple ast-grep patterns for different languages to find potential symbols, extracts details, deduplicates, applies fuzzy matching with thefuzz library, and returns the top matching symbols with their locations.

  def find_symbol(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
      """
      Find symbols matching the query using fuzzy search.
      Uses ast-grep to find all symbols, then fuzzy matches against the query.
      
      Returns a list of the top matching "Exact Symbol" objects.
      """
      all_symbols = []
      
      # Define patterns for different symbol types
      patterns = [
          # Python functions and classes
          ("def $NAME($$$):", "function"),
          ("class $NAME($$$):", "class"),
          ("async def $NAME($$$):", "function"),
          
          # JavaScript/TypeScript functions and classes
          ("function $NAME($$$)", "function"),
          ("const $NAME = ($$$) =>", "function"),
          ("let $NAME = ($$$) =>", "function"),
          ("var $NAME = ($$$) =>", "function"),
          ("class $NAME", "class"),
          ("interface $NAME", "interface"),
          ("type $NAME =", "type"),
          
          # Go functions and types
          ("func $NAME($$$)", "function"),
          ("func ($$$) $NAME($$$)", "method"),
          ("type $NAME struct", "struct"),
          ("type $NAME interface", "interface"),
      ]
      
      # Run ast-grep for each pattern
      for pattern, symbol_type in patterns:
          cmd = [
              "ast-grep",
              "--pattern", pattern,
              "--json",
              str(self.root_path)
          ]
          
          result = subprocess.run(cmd, capture_output=True, text=True)
          
          if result.returncode == 0:
              try:
                  matches = json.loads(result.stdout)
                  for match in matches:
                      # Extract details from match
                      text = match.get("text", "")
                      file_path = match.get("file", "")
                      start = match.get("range", {}).get("start", {})
                      end = match.get("range", {}).get("end", {})
                      
                      # Extract the name from metavariables
                      metavars = match.get("metaVariables", {})
                      name = None
                      
                      # Try to get NAME from metavariables
                      if "NAME" in metavars:
                          name = metavars["NAME"]["text"]
                      else:
                          # Fallback to regex extraction
                          name = self._extract_symbol_name(text)
                      
                      if name:
                          symbol = {
                              "name": name,
                              "type": symbol_type,
                              "path": file_path,
                              "start_line": start.get("line", 1),
                              "end_line": end.get("line", start.get("line", 1))
                          }
                          all_symbols.append(symbol)
              except json.JSONDecodeError:
                  continue
      
      # Deduplicate symbols (same name and location)
      seen = set()
      unique_symbols = []
      for symbol in all_symbols:
          key = (symbol["name"], symbol["path"], symbol["start_line"])
          if key not in seen:
              seen.add(key)
              unique_symbols.append(symbol)
      
      # Now perform fuzzy matching against the query
      scored_symbols = []
      for symbol in unique_symbols:
          # Calculate similarity score
          score = fuzz.partial_ratio(query.lower(), symbol["name"].lower())
          
          # Boost score for exact substring matches
          if query.lower() in symbol["name"].lower():
              score = max(score, 80)
          
          scored_symbols.append((score, symbol))
      
      # Sort by score and take top results
      scored_symbols.sort(key=lambda x: x[0], reverse=True)
      top_symbols = [s[1] for s in scored_symbols[:limit]]
      
      return top_symbols