jons-mcp-java

Instructions

Implementation Reference

• src/jons_mcp_java/tools/navigation.py:138-174 (handler)

  The core handler function for the 'type_definition' tool. It uses LSP 'textDocument/typeDefinition' request to find type definitions at a given position in a Java file, formats the locations, and handles initialization status.

  @mcp.tool()
  async def type_definition(
      file_path: str,
      line: int,
      character: int,
  ) -> dict:
      """
      Navigate to the type 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"}
  
      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_TYPE_DEFINITION,
          {
              "textDocument": {"uri": path_to_uri(file_path)},
              "position": {"line": line, "character": character}
          }
      )
  
      return format_locations(response)

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

  Import statement that loads the navigation module, thereby registering the @mcp.tool()-decorated 'type_definition' function with the FastMCP server.

  # 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-60 (helper)

  Helper function used by the type_definition handler (and similar tools) 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": []}

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

  LSP method constant used in the type_definition tool request.

  LSP_TEXT_DOCUMENT_TYPE_DEFINITION = "textDocument/typeDefinition"

• src/jons_mcp_java/tools/__init__.py:17-17 (registration)

  Lists 'type_definition' in __all__ for easy import of tools package.

  "type_definition",