Easy Code Reader

Easy Code Reader

---

機能

• 🤖 AI にやさしいインテリジェントなヒント：すべてのツールにインテリジェントなエラーヒント機能があり、クエリに失敗すると AI アシスタントに戦略の調整を促します。これにより、ハルシネーションや同じ試行の繰り返しを効果的に減らします
• 📦 Maven リポジトリからソースコードを読み込み：ローカル Maven リポジトリ（起動引数、MAVEN_REPO、Maven settings の設定に対応）から JAR パッケージのソースコードを自動で検索して読み込みます
• 🔍 ソースコードの読み込み：まず sources JAR からソースコードを抽出し、次にディスクキャッシュを再利用します。キャッシュを利用できない場合は、元の JAR をデコンパイルします
• 🛠️ 2 種類のデコンパイラーに対応：実行時の Java バージョンに応じて CFR または Fernflower を選択し、失敗した場合は互換性のある代替デコンパイラーを試します
• ⚡ インテリジェントなキャッシュ機能：デコンパイル結果を Maven のバージョンディレクトリに保存します。SNAPSHOT では最新のタイムスタンプ付きパッケージ名でキャッシュを管理し、入力された実際のパッケージのサイズと変更時刻を検証します
• 🔄 SNAPSHOT に対応：通常の SNAPSHOT メインパッケージを優先して読み込み、最新のタイムスタンプ付きパッケージ名でキャッシュを管理します
• 📄 行単位で読み込み：デフォルトでは全文を返しますが、start_line、end_line を指定して読み取る範囲を指定することもできます

ベストプラクティス

Easy Code Reader は Claude、ChatGPT などの LLM との併用に特に適しています。ここでは、VSCode と Copilot を組み合わせた場合を例に、いくつかのベストプラクティスを紹介します。

jar パッケージのソースコードを読み、ソースコードに基づいて実装する

サードパーティーの依存関係を使用する際、AI アシスタントに MCP 経由で指定バージョンのソースコードを取得させ、実際の実装に基づいて分析できます。Easy Code Reader には、jar パッケージ内のソースコードを読み込む read_jar_source ツールが用意されており、開発時の実装に役立ちます。次のコードを例に説明します。複数のサービスインスタンスを登録したいものの、NamingService の実装を把握していない場合、read_jar_source を活用できます。

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) throws NacosException, InterruptedException {
        logger.info("开始初始化 Nacos 客户端...");

        Properties properties = new Properties();
        properties.put(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
        properties.put(PropertyKeyConst.NAMESPACE, "7430d8fe-99ce-4b20-866e-ed021a0652c9");

        NamingService namingService = NacosFactory.createNamingService(properties);

        System.out.println("=== 注册服务实例 ===");
        try {
            // 注册一个服务实例
            namingService.registerInstance("test-service0", "127.0.0.1", 8080);
            // 添加事件监听器
            namingService.subscribe("test-service", event -> {
                System.out.println("服务实例变化: " + event);
            });
            // 注册多个服务实例

        } catch (Exception e) {
            System.out.println("服务注册失败(预期，因为服务器可能未启动): " + e.getMessage());
        }

        TimeUnit.HOURS.sleep(3);
    }
}

你是一位 Java 技术专家，精通 Nacos 框架，请你帮我在 #file:Main.java 中完成注册多个服务实例的逻辑，在编写代码前，你需要先使用 easy-code-reader 的 read_jar_source 工具读取 com.alibaba.nacos.api.naming.NamingService 的源码信息来了解注册多个服务实例的方法

処理の流れは次のとおりです。

このようにして、NamingService の実装の詳細をすばやく把握し、コードを実装できます。これにより、多くの時間を節約できます。

Easy Code Reader は、次のような用途にも利用できます。

• 例外の迅速な原因調査：外部 JAR パッケージの依存関係から例外がスローされた場合、read_jar_source ツールを使って例外スタックログから例外箇所をすばやく特定できます
• 依存関係のアップグレードによる影響の評価（旧バージョンと新バージョンの差異確認）：同じく read_jar_source ツールを使って、新旧バージョンの実装の差異を確認し、アップグレードの影響を評価できます

