Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lan-zk--mvnctx/badge.svg)](/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

i

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
  1. # mvnctx
  2. ![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go)
  3. ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)
  4. ![License](https://img.shields.io/badge/License-Apache--2.0-blue)
  5. [English](README.md) | [简体中文](README-zh.md)
  6. **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.
  7. ## How it works
  8. ```
  9. class context, three-tier waterfall (best source first):
  10. 1. -sources.jar → serve the real .java source (milliseconds)
  11. 2. CFR decompile → whole-jar decompile, cached on disk (5-30s first, then cached)
  12. 3. javap → signatures + annotations fallback (only if CFR fails)
  13. dependency resolution → delegated to `mvn dependency:list` (cached by pom.xml hash)
  14. class lookup → zip central-directory scan (no unzip, no bytecode parsing)
  15. spring metadata → spring-configuration-metadata.json / AutoConfiguration.imports read straight from the jar
  16. ```
  17. - Single static binary (CFR is embedded; works standalone)
  18. - No daemon, no index to maintain, no IDE required
  19. - Disk caches keyed by pom hash / jar path+mtime+size — new jar versions invalidate naturally
  20. ## Tools
  21. | Tool | What it does |
  22. |---|---|
  23. | `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`) |
  24. | `find_class` | Search class names (fqcn or simple name substring) across the project's dependency jars, ~1-2s |
  25. | `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]` |
  26. | `decompile` | Pre-decompile a whole artifact and return a package-level summary (packages with class counts) — survey an unfamiliar SDK cheaply |
  27. | `get_config_metadata` | Spring Boot `@ConfigurationProperties` metadata (keys, types, defaults, descriptions) + auto-configuration imports from a jar |
  28. ## Install
  29. ### Option 1 — one-liner (prebuilt binary from GitHub Releases)
  30. ```powershell
  31. # Windows (PowerShell)
  32. irm https://raw.githubusercontent.com/Lan-zk/mvnctx/main/install.ps1 | iex
  33. ```
  34. ```bash
  35. # Linux / macOS
  36. 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
  37. ```
  38. The script picks the right binary for your OS/arch, installs it, and prints the `claude mcp add` line.
  39. ### Option 2 — Homebrew (Linux / macOS)
  40. The formula is generated into this repo's `Formula/` directory by GoReleaser on every release:
  41. ```bash
  42. brew tap Lan-zk/mvnctx https://github.com/Lan-zk/mvnctx
  43. brew install mvnctx
  44. ```
  45. ### Option 3 — go install (requires Go 1.21+)
  46. ```bash
  47. go install github.com/Lan-zk/mvnctx@latest
  48. ```
  49. ### Option 4 — from source
  50. ```bash
  51. git clone https://github.com/Lan-zk/mvnctx && cd mvnctx
  52. go build -o mvnctx .
  53. # cross-compile (pure Go, no cgo):
  54. GOOS=linux GOARCH=amd64 go build -o mvnctx-linux .
  55. GOOS=darwin GOARCH=arm64 go build -o mvnctx-darwin .
  56. ```
  57. The CFR decompiler (~2 MB) is embedded in the binary — a single executable is a complete install.
  58. ### Register with Claude Code
  59. ```bash
  60. claude mcp add --scope user mvnctx -- /absolute/path/to/mvnctx
  61. ```
  62. ### Other MCP hosts
  63. Any stdio MCP client works. VS Code — `.vscode/mcp.json` (share it with the workspace):
  64. ```json
  65. {
  66. "servers": {
  67. "mvnctx": { "command": "/absolute/path/to/mvnctx" }
  68. }
  69. }
  70. ```
  71. Cursor — `~/.cursor/mcp.json`:
  72. ```json
  73. {
  74. "mcpServers": {
  75. "mvnctx": { "command": "/absolute/path/to/mvnctx" }
  76. }
  77. }
  78. ```
  79. Windows: point `command` at `mvnctx.exe`. Custom Maven layout: add `"env": { "MVNCTX_SETTINGS": "...", "MVNCTX_REPO": "..." }` to either entry — same variables as the table below.
  80. ## Configuration
  81. 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:
  82. ```
  83. MVNCTX_* env > standard conventions (JAVA_HOME, settings.xml, ~/.m2) > ~/.m2/repository
  84. ```
  85. | Env | Meaning | Default |
  86. |---|---|---|
  87. | `MVNCTX_JAVA_HOME` | JDK root (java + javap live in `bin/`) | `JAVA_HOME`, then `PATH` |
  88. | `MVNCTX_JAVA` / `MVNCTX_JAVAP` | Explicit binaries | derived from java home |
  89. | `MVNCTX_MVN` | Maven command | `mvn` on PATH, else `./mvnw` |
  90. | `MVNCTX_SETTINGS` | settings.xml to pass via `-s` | settings' own default |
  91. | `MVNCTX_REPO` | Local repository location | `<localRepository>` from settings, else `~/.m2/repository` |
  92. | `MVNCTX_CACHE` | Cache directory | system cache dir + `/mvnctx` |
  93. | `MVNCTX_CFR` | CFR jar path | embedded (materialized into the cache dir) |
  94. Non-default repository/settings layout — pass the values with the registration:
  95. ```bash
  96. # settings.xml declares <localRepository> → one value is enough
  97. claude mcp add -s user -e MVNCTX_SETTINGS=/path/settings.xml mvnctx -- /path/mvnctx
  98. # settings.xml does NOT declare it → add the repo (must be where mvn actually downloads,
  99. # otherwise every jar shows up as "NOT in local repo")
  100. claude mcp add -s user -e MVNCTX_SETTINGS=/path/settings.xml -e MVNCTX_REPO=/path/repo mvnctx -- /path/mvnctx
  101. ```
  102. ## CLI (same functionality, for debugging)
  103. ```
  104. mvnctx doctor # verify java/mvn/settings/repo/cfr/cache
  105. mvnctx resolve [-refresh] [-filter substr] [-scope all] <project_dir>
  106. mvnctx find -dir <project_dir> [-limit N] <pattern>
  107. mvnctx describe [-dir D] [-coords g:a[:v]] [-max-chars N] <fqcn>
  108. mvnctx decompile [-max-chars N] <g:a[:v]>
  109. mvnctx config [-max-chars N] <g:a[:v]>
  110. ```
  111. ## Latency expectations
  112. | Operation | First call | Cached |
  113. |---|---|---|
  114. | `resolve_deps` | 10-60s (Maven startup) | milliseconds (pom unchanged) |
  115. | `find_class` | ~1-2s | ~1-2s (zip central-dir scan) |
  116. | `describe_class` (sources jar) | milliseconds | milliseconds |
  117. | `describe_class` (CFR) | 5-30s (whole jar) | milliseconds |
  118. | `get_config_metadata` | milliseconds | milliseconds |
  119. JVM subprocesses are capped at 2 concurrent instances.
  120. ## Prerequisites (runtime)
  121. - A JDK (with `javap`) — standard `JAVA_HOME` is picked up automatically
  122. - Maven on `PATH`, or a project-provided wrapper (`mvnw` is used as fallback)
  123. - The target project must have been built once (dependencies present in the local repo)
  124. ## Limitations / non-goals
  125. - **Maven only** — no Gradle support
  126. - **Requires a JDK** — CFR and javap are JVM tools; a bare JRE without `javap` is not enough
  127. - `find_class` searches **project dependencies**, not the entire repository — repo-wide symbol indexing is a deliberate non-goal until proven necessary
  128. - `resolve_deps` caches by pom.xml hash; parent/BOM changes outside the pom require `refresh=true`
  129. - `${...}` interpolation inside `<localRepository>` is not expanded — set `MVNCTX_REPO` explicitly
  130. - Tested on Windows; Linux/macOS compile and follow the same conventions but are not routinely exercised
  131. ## Development
  132. ```bash
  133. go test ./... # unit tests always run
  134. # end-to-end protocol test (spawns the binary, exercises tools against a real project):
  135. go build -o mvnctx.exe . && MVNCTX_TEST_PROJECT=/path/to/a/built/maven/project go test -v -run TestSmokeProtocol
  136. ```
  137. 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`
  138. 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.
  139. ## License
  140. Apache-2.0 — see [LICENSE](LICENSE).
  141. 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 in

Free to use. If it’s helped, pass it on.