JVM Source Lens

jvmsrc — Give your coding agent a Java IDE

An MCP server and CLI that gives your coding agent the one thing it's missing on JVM codebases: the actual classpath.

---

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.

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

Requirements & Compatibility

Runtime: Node.js ≥ 20, Java on PATH.

Project types: JVM codebases (Java, Kotlin, Scala, Groovy). jvmsrc calls the build tool, not your editor.

Point -p / projectRoot at the Gradle root (settings.gradle(.kts) or root build.gradle(.kts)). Uses ./gradlew when present, else gradle on PATH. Maven-only trees get an explicit unsupported error.

Known Limitations

Early software; the supported path is narrow:

Composite builds, Android-only layouts, and exotic configurations are not fully validated. See ROADMAP.md.

Security & Privacy

• No telemetry.
• Local only — caches and diagnostics stay on disk; never writes under your project root.
• Subprocesses via argv only (no shell interpolation) — see SECURITY.md.
• Optional JVMSRC_ALLOWED_ROOTS to lock down which projects