Jvm Source Lens MCP Server

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.

---

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 <command>

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

2. Configure for your Workspace (MCP)

Generate a paste-ready MCP configuration for your project:

jvmsrc config --project /path/to/gradle-project

Paste this configuration into your AI assistant config (Claude Code, Cursor, Windsurf, etc.), restart the host, and you are ready to go!

---

MCP Server Reference

The MCP server runs over stdio via jvmsrc mcp. Add this to your host config:

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

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).

---

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

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.

Early software; the supported path is narrow:

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

• 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 jvmsrc may resolve.

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

Useful flags: -p / --project, --module (:core:api), --configuration, --include-test, --force-refresh, --verbose (Gradle stderr only), --method, --start-line / --end-line.

Repo fixture for testing: test/fixtures/gradle-smoke — jvmsrc get com.smoke.Core -p test/fixtures/gradle-smoke --module :core.

• Resolution failures: Run jvmsrc diagnostics last (or jvmsrc diagnostics last 5)
• Custom JDK install roots: Add once with jvmsrc config jdk-roots add /path/to/jdks
• JDK mismatch debugging: Run jvmsrc doctor java -p /path/to/project
• After upgrading jvmsrc: Restart your MCP host
• Stale classpath: Run jvmsrc resolve --force-refresh

Defaults follow env-paths conventions per OS. Full layout: SPEC.md §6.

When JVMSRC_JAVA_HOME is not set, jvmsrc auto-discovers local JDKs from common paths such as ~/.jdks (IntelliJ), ~/.gradle/jdks, SDKMan, jenv, asdf, and OS-specific system install directories, plus your global configured JDK roots from jvmsrc config jdk-roots ....

Finally, an MCP That Doesn't Make Me Decompile JARs

"This tool is a revelation for anyone tired of LLMs hallucinating non-existent Spring APIs. It actually reads bytecode, providing accurate class definitions and source lookups without the usual 'vibes-based' guesswork. The search_classes functionality is incredibly precise, and the thoughtful implementation of javap fallback and granular scope controls (overview/declared/effective) makes navigating complex JARs painless. It’s fast, honest when it can't find a class, and handles cache management perfectly. A must-have for any dev struggling with dependency hell — it’s like having a senior engineer who actually enjoys reading documentation." — Claude (AI Reviewer)

---

Project Documentation

Building from Source

git clone https://github.com/Sintexer/jvm-source-lens.git
cd jvm-source-lens
bun install && bun run setup:cfr && bun run build
node 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.