jdx
The jdx MCP server lets AI agents inspect, navigate, and analyze JVM codebases through structured, provenance-aware tools.
Show a type’s declaration card, including kind, supertypes, source, and provenance.
List a type’s members or outline, with filters for kind, visibility, inherited/declared, static/instance, docs, Kotlin/JVM view, and synthetic members.
Open method bodies and source slices with line numbers, context, signature, docs, and decompiler/source provenance.
Get signatures with real parameter names and quick documentation with supertype fallback.
Search and resolve symbols by glob, regex, fuzzy name, package, or artifact.
Browse workspace packages, artifact trees, manifests, resources, SPI services, and JPMS modules.
Find usages, annotated symbols, type hierarchies, implementors, callers, and callees.
Retrieve ranked real call-site samples as usage evidence.
Search string literals and
.propertieskeys/values across bytecode and resources.Diff two artifacts for public-API changes with named compatibility rules and CI gates.
Query the server version and health, and target stored named workspaces; environment diagnostics are intentionally refused over MCP.
Provides an MCP front-end for the GitHub Copilot CLI: jdx setup --agent copilot installs the jdx server for a project so the agent can query JVM classes, methods, sources/bytecode bodies, usages, and implementors across a classpath, workspace, or Maven coordinate, using token-budgeted output and explicit exits codes for not-found/ambiguous results.
jdx — an IDE for AI agents
Website & docs: mohammadmd1383.github.io/jdx
Try it in 30 seconds
curl -fsSL https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.sh | bash
jdx members java.util.HashMap --limit 5
# MCP (Claude Code / Cursor): {"mcpServers":{"jdx":{"command":"jdx","args":["mcp"]}}}
# MCP (OpenCode v1+v2): jdx setup --agent opencode --scope project (then restart opencode)
# MCP (Claude Code): jdx setup --agent claude-code --scope project (then restart claude)
# MCP (Cursor): jdx setup --agent cursor --scope project (then restart Cursor)
# MCP (Kilo Code): jdx setup --agent kilo --scope project (then restart Kilo Code)
# MCP (Cline): jdx setup --agent cline --scope system (then restart Cline)
# MCP (Codex CLI): jdx setup --agent codex --scope project (then restart codex)
# MCP (GitHub Copilot CLI): jdx setup --agent copilot --scope project (then restart copilot)
# MCP (Antigravity): jdx setup --agent antigravity --scope project (then restart Antigravity)
# MCP (Windsurf / Devin): jdx setup --agent windsurf --scope project (then restart Windsurf)
# MCP (Aider / AiderDesk): jdx setup --agent aider --scope project (then restart AiderDesk; core Aider has no MCP)An AI agent working on a JVM codebase spends most of its time — and most of its context window — answering questions a human answers in an IDE with one keystroke:
What methods does this class have? What does this method actually do? Who calls it? What implements this interface?
Today an agent answers those with unzip, javap, grep, and by reading 1,400-line source
files into its context. It is slow, noisy, and expensive, and javap gives it erased
signatures and raw opcodes.
jdx answers them directly — from .jar, -sources.jar, class directories, source
directories, Maven coordinates, and the JDK itself:
$ jdx members java.util.HashMap --limit 5
members of java.util.HashMap
constructors declared on java.util.HashMap:
constructor public HashMap()
constructor public HashMap(int initialCapacity)
...
5 of 54 members shown (--limit 54 to see more)
source: java.base (jrt)
$ jdx body 'java.util.HashMap#get(java.lang.Object)'
java.util.HashMap#get(java.lang.Object)
source: decompiled by vineflower from java.base · java/util/HashMap.java:178-182 ⚠ reconstructed
@Override
public V get(Object key) {
Node<K, V> e;
return (e = this.getNode(key)) == null ? null : e.value;
}No sources jar? It decompiles with Vineflower — and says so, so the agent knows it is
reading a reconstruction (pass --engine javap for raw opcodes instead).
Proof, not promises. One real task — list Gson's API, then show only
toJson(Object)— measured on gson-2.14.0:
Approach
calls
bytes in context (~tokens)
unzip+javap+grep+sed5
~17.5 KB (~4.4k) — and
head -200misses the method (line 542 of 1265)
jdx members+jdx body2
~4.6 KB (~1.2k) — exact method, 267 bytes (~67 tokens)
The body alone: 267 bytes vs 60,590 (
javap -c, 226×) vs 58,251 (fullGson.java, 218×). Tokens ≈ bytes/4. Reproduce it:sh docs/bench-compare.sh.
Same task, two agents — left does it with javap/grep, right with jdx:




