GDScript Code Analyzer

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)