---

動作環境

• Python 3.10 以降。
• uv：以下のインストールおよび実行コマンドで使用します。
• Java：デコンパイル結果の生成には、PATH 上に java が必要です。JDK 11 または 21 を推奨します。sources JAR または有効なキャッシュを直接読み込む場合、Java を起動する必要はありません。
• 自動テストの実行には javac が必要です。テストスクリプトでは javac --release 8 を使用します。同じく JDK 11 または 21 を推奨します。
• Inspector ブラウザーを使ったデバッグには、Node.js 22.19.0 以降と npx が必要です。

クイックスタート（方法 1）：uvx を使用（推奨）

次の 2 つの接続方法では、パッケージソース内のリリース済みバージョンを実行します。現在のリポジトリのコードをデバッグする場合は、ローカルでの開発と検証および Inspector によるデバッグを使用してください。

uv がまだインストールされていない場合は、次の方法ですばやくインストールできます。

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

または uv 公式サイトを参照してインストールし、uv のインストール先をシステム PATH に追加して、uvx コマンドを直接使えるようにしてください。uv は非常に高速な Python パッケージおよびプロジェクト管理ツールです。uvx を使えば、事前にインストールすることなく直接実行できます。mcpServers JSON 設定形式を使用するクライアントの場合は、次の例を参照してください。

• --maven-repo：Maven リポジトリのパスを指定します。/custom/path/to/maven/repository をローカル Maven リポジトリのパスに置き換えてください。設定されていない場合は、MAVEN_REPO、ユーザー settings、Maven のグローバル settings の順に読み込み、最後に ~/.m2/repository を使用します

{
  "mcpServers": {
    "easy-code-reader": {
      "command": "uvx",
      "args": [
        "easy-code-reader",
        "--maven-repo",
        "/custom/path/to/maven/repository"
      ],
      "env": {}
    }
  }
}

上記の設定が完了すると、AI アシスタントは MCP プロトコルを介して Easy Code Reader のツールを呼び出し、Maven 依存関係の Java ソースコードを読み込めるようになります。

クイックスタート（方法 2）：uv を使ってローカルにインストール

**クイックスタート（方法 1）**でインストールや実行に失敗する場合は、ローカルに直接インストールできます。次のコマンドを実行してください。

uv tool install easy-code-reader

インストールが成功したら、次のコマンドでインストール先を確認します。

which easy-code-reader

たとえば、出力が /Users/fangyuan/.local/bin/easy-code-reader の場合、これを MCP クライアントの command に設定し、起動引数を args に設定します。

{
  "mcpServers": {
    "easy-code-reader": {
      "command": "/Users/fangyuan/.local/bin/easy-code-reader",
      "args": [
        "--maven-repo",
        "/custom/path/to/maven/repository"
      ],
      "env": {}
    }
  }
}

通常はこの手順でインストールできます。今後バージョンが更新された場合は、次のコマンドでアップグレードできます。

uv tool install --upgrade easy-code-reader

よくある質問

Q1: 起動時に spawn uvx ENOENT と表示されます

uv コマンドが見つかりません。uv が正しくインストールされ、そのパスがシステム PATH に追加されていることを確認してください。動作環境を参照し、IDE を再起動してから MCP Server を起動してください。

Q2: Python または依存関係の初回ダウンロードがタイムアウトします

まずターミナルでクイックスタート（方法 2）に従ってインストールしてから、MCP クライアントを設定してください。ローカルのソースコードをデバッグする場合は、ローカルでの開発と検証に従い、インストール済みの Python を使って環境を作成することもできます。

---

ツールの説明

Easy Code Reader は、Maven 座標の検索と JAR パッケージのソースコードの読み込みに使用する 2 つのツールを提供します。

search_group_id

根据 artifactId 和可选的 groupId 前缀，在本地 Maven 仓库中查找 groupId 及可用版本，辅助调用 read_jar_source。

