Maven Decoder

Maven Decoder MCP サーバー

エージェントは、読んだことのないライブラリの API を推測してしまいます。このツールを使えば、実際に読めるようになります。

AI エージェントが Maven 依存関係の実際のソースを読めるようにします。~/.m2 または Maven Central から jar を逆コンパイルし、バージョン間の破壊的変更を比較します。

エージェントに 「org.jsoup:jsoup を 1.17.2 から 1.23.2 にアップグレードします。何が壊れますか？」 と尋ねても、jar を読む手段がなければ、記憶を頼りに回答するだけです。このサーバーでは、compare_versions が両方の jar を読み取り、実際に変更された内容を報告します。

	1.17.2 → 1.23.2
破壊的変更	45
削除されたメンバー	31
追加されたメンバー	150
API が変更されたクラス	比較対象 115 クラス中 47 クラス

メンバーは宣言どおりに比較されるため、スーパータイプに移動したメンバーは、引き続き呼び出せる場合でも削除されたものとして報告されます。この点はツールの出力にも明記されます。

sources jar がない成果物にも対応しています。extract_class_info は javap にフォールバックし、解析済みのフィールド、メソッド、バイトコードのバージョンを返します。これは、企業内の Nexus にある内部成果物でまさに当てはまるケースです。

1 つのコマンドで試す

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

これにより、エージェントがこれらのツールを使うべき場面を判断するための maven-code-search エージェントスキルがインストールされます。MCP サーバーを直接セットアップする場合は、インストールをご覧ください。

🚀 特長

主な機能

• Jar ファイルの解析：メタデータ、マニフェスト、構造など、jar ファイルを詳細に調査します
• 依存関係の解決：推移的依存関係を含む、依存関係ツリー全体を解析します
• ソースコードの抽出：ソース jar からソースコードを抽出するか、バイトコードを逆コンパイルします
• クラス情報：クラスのシグネチャ、メソッド、フィールド、アノテーションを詳細に表示します
• 検索機能：すべての成果物からクラス、メソッド、依存関係を検索します
• バージョン管理：バージョンを比較し、依存元を調べ、バージョンの競合を追跡します

Maven オンライン対応

• Maven Central の検索：ローカルにインストールされていない成果物やクラスを検索します
• リモートバージョンの一覧表示：手元にあるものだけでなく、公開済みのすべてのバージョンを確認できます
• オンデマンドダウンロード：任意の成果物（jar、sources、POM）をローカルキャッシュに取得します
• 透過的なフォールバック：すべての解析ツールは、見つからない成果物を自動的にダウンロードするため、一度もインストールしたことのない依存関係もそのまま逆コンパイルできます
• ミラー対応：認証情報を設定して、社内の Nexus／Artifactory を指定できます
• オフラインモード：環境変数を 1 つ設定するだけで、ネットワークを使わずローカルのみで動作する状態に戻せます

高度な機能

• 逆コンパイル対応：複数の Java デコンパイラー（CFR、Fernflower、Procyon）に対応しています
• 競合解析：依存関係のバージョン競合を検出して解析します
• リポジトリのナビゲーション：ローカルの Maven リポジトリ構造を参照、探索できます
• メタデータ解析：Maven POM ファイルとメタデータを抽出して解析します
• サービスの検出：Java サービスと SPI 実装を検索、解析します
• 応答の管理：大きな応答を対象に、インテリジェントなページネーションと要約を行います
• メソッドの抽出：大きな Java クラスから特定のメソッドを抽出します
• 整合性チェック：ダウンロードしたファイルは、リポジトリの SHA-1 チェックサムと照合して検証されます

📦 インストール

前提条件

• Java 8 以降（逆コンパイル機能用）
• Maven ローカルリポジトリ（~/.m2/repository）
• 次のいずれか：Python 3.8 以降、Node.js 14 以降、または Docker

🚀 クイックインストール

ワンラインインストール（推奨）

