java-lsp-mcp

Java semantic intelligence for Model Context Protocol (MCP) clients, powered by Eclipse JDT Language Server and ECJ.

java-lsp-mcp gives coding agents semantic navigation, diagnostics, compilation, tests, and refactoring previews. It never edits source files: changes are returned as hash-bound edits and optional diffs for the client to apply.

Features

• Workspace and dependency navigation

• Maven, Gradle, Eclipse, modular, and unmanaged projects

• Current-snapshot diagnostics and ECJ compilation

• Parallel JUnit tests, suspended JDWP test launches, affected-test discovery, and JaCoCo coverage

• Read-only fixes, refactorings, import, and formatting previews

• Bounded, paginated agent-friendly results

Related MCP server: jdtls-mcp

Prerequisites

• Node.js 24+ — the server runs on your Node; release launchers use node from PATH.

• A JDK — pointed to by JAVA_HOME or --tooling-jdk. It runs JDT LS and your tests.

• A Java workspace — Maven, Gradle, Eclipse, modular, or unmanaged.

Release archives bundle JDT LS, JUnit, and JaCoCo. Everything else comes from the prerequisites above.

Installation

Download the archive for your platform from the releases page, unpack it, and run:

java-lsp-mcp/bin/java-lsp-mcp serve --workspace /absolute/path/to/project --trust-workspace

On Windows use bin\java-lsp-mcp.cmd. Then verify with java-lsp-mcp doctor --workspace /project.

To use it in VS Code, add the launcher to .vscode/mcp.json in your project:

{
  "servers": {
    "java-lsp-mcp": {
      "command": "/absolute/path/to/java-lsp-mcp/bin/java-lsp-mcp",
      "args": ["serve", "--workspace", "/absolute/path/to/project", "--trust-workspace"]
    }
  }
}

java-lsp-mcp print-config generic --workspace /project --trust-workspace prints the equivalent snippet for other clients.

Configuration

Flags for serve (a java-lsp-mcp.json or java-lsp-mcp.toml file in the workspace and JAVA_LSP_MCP_* environment variables work too; flags win, then env, then the file):

Source reads honor --source-encoding first, then Eclipse resource encoding settings. Without either, valid UTF-8 is preserved and other source files are read as Windows-1252, with a SOURCE_ENCODING_FALLBACK warning on stderr. Source files are never converted or modified. Set the encoding explicitly for other legacy encodings; invalid or unsupported explicit encodings still report errors.

Other commands: doctor checks the setup, version prints versions, describe-tools prints the complete machine-readable tool schemas, print-config generates client configuration, and clear-cache wipes the workspace index.

If Eclipse cannot restore cached workspace metadata because a generated resource disappeared, the server detects the failed recovery, rebuilds its JDT cache once, and retries startup.

Tools

Source-based tools support the encoding fallback above. Symbol targets accept either qualifiedName or path plus a required one-based line. Omit column to select the innermost declaration enclosing that line; supply a one-based Unicode code-point column for an exact position. Columns beyond the line are clamped to its end.

java_search_symbols and java_find_definition require a queries array of 1–20 parameter objects. Batch related lookups to gather context in one call. Each entry has its own options, defaults, limit, and cursor. The response contains results in input order; failed entries contain error with code, message, and optional details, while other entries still complete. Top-level single-query parameters are rejected.

{"queries":[{"query":"OrderService"},{"query":"Customer","scope":"all"}]}

{"queries":[{"target":{"qualifiedName":"com.example.OrderService"},"expand":["body"]},{"target":{"path":"src/Customer.java","line":12}}]}

Symbol search and reference lookups retain independent result snapshots when another page is available. Subsequent pages reuse the collected matches and reference usage classification; a fresh request without a cursor performs a new lookup. The shared cache expires entries two minutes after creation and uses LRU eviction with limits of 32 result sets and 16 MiB of serialized results. Access does not extend expiry. Workspace changes and JDT reconnects invalidate cached continuations. An expired or evicted snapshot returns STALE_RESULT_SET; restart without a cursor. Results exceeding the cache byte limit bypass caching and retain ordinary pagination.

Source verification reads, decodes, and hashes each Java file once per verification, reusing the synchronized snapshot. Unchanged verification still offers the document to JDT (including retrying a failed initial synchronization) and avoids unnecessary watched-file change notifications.

Compilation retries an unsuccessful incremental build once as a clean build when current diagnostics contain no confirmed JDT syntax-error codes. Syntax errors are checked before severity filtering or pagination. Both attempts share the compilation timeout and preserve project exclusions and compileProjectOnly scope, including loaded prerequisites. Explicit clean builds, cancellation, unknown statuses, and request/configuration failures do not trigger a retry. java_compile.buildAttempts records the attempted build kinds and statuses; its diagnostics describe the final result.

java_run_tests compiles incrementally by default and uses the same recovery policy before launching tests. Successful builds are reused until the workspace generation changes; compile: "none" still skips compilation and compile: "clean" requests a clean build directly. Normal test results include buildAttempts (empty when a build was reused). Persistent build failures return status: "compile-failed" and a compilation object with build status, attempts, diagnostic counts, locations/messages, total, and diagnosticsTruncated for the bounded diagnostic sample. Test counts and test failures remain separate from compiler diagnostics. Debug launches use the same build policy; failed builds return compiler details in the tool error.

Run java-lsp-mcp describe-tools for the complete machine-readable tool schemas.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Build from source with:

npm ci
npm run fetch-runtime
npm run check
bin/java-lsp-mcp serve --workspace /absolute/path/to/project --trust-workspace

Security

Review SECURITY.md before granting workspace trust. Report vulnerabilities privately.

License

MIT. See LICENSE.