jar-inspector-mcp

Claude Code가 Java 아카이브 내부를 읽을 수 있게 해주는 MCP 서버 — 클래스, API, 소스, 리소스, 바이트코드 — 압축을 풀지 않고도 말이죠.

문제

Claude Code가 JVM 프로젝트에서 작업하다가 jar 안에 무엇이 있는지 알아야 할 때, 셸 도구에 의존하게 됩니다:

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가 뭐지", "이 문자열이 어디서 설정되지" — 에 답하고 그 결과만 반환하는 10개의 집중된 도구입니다.

jackson-databind-2.16.1.jar(클래스 779개, 압축 해제 시 4.1MB)에서 측정:

디스크에 기록되는 것은 없으며, JDK도 필요 없습니다 — 클래스 파일 파서는 순수 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 또는 Claude Code 내에서 /mcp로 확인하세요.

다른 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 (Spring Boot fat jar)

출력 예시

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로 컴파일된 경우), 가변 인자, 선언된 예외, 상수 값, 레코드, 열거형 및 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가 셸을 사용하는 모습이 보이면, 프로젝트의 CLAUDE.md에 한 줄을 추가하세요:

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

작동 방식

• 클래스 파싱은 클래스 파일 형식에 대한 의존성 없는 리더입니다: 상수 풀, 접근 플래그, Signature, MethodParameters, LocalVariableTable, Exceptions, Record, InnerClasses 및 런타임 애너테이션 속성. 메서드 본문은 jar_disassemble이 요청하지 않는 한 건너뜁니다.

• 아카이브는 메모리에서 zipfile을 통해 읽습니다. 중첩된 jar는 외부 항목의 바이트에서 열리므로 Spring Boot fat jar는 압축을 풀 필요가 없습니다.

• 소스는 아카이브 자체에서, 그 다음 Maven 레이아웃의 형제 -sources.jar에서, 그 다음 Gradle 캐시가 사용하는 이웃 해시 디렉터리에서 확인됩니다.

• 출력은 항상 제한되며, 잘렸을 때와 페이지를 넘기는 방법을 항상 알려줍니다.

개발

uv sync
uv run pytest          # 49 tests

테스트는 tests/java의 Java를 javac로 컴파일하고 실제 바이트코드에 대해 단언하므로 제네릭, 브리지 메서드, 레코드가 실제로 검증됩니다. JDK가 없으면 건너뜁니다. 파서는 추가로 Maven과 Gradle과 함께 제공되는 모든 jar의 모든 클래스 — 65,573개 클래스 — 에 대해 검사되며 실패가 없습니다.

라이선스

MIT