curl -fsSL https://raw.githubusercontent.com/salitaba/maven-decoder-mcp/main/install.sh | bash

📋 インストール方法

方法 1：uvx（推奨）

# Install uv (if not installed)
curl -Ls https://astral.sh/uv/install.sh | sh
# Ensure your shell PATH is updated (restart shell or eval as printed by installer)

# Run the server via uvx (isolated, fast, no venv needed)
uvx maven-decoder-mcp

# Optional: pick a specific Python
# uvx --python 3.12 maven-decoder-mcp

方法 2：Node.js／npm

# Install globally
npm install -g maven-decoder-mcp

# Or install locally
npm install maven-decoder-mcp

# Run the server
maven-decoder-mcp
# or if installed locally: npx maven-decoder-mcp

方法 3：Docker

# Pull and run
docker run --rm -it \
  -v ~/.m2:/home/mcpuser/.m2 \
  -v $(pwd):/workspace \
  ali79taba/maven-decoder-mcp:latest

方法 4：ソースからインストール（開発用）

# Clone repository
git clone https://github.com/salitaba/maven-decoder-mcp.git
cd maven-decoder-mcp

# Option A: Using Virtual Environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install "git+https://github.com/modelcontextprotocol/python-sdk.git"
./setup_decompilers.sh

# Option B: System-wide Installation (not recommended)
./setup_decompilers.sh

Windows

ソースのチェックアウトでは、Python 3.10 以降と PATH 上の JDK を使用します。リポジトリのルートから、PowerShell で仮想環境を作成して有効化します。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

# Point to your existing local Maven repository (drive-letter paths are supported)
$env:MAVEN_REPOSITORY = 'F:\data\repository'
maven-decoder-mcp

コマンドプロンプト（cmd.exe）では、.venv\Scripts\activate.bat で有効化し、代わりに set "MAVEN_REPOSITORY=F:\data\repository" でリポジトリを設定します。これらの環境設定は、そのターミナルから起動したプログラムに適用されます。MCP クライアントが別途サーバーを起動する場合は、クライアントの環境に設定してください。

リモートダウンロードでは、別のキャッシュを使用します。キャッシュの場所は次の順に解決されます（空の値はスキップされます）。

1. MAVEN_DECODER_CACHE_DIR：キャッシュディレクトリ全体を指定します。サブディレクトリは追加されません。
2. XDG_CACHE_HOME：maven-decoder-mcp\repository を追加します。
3. LOCALAPPDATA：maven-decoder-mcp\repository を追加します。
4. それ以外の場合は、ホームディレクトリの ~/.cache/maven-decoder-mcp/repository を使用します。

Windows では通常 %LOCALAPPDATA%\maven-decoder-mcp\repository が使用されます。XDG_CACHE_HOME が設定されている場合は、そちらが優先されます。キャッシュは Maven のディレクトリレイアウトを使用しますが、実際のローカルリポジトリとは分離されているため、ダウンロードが Maven のビルドに影響することはありません。MAVEN_REPOSITORY を設定しても、キャッシュの場所は変わりません。

🔧 Configuration

Cursor IDE の場合

~/.cursor/mcp_servers.json に追加します。

{
  "maven-decoder": {
    "command": "uvx",
    "args": ["maven-decoder-mcp"]
  }
}

その他の MCP クライアントの場合

このサーバーは標準の MCP サーバーとして実行され、MCP 対応のあらゆるクライアントと統合できます。

🧠 AI エージェントスキル

このリポジトリには、インストール済みの Maven パッケージのコードを検索する際に、この MCP をいつ、どのように使用するかを AI コーディングエージェントに伝える maven-code-search エージェントスキルが含まれています。

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

このスキルは skills/maven-code-search にあり、リポジトリをプッシュすると skills.sh でインデックス化できる状態になります。

🛠️ 利用可能なツール

ローカル分析

