references
Locate all references to Java symbols in codebases to track usage and dependencies across 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 LSP client to perform a textDocument/references request at the specified position, formats the results, and handles initialization states.@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)Explicit import of tools modules after FastMCP server creation, which triggers the @mcp.tool() decorators to register the 'references' tool (imported via navigation module).# Import tools to register them from jons_mcp_java.tools import navigation, symbols, diagnostics, info # noqa: E402, F401
- src/jons_mcp_java/constants.py:15-15 (helper)LSP method constant for textDocument/references, used directly in the references handler.LSP_TEXT_DOCUMENT_REFERENCES = "textDocument/references"
- src/jons_mcp_java/utils.py:38-60 (helper)Utility function to normalize LSP location responses (single or array of Location/LocationLink) into a standard {'locations': [...]} format, used by the references handler.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": []}