jons-mcp-java

Instructions

Implementation Reference

• src/jons_mcp_java/tools/navigation.py:15-55 (handler)

  The main implementation of the 'definition' tool. This async function uses the @mcp.tool() decorator, sends an LSP 'textDocument/definition' request to the appropriate JDT.LS client, and formats the response locations.

  @mcp.tool()
  async def definition(
      file_path: str,
      line: int,
      character: int,
  ) -> dict:
      """
      Navigate to the definition of a symbol at the given position.
  
      Args:
          file_path: Absolute path to the Java file
          line: 0-indexed line number
          character: 0-indexed character position
  
      Returns:
          Dictionary with 'locations' array or 'status'/'message' if initializing
      """
      manager = get_manager()
      if manager is None:
          return {"status": "error", "message": "Server not initialized"}
  
      # Get client with status feedback
      client, status = await manager.get_client_for_file_with_status(Path(file_path))
  
      if client is None:
          return {"status": "initializing", "message": status}
  
      # Ensure file is open
      await client.ensure_file_open(file_path)
  
      # Make LSP request
      response = await client.request(
          LSP_TEXT_DOCUMENT_DEFINITION,
          {
              "textDocument": {"uri": path_to_uri(file_path)},
              "position": {"line": line, "character": character}
          }
      )
  
      return format_locations(response)

• src/jons_mcp_java/server.py:65-65 (registration)

  Import statement that loads the navigation module, triggering registration of the 'definition' tool via its @mcp.tool() decorator.

  from jons_mcp_java.tools import navigation, symbols, diagnostics, info  # noqa: E402, F401

• src/jons_mcp_java/constants.py:13-13 (helper)

  Constant defining the LSP method name used in the definition tool request.

  LSP_TEXT_DOCUMENT_DEFINITION = "textDocument/definition"

• src/jons_mcp_java/utils.py:38-61 (helper)

  Utility function used by the definition tool to normalize and format LSP location responses into a standard dictionary 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": []}

• src/jons_mcp_java/utils.py:8-25 (helper)

  Utility function used to convert file paths to LSP-compatible file:// URIs for requests.

  def path_to_uri(path: str | Path) -> str:
      """Convert a file path to a file:// URI."""
      if isinstance(path, str):
          path = Path(path)
  
      # Resolve to absolute path
      path = path.resolve()
  
      # Convert to URI format
      # On Unix, paths start with / so we get file:///
      path_str = str(path)
      if not path_str.startswith("/"):
          path_str = "/" + path_str
  
      # Quote special characters but preserve /
      encoded = quote(path_str, safe="/")
      return f"file://{encoded}"