ツール	説明
list_artifacts	Maven リポジトリ内のアーティファクトをフィルタリングして一覧表示します
analyze_jar	JAR ファイルの構造と内容を分析します
extract_class_info	Java クラスの詳細情報を取得します
get_dependencies	POM ファイルから Maven の依存関係を取得します
search_classes	アノテーションによる任意のフィルタリングに対応し、すべての JAR 内のクラスを検索します
extract_source_code	Java ソースコードを逆コンパイルして抽出します
extract_jar_resource	.proto ファイル、サービス、メタデータなどのテキストリソースを抽出します
compare_versions	公開 API の差分と破壊的変更を含め、2 つのバージョンを比較します
find_usage_examples	指定されたクラスまたはメソッドを参照するクラスを検索します
get_dependency_tree	依存関係ツリー全体を取得します
find_dependents	特定のアーティファクトに依存するアーティファクトを検索します
get_version_info	アーティファクトのインストール済みバージョンを取得します（公開済みバージョンを追加するには include_remote を設定します）
analyze_jar_structure	JAR の全体的な構造とメタデータを分析します
extract_method_info	Java クラスから特定のメソッド情報を抽出します

オンライン（Maven Central）

ツール	説明
search_maven_central	名前、座標、または含まれるクラスを指定して Maven Central のアーティファクトを検索します
get_remote_versions	リモートで公開されているすべてのバージョンを一覧表示し、インストール済みのものに印を付けます
download_artifact	アーティファクト（JAR／ソース／POM）をローカルキャッシュにダウンロードします。latest を指定できます

ツールのパラメーター

