jons-mcp-java

Instructions

Implementation Reference

• src/jons_mcp_java/tools/symbols.py:52-102 (handler)

  The main handler function for the 'workspace_symbols' MCP tool. Decorated with @mcp.tool(), it sends an LSP 'workspace/symbol' request to search for symbols matching the query, formats the results, and handles initialization states.

  @mcp.tool()
  async def workspace_symbols(
      query: str,
      file_path: str | None = None,
  ) -> dict:
      """
      Search for symbols in the workspace.
  
      Args:
          query: Search query string (symbol name or pattern)
          file_path: Optional file path to determine which project to search
  
      Returns:
          Dictionary with 'symbols' array or 'status'/'message' if initializing
      """
      manager = get_manager()
      if manager is None:
          return {"status": "error", "message": "Server not initialized"}
  
      # If file_path provided, use that project; otherwise use first available
      if file_path:
          client, status = await manager.get_client_for_file_with_status(Path(file_path))
      else:
          # Get any initialized client
          for project in manager._projects.values():
              if project.client and project.client.is_initialized:
                  client = project.client
                  status = "ready"
                  break
          else:
              return {
                  "status": "error",
                  "message": "No initialized projects. Provide a file_path to start initialization."
              }
  
      if client is None:
          return {"status": "initializing", "message": status}
  
      response = await client.request(
          LSP_WORKSPACE_SYMBOL,
          {
              "query": query,
          }
      )
  
      if response is None:
          return {"symbols": []}
  
      # Response is SymbolInformation[]
      symbols = [format_symbol(sym) for sym in response]
      return {"symbols": symbols}

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

  Import of the 'symbols' module in the FastMCP server setup, which triggers automatic registration of the @mcp.tool()-decorated 'workspace_symbols' function.

  # Import tools to register them
  from jons_mcp_java.tools import navigation, symbols, diagnostics, info  # noqa: E402, F401

• src/jons_mcp_java/utils.py:106-147 (helper)

  Utility function to normalize and format LSP symbol information from workspace/symbol response into a consistent structure, recursively handling children for DocumentSymbol.

  def format_symbol(symbol: dict, include_children: bool = True) -> dict:
      """Format a DocumentSymbol or SymbolInformation to a common format."""
      # DocumentSymbol has range, SymbolInformation has location
      if "location" in symbol:
          # SymbolInformation
          loc = symbol["location"]
          uri = loc.get("uri", "")
          range_obj = loc.get("range", {})
          try:
              path = str(uri_to_path(uri))
          except ValueError:
              path = uri
      else:
          # DocumentSymbol (no path, just range within current file)
          path = None
          range_obj = symbol.get("range", {})
  
      start = range_obj.get("start", {})
  
      result = {
          "name": symbol.get("name", ""),
          "kind": symbol.get("kind", 0),
          "kind_name": SYMBOL_KINDS.get(symbol.get("kind", 0), "Unknown"),
          "line": start.get("line", 0),
          "character": start.get("character", 0),
      }
  
      if path:
          result["path"] = path
  
      # Include container name if present (SymbolInformation)
      if "containerName" in symbol:
          result["container"] = symbol["containerName"]
  
      # Include children if present (DocumentSymbol hierarchy)
      if include_children and "children" in symbol:
          result["children"] = [
              format_symbol(child, include_children=True)
              for child in symbol["children"]
          ]
  
      return result

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

  LSP constant for the 'workspace/symbol' method invoked by the tool handler.

  LSP_WORKSPACE_SYMBOL = "workspace/symbol"