@knno/jdtls-mcp

MCP (Model Context Protocol) server for JDTLS (Java Development Tools Language Server). Provides Java language server capabilities to AI coding assistants through the MCP protocol.

Installation

# Use directly with npx
npx @knno/jdtls-mcp

# Or install globally
npm install -g @knno/jdtls-mcp
jdtls-mcp

Usage

Basic Usage

# Auto-detect Java project in current directory
npx @knno/jdtls-mcp

# Specify workspace
npx @knno/jdtls-mcp --workspace /path/to/java/project

Command Line Options

| Option | Short | Description | |--------|-------|-------------| | --workspace <path> | -w | Java project root directory (contains pom.xml or build.gradle) | | --download | -d | Use downloaded JDTLS (reuse cache if available) | | --force-download | -f | Force re-download JDTLS (delete local cache first) | | --help | -h | Show help information |

Environment Variables

| Variable | Description | |----------|-------------| | JDTLS_HOME | Specify JDTLS installation directory (highest priority) |

JDTLS Discovery Order

1. JDTLS_HOME environment variable
2. Cached ~/.jdtls/bin/jdtls
3. VSCode Red Hat Java extension bundled jdtls
4. Auto-download on first use

Download Options

• --download: Use downloaded JDTLS, prioritize local cache (extracted > archive > download)
• --force-download: Force fresh download, delete all local caches

Available Tools

| Tool | Description | |------|-------------| | java_getDiagnostics | Get compilation errors, warnings, and code issues | | java_findReferences | Find all references to a symbol | | java_getDefinition | Go to symbol definition | | java_getHover | Get hover information | | java_searchSymbols | Search workspace symbols (including third-party libraries) | | java_getClassFileContents | Get decompiled source code from third-party libraries. Supports startLine/endLine to get partial content. | | java_getCompletions | Get code completion suggestions. Low context consumption, suitable for quickly querying class members. | | java_resolveCompletion | Resolve completion item details (e.g., Javadoc) | | java_getSignatureHelp | Get signature help for methods | | java_getImplementation | Get implementations of an interface/class | | java_getTypeDefinition | Go to type definition | | java_rename | Rename symbol | | java_organizeImports | Organize imports | | java_prepareCallHierarchy | Prepare call hierarchy for a method | | java_callHierarchyIncomingCalls | Get incoming calls | | java_callHierarchyOutgoingCalls | Get outgoing calls | | java_prepareTypeHierarchy | Prepare type hierarchy for a class | | java_typeHierarchySupertypes | Get supertypes | | java_typeHierarchySubtypes | Get subtypes |

Tool Selection Guide

When choosing between tools, consider context consumption:

• java_getCompletions - Low context consumption. Use for quickly checking available methods/fields.
• java_getClassFileContents - Higher context consumption. Use when you need implementation details. Use startLine/endLine to limit content.

Auto-Wait for LSP Ready

All tools automatically wait for the JDTLS server to be ready before executing. No need to call a separate "waitForReady" tool.

Configuration

The server stores JDTLS in ~/.jdtls/ directory:

~/.jdtls/
├── bin/              # JDTLS executable
├── plugins/          # JDTLS plugins
├── config/           # Configuration files
├── workspace/        # Project-specific workspace data
└── jdtls.tar.gz      # Downloaded archive (cached)

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Development mode (watch)
pnpm run dev

# Run test suite
pnpm test

# Run basic test
pnpm run test:basic

# Run specific tool test
node test/test-suite.mjs --tool=java_getDiagnostics

Test Project

The test/java_demo_project/ directory contains a sample Java project used for testing. It includes:

• Maven project with Apache HttpClient and Jackson dependencies
• Sample classes for testing various LSP features
• A BuggyClass.java with intentional errors for diagnostics testing

Requirements

• Node.js >= 18
• Java Runtime (JDK 17+ recommended for JDTLS)

License

ISC