ツール	パラメーター	型	デフォルト	説明
list_artifacts	group_id	string	—	グループ ID で絞り込みます（例：'org.springframework'）
list_artifacts	artifact_id	string	—	アーティファクト ID で絞り込みます（例：'spring-core'）
list_artifacts	version	string	—	バージョンで絞り込みます（例：'5.3.21'）
list_artifacts	sort_by	string	name	結果の並べ替え基準：'name'（グループ／アーティファクト／バージョンの昇順、デフォルト）、'size'（サイズの大きい JAR を先頭）、または 'modified'（更新日時の新しいものを先頭）。不明な値は 'name' として扱われます。
list_artifacts	limit	integer	50	返すアーティファクトの最大数
list_artifacts	page	integer	1	ページネーションのページ番号
list_artifacts	items_per_page	integer	20	1 ページあたりの項目数
analyze_jar	group_id*	string	—	Maven グループ ID
analyze_jar	artifact_id*	string	—	Maven アーティファクト ID
analyze_jar	version*	string	—	Maven バージョン
analyze_jar	include_bytecode	boolean	False	バイトコード解析を含めます
analyze_jar	include_manifest	boolean	True	JAR マニフェストを含めます
analyze_jar	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
extract_class_info	group_id*	string	—	Maven グループ ID
extract_class_info	artifact_id*	string	—	Maven アーティファクト ID
extract_class_info	version*	string	—	Maven バージョン
extract_class_info	class_pattern	string	—	クラス名に一致するパターン（正規表現をサポート）
extract_class_info	include_methods	boolean	True	メソッドシグネチャを含めます
extract_class_info	include_fields	boolean	True	フィールド情報を含めます
extract_class_info	include_bytecode	boolean	False	一致したクラスの詳細な javap バイトコード出力を含めます
extract_class_info	page	integer	1	ページネーションのページ番号
extract_class_info	items_per_page	integer	20	1 ページあたりの項目数
extract_class_info	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
get_dependencies	group_id*	string	—	Maven グループ ID
get_dependencies	artifact_id*	string	—	Maven アーティファクト ID
get_dependencies	version*	string	—	Maven バージョン
get_dependencies	include_transitive	boolean	False	推移的依存関係を含めます
get_dependencies	page	integer	1	ページネーションのページ番号
get_dependencies	items_per_page	integer	20	1 ページあたりの項目数
search_classes	class_name	string	—	検索するクラス名（ワイルドカードをサポート）
search_classes	package_pattern	string	—	絞り込みに使用するパッケージパターン
search_classes	annotation	string	—	特定のアノテーションを持つクラスを検索します
search_classes	case_sensitive	boolean	True	class_name と package_pattern を大文字と小文字を区別して照合します。大文字と小文字を区別しない検索を行うには false を設定します（例：'arraylist' で 'ArrayList' に一致）。
search_classes	limit	integer	100	返す結果の最大数
search_classes	page	integer	1	ページネーションのページ番号
search_classes	items_per_page	integer	20	1 ページあたりの項目数
extract_source_code	group_id*	string	—	Maven グループ ID
extract_source_code	artifact_id*	string	—	Maven アーティファクト ID
extract_source_code	version*	string	—	Maven バージョン
extract_source_code	class_name*	string	—	完全修飾クラス名
extract_source_code	prefer_sources	boolean	True	デコンパイルよりソース JAR を優先します
extract_source_code	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
extract_source_code	max_lines	integer	500	返す最大行数（0 の場合はすべて）
extract_jar_resource	group_id*	string	—	Maven グループ ID
extract_jar_resource	artifact_id*	string	—	Maven アーティファクト ID
extract_jar_resource	version*	string	—	Maven バージョン
extract_jar_resource	resource_path	string	—	JAR 内の正確なリソースパス
extract_jar_resource	resource_pattern	string	—	リソースパスに一致する正規表現パターン
extract_jar_resource	max_bytes	integer	65536	リソースごとに読み取る最大バイト数
extract_jar_resource	limit	integer	20	返す一致リソースの最大数
compare_versions	group_id*	string	—	Maven グループ ID
compare_versions	artifact_id*	string	—	Maven アーティファクト ID
compare_versions	version1*	string	—	比較する最初の（古い）バージョン
compare_versions	version2*	string	—	比較する2番目の（新しい）バージョン
compare_versions	compare_api	boolean	True	パブリック API の差分を取得します。追加／削除された public および protected メソッドとフィールド、ならびに破壊的変更が対象です
compare_versions	resolve_inherited	boolean	False	新しい JAR 内のスーパタイプで引き続き宣言されているためにクラスから消えたメンバーを、破壊的な削除として数える代わりに「スーパタイプに移動」カテゴリに再分類します。デフォルトは false（宣言どおりの差分とバイト単位で同一）です。
compare_versions	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
find_usage_examples	class_name*	string	—	使用例を検索するクラス名
find_usage_examples	method_name	string	—	メソッド名
find_usage_examples	search_tests	boolean	True	テスト JAR 内を検索します
find_usage_examples	limit	integer	50	返す結果の最大数
find_usage_examples	page	integer	1	ページネーションのページ番号
find_usage_examples	items_per_page	integer	20	1 ページあたりの項目数
get_dependency_tree	group_id*	string	—	Maven グループ ID
get_dependency_tree	artifact_id*	string	—	Maven アーティファクト ID
get_dependency_tree	version*	string	—	Maven バージョン
get_dependency_tree	max_depth	integer	3	表示する最大の深さ
get_dependency_tree	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
find_dependents	group_id*	string	—	対象のグループ ID
find_dependents	artifact_id*	string	—	対象のアーティファクト ID
find_dependents	version	string	—	検索する特定のバージョン（任意）
find_dependents	limit	integer	100	返す結果の最大数
find_dependents	page	integer	1	ページネーションのページ番号
find_dependents	items_per_page	integer	20	1 ページあたりの項目数
get_version_info	group_id*	string	—	Maven グループ ID
get_version_info	artifact_id*	string	—	Maven アーティファクト ID
get_version_info	include_remote	boolean	False	インストール済みのバージョンだけでなく、リモートリポジトリで公開されているバージョンも一覧表示します
get_version_info	limit	integer	50	返すバージョンの最大数
get_version_info	page	integer	1	ページネーションのページ番号
get_version_info	items_per_page	integer	20	1 ページあたりの項目数
analyze_jar_structure	group_id*	string	—	Maven グループ ID
analyze_jar_structure	artifact_id*	string	—	Maven アーティファクト ID
analyze_jar_structure	version*	string	—	Maven バージョン
analyze_jar_structure	summarize_large_content	boolean	True	大きなコンテンツを自動的に要約します
extract_method_info	group_id*	string	—	Maven グループ ID
extract_method_info	artifact_id*	string	—	Maven アーティファクト ID
extract_method_info	version*	string	—	Maven バージョン
extract_method_info	class_name*	string	—	完全修飾クラス名
extract_method_info	method_pattern	string	—	メソッド名に一致するパターン（正規表現をサポート）
extract_method_info	include_bytecode	boolean	False	バイトコード解析を含めます
extract_method_info	max_methods	integer	10	返すメソッドの最大数
search_maven_central	query	string	—	フリーテキスト検索語（例：'jackson databind'）
search_maven_central	group_id	string	—	完全一致するグループ ID のフィルター（例：'org.springframework'）
search_maven_central	artifact_id	string	—	完全一致するアーティファクト ID のフィルター（例：'spring-core'）
search_maven_central	class_name	string	—	クラスを含むアーティファクトを検索するための単純クラス名（例：'ObjectMapper'）
search_maven_central	fully_qualified_class	string	—	完全修飾クラス名（例：'com.fasterxml.jackson.databind.ObjectMapper'）
search_maven_central	packaging	string	—	パッケージ形式のフィルター（例：'jar'、'pom'）
search_maven_central	all_versions	boolean	False	アーティファクトごとの最新バージョンだけでなく、公開済みのすべてのバージョンを返します
search_maven_central	limit	integer	20	返す結果の最大数（最大 200）
search_maven_central	page	integer	1	ページネーションのページ番号
get_remote_versions	group_id*	string	—	Maven グループ ID
get_remote_versions	artifact_id*	string	—	Maven アーティファクト ID
get_remote_versions	include_snapshots	boolean	True	-SNAPSHOT バージョンを含めます。リリース済みバージョンのみを一覧表示するには false を設定します。
get_remote_versions	limit	integer	100	返すバージョンの最大数
download_artifact	group_id*	string	—	Maven グループ ID
download_artifact	artifact_id*	string	—	Maven アーティファクト ID
download_artifact	version*	string	—	ダウンロードするバージョン、または最新のリリースを指定する 'latest'
download_artifact	include_sources	boolean	True	公開されている場合はソース JAR もダウンロードします
download_artifact	include_javadoc	boolean	False	公開されている場合は javadoc JAR もダウンロードします
download_artifact	classifier	string	—	メインの JAR ではなく、指定した classifier の JAR をダウンロードします
download_artifact	force	boolean	False	ファイルがすでにキャッシュされている場合も再ダウンロードします
* 必須 — このパラメーターは、ツールの inputSchema の required 配列に含まれています。* のないパラメーターは省略可能です。