参数：

• artifact_id（必需）：不含版本号的 Maven artifact ID，例如 spring-core。
• group_prefix（可选）：完整 groupId 前缀（按点号分段匹配，不区分大小写），例如 org.springframework，用于缩小搜索范围。
• version_hint（可选）：版本子串，例如 5.3.21 或 SNAPSHOT；不确定版本时可不传。

每次调用都直接搜索当前 Maven 仓库，不缓存搜索结果。新依赖安装或删除后，下次搜索即可反映变化。

示例：

{
  "artifact_id": "spring-core",
  "group_prefix": "org.springframework",
  "version_hint": "5.3.21"
}

返回内容：

• matches：按 groupId 排序的候选列表，每项包含 group_id、matched_versions（按 Maven 版本顺序降序排列，最多 10 个）和 total_versions。
• total_matches：匹配的 groupId 数量。
• search_stats：实际扫描目录数和耗时；scanned_groups 保留为扫描目录数的兼容字段。
• hint：后续操作建议。

典型工作流：

1. 使用 search_group_id 查找 groupId 和可用版本。
2. 从结果中选择正确的 Maven 坐标。
3. 使用 read_jar_source 读取指定类的源码。

没有匹配结果时，检查 artifact ID 拼写，放宽 group_prefix 或移除 version_hint 后重试。

read_jar_source

从本地 Maven 依赖读取 Java 类源码，依次尝试 sources JAR、反编译缓存和原始 JAR 反编译。

参数：

• group_id (必需): Maven group ID，例如 org.springframework
• artifact_id (必需): Maven artifact ID，例如 spring-core
• version (必需): Maven version，例如 5.3.21
• class_name (必需): 完全限定的类名，例如 org.springframework.core.SpringVersion
• prefer_sources（可选，默认 true）：优先读取 sources JAR；设为 false 时跳过源码包，但仍会复用有效的反编译缓存。
• start_line / end_line（可选）：从 1 开始，包含首尾；不传时保持全文返回。只传一端时读取到对应文件边界。起始行越界或范围倒置返回错误，结束行超过文件长度时取文件末尾。

读取流程：

1. 校验参数，定位 Maven 依赖；二进制主包存在时，先确认目标 .class 条目及基本文件头有效。
2. prefer_sources=true 时，尝试从 sources JAR 读取目标源码；支持只有源码包的依赖版本。
3. 源码不可用时，检查 easy-code-reader/ 下的正式缓存。缓存有效则直接返回。
4. 缓存未命中时，反编译器直接读取原始 JAR，反编译整个包，再从结果中读取请求类的源码。
5. 结果校验并写入正式缓存后，执行缓存容量清理和本次临时目录清理，然后返回源码。

SNAPSHOT 选择规则：

仓库中的主包	实际反编译输入	缓存文件名
普通 SNAPSHOT 和时间戳包都存在	普通 SNAPSHOT 主包	最新时间戳主包名
只有普通 SNAPSHOT 主包	普通 SNAPSHOT 主包	与主包同名
只有时间戳主包	最新时间戳主包	与该时间戳包同名

时间戳按日期时间和数字构建号排序。普通 SNAPSHOT 主包优先使用普通 sources，缺失时尝试该时间戳构建的 sources；直接读取时间戳主包时匹配其 sources。普通发布版本精确匹配主包及对应 sources。

内部类名使用 Outer$Inner，必要时返回包含它的外部类源码并附带提示。仅有 sources JAR 时也可以读取；tests、all 等 classifier 包不会被当作主包。

错误处理：

失败时 MCP 响应设置 isError=true，文本内容中的 JSON 包含 error.code、error.message 和 error.hint。例如：

{
  "error": {
    "code": "ARTIFACT_NOT_FOUND",
    "message": "未找到 JAR 文件: org.example:demo:1.0",
    "hint": "使用 search_group_id 核对 Maven 坐标。"
  }
}

