JVM Source Lens

jvmsrc — Give your coding agent a Java IDE

The Problem

You use an IDE to write Java. Your coding agent doesn't have one.

When your agent hits an unfamiliar library type — say, a superclass from a proprietary internal library — it spends 25+ turns walking ~/.gradle/caches, opening JARs by hand with jar tf, picking one by guesswork, and trying to answer a question your IDE would answer in one keystroke: does this superclass have a public utility method called X?

The Solution

jvmsrc queries your build tool (Gradle) for this project's resolved classpath, then hands your agent real source, real signatures, and real structure — for the exact version your build actually uses.

• As an MCP server – Connect to Claude Code, Cursor, Windsurf, or any other MCP host and equip your agent with six purpose-built classpath tools.
• As the jvmsrc CLI – Same engine, scriptable, pipe-friendly, and useful on its own when you just want to read a class.

[jvmsrc resolving a Spring class in Claude Code]
Claude Code resolving HandlerInterceptor signatures via jvmsrc — 3 calls, correct answer, no cache walking.

What it saves, daily

On JVM projects with private libraries and no public Javadocs, jvmsrc is a force multiplier:

• ~50K tokens saved per "what's on this external class" investigation — roughly 70% reduction in cost.
• 15+ agent panic loops avoided daily — no grinding through Gradle caches, opening wrong JARs, or giving up.
• Unlock delegation for complex tasks touching internal SDKs that you previously had to do yourself.

The Difference in Action

Without jvmsrc (The 25-turn blind grind)

User: Override the audit hook from AbstractTradingService — is there a public utility method on it we should reuse?

Agent:

1. Searches workspace for AbstractTradingService.java ➔ 0 hits
2. Runs: find ~/.gradle -name "trading-core*"
3. Finds 4 versions: 2.1.0, 2.3.0, 2.4.1, 3.0.0-SNAPSHOT
4. Guesses: Picks trading-core-2.4.1.jar (the project actually uses 3.0.0-SNAPSHOT!)
5. Runs: jar tf and javap -p on the wrong JAR
6. [22 turns later] "I don't see a utility method, you'll have to implement it yourself."

Reality: 3.0.0-SNAPSHOT added maskSensitiveFields() as a protected helper exactly for this case. The agent didn't hallucinate — it was just blind.

With jvmsrc (The 3-turn instant resolution)

User: Override the audit hook from AbstractTradingService — is there a public utility method on it we should reuse?

Agent:

1. search_classes("AbstractTradingService") ➔ Finds FQN & exact resolved library.
2. get_class_structure(scope: "overview") ➔ Discovers maskSensitiveFields() in 3.0.0-SNAPSHOT.
3. get_method_signature("maskSensitiveFields") ➔ Gets accurate signature and generics.

Result: Writes the override correctly on the first try. No cache walking, no guessing, no wrong version.

How It Works

1. Build Tool Inquiry: jvmsrc queries your active build tool (e.g., Gradle) for the exact resolved classpath configuration.
2. Intelligent Caching: It caches the resolved classpath, tracking changes to build files to stay current.
3. Precision AI Tools: Instead of full-code dumping, it exposes precise, high-granularity tools (signatures, structure, search) to keep context windows small and token usage ultra-low.

Installation & Quick Start

1. Install CLI

npm install -g jvmsrc

Or use it directly via npx:

npx jvmsrc mcp

[!IMPORTANT]
Requires Node ≥ 20 and Java on PATH (for CFR decompiler + javap).

2. Add the MCP server

Paste this into your AI assistant config (Cursor, Claude Code, Windsurf, etc.), then restart the host:

{  "mcpServers": {    "jvmsrc": {      "command": "jvmsrc",      "args": ["mcp"]    }  }}

Optional: jvmsrc config (or jvmsrc config --project /path/to/gradle-project) prints a paste-ready block plus environment hints. Most users can skip it and copy the snippet above.

MCP Server Reference

The MCP server runs over stdio via jvmsrc mcp. The default config needs no environment variables:

{  "mcpServers": {    "jvmsrc": {      "command": "jvmsrc",      "args": ["mcp"]    }  }}

Private repository credentials (optional)

Only needed when your Gradle build requires credential env vars for a private Maven/Artifactory/Nexus-style repo. MCP hosts often do not inherit your interactive shell, so those vars must be set on the jvmsrc MCP process (then restart the server).