💡 使用例

依存関係の検索

"Show me all dependencies of org.springframework:spring-core:5.3.21"

クラスの逆コンパイル

"Decompile the class com.example.MyService from my Maven repository"

競合の分析

"Find all version conflicts in my Maven repository"

アップグレードによる破壊的変更の確認

"Compare org.jsoup:jsoup 1.17.2 with 1.23.2 and tell me what would break"

compare_versions は、2つのバージョンに共通するすべてのクラスの public メンバーと protected メンバーを比較し、削除と追加を分けて報告します。削除されたメンバーとクラスは、破壊的変更として数えられます。メンバーは 宣言された状態 で比較されるため、上位型に移動したメンバーは、引き続き呼び出せる場合でも削除として報告されます。

API の調査

"Show me all public methods in the Jackson ObjectMapper class"

実際の呼び出し元の検索

"Find classes that call ObjectMapper.readValue, including examples from test jars"

find_usage_examples はコンパイル済みクラスの定数プールをスキャンするため、単純な名前の一致ではなく、実際の呼び出し元を見つけます。特定のメソッドを呼び出すコードに絞り込むには、method_name（例：readValue）を指定します。テスト jar はデフォルトで含まれ、最も明確な例が含まれていることが多いため、優先して表示されます。除外するには、search_tests を false に設定してください。大規模なリポジトリでも応答性を保つため、スキャンは MCP_USAGE_SCAN_LIMIT クラス（デフォルト：200000）で停止します。