Related MCP server: srclight
Install
Requires JDK 21+. Every push of a vX.Y.Z tag publishes per-OS bundles as
GitHub Releases —
jdx-<version>-<os>.tar.gz and jdx-<version>-<os>.zip (<os> is linux,
macos, or windows), each with a .sha256 checksum and a jdx.jsa
trained on that OS:
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.ps1 | iexLinux/macOS installs per-user into ~/.local/share/jdx and links ~/.local/bin/jdx.
Windows installs into %LOCALAPPDATA%\Programs\jdx and adds that directory to
the user PATH (jdx.bat is the entry point). Verify with jdx version
(jdx doctor reports JDK, cache, index, Kotlin sidecar, AppCDS archive,
daemon, and workspace status). Release installs self-update with jdx upgrade.
Building from source: ./gradlew :app:installDist && ./install.sh (POSIX) or
gradlew.bat :app:installDist then .\install.ps1 (Windows) — see
CONTRIBUTING.md.
Releases are unsigned: Windows SmartScreen and macOS Gatekeeper will warn on first run.
Unblock-File jdx.bat(PowerShell) orxattr -d com.apple.quarantine <install-dir>/jdxclears it. Details and the asset table live indocs/PROPOSAL.md§17.2.
Quickstart
# No setup: the running JDK is always on the classpath via jrt:/
jdx members java.util.HashMap --inherited --limit 10
jdx body 'com.google.gson.Gson#toJson(Object)' --jars gson.jar
# Name a classpath once, reuse it everywhere (incl. daemon/MCP/HTTP/batch)
jdx ws create fx --jars 'libs/*.jar' --src ./src
jdx -w fx usages 'com.example.Service#run()'
# Maven coordinates resolve from ~/.gradle/caches + ~/.m2 first;
# --fetch downloads from Maven Central (with -sources.jar) when allowed
jdx show com.google.gson.Gson --coord com.google.code.gson:gson:2.14.0 --fetch
# Token budgets for the biggest listings (text only; --json bytes are unaffected)
jdx members java.util.HashMap --inherited --brief --max-lines 20
# Warm path: start once, query at ~20 ms instead of ~250 ms cold.
# The daemon never fetches — prime stored --coord jars once cold with --fetch
# (or use --jars) before `daemon start` / `mcp` / `serve`.
jdx daemon start -w fx
jdx -w fx members 'com.example.Service' # served warm automatically
# One process, many queries
echo '{"command":"show","query":"java.util.Map"}' | jdx batch --jars gson.jar
# Upgrading a dependency? Ask what actually breaks
jdx diff gson-2.11.0.jar gson-2.14.0.jar --fail-on breakingWhat makes it an IDE, not a better javap
Inherited members resolved transitively, with generic substitution — the agent never walks a class hierarchy by hand again.
A real index, so find usages, implementors, and call hierarchy work across an entire classpath, not just one jar.
Sources when they exist, decompilation when they don't — uniformly, behind one command.
True Kotlin signatures from
@Metadata:suspend, properties, default arguments,@JvmNamemappings — not the misleading JVM projection.Javadoc/KDoc, including documentation inherited from a supertype.
jdx samples— real call sites from the classpath as usage examples. Evidence instead of recollection.jdx literals— search string constants (LDC/ConstantValue) and.propertieskeys/values across a workspace for resource keys, log messages, and markers (issue #86). No moreunzip | tr | grep.jdx services— listMETA-INF/servicesSPI providers across a workspace (issue #25). Answer "who providescom.foo.Spi?" without unzipping jars.jdx modules— list JPMSmodule-infodescriptors (requires / exports / opens / uses / provides) across jars and the running JDK (issue #25).jdx manifest— listMETA-INF/MANIFEST.MFattributes across a workspace (issue #25): main attributes by default (Main-Class,Multi-Release, …);--entriesfor per-entry (JarEntry) sections.jdx resources— list non-class resource paths (META-INF/…,.properties, versionedMETA-INF/versions/…copies, …) across a workspace (issue #25);--catprints the unique match's text (binary payloads refuse to dump bytes).jdx diff a.jar b.jar— the public-API diff for a dependency upgrade, with every difference named as a rule (MEMBER_REMOVED,RETURN_TYPE_CHANGED, …) atbreaking/suspicious/info, and a--fail-ongate for CI.
What makes it for agents, not for humans
Minimal correct output. Bounded, with an explicit hint for getting the rest. Never a file dump when a method was asked for.
Never guesses. An ambiguous reference exits
2and lists every candidate as a copy-pasteable reference.Machine-legible outcomes. Distinct exit codes for not found, ambiguous, no index, bad usage — branch without parsing prose.
--jsonfor everything.Provenance on every answer — which jar, sources or bytecode, which decompiler.
jdx batch— many queries, one process, one index load.Four front-ends over one engine: one-shot CLI, MCP server, a daemon, and a local HTTP/JSON API.
jdx help --agent— a compact paste-ready block forCLAUDE.md/ system prompts.
Full command reference
The catalogue lives in docs/COMMANDS.md — every command, flag,
exit code, and the symbol-reference grammar. jdx <command> --help documents each
command; jdx help --agent prints the compact agent block.
Known limitations (by design)
Graph queries re-scan live bytecode roots per query (no persistent-index acceleration
yet). callers is override-aware by default (--exact for invoke-owner matching);
calls stays bytecode-exact. Full list in
GitHub Issues. Out-of-scope for v1
(mappings/remap, …) is the phase-2 backlog, also tracked there. To inspect a
Minecraft jar, pass the mapped jar your toolchain already produced — see
Inspect Minecraft mod jars.
Documentation
Guides, generated command and MCP reference, integrations, FAQ | |
User guides: install, quickstart, AI agents, classpath, reading and navigating code, API diff, Minecraft mod jars | |
Full command reference (flags, exit codes, symbol grammar) | |
| Contributor notes: architecture rules, gotchas, build/test |
Full design specification (Appendix B is the flag reference) | |
Testing strategy — required reading before writing tests | |
Conventions, code style, definition of done | |
Limitations, caveats, and the phase-2 backlog |
Contributing
Contributors here — human and AI — do not share memory. Read
CONTRIBUTING.md before your first change; it is short and it explains the
documentation discipline that keeps the project resumable by anyone.
License
Apache-2.0 (see LICENSE). Bundled third-party components and their licenses are listed in
docs/PROPOSAL.md §19 and will be reproduced in NOTICE.
Available Tools
27 toolsjdx_annotatedA
List classes/members carrying an annotation (issue #26). Query may be a type, '@Type(k=v)' use spelling, or a recipe alias (deprecated|forRemoval|test|junit5|junit4|bean). Equivalent to usages with kind=annotation.
Inputs: query (required), in, limit, where, +3 more.
jdx_bodyB
Open the method: the source body of one member, sliced verbatim with provenance.
Inputs: query (required), engine, context, withDoc, +4 more.
jdx_callersA
Call hierarchy in: who calls this method, as a depth-bounded tree. Override-aware by default; set exact=true for invoke-owner matching only.
Inputs: query (required), in, depth, exact, +3 more.
jdx_callsC
Call hierarchy out: what this method calls, as a depth-bounded tree.
Inputs: query (required), in, depth, limit, +3 more.
jdx_diffA
What changed between two artifacts? Public-API diff with named binary-compatibility rules (MEMBER_REMOVED, RETURN_TYPE_CHANGED, ...), most breaking first. query is the OLD artifact and new the candidate; each is a jar, class dir, glob, or Maven coordinate. Exits 0 whenever the comparison ran.
Inputs: new (required), query (required), limit, failOn, +4 more.
jdx_docB
Quick documentation for a type or member, falling back to the nearest documenting supertype like IntelliJ quick-doc.
Inputs: query (required), raw, maxLines, inherited, +2 more.
jdx_doctorA
Environment report. The server refuses this over MCP — it describes the server's machine, not the client's — run jdx doctor in a shell instead.
Inputs: query, workspace.
jdx_healthB
Liveness probe: uptime, workspace served and queries answered.
Inputs: query, workspace.
jdx_hierarchyC
Type hierarchy: supertypes upward and subtypes downward across the workspace.
Inputs: query (required), in, up, down, +5 more.
jdx_implementorsB
Who implements this interface or extends this class, transitively.
Inputs: query (required), in, depth, limit, +3 more.
jdx_literalsB
Search string constants across bytecode roots (LDC loads and String field ConstantValue) and .properties resource keys/values. Substring by default; set regex=true for a Java regex.
Inputs: query (required), in, limit, regex, +3 more.
jdx_lsC
External library browser: packages in the workspace roots.
Inputs: limit, query, workspace.
jdx_manifestA
List META-INF/MANIFEST.MF attributes across the workspace jars. Default: main-section attributes. Set entries=true for per-entry (JarEntry) attributes instead. Omit query to list every attribute in that section; with a query, match the attribute name or value (and entry path when entries=true). Does not extract resource file bytes (use jdx_resources with cat=true for text).
Inputs: in, limit, query, regex, +4 more.
jdx_membersA
List the members of a type — the '.' completion equivalent. Inherited members are included by default, grouped by declaring type.
Inputs: query (required), from, grep, kind, +10 more.
jdx_modulesA
List JPMS module-info descriptors across the workspace (requires, exports, opens, uses, provides). Omit query to list every module; with a query, match the module name, an exported/opened package, a uses/provides service, or a provider class. Does not read META-INF/MANIFEST.MF attributes (use jdx_manifest for that).
Inputs: in, limit, query, regex, +3 more.
jdx_outlineC
File Structure: one dense line per member declared on a type (never inherited).
Inputs: query (required), from, grep, kind, +9 more.
jdx_resolveB
What is this symbol? Short-name resolution with copy-pasteable candidates.
Inputs: query (required), limit, workspace.
jdx_resourcesA
List non-class resource paths across the workspace jars (META-INF, .properties, versioned META-INF/versions/… copies, …). Omit query to list every resource; with a query, match the entry path. Pass cat=true to print the unique match's text contents (binary payloads refuse to dump bytes; ambiguous matches exit 2). maxLines caps --cat text lines (default 200).
Inputs: in, cat, limit, query, +5 more.
jdx_samplesB
How is this symbol really used? Ranked call sites with source snippets as evidence.
Inputs: query (required), in, limit, exclude, +3 more.
jdx_searchA
Search symbols by glob, regex or fuzzy name. Default kind=all covers types, packages and modules; pass kind=method|field to scan members. A default-kind miss hints at --kind method.
Inputs: query (required), in, kind, fuzzy, +4 more.
jdx_servicesA
List META-INF/services SPI registrations across the workspace jars. Omit query to list every registration; with a query, match the service interface FQN or a provider class FQN. Does not read module-info provides (use jdx_modules for that).
Inputs: in, limit, query, regex, +3 more.
jdx_showB
Go to declaration: the class card for a type (kind, supertypes, source, provenance).
Inputs: query (required), workspace.
jdx_signatureC
Parameter info: one signature line per overload, with real parameter names.
Inputs: query (required), view, limit, workspace, +1 more.
jdx_sourceC
Open the file: whole source for a type, or a slice of it, with provenance.
Inputs: query (required), lines, around, engine, +4 more.
jdx_treeC
External library browser: artifacts and their package trees.
Inputs: depth, limit, query, counts, +1 more.
jdx_usagesB
Find usages of a type or member across the workspace jars and source dirs. With kind=annotation, query may use annotation-use spelling '@Type(k=v)' (issue #26).
Inputs: query (required), in, kind, limit, +4 more.
jdx_versionB
The jdx version this server was built as.
Inputs: query, workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Most tools have a clearly stated niche, and descriptions proactively cross-reference siblings (e.g. services vs modules vs manifest each name the tool to use instead). However there are real overlaps: jdx_annotated is explicitly 'equivalent to usages with kind=annotation', jdx_hierarchy's downward direction largely duplicates jdx_implementors, jdx_members vs jdx_outline differ only by inheritance handling, and jdx_ls vs jdx_tree both open with 'External library browser'. An agent can recover from the rich descriptions, but misselection is likely in those pairs.
Every tool uses the identical `jdx_` prefix plus a single lowercase token (tree, resolve, members, callers, diff...), with no camelCase or separator drift anywhere. The verb/noun mix is intentional and readable (verbs like resolve/search/show/diff, nouns like members/hierarchy), so the convention is fully predictable.
27 tools exceeds the comfortable range, and a few don't earn their place: jdx_doctor is explicitly non-functional over MCP, and jdx_version/jdx_health are thin meta probes. The remaining surface is broad but genuinely differentiated across navigation, relationships, and bytecode/artifact inspection, so it's heavy rather than bloated.
For a read-only JVM code-intelligence server the lifecycle is well covered: symbol search, short-name resolution, declarations, members, bodies, source slices, signatures, docs, usages, hierarchy, call graphs, samples, literals, SPI/JPMS/manifest/resource scanning, and artifact diffing. Gaps are minor for the stated purpose (no type-of-expression or diagnostics/compile-check operation), and read-only operation means no write tools are expected.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ship better Java with your coding agent.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI tools to analyze Java dependencies by scanning Maven projects, decompiling JAR files, and extracting detailed class information including methods, fields, and inheritance relationships. Solves the problem of AI hallucinations when generating code that calls external dependencies by providing accurate class structures through decompilation.321 npm42Apache 2.0
- AlicenseNot gradedqualityAmaintenanceDeep code indexing for AI agents. Search symbols, navigate call graphs, explore inheritance, track git history — all via MCP.76 PyPI59MIT
- AlicenseAqualityCmaintenanceDecompiles Maven dependencies into readable Java source directly inside your AI agent.1078 npm1Apache 2.0
- AlicenseNot gradedqualityAmaintenanceIndexes local Maven and Gradle caches to enable AI agents to search for Java classes, method signatures, and source code, including from internal or obscure libraries.24ISC