jar-inspector-mcp

MCP-сервер, который позволяет Claude Code читать внутри Java-архивов — классы, API, исходники, ресурсы, байткод — без их извлечения.

Проблема

Когда Claude Code работает над JVM-проектом и ему нужно узнать, что внутри jar-файла, он прибегает к shell-инструментам:

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

Всё это попадает в контекстное окно, большая часть — шум, а кое-что записывает временные файлы в рабочее дерево.

Решение

Десять узконаправленных инструментов, которые отвечают на фактические вопросы — «что в этом jar», «каков API этого класса», «где задаётся эта строка» — и возвращают только это.

Измерено на jackson-databind-2.16.1.jar (779 классов, 4.1 МБ в распакованном виде):

Ничего не записывается на диск, и JDK не требуется — парсер class-файлов написан на чистом Python. (jar_disassemble — единственное исключение; он вызывает javap.)

Установка

Требуется uv и 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

Добавьте --scope project, чтобы поделиться им с репозиторием через .mcp.json, или --scope user, чтобы включить его везде. Чтобы подключить вручную:

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

Проверьте с помощью claude mcp list или /mcp внутри Claude Code.

Другие MCP-клиенты: сервер говорит по stdio, так что uvx --from … jar-inspector-mcp работает как команда где угодно.

Инструменты

Каждый инструмент доступен только для чтения и принимает аргумент jar, который может быть:

• архивом — .jar, .war, .ear, .aar, .zip, .jmod

• развёрнутым каталогом классов — target/classes, build/classes/java/main

• вложенным архивом — app.jar!BOOT-INF/lib/dep-1.0.jar (толстые jar-файлы Spring Boot)

Как выглядит вывод

jar_class_outline, дословно (это точный вывод, на который опираются тесты):

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)

Обобщённые сигнатуры, имена параметров (при компиляции с -g), varargs, объявленные исключения, константные значения, записи (records), перечисления и методы default сохраняются. Тела методов, мостовые методы и пулы констант — нет.

Конфигурация

jar_find ищет по порядку: ./target, ./build/libs, ./libs, ./lib, репозиторий Maven, кэш модулей Gradle, кэш Ivy и кэш Coursier.

Чтобы ограничить сервер одним деревом:

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 использовать его

Сервер поставляется с MCP-instructions, сообщающими клиентам, что эти инструменты заменяют unzip, jar xf и javap. Если вы всё ещё видите, что Claude тянется к shell, добавьте строку в CLAUDE.md вашего проекта:

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

Как это работает

• Разбор классов — это независимый от зависимостей читатель формата class-файлов: пул констант, флаги доступа, Signature, MethodParameters, LocalVariableTable, Exceptions, Record, InnerClasses и атрибуты аннотаций времени выполнения. Тела методов пропускаются, если только jar_disassemble не запрашивает их.

• Архивы читаются через zipfile в памяти. Вложенные jar-файлы открываются из байтов внешней записи, поэтому толстый jar Spring Boot не требует распаковки.

• Исходники ищутся в самом архиве, затем в соседнем -sources.jar в структуре Maven, затем в соседнем хэш-каталоге, который использует кэш Gradle.

• Вывод всегда ограничен и всегда сообщает, когда он был обрезан и как листать дальше.

Разработка

uv sync
uv run pytest          # 49 tests

Тесты компилируют Java-код в tests/java с помощью javac и проверяют реальный байткод, так что обобщения, мостовые методы и записи проверяются по-настоящему; они пропускаются, если JDK отсутствует. Парсер дополнительно проверяется на каждом классе в каждом jar-файле, поставляемом с Maven и Gradle — 65 573 класса, без сбоев.

Лицензия

MIT