コンパイル済み成果物のみの調査

"The sources jar is missing. Use extract_class_info for bytecode-backed fields and methods."
"Find and read .proto resources from com.example:protobuf-lib:1.0.0"

依存関係にソース jar がない場合、extract_class_info は内部で javap を使用し、解析したフィールド、メソッド、バイトコードのバージョン、および任意の詳細なバイトコード出力を返します。エージェントは jar や javap を直接実行する代わりに、この MCP 経由で analyze_jar、extract_class_info、extract_source_code、extract_jar_resource を使用してください。

大きなレスポンスの処理

"List all Spring classes with pagination (page 2, 10 items per page)"
"Extract source code for a large class with summarization"
"Get method information for specific patterns in a class"

Maven Central の検索（オンライン）

"Which Maven artifact contains the class HikariDataSource?"
"Search Maven Central for retrofit"
"What is the newest published version of org.apache.commons:commons-lang3?"
"Download com.google.code.gson:gson:latest and show me the JsonParser class"

🌐 Maven のオンラインサポート

サーバーはローカルリポジトリ と リモートリポジトリの両方を対象に動作します。オンラインアクセスはデフォルトで有効です。

仕組み

1. すべてのツールは、まずローカルリポジトリ（~/.m2/repository）を検索します。
2. 見つからない場合、成果物は標準的な Maven レイアウトを使用するキャッシュ（~/.cache/maven-decoder-mcp/repository）にある Maven Central からダウンロードされます。
3. その後、逆コンパイル、クラス情報、依存関係などの既存の分析が、インストール済みの成果物と同様にキャッシュされた成果物に対して実行されます。

ダウンロードが Maven または Gradle のビルドに影響しないよう、キャッシュは意図的に ~/.m2 とは別に しています。レスポンスには origin フィールド（local-repository または remote-cache）が含まれるため、結果の取得元を常に確認できます。

オフラインでの使用

MAVEN_OFFLINE=true   # no network access at all; original local-only behavior
MAVEN_AUTO_DOWNLOAD=false   # keep online search, but never auto-download

プライベートミラーの使用

MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"
MAVEN_REMOTE_USERNAME=builder
MAVEN_REMOTE_PASSWORD=secret

検索インデックスについて

成果物の ダウンロード には、高速で信頼性の高い repo1.maven.org を使用します。成果物の 検索 には、クラスレベルの（c: / fc:）クエリに正しく応答する唯一の公開インデックスである search.maven.org を使用します。このインデックスは短時間に集中するリクエストをレート制限するため、リクエストはバックオフを伴って再試行されます。それでも、混雑時にはタイムアウトが発生することがあります。ダウンロードとバージョン一覧には影響しません。これらはリポジトリから maven-metadata.xml を直接読み取るためです。

🔄 レスポンスの管理

ページネーションのサポート

サーバーは、インテリジェントなページネーションによって大きなレスポンスを自動的に処理します。

• 自動検出：50KB を超えるレスポンスは自動的にページネーションされます
• ページサイズの設定：デフォルトは 1 ページあたり 20 項目で、リクエストごとに変更できます
• ページネーションのメタデータ：各レスポンスにはページネーション情報が含まれます
• 対応ツール：list_artifacts、extract_class_info、search_classes、get_dependencies、find_dependents、get_version_info

要約機能

読みやすさを向上させるため、大きなテキストコンテンツは自動的に要約されます。