常见错误码包括 INVALID_ARGUMENT、CONFIG_ERROR、ARTIFACT_NOT_FOUND、CLASS_NOT_FOUND、SOURCE_DECODE_ERROR、INVALID_JAR、DECOMPILER_UNAVAILABLE、DECOMPILE_FAILED、DECOMPILE_TIMEOUT、CACHE_UNAVAILABLE 和 INPUT_CHANGED。

JAR 缺失时可先用 search_group_id 核对坐标；依赖需要预先通过 Maven 下载或安装到本地仓库。反编译失败会返回错误说明。

示例：

{
  "group_id": "org.springframework",
  "artifact_id": "spring-core",
  "version": "5.3.21",
  "class_name": "org.springframework.core.SpringVersion"
}

返回结构示例（code 已简化）：

{
  "class_name": "org.springframework.core.SpringVersion",
  "artifact": "org.springframework:spring-core:5.3.21",
  "source_type": "sources.jar",
  "code": "package org.springframework.core;\n\npublic class SpringVersion {\n    // ...\n}"
}

全文读取仅返回上面四个字段。显式传入行范围时，另外返回 total_lines、start_line、end_line 和 is_partial。内部类映射或源码解码回退等特殊情况可附带简短的 warnings。实际 JAR 路径和解析版本仅用于内部处理及调试日志。

source_type 字段说明：

source_type 字段标识源码的来源，帮助 AI 助手了解代码的可靠性和新鲜度：

• "sources.jar"：从本地 sources JAR 提取的源文件
• "decompiled": 通过反编译器新反编译生成（可能存在反编译不完整的情况）
• "decompiled_cache": 从之前反编译的缓存中读取（避免重复反编译，提升性能）

💡 使用建议：

• 有 sources JAR 时优先阅读其中的原始源码
• decompiled 来源的代码可能会有语法糖恢复、泛型擦除等反编译特征
• decompiled_cache 与 decompiled 质量相同，只是从缓存读取以提升效率

---

技术细节

项目结构

easy-code-reader/
├── src/easy_code_reader/
│   ├── __init__.py          # Python 包入口
│   ├── __main__.py          # 程序入口点
│   ├── server.py            # 两个 MCP Tool 与使用指南
│   ├── service.py           # 源码读取流程
│   ├── repository.py        # Maven 文件解析与实时搜索
│   ├── versions.py          # Maven 版本排序
│   ├── source.py            # 内部类、源码提取与行范围
│   ├── cache.py             # 按 JAR 名称保存的磁盘缓存
│   ├── errors.py            # 统一错误
│   ├── io_utils.py          # 可安全取消的文件操作调度
│   ├── config.py            # 配置管理
│   ├── decompiler.py        # 反编译器集成
│   └── decompilers/         # 反编译器 JAR 文件目录
│       ├── fernflower.jar   # Fernflower 反编译器
│       └── cfr.jar          # CFR 反编译器
├── tests/                   # 测试文件
├── scripts/                 # MCP 冒烟验证与发布脚本
├── docs/CHANGELOG.md         # 版本变更说明
├── pyproject.toml           # Python 项目配置
├── requirements.txt         # Python 依赖
└── README.md                # 本文档

反编译器

按运行时 Java 版本选择优先使用的反编译器：

Java 运行时版本	优先使用	说明
6–20	CFR	使用随包提供的 decompilers/cfr.jar
21 及以上	Fernflower	使用随包提供的 decompilers/fernflower.jar，失败时可尝试 CFR

只有满足 Java 运行要求且文件可用的反编译器会被执行；尝试备用反编译器也计入同一次请求的超时预算。Fernflower 显式开启泛型签名恢复（-dgs=1），以保留字节码中已有的泛型信息。反编译结果仍可能存在语法糖等还原差异。

逆コンパイルキャッシュと実行

キャッシュは実際の JAR が置かれているバージョンディレクトリ内の easy-code-reader/ に直接保存されるため、キャッシュパスを個別に設定する必要はありません。通常のバージョンでは元の JAR と同じ名前を使用します。SNAPSHOT では、タイムスタンプ付きパッケージがある場合は最新のタイムスタンプ付きパッケージ名を使用し、ない場合は通常の SNAPSHOT パッケージ名を使用します。

