jvmsrc
Queries the Gradle build tool to resolve the exact classpath for a project, enabling accurate source and signature lookups.
Provides source and structure information for Kotlin libraries on the classpath, on a best-effort basis.
Provides source and structure information for Scala libraries on the classpath, on a best-effort basis.
Targets Spring Boot projects, providing accurate classpath resolution for Spring Boot dependencies.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
jvmsrc — Give your coding agent a Java IDE
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 or ~/.m2 and often reads the wrong JAR.
jvmsrc asks your build tool (Gradle and Maven) 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 mcpAdd 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.
Related MCP server: codeweave-mcp
Why jvmsrc
Question: "Does AbstractTradingService have a public helper we can reuse in our override?" (a private library, no public Javadoc)
Without | With | |
Agent turns | ~25 | 3 |
How it works |
|
|
Version used | Wrong ( | The one Gradle resolved |
Result | "No helper exists, write your own" | Finds |
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
Build tool query:
jvmsrcasks your build tool (Gradle) for the exact resolved classpath.Cache: it caches the result and watches your build files, so the data stays current.
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.
Tool | What it does |
| Find a class by simple name or glob; returns compact FQN + lib name lists |
| Retrieves class overview (purpose + method names) or declared signatures |
| Fetches real overloads for a method, with parameter names and generics |
| Greps one known class's source for a string or identifier (literal; regex optional) |
| Retrieves method bodies or line ranges (used as a last resort) |
| Greps text across all classes in one resolved dependency JAR |
| Analyzes the actual dependency graph this project uses |
Every source response includessourceAvailable: true for real sources (Javadoc, parameter names, generics), false for CFR decompilation (structure reliable, names may be synthetic). Nested types (Outer$Inner, including ImmutableList.Builder) return structure, signatures, method excerpts, and decompiled source from the enclosing type.
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.
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; a file under src/test/ also selects the test classpath); 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. To save tokens on every turn, projectRoot, configuration and forceRefresh (except on resolve_dependencies) are accepted but not listed in the tool schemas.
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
Tool | Approach | Gap |
Cache Indexers / | Scan global caches | No per-project resolved version |
Static Parsers (e.g., | Parse declarations only | Misses transitive dependencies, BOMs, dynamic versions |
| User supplies manual JAR paths | No automatic build/classpath resolution |
Gradle MCP (Tooling API) | Task/build focused | Not optimized for classpath-accurate FQN source lookup |
| Queries actual build tool & caches | Version-correct sources and signatures for agents |
Target Audience
Primarily Java + Spring Boot projects on Gradle and Maven. Other JVM languages (Kotlin, Scala, Groovy) work today — see PLAN.md.
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 system | Status |
Gradle | Supported — multimodule included |
Maven | Supported — multimodule reactor, nearest-wins conflict resolution, |
Bazel | Planned (SPEC.md) |
-p / projectRoot can be the build root or any directory inside it; jvmsrc walks up to the Gradle root (gradlew / settings.gradle(.kts)) or Maven reactor root (pom.xml); the nearest root wins. MCP tools can omit projectRoot, and the CLI can omit -p (it uses JVMSRC_PROJECT_ROOT, else the build that contains the working directory). Uses ./gradlew / ./mvnw when present, else gradle / mvn.
Early software; the supported path is narrow:
Area | Today |
Build tool | Gradle and Maven (single-module and multi-module reactors) |
Integration | Bundled Gradle init script ( |
Classpaths | Standard JVM + Kotlin MPP |
Output | Original source when available ( |
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_ROOTSto 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.mdor 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 globallyThen 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 # shorthand for get; project = build containing cwd
jvmsrc com.example.MyClass -p /path/to/gradle-project # explicit project
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 serverUseful flags: -p / --project (optional), --module (:core:api, or a file inside the module), --configuration, --include-test (implied when --module is under src/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(orjvmsrc diagnostics last 5)Custom JDK install roots: Add once with
jvmsrc config jdk-roots add /path/to/jdksJDK mismatch debugging: Run
jvmsrc doctor java -p /path/to/projectAfter upgrading jvmsrc: Restart your MCP host
Stale classpath: Run
jvmsrc resolve --force-refreshTool-usage analysis: Set
JVMSRC_CALL_LOG=1in the MCP serverenv; calls are logged tocalls.lognext to the failure log (macOS:~/Library/Logs/jvmsrc/)
Variable | Purpose |
| Force JDK home for Gradle/CFR child processes |
| Global jvmsrc config directory (absolute) |
| Cache root (absolute) |
| Diagnostic logs (absolute) |
|
|
| Allowed |
| Default project root when MCP |
| Max source body size (default 524288) |
| Unscoped full-file |
| Gradle timeout |
|
|
| Maven timeout (default 600000) |
|
|
| Explicit |
| Max size of a JAR read into memory (default 524288000 = 500 MB); larger JARs return |
| Wall-clock limit for regex mode in |
| Custom 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_classesfunctionality is incredibly precise, and the thoughtful implementation ofjavapfallback 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
Document | Contents |
Schemas, contracts, CLI/MCP details | |
Build, test, PR notes | |
Branching, semver, npm releases | |
Version history | |
Status and checkpoint plan | |
Vulnerability 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 setup:maven-analyzer && bun run build
node dist/cli.js --versionFull 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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP Server for JFrog, providing tools for development and artifact management.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server for intelligently reading Java source code, supporting extraction from Maven dependencies and local projects with dual decompilers.232 PyPI154Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.73 npm4Apache 2.0
- AlicenseAqualityDmaintenanceA high-performance MCP server that bridges AI agents with Java codebases, providing professional-grade Java language intelligence via Eclipse JDT.LS.1515 npm3GPL 3.0
- AlicenseAqualityCmaintenanceAn MCP server that empowers AI coding agents to work effectively with Minecraft mod development, providing static analysis of decompiled source code and runtime interaction with a running Minecraft instance.3159 npm18MIT