jons-mcp-java

Instructions

Implementation Reference

• src/jons_mcp_java/tools/navigation.py:57-96 (handler)

  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"