jar-inspector-mcp

An MCP server that lets Claude Code read inside Java archives — classes, APIs, sources, resources, bytecode — without extracting them.

The problem

When Claude Code works on a JVM project and needs to know what is inside a jar, it falls back on shell tools:

unzip -l target/lib/jackson-databind-2.16.1.jar     # 780 lines of entry listing
unzip -o app.jar -d /tmp/x && cat /tmp/x/…/Foo.java # a whole file to answer one question
javap -p -c -cp app.jar com.acme.Foo                # 300 KB of bytecode

All of it lands in the context window, most of it is noise, and some of it writes temporary files into the working tree.

The solution

Ten focused tools that answer the actual questions — "what is in this jar", "what is this class's API", "where is this string set" — and return only that.

Measured on jackson-databind-2.16.1.jar (779 classes, 4.1 MB extracted):

Nothing is ever written to disk, and no JDK is required — the class file parser is pure Python. (jar_disassemble is the one exception; it shells out to javap.)

Install

Requires uv and Python 3.10+.

# from GitHub, nothing to clone
claude mcp add jar-inspector -- uvx --from git+https://github.com/pgatzka/jar-inspector-mcp jar-inspector-mcp

# or from a local clone
git clone https://github.com/pgatzka/jar-inspector-mcp && cd jar-inspector-mcp
claude mcp add jar-inspector -- uv run --directory "$PWD" jar-inspector-mcp

Add --scope project to share it with a repo through .mcp.json, or --scope user to enable it everywhere. To wire it up by hand instead:

// .mcp.json
{
  "mcpServers": {
    "jar-inspector": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/pgatzka/jar-inspector-mcp", "jar-inspector-mcp"]
    }
  }
}

Verify with claude mcp list, or /mcp inside Claude Code.

Other MCP clients: the server speaks stdio, so uvx --from … jar-inspector-mcp works as the command anywhere.

Tools

Every tool is read-only and takes a jar argument that accepts:

• an archive — .jar, .war, .ear, .aar, .zip, .jmod

• an exploded classes directory — target/classes, build/classes/java/main

• a nested archive — app.jar!BOOT-INF/lib/dep-1.0.jar (Spring Boot fat jars)

What the output looks like

jar_class_outline, verbatim (this is the exact output the tests assert on):

com.acme.demo.UserService  [class, Java 21, UserService.java]
// source is attached -- jar_read_source(jar, 'com.acme.demo.UserService') shows it

@Deprecated
@Marker(enabled=true, code='z', tags={"alpha", "beta"})
public class UserService implements Repository<String, Integer>

  // fields (2)
  public static final String CACHE_KEY = "user.cache"
  protected volatile boolean dirty

  // constructors (1)
  public UserService(Map<Integer, String> users)

  // methods (5)
  public long count()
  public List<String> findAll()
  public Optional<String> findById(Integer id) throws IllegalStateException
  public <R extends Comparable<R>> List<R> mapAll(Function<String, R> fn)
  public void rename(int id, String newName, String... aliases)

  // nested (1)
  UserService.Builder

  // 4 more member(s) hidden (visibility below 'protected', synthetic or bridge)

Generic signatures, parameter names (when compiled with -g), varargs, declared exceptions, constant values, records, enums and default methods all survive. Method bodies, bridge methods and constant pools do not.

Configuration

jar_find searches, in order: ./target, ./build/libs, ./libs, ./lib, the Maven repository, the Gradle module cache, the Ivy cache and the Coursier cache.

To confine the server to one tree:

claude mcp add jar-inspector --env JAR_INSPECTOR_ALLOW="$HOME/work:$HOME/.m2" \
  -- uvx --from git+https://github.com/pgatzka/jar-inspector-mcp jar-inspector-mcp

Nudging Claude to use it

The server ships MCP instructions telling clients these tools replace unzip, jar xf and javap. If you still see Claude reaching for the shell, add a line to your project's CLAUDE.md:

To inspect jars, use the jar-inspector MCP tools instead of unzip/jar/javap.

How it works

• Class parsing is a dependency-free reader for the class file format: constant pool, access flags, Signature, MethodParameters, LocalVariableTable, Exceptions, Record, InnerClasses and the runtime annotation attributes. Method bodies are skipped unless jar_disassemble asks for them.

• Archives are read through zipfile in memory. Nested jars are opened from the bytes of the outer entry, so a Spring Boot fat jar needs no unpacking.

• Sources are resolved from the archive itself, then from the sibling -sources.jar in Maven layout, then from the neighbouring hash directory that Gradle's cache uses.

• Output is always capped and always says when it was truncated and how to page.

Development

uv sync
uv run pytest          # 49 tests

The tests compile the Java in tests/java with javac and assert against real bytecode, so generics, bridge methods and records are exercised for real; they skip when no JDK is present. The parser is additionally checked against every class in every jar shipped with Maven and Gradle — 65,573 classes, no failures.

License

MIT