Java Inspector

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

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