REPO_USER / REPO_PASS below are sample names only — they are not required by jvmsrc. Use whatever variable names your project’s Gradle scripts document:

{  "mcpServers": {    "jvmsrc": {      "command": "jvmsrc",      "args": ["mcp"],      "env": {        "REPO_USER": "your-username",        "REPO_PASS": "your-password"      }    }  }}

Omit the env block entirely when the project does not need them.

Tools your agent gets

[!TIP]
Every source response includes sourceAvailable: true for real sources (Javadoc, parameter names, generics), false for CFR decompilation (structure reliable, names may be synthetic).

[!NOTE]
Multimodule: omit modulePath and jvmsrc auto-picks the unique owning module; on a miss it lists candidate modulePaths. Methods: search_classes matches declared method names when the index has source enrichment; for body text in a known JAR use search_in_artifact. get_class_source methodNames also walks superclasses for unmatched names.

Make your agent use it

Tool descriptions help, but a built-in Bash tool the agent already trusts will often win. Two small additions make jvmsrc the default for dependency questions.

1. Add a rule to your agent's instructions (CLAUDE.md, AGENTS.md, Cursor rules) — many clients do not show MCP server instructions at all:

## Dependencies (jvmsrc)For any question about a third-party library class, method or version, use the jvmsrc MCP tools(search_classes → get_class_structure → get_class_source with methodNames; resolve_dependencies for versions).When working inside one module, pass modulePath (':app' or the file you are editing) to get that module's versions.Never use javap, unzip/jar on JARs, or ~/.gradle/caches. Code under this repo's src/ → grep/read as usual.

2. (Claude Code) Block the shell fallbacks with a hook. docs/hooks/block-jvm-fallbacks.mjs denies javap, unzip/jar on JARs, and ~/.gradle/caches / ~/.m2 access, and tells the agent to use jvmsrc instead, so it redirects instead of silently reading the wrong version. Save the script somewhere stable and add to .claude/settings.json (project) or ~/.claude/settings.json (all projects):

{  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [{ "type": "command", "command": "node /absolute/path/to/block-jvm-fallbacks.mjs" }]      }    ]  }}

Set JVMSRC_HOOK_DISABLE=1 to switch it off temporarily. Other clients have their own hook mechanisms; check their current docs before porting.

Check that your client shows the server instructions: ask the agent "What instructions does the jvmsrc MCP server give?". If it cannot answer, rely on the rule in step 1.

[!NOTE] Inputs are forgiving. projectRoot can be omitted (the workspace is used, or set JVMSRC_PROJECT_ROOT); modulePath accepts app, /app, :app, or a file/directory inside the module (omit it, or pass "*", to search all modules); className accepts a simple name, Outer.Inner, or a trailing .class/.java. The first call on a project runs Gradle (typically 5–10s); later calls use the cache. Pass forceRefresh: true only after something changed that the build files do not show, such as a SNAPSHOT republish.

How It Compares

Target Audience

Primarily Java + Spring Boot projects on Gradle. Other JVM languages (Kotlin, Scala) and Android work today on a best-effort basis and are on the roadmap as first-class targets — see ROADMAP.md.

If you're on Maven or Bazel, it's planned but not shipping yet. Star the repo or open an issue and I'll prioritize accordingly.

Detailed Reference

jvmsrc com.example.MyClass -p /path/to/gradle-project          # shorthand for getjvmsrc get com.example.MyClass -p /path/to/project -q > MyClass.javajvmsrc resolve -p /path/to/project --force-refreshjvmsrc config jdk-roots add /path/to/jdks                      # one-time JDK roots setupjvmsrc doctor java -p /path/to/project                         # check JDK requirement + selectionjvmsrc diagnostics last                                         # latest failure messagejvmsrc mcp                                                     # run as MCP server

Project Documentation

Building from Source

git clone https://github.com/Sintexer/jvm-source-lens.gitcd jvm-source-lensbun install && bun run setup:cfr && bun run buildnode dist/cli.js --version

Full contributor workflow: CONTRIBUTING.md.

I built jvmsrc because I kept running into the same wall: agents that are great at writing Java but blind to the actual classpath. If it saves you the same 25-turn grind it saved me, that's exactly why this exists. Found a bug, have an idea, or just want to say it helped? Open an issue or a PR — I read everything.

License

MIT — see LICENSE.