• スマートな要約：重要な部分（パッケージ宣言、メソッドシグネチャ、閉じ波括弧）を保持します
• 上限の設定：デフォルトのテキスト上限は 10KB で、変更できます
• Java 向け：Java ソースコードの構造に合わせて最適化されています
• メタデータの保持：元の構造とメタデータが維持されます

メソッドの抽出

特定のメソッドに的を絞ってアクセスするための新しいツールです。

• パターンマッチング：正規表現パターンを使用して、特定のメソッドを検索します
• 結果数の制限：返されるメソッドの数を指定できます
• 完全なコンテキスト：メソッドのシグネチャ、本文、行番号が含まれます
• 効率的な処理：クラス全体ではなく、要求されたメソッドのみを抽出します

🏗️ アーキテクチャ

サーバーはモジュール式のアーキテクチャで構築されています。

• MavenDecoderServer：MCP サーバーの主要な実装
• ResponseManager：ページネーションと要約を処理します
• JavaDecompiler：複数の逆コンパイル方式を処理します
• MavenDependencyAnalyzer：Maven の依存関係とメタデータを分析します
• MavenCentralClient：リモート検索、バージョン一覧表示、アーティファクトのダウンロードを行います
• 逆コンパイラー：CFR、Procyon、Fernflower、javap の統合

🧪 開発

テストの実行

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test
python test_startup.py

パッケージのビルド

# Build distribution
python setup.py sdist bdist_wheel

# Install locally
pip install dist/maven_decoder_mcp-*.whl

Docker での開発

# Build Docker image
docker build -t maven-decoder-mcp .

# Run container
docker run --rm -it maven-decoder-mcp

📝 設定オプション

環境変数

ローカルリポジトリ

• MAVEN_REPOSITORY / MAVEN_REPO：ローカル Maven リポジトリへの直接パス（例：F:\data\repository）。最優先されます。
• MAVEN_HOME / M2_HOME：Maven のインストールディレクトリ、またはリポジトリディレクトリです。存在する場合は、ネストされた repository/ サブディレクトリが優先されます。conf/settings.xml の <localRepository> も適用されます。
• 環境変数が設定されていない場合は、~/.m2/settings.xml の <localRepository> が適用されます。フォールバック先は ~/.m2/repository です。

オンラインアクセス

• MAVEN_OFFLINE：true に設定すると、すべてのネットワークアクセスを無効にします（デフォルト：false）
• MAVEN_AUTO_DOWNLOAD：ローカルにないアーティファクトを自動取得します（デフォルト：true）
• MAVEN_REMOTE_REPOS / MAVEN_REMOTE_REPO：カンマまたはスペースで区切ったリポジトリのベース URL（デフォルト：https://repo1.maven.org/maven2）
• MAVEN_SEARCH_URL：カンマまたはスペースで区切った Solr 検索エンドポイント（デフォルト：https://search.maven.org/solrsearch/select）
• MAVEN_DECODER_CACHE_DIR：ダウンロードしたアーティファクトのキャッシュ先（デフォルト：~/.cache/maven-decoder-mcp/repository）
• MAVEN_REMOTE_USERNAME / MAVEN_REMOTE_PASSWORD：プライベートミラー用のベーシック認証情報
• MAVEN_HTTP_TIMEOUT：リクエストごとのタイムアウト（秒）（デフォルト：30）
• MAVEN_HTTP_RETRIES：一時的なネットワーク障害時の再試行回数（デフォルト：3）
• MAVEN_MAX_DOWNLOAD_SIZE：ダウンロードの最大サイズ（バイト）（デフォルト：104857600）
• MAVEN_VERIFY_CHECKSUM：ダウンロードを公開済みの SHA-1 と照合して検証します（デフォルト：true）

レスポンス

