Java Inspector

Decompile Maven dependencies into readable Java source — directly inside your AI agent.

npm License

---

What is this?

AI editors can't read compiled .class files. Ask "How does JpaRepository work?" and the agent hallucinates.

Java Inspector is an MCP server that exposes the internals of your project's Maven dependencies (Spring, Hibernate, Jackson, Micrometer, etc.) as decompiled Java source code. Zero configuration — just point your agent at it.

Supported operations

Tool	What it does
scan_dependencies	Kicks off a background scan of every JAR on the Maven classpath. Call again to poll progress.
decompile_class	Returns the full Java source (method bodies and all) via Vineflower. Optionally extract a single method by methodName, or paginate with offset/limit.
analyze_class	Returns the structural signature — fields, methods, constructors, inheritance — via javap. No method bodies.
search_class	Fuzzy-find classes by partial name (e.g. "ObservationRegistry").
get_inheritance_tree	Walks the superclass chain up to java.lang.Object.

Response formats

Every tool accepts a format parameter (text | json | toon). Default is text.

Format	What you get	Best for
text	Human-readable markdown, tables, code blocks	Reading by LLMs and humans
json	Pure structuredContent — no text wrapper	Programmatic consumption, piping to other tools
toon	Token-Oriented Object Notation — compact, schema-aware text	LLM prompts where token count matters (~40% fewer tokens than JSON)

json strips the text wrapper and returns only the structured payload.
toon encodes the same payload via @toon-format/toon, giving you YAML-like readability with CSV-like compactness for uniform arrays.

---

Architecture

graph LR
    A[AI Agent<br/>Claude / Cursor / Codex / Opencode] -->|MCP| B[java-inspector<br/>TypeScript Server]
    B -->|auto-detect| C{Maven Resolver}
    C -->|priority 1| D[MAVEN_CMD env]
    C -->|priority 2| E[mvnd daemon<br/>~2x faster]
    C -->|priority 3| F[MAVEN_HOME/bin/mvn]
    C -->|priority 4| G[mvn from PATH]
    B -->|dependency:build-classpath| H[~/.m2/repository]
    H -->|JAR streams| I[yauzl extractor]
    I -->|class names| J[JSON Lines Cache]
    B -->|cache hit| J
    B -->|cache miss| I
    B -->|java -jar vineflower.jar| K[Vineflower 1.11.2<br/>Decompiler]
    K -->|*.java source| A

Why JSON Lines?

Traditional JSON caches rewrite the entire file on every batch — O(n²) overhead for large projects. We use append-only JSON Lines:

• Crash-safe: each line is independent; a truncated final line is skipped on reload.
• Fast startup: the server replays the JSONL into an in-memory Map<string, ClassIndexEntry> on launch.
• Low memory: ~35 MB RAM for 100,000 classes.

Cache layout

~/.cache/java-inspector/<project>_<hash>/
├── classpath.json           # pomHash + jarPaths[] + classpathHash + timestamp
├── class-index.jsonl        # Append-only ClassIndexEntry batches
├── scan-state.json          # jarCount, processedJars[], isComplete
├── server-<pid>.log         # Per-process append-only logs (multi-process safe)
├── write.lock               # Cross-process lock for JSONL / state writes
├── scan.lock                # Cross-process lock for scan lifecycle
└── decompile-cache-vineflower/  # Cached .java sources

---

Quick Start

Add to your MCP client config:

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "java-inspector": {
      "command": "npx",
      "args": ["-y", "@mustafagoksever/java-inspector"]
    }
  }
}

Cursor

Settings → MCP Servers → Add:

{
  "mcpServers": {
    "java-inspector": {
      "command": "npx",
      "args": ["-y", "@mustafagoksever/java-inspector"]
    }
  }
}

Codex

Edit ~/.codex/config.toml:

[mcp_servers.java-inspector]
command = "npx"
args = ["-y", "@mustafagoksever/java-inspector"]

Opencode

Edit %APPDATA%\opencode\config.json:

{
  "mcp": {
    "java-inspector": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mustafagoksever/java-inspector"
      ]
    }
  }
}

Restart your editor and ask: "Show me the source of ObservationRegistry"

That's it. No JAVA_HOME tweaks. No manual decompiler download. The server ships the ~1.8 MB Vineflower JAR inside the package.

---

Workflow

