mvnctx
MCP server that gives AI coding agents instant Maven context — resolve dependency trees, locate classes in local jars, and read sources or decompiled bytecode without leaving the chat.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/lan-zk--mvnctx)HTML
<a href="/listings/lan-zk--mvnctx"><img src="/api/listings/lan-zk--mvnctx/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Option 1 — one-liner (prebuilt binary from GitHub Releases)
# Windows (PowerShell) irm https://raw.githubusercontent.com/Lan-zk/mvnctx/main/install.ps1 | iex
# Linux / macOS curl -fsSL https://raw.githubusercontent.com/Lan-zk/mvnctx/main/install.sh | bash
The script picks the right binary for your OS/arch, installs it, and prints the `claude mcp add` line.
Option 2 — Homebrew (Linux / macOS)
The formula is generated into this repo's `Formula/` directory by GoReleaser on every release:
brew tap Lan-zk/mvnctx https://github.com/Lan-zk/mvnctx brew install mvnctx
Option 3 — go install (requires Go 1.21+)
go install github.com/Lan-zk/mvnctx@latest
Option 4 — from source
git clone https://github.com/Lan-zk/mvnctx && cd mvnctx go build -o mvnctx . # cross-compile (pure Go, no cgo): GOOS=linux GOARCH=amd64 go build -o mvnctx-linux . GOOS=darwin GOARCH=arm64 go build -o mvnctx-darwin .
The CFR decompiler (~2 MB) is embedded in the binary — a single executable is a complete install.
Register with Claude Code
claude mcp add --scope user mvnctx -- /absolute/path/to/mvnctx
Other MCP hosts
Any stdio MCP client works. VS Code — `.vscode/mcp.json` (share it with the workspace):
{
"servers": {
"mvnctx": { "command": "/absolute/path/to/mvnctx" }
}
}Cursor — `~/.cursor/mcp.json`:
{
"mcpServers": {
"mvnctx": { "command": "/absolute/path/to/mvnctx" }
}
}Windows: point `command` at `mvnctx.exe`. Custom Maven layout: add `"env": { "MVNCTX_SETTINGS": "...", "MVNCTX_REPO": "..." }` to either entry — same variables as the table below.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 195 lines · 2 findings marked
- # mvnctx
- 
- 
- 
- [English](README.md) | [简体中文](README-zh.md)
- **mvnctx** is an [MCP](https://modelcontextprotocol.io) server that gives coding agents instant context from a **local Maven repository**: dependency resolution, class lookup, and decompiled SDK sources — so an agent working on a Spring Boot project can answer *"what does this SDK class do, what are its methods and annotations, what config keys does this starter accept?"* in one tool call, without leaving the editor or guessing from import statements.
- ## How it works
- ```
- class context, three-tier waterfall (best source first):
- 1. -sources.jar → serve the real .java source (milliseconds)
- 2. CFR decompile → whole-jar decompile, cached on disk (5-30s first, then cached)
- 3. javap → signatures + annotations fallback (only if CFR fails)
- dependency resolution → delegated to `mvn dependency:list` (cached by pom.xml hash)
- class lookup → zip central-directory scan (no unzip, no bytecode parsing)
- spring metadata → spring-configuration-metadata.json / AutoConfiguration.imports read straight from the jar
- ```
- - Single static binary (CFR is embedded; works standalone)
- - No daemon, no index to maintain, no IDE required
- - Disk caches keyed by pom hash / jar path+mtime+size — new jar versions invalidate naturally
- ## Tools
- | Tool | What it does |
- |---|---|
- | `resolve_deps` | Full dependency list of a project (transitives resolved by Maven itself). Compact output: scope + `g:a:v` + sources-jar availability. Test scope hidden by default (`scope=all`), `filter` narrows by substring (e.g. `filter=com.mycompany`) |
- | `find_class` | Search class names (fqcn or simple name substring) across the project's dependency jars, ~1-2s |
- | `describe_class` | Java source/context for one class — the three-tier waterfall above. Locate the jar via `project_dir` (among project deps) or `coords` `g:a[:v]` |
- | `decompile` | Pre-decompile a whole artifact and return a package-level summary (packages with class counts) — survey an unfamiliar SDK cheaply |
- | `get_config_metadata` | Spring Boot `@ConfigurationProperties` metadata (keys, types, defaults, descriptions) + auto-configuration imports from a jar |
- ## Install
- ### Option 1 — one-liner (prebuilt binary from GitHub Releases)
- ```powershell
- # Windows (PowerShell)
- irm https://raw.githubusercontent.com/Lan-zk/mvnctx/main/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 44 on GitHub
- ```
- ```bash
- # Linux / macOS
- curl -fsSL https://raw.githubusercontent.com/Lan-zk/mvnctx/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 49 on GitHub
- ```
- The script picks the right binary for your OS/arch, installs it, and prints the `claude mcp add` line.
- ### Option 2 — Homebrew (Linux / macOS)
- The formula is generated into this repo's `Formula/` directory by GoReleaser on every release:
- ```bash
- brew tap Lan-zk/mvnctx https://github.com/Lan-zk/mvnctx
- brew install mvnctx
- ```
- ### Option 3 — go install (requires Go 1.21+)
- ```bash
- go install github.com/Lan-zk/mvnctx@latest
- ```
- ### Option 4 — from source
- ```bash
- git clone https://github.com/Lan-zk/mvnctx && cd mvnctx
- go build -o mvnctx .
- # cross-compile (pure Go, no cgo):
- GOOS=linux GOARCH=amd64 go build -o mvnctx-linux .
- GOOS=darwin GOARCH=arm64 go build -o mvnctx-darwin .
- ```
- The CFR decompiler (~2 MB) is embedded in the binary — a single executable is a complete install.
- ### Register with Claude Code
- ```bash
- claude mcp add --scope user mvnctx -- /absolute/path/to/mvnctx
- ```
- ### Other MCP hosts
- Any stdio MCP client works. VS Code — `.vscode/mcp.json` (share it with the workspace):
- ```json
- {
- "servers": {
- "mvnctx": { "command": "/absolute/path/to/mvnctx" }
- }
- }
- ```
- Cursor — `~/.cursor/mcp.json`:
- ```json
- {
- "mcpServers": {
- "mvnctx": { "command": "/absolute/path/to/mvnctx" }
- }
- }
- ```
- Windows: point `command` at `mvnctx.exe`. Custom Maven layout: add `"env": { "MVNCTX_SETTINGS": "...", "MVNCTX_REPO": "..." }` to either entry — same variables as the table below.
- ## Configuration
- Zero configuration on a machine that follows the standard conventions (`JAVA_HOME`, `~/.m2/settings.xml`, `~/.m2/repository` or a `<localRepository>` declared in settings). Resolution order, most specific first:
- ```
- MVNCTX_* env > standard conventions (JAVA_HOME, settings.xml, ~/.m2) > ~/.m2/repository
- ```
- | Env | Meaning | Default |
- |---|---|---|
- | `MVNCTX_JAVA_HOME` | JDK root (java + javap live in `bin/`) | `JAVA_HOME`, then `PATH` |
- | `MVNCTX_JAVA` / `MVNCTX_JAVAP` | Explicit binaries | derived from java home |
- | `MVNCTX_MVN` | Maven command | `mvn` on PATH, else `./mvnw` |
- | `MVNCTX_SETTINGS` | settings.xml to pass via `-s` | settings' own default |
- | `MVNCTX_REPO` | Local repository location | `<localRepository>` from settings, else `~/.m2/repository` |
- | `MVNCTX_CACHE` | Cache directory | system cache dir + `/mvnctx` |
- | `MVNCTX_CFR` | CFR jar path | embedded (materialized into the cache dir) |
- Non-default repository/settings layout — pass the values with the registration:
- ```bash
- # settings.xml declares <localRepository> → one value is enough
- claude mcp add -s user -e MVNCTX_SETTINGS=/path/settings.xml mvnctx -- /path/mvnctx
- # settings.xml does NOT declare it → add the repo (must be where mvn actually downloads,
- # otherwise every jar shows up as "NOT in local repo")
- claude mcp add -s user -e MVNCTX_SETTINGS=/path/settings.xml -e MVNCTX_REPO=/path/repo mvnctx -- /path/mvnctx
- ```
- ## CLI (same functionality, for debugging)
- ```
- mvnctx doctor # verify java/mvn/settings/repo/cfr/cache
- mvnctx resolve [-refresh] [-filter substr] [-scope all] <project_dir>
- mvnctx find -dir <project_dir> [-limit N] <pattern>
- mvnctx describe [-dir D] [-coords g:a[:v]] [-max-chars N] <fqcn>
- mvnctx decompile [-max-chars N] <g:a[:v]>
- mvnctx config [-max-chars N] <g:a[:v]>
- ```
- ## Latency expectations
- | Operation | First call | Cached |
- |---|---|---|
- | `resolve_deps` | 10-60s (Maven startup) | milliseconds (pom unchanged) |
- | `find_class` | ~1-2s | ~1-2s (zip central-dir scan) |
- | `describe_class` (sources jar) | milliseconds | milliseconds |
- | `describe_class` (CFR) | 5-30s (whole jar) | milliseconds |
- | `get_config_metadata` | milliseconds | milliseconds |
- JVM subprocesses are capped at 2 concurrent instances.
- ## Prerequisites (runtime)
- - A JDK (with `javap`) — standard `JAVA_HOME` is picked up automatically
- - Maven on `PATH`, or a project-provided wrapper (`mvnw` is used as fallback)
- - The target project must have been built once (dependencies present in the local repo)
- ## Limitations / non-goals
- - **Maven only** — no Gradle support
- - **Requires a JDK** — CFR and javap are JVM tools; a bare JRE without `javap` is not enough
- - `find_class` searches **project dependencies**, not the entire repository — repo-wide symbol indexing is a deliberate non-goal until proven necessary
- - `resolve_deps` caches by pom.xml hash; parent/BOM changes outside the pom require `refresh=true`
- - `${...}` interpolation inside `<localRepository>` is not expanded — set `MVNCTX_REPO` explicitly
- - Tested on Windows; Linux/macOS compile and follow the same conventions but are not routinely exercised
- ## Development
- ```bash
- go test ./... # unit tests always run
- # end-to-end protocol test (spawns the binary, exercises tools against a real project):
- go build -o mvnctx.exe . && MVNCTX_TEST_PROJECT=/path/to/a/built/maven/project go test -v -run TestSmokeProtocol
- ```
- Layout: `main.go` (config/CLI/MCP registration) · `maven.go` (dependency resolution, coordinates) · `jar.go` (zip scanning) · `engine.go` (sources→CFR→javap pipeline, caches) · `smoke_test.go`
- Releasing: push a `v*` tag — the GitHub Actions workflow builds all platforms via GoReleaser, attaches binaries + checksums to a GitHub Release, and commits the updated Homebrew formula to `Formula/` automatically.
- ## License
- Apache-2.0 — see [LICENSE](LICENSE).
- Third-party notice: the embedded CFR decompiler ([org.benf:cfr](https://www.benf.org/other/cfr/), LGPL-2.1) is distributed unmodified and invoked as a separate JVM process at runtime.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.