~/.m2/repository/org/example/demo/1.0-SNAPSHOT/
├── demo-1.0-SNAPSHOT.jar            # 优先作为反编译输入
├── demo-1.0-20260916.120000-2.jar    # 用于确定缓存版本名称
└── easy-code-reader/
    └── demo-1.0-20260916.120000-2.jar

最新のタイムスタンプ付きパッケージ名が変わると、新しいキャッシュファイルが使用されます。キャッシュには、実際に読み込んだ入力パッケージのサイズと更新日時が記録されます。通常の SNAPSHOT パッケージが更新された場合、タイムスタンプ付きファイル名が変わらなくてもキャッシュが再生成されます。同名のファイルが上書きされ、サイズと更新日時のどちらも変わらない場合は、対応するキャッシュを手動で削除する必要があります。

キャッシュがヒットした場合は、ディスク上のファイルを直接読み込みます。キャッシュがない場合、逆コンパイラーは解析された元の JAR を直接読み込み、中間出力を独立した一時ディレクトリに書き込みます。逆コンパイル結果を検証し、元のファイルに変更がないことを確認した後、アトミック置換によって正式なキャッシュに書き込みます。同時リクエストではそれぞれ独自の一時出力ディレクトリを使用し、完了後にクリーンアップします。

新しいキャッシュを生成するたびに、そのバージョンディレクトリの既定の予算である 1 GiB に基づき、長期間使用されていない新形式のキャッシュを削除します。今回生成したキャッシュは、その回のクリーンアップでは削除されないため、予算を一時的に超えることがあります。同名の既存キャッシュに入力検証情報がない場合、次回対応する JAR を読み込む際に再生成されます。

逆コンパイルには、対応する Maven キャッシュディレクトリへの書き込み権限が必要です。権限が不足している場合は明確なエラーが表示されます。sources JAR を直接読み込む場合、キャッシュへの書き込みは不要です。Python のインストールディレクトリへの書き込み権限は必要ありません。

• --decompile-timeout：逆コンパイルリクエストの制限時間。既定値は 60 秒です。タイムアウトまたはキャンセル時には、Java プロセスを終了して回収します。
• ログは stderr にのみ出力され、インストールディレクトリにファイルは作成されません。
• ソースコードは厳密な UTF-8 でデコードされます。失敗した場合は対応するバイナリパッケージにフォールバックし、warnings が付加されます。
• MCP 呼び出しは、ソースの読み込みまたは逆コンパイルが完了してから結果を一括で返します。非同期サブプロセスにより、Java の処理中もサーバーは他のリクエストやキャンセルを引き続き処理できます。バックグラウンドタスク ID は返されず、クライアントによるポーリングも不要です。

設定と移行

Maven パスの優先順位は、--maven-repo → MAVEN_REPO → ~/.m2/settings.xml の localRepository → Maven インストールディレクトリの conf/settings.xml → ~/.m2/repository です。MAVEN_HOME / M2_HOME は Maven インストールディレクトリの特定に使用され、/repository は連結されなくなりました。この動作に依存していたユーザーは、--maven-repo を明示的に設定してください。

~、相対パス（サーバーの起動時の作業ディレクトリを基準とします）、${user.home}、${env.NAME} に対応しています。settings 内の変数を解決できない場合はエラーが表示されます。起動パラメーターで上書きできます。

このバージョンには mcp>=1.30,<2 が必要です。read_jar_source は既定で全文を返します。group_prefix は完全な groupId のプレフィックス（例：org.springframework）でセグメント単位の一致を行います。以前のように中間部分文字列を使用している呼び出しは、それに合わせて変更してください。詳しくは1.4.0 変更履歴を参照してください。

ローカル開発と検証

以下のコマンドはリポジトリのルートディレクトリから実行します。macOS/Linux に対応しています。.venv がすでにある場合は、環境の作成を省略できます。