sequenceDiagram
    participant U as User
    participant A as AI Agent
    participant S as java-inspector
    participant M as Maven / mvnd
    participant C as Cache

    U->>A: "Show me JpaRepository source"
    A->>S: decompile_class("org.springframework.data.jpa.repository.JpaRepository")
    alt Index not built yet
        S->>M: dependency:build-classpath
        M-->>S: JAR list
        S->>S: Background scan (20 JARs in parallel)
        S-->>A: Class found via lazy JAR search
    else Cache hit
        S->>C: Map.get(className) — O(1)
        C-->>S: ClassIndexEntry
    end
    S->>S: Extract .class from JAR (yauzl)
    S->>S: java -jar vineflower.jar ...
    S-->>A: Decompiled .java source
    A-->>U: Formatted response

Cache invalidation

flowchart TD
    A[scan_dependencies called] --> B{isIndexComplete?}
    B -->|pomHash mismatch| C[Invalidate disk + memory]
    B -->|classpathHash mismatch| C
    B -->|both match| D[Return existing index]
    C --> E[Delete ~/.cache/java-inspector/<hash>/*]
    E --> F[Re-run Maven dependency:build-classpath]
    F --> G[Start background scan]
    D --> H[Return Map of classes]

Invalidation triggers:

1. Module pom.xml changes — pomHash mismatch.
2. Parent POM / dependency-management changes — classpathHash mismatch.
3. Manual — call scan_dependencies with forceRefresh: true. This force-releases cross-process locks and wipes the cache directory before restarting.

---

Platform Support

OS	Command
Windows	npx -y @mustafagoksever/java-inspector
Linux	npx -y @mustafagoksever/java-inspector
macOS	npx -y @mustafagoksever/java-inspector

Requirements: Node.js ≥ 16, Java runtime, Maven (or mvnd for faster resolves).

---

Environment variables

Variable	Effect
JAVA_HOME	Locates java and javap.
MAVEN_HOME	Locates mvn / mvn.cmd.
MAVEN_CMD	Override executable entirely — e.g. mvnd, mvnw, or a full path.
MAVEN_REPO	Overrides ~/.m2/repository.
DECOMPILER_PATH	Use a custom Vineflower JAR instead of the bundled one.
NODE_ENV=development	Enables verbose server.log output.

---

Installation alternatives

Zero-setup (recommended)

npx @mustafagoksever/java-inspector

Global install

npm install -g @mustafagoksever/java-inspector
java-inspector start

Build from source

git clone https://github.com/mustafagoksever/java-inspector.git
cd java-inspector
npm install
npm run build

---

Troubleshooting

Log Files

All logs are stored in the cache directory under your user home:

~/.cache/java-inspector/<project>_<hash>/server-<pid>.log

Viewing logs while connected:

# PowerShell
Get-Content ~/.cache/java-inspector/<project>_<hash>/server-<pid>.log -Wait -Tail 20

# Unix/macOS
tail -f ~/.cache/java-inspector/<project>_<hash>/server-<pid>.log

Log files are cleared when cache is invalidated (forceRefresh: true or hash mismatch).

Tag	Description
[SERVER]	Server startup/shutdown
[AUTO-SCAN]	Automatic scan on startup
[MAVEN]	Maven command resolution & classpath building
[SCAN]	Background JAR scanning
[JAVAP]	javap class analysis
[DECOMPILE]	Vineflower decompilation
[TOOL:<name>]	Tool call entry/exit with duration
[CACHE]	Cache invalidation & state
[LOCK]	Cross-process lock acquire/release/compromise

Common Issues

"command not found" error

• Ensure Node.js and npm are in your PATH.

Maven not found

• Set MAVEN_HOME environment variable or ensure Maven is in your PATH.
• Try using mvnd (Maven Daemon) for ~2x faster resolves.

Lock timeout errors

• If a process was killed with SIGKILL while scanning, locks become stale after 60 seconds.
• Another process can then acquire the lock. No action needed unless the problem persists.

Cache problems

• Call scan_dependencies with forceRefresh: true to clear cache and restart.

---

Technical stack

Layer	Technology
Language	TypeScript 5.7
Runtime	Node.js 16+
Protocol	Model Context Protocol (MCP)
Decompiler	Vineflower 1.11.2 (bundled)
JAR reader	yauzl (streaming, lazy entries)
Build tool	tsc
Package manager	npm
License	Apache-2.0

---

Performance Test Results

Spring AI Project Test (April 2026)

Test Environment: Windows, Maven Daemon (mvnd) Project: Spring AI (multi-module project)

Operation	Time
Maven classpath resolution (185 JARs)	44.87s
Background scan (185 JARs, 30,612 classes)	12.38s
Total initial scan	~57s
analyze_class (UserMessage)	<1s
decompile_class (UserMessage)	<1s
search_class (query: "UserMessage")	<1s

Notes:

• First call triggers classpath resolution + background scan (non-blocking)
• Subsequent calls use cached index (in-memory Map)
• Cross-process locking prevents duplicate scans

License

Apache-2.0