Back to Browse

Jvm Source Lens MCP Server

Developer ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Gradle-accurate JVM classpath; fetch Java source, signatures, and class structure for agents.

About

Gradle-accurate JVM classpath; fetch Java source, signatures, and class structure for agents.

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (2 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.

3 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Optional comma-separated absolute paths; only these project roots are allowed.Optional

Environment variable: JVMSRC_ALLOWED_ROOTS

Optional absolute path for resolution and decompile caches (default: OS cache dir).Optional

Environment variable: JVMSRC_CACHE_ROOT

Optional absolute path for failure diagnostic logs.Optional

Environment variable: JVMSRC_LOG_DIR

Max characters returned for full-file source (default 524288).Optional

Environment variable: JVMSRC_MAX_SOURCE_OUTPUT_CHARS

Gradle resolution subprocess timeout in milliseconds.Optional

Environment variable: JVMSRC_GRADLE_TIMEOUT_MS

Optional path to a custom CFR JAR for decompilation.Optional

Environment variable: JVMSRC_CFR_PATH

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "npx",
      "args": [
        "-y",
        "jvmsrc@1.16.0"
      ],
      "env": {
        "JVMSRC_LOG_DIR": "your-jvmsrc-log-dir-here",
        "JVMSRC_CFR_PATH": "your-jvmsrc-cfr-path-here",
        "JVMSRC_CACHE_ROOT": "your-jvmsrc-cache-root-here",
        "JVMSRC_ALLOWED_ROOTS": "your-jvmsrc-allowed-roots-here",
        "JVMSRC_GRADLE_TIMEOUT_MS": "your-jvmsrc-gradle-timeout-ms-here",
        "JVMSRC_MAX_SOURCE_OUTPUT_CHARS": "your-jvmsrc-max-source-output-chars-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

jvmsrc — Give your coding agent a Java IDE

CI npm version License: MIT Node

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

Your IDE knows which library version your build uses. Your coding agent does not. It guesses from ~/.gradle/caches and often reads the wrong JAR. jvmsrc asks your build tool (Gradle) for the resolved classpath. Then it gives the agent real source, real signatures and real structure for the exact version in use.


Quick Start

Requires Node ≥ 20 and Java on PATH (for the CFR decompiler and javap).

1. Add the MCP server — run in your terminal

claude mcp add jvmsrc -- npx -y jvmsrc mcp

Add this to the MCP config of your client, then restart the client:

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

VS Code (mcp.json) uses the key servers instead of mcpServers.

To install the CLI globally, run npm install -g jvmsrc. Then use "command": "jvmsrc" and "args": ["mcp"]. jvmsrc config prints a paste-ready block with environment hints.

2. Check it works — type in your agent chat, not in the terminal

"Use jvmsrc: which methods does <a library class from your project> declare?"

The first call runs Gradle (about 5–10 s). Later calls use the cache.

3. Make your agent use it

Agents often prefer Bash and javap out of habit. Add this rule to CLAUDE.md, AGENTS.md or your Cursor rules:

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

Details, and an optional Claude Code hook that blocks the shell fallbacks: Make your agent use it.


Why jvmsrc

Question: "Does AbstractTradingService have a public helper we can reuse in our override?" (a private library, no public Javadoc)

Without jvmsrcWith jvmsrc
Agent turns~253
How it worksfind ~/.gradle, then jar tf and javap on a JAR it picked by guesssearch_classes → get_class_structure → get_method_signature
Version usedWrong (2.4.1, the project uses 3.0.0-SNAPSHOT)The one Gradle resolved
Result"No helper exists, write your own"Finds maskSensitiveFields(), correct override on the first try

Typical result on JVM projects with private libraries (author's own use, not a benchmark):

  • About 50K tokens saved per "what is on this external class" question.
  • Far fewer agent loops that walk Gradle caches, open wrong JARs or give up.
  • Tasks that touch internal SDKs become safe to delegate.

How it works

  1. Build tool query: jvmsrc asks your build tool (Gradle) for the exact resolved classpath.
  2. Cache: it caches the result and watches your build files, so the data stays current.
  3. Small tools: it exposes precise tools (signatures, structure, search) instead of full-source dumps. Context stays small.

Tools your agent gets

The MCP server runs over stdio (jvmsrc mcp). It needs no environment variables by default.

ToolWhat it does
search_classesFind a class by simple name or glob; returns compact FQN + lib name lists
get_class_structureRetrieves class overview (purpose + method names) or declared signatures
get_method_signatureFetches real overloads for a method, with parameter names and generics
find_in_class_sourceGreps one known class's source for a string or identifier (literal; regex optional)
get_class_sourceRetrieves method bodies or line ranges (used as a last resort)
search_in_artifactGreps text across all classes in one resolved dependency JAR
resolve_dependenciesAnalyzes the actual dependency graph this project uses

[!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.

[!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. When jvmsrc reinterprets an input (simple name to FQN, subdirectory to Gradle root), the result ends with a note: line. Pass forceRefresh: true only after something changed that the build files do not show, such as a SNAPSHOT republish.

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 set those vars on the jvmsrc MCP process (then restart the server).

REPO_USER / REPO_PASS below are sample names only — jvmsrc does not require them. Use the variable names your Gradle scripts document:

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

Omit the env block when the project does not need it.


Make your agent use it

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

1. Rule in the agent instructions. Use the block from Quick Start. Many clients do not show MCP server instructions at all.

2. (Claude Code) Hook that blocks shell fallbacks. docs/hooks/block-jvm-fallbacks.mjs denies javap, unzip/jar on JARs, and ~/.gradle/caches / ~/.m2 access. It tells the agent to use jvmsrc instead. Save the script in a stable place. Add this 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 for a while. Other clients have their own hook systems; read their current docs before you port it.

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.


How It Compares

ToolApproachGap
Cache Indexers / ~/.gradle grepScan global cachesNo per-project resolved version
Static Parsers (e.g., build.gradle parser)Parse declarations onlyMisses transitive dependencies, BOMs, dynamic versions
mcp-javadoc / path-only CFRUser supplies manual JAR pathsNo automatic build/classpath resolution
Gradle MCP (Tooling API)Task/build focusedNot optimized for classpath-accurate FQN source lookup
jvmsrcQueries actual build tool & cachesVersion-correct sources and signatures for agents

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

Build systemStatus
GradleSupported — multimodule included
Maven, BazelPlanned (SPEC.md)

-p / projectRoot can be the Gradle root or any directory inside it; jvmsrc walks up to the nearest gradlew / settings.gradle(.kts). MCP tools can omit projectRoot. Uses ./gradlew when present, else gradle on PATH. Maven-only trees get an explicit unsupported error.

Early software; the supported path is narrow:

AreaToday
Build toolGradle only
IntegrationGroovy init script (--init-script) — not a Gradle Portal plugin
ClasspathsStandard JVM + Kotlin MPP jvm* configurations when Gradle exposes them
OutputJava-shaped .java text (sources JAR, inter-project src, or CFR)

Composite builds, Android-only layouts, and exotic configurations are not fully validated. See PLAN.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.
  • Files it writes: the cache, config and log folders only (OS defaults from env-paths; see Environment Variables). It does not edit your agent config, CLAUDE.md or hooks. You add those yourself.

Uninstall

claude mcp remove jvmsrc        # Claude Code. Other clients: delete the "jvmsrc" entry from the MCP config
npm uninstall -g jvmsrc         # only if you installed it globally

Then delete the jvmsrc cache folder (JVMSRC_CACHE_ROOT, or the OS default), the rule block in your agent instructions and the hook entry, if you added them.

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
  • Tool-usage analysis: Set JVMSRC_CALL_LOG=1 in the MCP server env; calls are logged to calls.log next to the failure log (macOS: ~/Library/Logs/jvmsrc/)
VariablePurpose
JVMSRC_JAVA_HOMEForce JDK home for Gradle/CFR child processes
JVMSRC_CONFIG_DIRGlobal jvmsrc config directory (absolute)
JVMSRC_CACHE_ROOTCache root (absolute)
JVMSRC_LOG_DIRDiagnostic logs (absolute)
JVMSRC_CALL_LOG1 = append one line per MCP tool call to calls.log (opt-in; see SPEC §6.3)
JVMSRC_ALLOWED_ROOTSAllowed projectRoot prefixes
JVMSRC_PROJECT_ROOTDefault project root for MCP tools when projectRoot is omitted and the client sends no workspace roots (falls back to the working directory)
JVMSRC_MAX_SOURCE_OUTPUT_CHARSMax source body size (default 524288)
JVMSRC_MAX_FULL_SOURCE_CHARSUnscoped full-file get_class_source larger than this is refused with SOURCE_OUTPUT_TOO_LARGE (default 65536)
JVMSRC_GRADLE_TIMEOUT_MSGradle timeout
JVMSRC_USE_SYSTEM_GRADLE1 = run gradle on PATH, not the project's ./gradlew (see SECURITY.md)
JVMSRC_MAX_JAR_BYTESMax size of a JAR read into memory (default 524288000 = 500 MB); larger JARs return ZIP_READ_ERROR
JVMSRC_REGEX_TIMEOUT_MSWall-clock limit for regex mode in find_in_class_source / search_in_artifact (default 2000)
JVMSRC_CFR_PATHCustom CFR JAR

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

DocumentContents
SPEC.mdSchemas, contracts, CLI/MCP details
CONTRIBUTING.mdBuild, test, PR notes
RELEASING.mdBranching, semver, npm releases
CHANGELOG.mdVersion history
PLAN.mdStatus and checkpoint plan
SECURITY.mdVulnerability reporting

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.

Reviews

No reviews yet

Be the first to review this server!