uv venv .venv --python python3
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m easy_code_reader --help
.venv/bin/python -m pytest -q
.venv/bin/python scripts/smoke_test.py

編集可能インストールを行うと、現在のリポジトリのコードが読み込まれます。スモークテストスクリプトは一時的な Maven リポジトリと実際にコンパイルした JAR を作成し、MCP stdio 経由でツールの検出、検索、全文／分割読み込み、逆コンパイル、キャッシュ、エラーレスポンスを検証します。成功すると "smoke": "passed" と各ステップの所要時間が出力されます。

mcpServers JSON 設定を使用するクライアントでは、ローカル仮想環境の Python の絶対パスを command に設定できます。

{
  "mcpServers": {
    "easy-code-reader-local": {
      "command": "/absolute/path/to/easy-code-reader/.venv/bin/python",
      "args": [
        "-m",
        "easy_code_reader",
        "--maven-repo",
        "/absolute/path/to/maven/repository"
      ]
    }
  }
}

このプロジェクトは stdio 通信を使用し、MCP クライアントがサーバープロセスを起動します。手動で起動した後に入力待ちになるのは正常な動作です。コードを変更した後は、接続を切断して再接続し、Python プロセスにモジュールを再読み込みさせる必要があります。

配布パッケージをビルドして確認します。

.venv/bin/python -m build
.venv/bin/python -m twine check dist/*

Windows では .venv/bin/python を .venv/Scripts/python.exe に置き換え、使用するターミナルに応じたパス構文を使用してください。

MCP Inspector を使用したデバッグ

ローカルでの編集可能インストールが完了したら、以下の検証済み Inspector 2.7.0 コマンド（macOS/Linux）を使用できます。リポジトリのパスは ~/.m2/repository を例としており、実際のパスに置き換えられます。

npx --registry=https://registry.npmjs.org -y \
  @modelcontextprotocol/[email protected] \
  "$PWD/.venv/bin/python" -- \
  -m easy_code_reader \
  --maven-repo "$HOME/.m2/repository"

このコマンドは今回のダウンロードに npm 公式レジストリを指定するもので、グローバルな npm 設定は変更しません。Inspector がローカルの Web インターフェースを起動します。ターミナルに表示された完全なアドレスを開いてください。アドレスには今回のセッションのアクセストークンが含まれています。

1. Servers で事前入力済みのローカルサービスを選択し、Connect をクリックします。
2. Tools を開き、search_group_id と read_jar_source があることを確認します。
3. まず search_group_id を使用して、artifact_id=spring-core、group_prefix=org.springframework を指定して検索し、ローカルに実在するバージョンを選択します。
4. read_jar_source を呼び出して org.springframework.core.SpringVersion を読み込み、prefer_sources を false に設定して、続けて 2 回呼び出します。有効なキャッシュがない場合、1 回目は decompiled、2 回目以降は decompiled_cache を返します。有効なキャッシュがすでにある場合は、1 回目からキャッシュがヒットすることもあります。
5. start_line と end_line を設定して、分割読み込みを検証することもできます。オプションパラメーターを使用しない場合は、フォームで該当するフィールドを省略してください。

ツールの戻り値は Tools で、プロセスの stderr は Console で、プロトコルのリクエストとレスポンスは Protocol で確認できます。コードを変更した後は、切断してから再接続すると再読み込みされます。

参考：Inspector 公式ドキュメント、Web インターフェースのドキュメント。

現在の適用範囲

入力はローカルの Maven 座標と完全な Java クラス名です。依存関係は事前にリポジトリへダウンロードまたはインストールしておく必要があります。最上位／基本バージョンのクラスパスを読み込みます。ネストされた JAR や Multi-release の実行時バージョンの選択には、現時点では対応していません。

ライセンス

Apache License 2.0。詳しくは LICENSE ファイルを参照してください。

先人の肩の上に立つ

• Github: maven-decoder-mcp
• Github: fernflower
• Github: Model Context Protocol(MCP) プログラミング超速入門