jar-inspector-mcp

Ein MCP-Server, mit dem Claude Code in Java-Archive hineinlesen kann — Klassen, APIs, Quellen, Ressourcen, Bytecode — ohne sie zu entpacken.

Das Problem

Wenn Claude Code an einem JVM-Projekt arbeitet und wissen muss, was in einem jar steckt, weicht es auf Shell-Werkzeuge aus:

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 das landet im Kontextfenster, das meiste davon ist Rauschen, und einiges davon schreibt temporäre Dateien in den Arbeitsbaum.

Die Lösung

Zehn fokussierte Werkzeuge, die die tatsächlichen Fragen beantworten — „Was ist in diesem jar?“, „Wie sieht die API dieser Klasse aus?“, „Wo wird dieser String gesetzt?“ — und genau das zurückgeben.

Gemessen an jackson-databind-2.16.1.jar (779 Klassen, 4,1 MB entpackt):

Es wird nie etwas auf die Festplatte geschrieben und kein JDK ist erforderlich — der Parser für Klassendateien ist reines Python. (jar_disassemble ist die einzige Ausnahme; er ruft javap von der Shell aus auf.)

Installation

Voraussetzungen: uv und 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

Füge --scope project hinzu, um es über .mcp.json mit einem Repository zu teilen, oder --scope user, um es überall zu aktivieren. Um es stattdessen manuell zu verdrahten:

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

Verifiziere mit claude mcp list" oder /mcp` in Claude Code.

Andere MCP-Clients: Der Server spricht stdio, daher funktioniert uvx --from … jar-inspector-mcp überall als Befehl.

Werkzeuge

Jedes Werkzeug ist schreibgeschützt und erwartet ein jar-Argument. Dieses akzeptiert:

• ein Archiv — .jar, .war, .ear, .aar, .zip, .jmod

• ein entpacktes Klassenverzeichnis — target/classes, build/classes/java/main

• ein verschachteltes Archiv — app.jar!BOOT-INF/lib/dep-1.0.jar (Spring-Boot-Fat-JARs)

Wie die Ausgabe aussieht

jar_class_outline — unverändert (das ist die genaue Ausgabe, auf die die Tests prüfen):

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)

Generische Signaturen, Parameternamen (bei Kompilation mit -g), Vararg-Parameter, Arrays, Konstanten, Records, Enums und default-Methoden überstehen es. Methodenrüke (Method bodies), Brücken-Methoden und Konstpools überstehen es nicht.

Konfiguration

jar_find durchsucht in dieser Reihenfolge: ./target, ./build/libs, ./libs, ./lib, das Maven-Repository, den Gradle-Modul-Cache, den Ivy-Cache und den Coursier-Cache.

Um den Server auf einen Verzeichnisbaum zu beschränken:

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

Claude dazu bringen, es zu verwenden

Der Server bringt MCP-instructions mit, die Clients darüber informieren, dass diese Werkzeuge unzip, jar xf und javap ersetzen werden. Wenn du immer noch dabei beobachtest, wie Claude zur Shell greift, füge eine Zeile in dein CLAUDE.md in deinem Projekt hinzu:

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

Funktionsweise

• Klassen-Parsing ist ein kalte Abhängigheitsfreier Reader für das Klassendateiformat: Konstantenpool, Zugriffsflags, Attributnamen wie Signature, MethodParameters, LocalVariableTable, Exceptions, Record, InnerClasses sowie die Attributen der Laufzeit-Annotationen. Methodrüke werden übersprungen, außer jar_disassemble fragt danach.

• Archive werden über zipfile im Speicher gelesen. Verschachtelte JARs werden aus den Bytes des äußeren Eintrags geöffnet, sodass ein Spring-Boot-Fat-JAR nicht entpackt werden muss.

• Quellen werden zuerst im Archiv selbst gefunden, danach im benachbarten -sources.jar im Maven-Layout, schließlich im zugehörigen Hash-Dhat, das im Gradle-Cache verwendet wird.

• Ausgabe ist immer begrenzt und sagt immer, wenn sie abgeschnitten wurde und wie man weiterscheidet.

Entwicklung

uv sync
uv run pytest          # 49 tests

Die Tests kompilieren den Java-Code in tests/java mit javac und prüfen gegen echten Bytecode, sodass generics, Brücken-Methoden und Records echte ausprobiert werden; sie werden übersprungen, wenn kein JDK vorhanden ist. Zusätzlich wird der Parser gegen jede Klasse in jedem JAR geprüft, das mit Maven und Gradle ausgeliefert wird — insgesamt 65,573 Klassen, null Fehler.

Lizenz

MIT