Java Jdtls Server

English | 简体中文

This project is a high-performance bridge between AI agents and Java codebases. It functions as both a Model Context Protocol (MCP) server and a Gemini CLI Extension, providing professional-grade Java language intelligence through Eclipse JDT.LS.

🌟 Key Features

• Gemini Extension & Agent Skills: Pre-packaged with structured Agent Skills for Navigation, Verification, and Lifecycle management, ensuring AI agents follow optimal workflows.
• Native JDT.LS Launch: Directly spawns the Java Language Server via JVM for maximum stability and performance.
• Enterprise-Grade Analysis: Supports loading entire Maven projects to resolve dependencies and symbols across the whole codebase.
• Diagnostics Support: Real-time retrieval of compilation errors and warnings to help AI agents verify their code changes.
• Environment & Instance Isolation: Uses workspace path hashing for isolated data directories and automatically clears conflicting environment variables (like PORT) for reliable communication.
• Full LSP Capabilities: Supports Go to Definition, Find References, Hover documentation, Global Symbol Search, and Document Symbol extraction.

🛠️ Prerequisites

• Node.js: v18.0.0 or higher.
• Java Development Kit (JDK): Java 17 or higher (Java 21+ recommended).
• Eclipse JDT.LS: An installation of Eclipse JDT.LS.

🚀 Installation & Setup

For Gemini CLI (Extension Mode)

This project is optimized for use as a Gemini CLI extension.

# Clone the repository
git clone <repository-url>
cd java-jdtls-mcp-server
npm install && npm run build

# Install as Gemini extension
gemini extensions install .

For Claude Code / Other MCP Clients

For Claude Code, Claude Desktop, or other MCP clients, you'll need to configure the server explicitly as an MCP tool.

1. Build the project as shown above.
2. Edit your client's configuration file (e.g., claude_desktop_config.json for Claude Desktop).
3. Add the server configuration and define your global environment variables directly within the env section:

{
  "mcpServers": {
    "java-mcp-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/java-jdtls-mcp-server/dist/index.js"
      ],
      "env": {
        "JDTLS_HOME": "D:/software/jdt-language-server-latest",
        "JDTLS_JAVA_HOME": "D:/software/java/jdk-23.0.1",
        "JDTLS_JAVA_RUNTIMES": "[{\"name\":\"JavaSE-1.8\",\"path\":\"C:/Program Files/Java/jdk1.8.0_361\"},{\"name\":\"JavaSE-17\",\"path\":\"D:/software/jdk-17.0.7\"}]",
        "JDTLS_MAVEN_USER_SETTINGS": "D:/software/apache-maven-3.9.3/conf/settings.xml",
        "JDTLS_MAVEN_GLOBAL_SETTINGS": "D:/software/apache-maven-3.9.3/conf/settings.xml"
      }
    }
  }
}

Note: When using Claude Code, the project-level .env file logic (like JAVA_PROJECT=true) might not be loaded natively unless supported by the specific MCP client implementation. You may need to manage project-specific variables within the client's configuration directly.

1. Global Setup (User-level .env)

Global environment variables are recommended for common paths to avoid repeating them in every project. The global configuration file is typically located at: USER_HOME\.gemini\extensions\java-jdtls-mcp-server\.env (where USER_HOME is your user directory, e.g., C:\Users\User1).

How to Configure:

1. During Installation (Recommended): If you have enabled the experimental.extensionConfig setting in Gemini CLI, you will be prompted to input these environment variables during the initial installation. Gemini CLI will then auto-generate the .env file at the path above.
2. Manual Configuration: Alternatively, you can manually create the user-level .env file at this location and fill in the recommended information.

Recommended Configuration Example:

JDTLS_HOME=D:/software/jdt-language-server-latest
JDTLS_JAVA_HOME=D:/software/java/jdk-23.0.1
JAVA_WORKSPACE_PATH=
JDTLS_JAVA_RUNTIMES=[{"name":"JavaSE-1.8","path":"C:/Program Files/Java/jdk1.8.0_361"},{"name":"JavaSE-17","path":"D:/software/jdk-17.0.7"}]
JDTLS_MAVEN_USER_SETTINGS=D:/software/apache-maven-3.9.3/conf/settings.xml
JDTLS_MAVEN_GLOBAL_SETTINGS=D:/software/apache-maven-3.9.3/conf/settings.xml

