find_references

Instructions

Implementation Reference

• src/mcp_gdscript/tools.py:453-518 (handler)

  Main handler function that implements the core logic of the 'find_references' tool: determines search scope (file or project), parses relevant files, invokes parser.find_references on each, aggregates results, and returns formatted JSON output.

  def _find_references(self, symbol_name: str, file_path: Optional[str] = None) -> CallToolResult:
      """Find references to a symbol.
  
      Args:
          symbol_name: Name of the symbol to find
          file_path: Optional specific file to search in
  
      Returns:
          CallToolResult with references
      """
      try:
          files_to_search: list[Path] = []
  
          if file_path:
              # Search in specific file
              path = Path(file_path)
              if not path.exists():
                  return CallToolResult(
                      content=[TextContent(type="text", text=f"File not found: {file_path}")],
                      isError=True,
                  )
              files_to_search = [path]
          elif self.project_root:
              # Search in project
              files_to_search = self._gdscript_files
          else:
              return CallToolResult(
                  content=[TextContent(type="text", text="No project root set and no specific file provided")],
                  isError=True,
              )
  
          all_references = []
  
          for file in files_to_search:
              try:
                  code = file.read_text(encoding="utf-8")
                  tree = self.parser.parse(code)
                  references = self.parser.find_references(tree, symbol_name)
  
                  for ref in references:
                      all_references.append({
                          "file": str(file.relative_to(self.project_root) if self.project_root else file),
                          "line": ref["line"],
                          "column": ref["column"],
                          "end_line": ref["end_line"],
                          "end_column": ref["end_column"],
                      })
              except Exception as e:
                  # Skip files that can't be parsed
                  continue
  
          result = {
              "symbol": symbol_name,
              "total_references": len(all_references),
              "references": all_references,
          }
  
          return CallToolResult(
              content=[TextContent(type="text", text=json.dumps(result, indent=2))],
              isError=False,
          )
      except Exception as e:
          return CallToolResult(
              content=[TextContent(type="text", text=f"Error finding references: {str(e)}")],
              isError=True,
          )

• src/mcp_gdscript/tools.py:128-140 (schema)

  JSON schema defining the input parameters for the 'find_references' tool: required 'symbol_name' string and optional 'file_path' string.

  inputSchema={
      "type": "object",
      "properties": {
          "symbol_name": {
              "type": "string",
              "description": "Name of the symbol to find references for",
          },
          "file_path": {
              "type": "string",
              "description": "Optional: Limit search to a specific file. If not provided, searches entire project.",
          },
      },
      "required": ["symbol_name"],

• src/mcp_gdscript/tools.py:125-142 (registration)

  MCP Tool object registration in get_tools(), defining name, description, and input schema for 'find_references'.

  Tool(
      name="find_references",
      description="Find all references to a symbol across the project or in a specific file.",
      inputSchema={
          "type": "object",
          "properties": {
              "symbol_name": {
                  "type": "string",
                  "description": "Name of the symbol to find references for",
              },
              "file_path": {
                  "type": "string",
                  "description": "Optional: Limit search to a specific file. If not provided, searches entire project.",
              },
          },
          "required": ["symbol_name"],
      },
  ),

• src/mcp_gdscript/parser.py:319-365 (helper)

  Helper method in GDScriptParser invoked by the tool handler. Recursively traverses the Tree-sitter AST to locate all 'identifier' or 'name' nodes matching the symbol_name, collecting their line/column positions.

  def find_references(self, tree: Tree, symbol_name: str) -> list[dict[str, Any]]:
      """Find all references to a symbol in the code.
  
      Args:
          tree: The parsed syntax tree
          symbol_name: Name of the symbol to find references for
  
      Returns:
          List of reference locations with context
      """
      references = []
      self._find_references_recursive(tree.root_node, symbol_name, references)
      return references
  
  def _find_references_recursive(
      self, node: Node, symbol_name: str, references: list[dict[str, Any]], depth: int = 0
  ) -> None:
      """Recursively find symbol references in tree nodes.
  
      Args:
          node: Current tree node
          symbol_name: Name of the symbol to find
          references: List to populate with references
          depth: Current recursion depth
      """
      if depth > 20:  # Prevent infinite recursion
          return
  
      node_type = node.type
  
      # Check if this is an identifier or name node matching the symbol
      if node_type in ("identifier", "name"):
          text = node.text.decode("utf-8") if isinstance(node.text, bytes) else str(node.text)
          if text == symbol_name:
              references.append(
                  {
                      "line": node.start_point[0] + 1,
                      "column": node.start_point[1],
                      "end_line": node.end_point[0] + 1,
                      "end_column": node.end_point[1],
                  }
              )
  
      # Recursively process child nodes
      for child in node.children:
          self._find_references_recursive(child, symbol_name, references, depth + 1)