• MCP_LOG_LEVEL：ログレベル（DEBUG、INFO、WARNING、ERROR）
• MCP_MAX_RESPONSE_SIZE：レスポンスの最大サイズ（バイト）（デフォルト：50000）
• MCP_MAX_ITEMS_PER_PAGE：ページあたりのデフォルト項目数（デフォルト：20）
• MCP_MAX_TEXT_LENGTH：要約前の最大テキスト長（デフォルト：10000）
• MCP_MAX_LINES：要約前の最大行数（デフォルト：500）
• MCP_USAGE_SCAN_LIMIT：find_usage_examples でスキャンするクラスの最大数（デフォルト：200000）
• MCP_API_DIFF_LIMIT：compare_versions で比較するクラスの最大数（デフォルト：2000）
• MAVEN_DECODER_DECOMPILER_DIR：cfr.jar / procyon-decompiler.jar を格納するディレクトリ

詳細設定

サーバーは以下を自動的に検出して設定します。

• Maven リポジトリの場所
• 利用可能な Java 逆コンパイラー
• システムの機能

🔍 トラブルシューティング

よくある問題

サーバーが起動しない

# Check Python installation
python --version

# Check Maven repository
ls ~/.m2/repository

# Check logs
maven-decoder-mcp --debug

逆コンパイルに失敗する

# Check the environment: Java, repository, cache and available decompilers
maven-decoder-setup status

# Install the optional CFR and Procyon decompilers
maven-decoder-setup decompilers

ソースチェックアウトからは、代わりに ./setup_decompilers.sh を実行できます。このスクリプトと同じ階層にある decompilers/ ディレクトリに CFR と Procyon がダウンロードされ、decompilers/cfr.jar と decompilers/procyon-decompiler.jar として保存されます。

maven-decoder-setup status で逆コンパイラーが見つからないと報告される場合、JAR があっても、サーバーが検索しない場所に置かれています。次のルートを順に検索し、最初に見つかったものを使用します。

1. $MAVEN_DECODER_DECOMPILER_DIR が設定されている場合はその値
2. インストール済みパッケージ内の decompilers/
3. パッケージと同じ階層にある decompilers/ — ソースチェックアウト時の配置
4. ~/.cache/maven-decoder-mcp/decompilers
5. 現在の作業ディレクトリ内の decompilers/
6. 現在の作業ディレクトリ自体

MCP クライアントは任意の作業ディレクトリからサーバーを起動するため、実際には最後の 2 つは確実ではありません。JAR がそれ以外の場所にある場合は、明示的に指定してください。

export MAVEN_DECODER_DECOMPILER_DIR=~/tools/decompilers

ディレクトリには、正確な名前 cfr.jar と procyon-decompiler.jar で JAR が含まれている必要があります。この値では ~ と環境変数が展開されます。

CFR または Procyon がなくてもサーバーは動作し、シグネチャ、フィールド、メソッドの取得には JDK の javap にフォールバックします。

アーティファクトが見つからない

# Verify Maven repository location
ls ~/.m2/repository

# Run a Maven build to populate repository
mvn dependency:resolve

Maven Central の検索がタイムアウトする

公開検索インデックスでは、短時間に集中するリクエストがレート制限されます。バックオフを伴う再試行が組み込まれていますが、強いスロットリングが発生している間は検索に失敗することがあります。回避策：

# Wait a moment and retry, or raise the retry budget
MAVEN_HTTP_RETRIES=5

# Downloads and version listing do not use the search index, so these keep
# working even while search is throttled:
#   get_remote_versions, download_artifact

プロキシまたはファイアウォール経由でダウンロードに失敗する

# requests honors the standard proxy variables
export HTTPS_PROXY=http://proxy.corp:8080

# Or point at an internal mirror
export MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"

# Or turn the network off entirely
export MAVEN_OFFLINE=true

🤝 貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• Model Context Protocol - このサーバーを支えるプロトコル
• CFR - Java 逆コンパイラー
• Procyon - Java 逆コンパイラー
• Maven - 依存関係管理

📊 統計

---

Java 開発コミュニティのために ❤️ を込めて作成