JVM Source Lens

jvmsrc — コーディングエージェントに Java IDE を

問題

Java のコードを書くときには IDE を使います。しかし、コーディングエージェントには IDE がありません。

エージェントが見慣れないライブラリの型、たとえば独自の内部ライブラリにあるスーパークラスに遭遇すると、25 回以上のやり取りを費やして ~/.gradle/caches を探し回り、jar tf で JAR を手作業で開き、推測でそのうちの 1 つを選んで、IDE ならキーを 1 回押すだけで答えられる疑問に答えようとします。つまり、このスーパークラスに X という名前のパブリックなユーティリティメソッドがあるか、という疑問です。

解決策

jvmsrc はビルドツール（Gradle）に問い合わせて、このプロジェクトで解決されたクラスパスを取得し、実際にビルドで使われている正確なバージョンの実際のソース、実際のシグネチャ、実際の構造をエージェントに渡します。

• MCP サーバーとして — Claude Code、Cursor、Windsurf、その他の MCP ホストに接続し、クラスパス専用に設計された 6 つのツールをエージェントに提供します。
• jvmsrc CLI として — 同じエンジンを使い、スクリプトで利用でき、パイプにも対応しています。クラスを読むだけなら、単独でも便利です。

Claude Code が jvmsrc を使って HandlerInterceptor のシグネチャを解決。3 回の呼び出しで正確な答えに到達し、キャッシュを探し回る必要はありません。

毎日削減できること

プライベートライブラリがあり、公開 Javadoc がない JVM プロジェクトでは、jvmsrc が作業効率を大きく高めます。

• 「この外部クラスには何があるか」という調査 1 件あたり約 50K トークンを節約 — コストを**約 70%**削減します。
• エージェントのパニックループを毎日 15 回以上回避 — Gradle キャッシュを延々と調べたり、間違った JAR を開いたり、諦めたりする必要はありません。
• 以前は自分で対応するしかなかった、内部 SDK に触れる複雑なタスクを委任できるようになります。

実際の違い

jvmsrc なし（25 回のやり取りにわたる手探り）

ユーザー： AbstractTradingService の監査フックをオーバーライドしたいのですが、再利用できるパブリックなユーティリティメソッドはありますか？

エージェント：

1. ワークスペースで AbstractTradingService.java を検索 ➔ 0 hits
2. 実行： find ~/.gradle -name "trading-core*"
3. 4 つのバージョンを発見： 2.1.0、2.3.0、2.4.1、3.0.0-SNAPSHOT
4. 推測： trading-core-2.4.1.jar を選択（実際にプロジェクトで使われているのは 3.0.0-SNAPSHOT！）
5. 間違った JAR に対して jar tf と javap -p を実行
6. ［22 回のやり取りの後］ 「ユーティリティメソッドは見当たりません。ご自身で実装してください。」

実際は： 3.0.0-SNAPSHOT には、この用途にぴったりの maskSensitiveFields() という protected ヘルパーが追加されていました。エージェントは幻覚を起こしたのではなく、ただ見えていなかったのです。

jvmsrc あり（3 回のやり取りで即座に解決）

ユーザー： AbstractTradingService の監査フックをオーバーライドしたいのですが、再利用できるパブリックなユーティリティメソッドはありますか？

エージェント：

1. search_classes("AbstractTradingService") ➔ FQN と、正確に解決されたライブラリを特定します。
2. get_class_structure(scope: "overview") ➔ 3.0.0-SNAPSHOT にある maskSensitiveFields() を見つけます。
3. get_method_signature("maskSensitiveFields") ➔ 正確なシグネチャとジェネリクスを取得します。

結果： 初回から正しくオーバーライドを記述できます。キャッシュを探し回る必要も、推測も、バージョン違いもありません。

仕組み

1. ビルドツールへの問い合わせ： jvmsrc がアクティブなビルドツール（Gradle など）に問い合わせて、正確に解決されたクラスパス設定を取得します。
2. インテリジェントなキャッシュ： 解決されたクラスパスをキャッシュし、ビルドファイルの変更を追跡して最新の状態を保ちます。
3. 精密な AI ツール： コード全体を出力する代わりに、コンテキストウィンドウを小さく保ち、トークン使用量を極めて低く抑えるため、精度と粒度の高いツール（シグネチャ、構造、検索）を提供します。

インストールとクイックスタート

1. CLI をインストール

npm install -g jvmsrc

または、npx から直接実行できます：

npx jvmsrc mcp

重要

Node ≥ 20 と PATH 上の Java（CFR デコンパイラーと javap 用）が必要です。

2. MCP サーバーを追加

これを AI アシスタントの設定（Cursor、Claude Code、Windsurf など）に貼り付けてから、ホストを再起動してください：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

任意：jvmsrc config（または jvmsrc config --project /path/to/gradle-project）を実行すると、貼り付け用のブロックと環境に関するヒントが表示されます。ほとんどのユーザーはこの手順を省略し、上記のスニペットをコピーできます。

MCP サーバーのリファレンス

MCP サーバーは jvmsrc mcp を介して stdio で実行されます。デフォルト設定では環境変数は不要です：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

プライベートリポジトリの認証情報（任意）

Gradle ビルドで、プライベートな Maven／Artifactory／Nexus 系リポジトリ用の認証情報を環境変数で指定する必要がある場合にのみ必要です。MCP ホストは対話型シェルの環境を引き継がないことが多いため、これらの変数は jvmsrc MCP プロセスに設定する必要があります（その後、サーバーを再起動してください）。