Variable	Description	Required	Default
JDTLS_HOME	Path to JDT.LS installation root directory	Yes	-
JDTLS_JAVA_HOME	Dedicated JDK path for JDT.LS (Overrides JAVA_HOME)	No	System JAVA_HOME
JAVA_WORKSPACE_PATH	Root path of your Java project	No	Current Working Directory
JDTLS_JAVA_RUNTIMES	JSON list of Java Runtimes for different project versions	No	-
JDTLS_MAVEN_USER_SETTINGS	Path to custom Maven user settings.xml	No	-
JDTLS_MAVEN_GLOBAL_SETTINGS	Path to custom Maven global settings.xml	No	-
JDTLS_MAVEN_OFFLINE	Enable Maven offline mode (true/false)	No	false

2. Project-Level Activation (Project-level .env)

Project-level env info is loaded and read by agent tools like Gemini CLI. For example, when using Gemini CLI, the project-level env path is usually: [Project Root]/.gemini/.env.

To prevent the Java language server from starting unnecessarily in non-Java projects, you must enable it explicitly per project. Please add the following to your project-level .env file:

# REQUIRED: Activates the Java Language Server for this specific workspace
JAVA_PROJECT=true

(Optional) You can also place any of the global settings in this local .env file to override them for a specific project.

🧩 Expert Skills & AI Rules

This project provides a set of high-level Expert Skills (located in skills/) that guide AI agents on the most efficient ways to interact with the Java Language Server. These skills prevent common pitfalls (like redundant server restarts) and improve code intelligence accuracy.

Skill	Expert Guide	Key Benefit
java-lifecycle	Server management	Standardizes JDT.LS startup, status checks, and error recovery.
java-navigation	Code intelligence	Optimizes finding definitions, references, and symbols.
java-project-load	Project indexing	Speeds up Maven project loading without manual file scanning.
java-verification	Diagnostics	Enforces real-time error checking and verification.

🚀 Usage in Gemini CLI

Gemini CLI can install these skills as part of the extension. Once installed, they are activated automatically or on-demand:

• activate_skill java-lifecycle
• activate_skill java-navigation

🤖 Usage in Claude Code / Other MCP Clients

While Claude Code doesn't support Gemini's extension packaging, it can still leverage these skills through its Rules system:

1. Project-Level Rules: Copy the contents (or relevant parts) of the SKILL.md files from the skills/ directory into a .clauderules file in your Java project's root.
2. Global Rules: Alternatively, you can add these instructions to your global Claude configuration.

By placing these rules in .clauderules, Claude Code will automatically adopt these "expert workflows" whenever it detects it is working within this project environment.

---

🧰 Available Tools

Tool Name	Description	Key Parameters
java_start	Initializes JDT.LS. Restarts if already running.	jdtlsHome, workspacePath, javaHome
java_restart	Forces a fresh restart of the JDT.LS process.	jdtlsHome, workspacePath, javaHome
java_load_maven_project	New! Loads an entire Maven project and indexes symbols.	projectPath
java_search_symbols	New! Performs global symbol search across the workspace.	query
java_get_file_symbols	New! Extracts all symbols (classes/methods) from a file.	filePath
java_open_file	Notifies the server about file content (required for diagnostics).	filePath, content
java_get_diagnostics	Retrieves errors and warnings for a specific file.	filePath
java_get_definition	Retrieves the definition location for a symbol.	filePath, line, character
java_get_references	Finds all references for a symbol.	filePath, line, character
java_get_hover	Gets type info and documentation for a symbol.	filePath, line, character

🧠 Agent Skills

The folder skills/ contains specialized Markdown files that guide AI agents on how to use these tools effectively:

• Navigation: Strategies for exploring codebases and using symbol search.
• Verification: Workflows for checking code correctness via diagnostics.
• Lifecycle: Handling server initialization and auto-start configuration.

📚 Design Documentation

This project follows a structured design process. Detailed technical documents can be found in the design/ directory:

• High-level Design: Describes the system architecture, core modules, and external interfaces.
• Detailed Design: Covers class models, sequence diagrams, and internal implementation details of the JavaLanguageServer.

📄 License

This project is licensed under the ISC License.