references
Locate all references to Java symbols in your codebase by specifying file, line, and character position. This tool helps developers understand symbol usage and track dependencies across Java projects.
Instructions
Find all references to the symbol at the given position.
Args: file_path: Absolute path to the Java file line: 0-indexed line number character: 0-indexed character position include_declaration: Whether to include the declaration in results
Returns: Dictionary with 'locations' array or 'status'/'message' if initializing
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| line | Yes | ||
| character | Yes | ||
| include_declaration | No |
Implementation Reference
- The core handler function for the 'references' MCP tool. It uses the JDT.LS client to send an LSP 'textDocument/references' request and formats the locations.@mcp.tool() async def references( file_path: str, line: int, character: int, include_declaration: bool = True, ) -> dict: """ Find all references to the symbol at the given position. Args: file_path: Absolute path to the Java file line: 0-indexed line number character: 0-indexed character position include_declaration: Whether to include the declaration in results Returns: Dictionary with 'locations' array or 'status'/'message' if initializing """ manager = get_manager() if manager is None: return {"status": "error", "message": "Server not initialized"} client, status = await manager.get_client_for_file_with_status(Path(file_path)) if client is None: return {"status": "initializing", "message": status} await client.ensure_file_open(file_path) response = await client.request( LSP_TEXT_DOCUMENT_REFERENCES, { "textDocument": {"uri": path_to_uri(file_path)}, "position": {"line": line, "character": character}, "context": {"includeDeclaration": include_declaration} } ) return format_locations(response)
- src/jons_mcp_java/server.py:64-65 (registration)Imports the tools modules, which triggers registration of the @mcp.tool()-decorated 'references' function via FastMCP.# Import tools to register them from jons_mcp_java.tools import navigation, symbols, diagnostics, info # noqa: E402, F401
- src/jons_mcp_java/utils.py:38-92 (helper)Helper function used by the 'references' handler (and others) to normalize LSP location responses into a standard {'locations': [...]} format.def format_locations(response: dict | list | None) -> dict: """ Normalize LSP Location response to a consistent format. LSP methods like definition can return: - null/None - Single Location object - Array of Location objects - Array of LocationLink objects This normalizes to: {"locations": [...]} """ if response is None: return {"locations": []} if isinstance(response, dict): # Single Location or LocationLink return {"locations": [_normalize_location(response)]} if isinstance(response, list): return {"locations": [_normalize_location(loc) for loc in response]} return {"locations": []} def _normalize_location(loc: dict) -> dict: """Normalize a Location or LocationLink to a common format.""" # LocationLink has targetUri/targetRange, Location has uri/range if "targetUri" in loc: # LocationLink uri = loc["targetUri"] range_obj = loc.get("targetSelectionRange") or loc.get("targetRange", {}) else: # Location uri = loc.get("uri", "") range_obj = loc.get("range", {}) # Convert URI to path for easier consumption try: path = str(uri_to_path(uri)) except ValueError: path = uri start = range_obj.get("start", {}) end = range_obj.get("end", {}) return { "path": path, "uri": uri, "line": start.get("line", 0), "character": start.get("character", 0), "end_line": end.get("line", 0), "end_character": end.get("character", 0), }
- src/jons_mcp_java/constants.py:15-15 (helper)LSP method constant used in the 'references' tool request.LSP_TEXT_DOCUMENT_REFERENCES = "textDocument/references"