以下の REPO_USER／REPO_PASS はサンプル名にすぎません。jvmsrc で必須の変数ではありません。プロジェクトの Gradle スクリプトで指定されている変数名を使用してください：

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"],
      "env": {
        "REPO_USER": "your-username",
        "REPO_PASS": "your-password"
      }
    }
  }
}

プロジェクトでこれらの変数が不要な場合は、env ブロック全体を省略してください。

エージェントが利用できるツール

ヒント

ソースの応答にはすべて sourceAvailable が含まれます。実際のソース（Javadoc、パラメーター名、ジェネリクス）がある場合は true、CFR による逆コンパイルの場合は false です（構造は信頼できますが、名前は合成されたものの場合があります）。

メモ

マルチモジュール： modulePath を省略すると、jvmsrc が該当するモジュールを一意に特定します。特定できない場合は、候補となる modulePath の一覧を表示します。メソッド： インデックスにソース情報が補完されている場合、search_classes は宣言されたメソッド名も検索します。既知の JAR 内で本体のテキストを検索するには search_in_artifact を使用してください。get_class_source の methodNames は、一致しなかった名前についてもスーパークラスを調べます。

エージェントに使わせる

ツールの説明は役立ちますが、エージェントがすでに信頼している組み込みの Bash ツールが優先されることがよくあります。小さな追加を2つ行うと、依存関係に関する質問で jvmsrc がデフォルトになります。

1. エージェントの指示にルールを追加します（CLAUDE.md、AGENTS.md、Cursor のルール）。多くのクライアントでは、MCP サーバーの instructions がまったく表示されません。

## Dependencies (jvmsrc)
For any question about a third-party library class, method or version, use the jvmsrc MCP tools
(search_classes → get_class_structure → get_class_source with methodNames; resolve_dependencies for versions).
When working inside one module, pass modulePath (':app' or the file you are editing) to get that module's versions.
Never use javap, unzip/jar on JARs, or ~/.gradle/caches. Code under this repo's src/ → grep/read as usual.

2. （Claude Code）フックでシェルへのフォールバックをブロックします。 docs/hooks/block-jvm-fallbacks.mjs は、JAR に対する javap、unzip／jar、および ~/.gradle/caches／~/.m2 へのアクセスを拒否し、代わりに jvmsrc を使うようエージェントに伝えます。これにより、間違ったバージョンを黙って読み込むのではなく、処理が切り替わります。スクリプトを安定した場所に保存し、.claude/settings.json（プロジェクト用）または ~/.claude/settings.json（すべてのプロジェクト用）に追加します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node /absolute/path/to/block-jvm-fallbacks.mjs" }]
      }
    ]
  }
}

一時的に無効にするには、JVMSRC_HOOK_DISABLE=1 を設定します。他のクライアントにはそれぞれ独自のフック機構があります。移植する前に、最新のドキュメントを確認してください。

クライアントにサーバーの指示が表示されることを確認します： エージェントに 「jvmsrc MCP サーバーからどのような指示が出ていますか？」 と尋ねます。答えられない場合は、手順1のルールに従ってください。

メモ

入力は柔軟に指定できます。 projectRoot は省略可能です（ワークスペースが使用されるか、JVMSRC_PROJECT_ROOT を設定します）。modulePath には app、/app、:app、またはモジュール内のファイル／ディレクトリを指定できます（省略するか "*" を渡すと、すべてのモジュールが検索されます）。className には単純名、Outer.Inner、末尾に .class／.java を付けた名前を指定できます。プロジェクトでの最初の呼び出しでは Gradle が実行されます（通常5～10秒）。それ以降の呼び出しではキャッシュが使われます。forceRefresh: true を渡すのは、ビルドファイルには示されない変更があった場合（たとえば、SNAPSHOT が再公開された場合）に限ってください。

比較

対象ユーザー

主な対象は、Gradle を使う Java + Spring Boot プロジェクトです。その他の JVM 言語（Kotlin、Scala）と Android は現在ベストエフォートで動作し、今後、正式な対象としてロードマップに追加される予定です。詳しくは ROADMAP.md を参照してください。

Maven または Bazel をお使いの場合、対応は計画中ですが、まだリリースされていません。リポジトリにスターを付けるか、Issue を作成してください。優先順位の参考にします。

詳細リファレンス

jvmsrc com.example.MyClass -p /path/to/gradle-project          # shorthand for get
jvmsrc get com.example.MyClass -p /path/to/project -q > MyClass.java
jvmsrc resolve -p /path/to/project --force-refresh
jvmsrc config jdk-roots add /path/to/jdks                      # one-time JDK roots setup
jvmsrc doctor java -p /path/to/project                         # check JDK requirement + selection
jvmsrc diagnostics last                                         # latest failure message
jvmsrc mcp                                                     # run as MCP server

プロジェクトドキュメント

ソースからのビルド

git clone https://github.com/Sintexer/jvm-source-lens.git
cd jvm-source-lens
bun install && bun run setup:cfr && bun run build
node dist/cli.js --version

貢献に関するワークフロー全体については、CONTRIBUTING.mdをご覧ください。

Java のコードを書くのは得意でも、実際のクラスパスを把握できないエージェントに何度も悩まされてきたため、jvmsrcを作りました。これによって、私が経験した25ターンの苦労を皆さんがせずに済むなら、それこそがこのツールを作った理由です。バグを見つけた方、アイデアがある方、あるいは役に立ったと伝えたい方は、Issue または PR をお寄せください。すべて目を通しています。

ライセンス

MIT — LICENSEをご覧ください。