Maven Indexer Mcp

Maven Index

ローカルの Maven リポジトリ（~/.m2/repository）と Gradle キャッシュ（~/.gradle/caches/modules-2/files-2.1）をインデックス化し、AI エージェントが Java クラス、メソッドシグネチャ、ソースコードを検索できるようにする MCP サーバーおよび CLI です。社内パッケージや、あまり知られていない公開ライブラリも検索できます。

クイックインストール

エージェントにインデックスを利用させる方法は2つあります。どちらか一方、または両方を選んでください。

• CLI + エージェントスキル：ターミナルで動作するコーディングエージェント（Claude Code、Codex、Gemini CLI、OpenCode、Cursor）向けです。エージェントは maven-indexer スキルのガイドに従って maven-indexer-cli コマンドを実行します。ツールのスキーマがコンテキストウィンドウに含まれないため、使用するトークンを抑えられます。
• MCP サーバー：IDE と統合されたエージェント（Cursor、Kiro、Windsurf、JetBrains、...）向けです。MCP サーバーを参照してください。

CLI + エージェントスキル

インストールスクリプト（推奨）

1つのコマンドで npm から maven-indexer-cli をインストールし、検出されたすべてのコーディングエージェントに maven-indexer スキルをインストールします。

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

Node.js 18+ と npm が必要です。bash -s -- の後にオプションを指定してください。

curl -fsSL https://raw.githubusercontent.com/tangcent/maven-indexer-mcp/main/install.sh | bash -s -- --target claude,agents --index

オプション	意味
--target <t>	スキルをインストールするエージェント：auto（検出されたエージェント、デフォルト）、all、または claude、agents、cursor の CSV（スキルディレクトリを参照）。
--location <l>	global（ホームディレクトリ、デフォルト）または local（現在のプロジェクト）。
--dir <path>	代わりにこのスキルディレクトリにインストールします。
--version <v>	インストールする maven-indexer-cli のバージョン（デフォルトは latest）。
--skip-cli / --skip-skills	スキルのみ／CLI のみをインストールします。
--index	インストール直後にインデックスを作成します。

スクリプトを再実行すると、CLI とスキルの両方がアップグレードされます。スキルを読み込ませるため、その後エージェントを再起動するか、新しいセッションを開始してください。

手動インストール：maven-indexer-cli

npm install -g maven-indexer-cli
maven-indexer-cli refresh-index   # build the index once; later runs use `maven-indexer-cli sync`

インストールせずに実行する場合は、npx -y maven-indexer-cli <command> を使用してください。

maven-indexer-cli でスキルをインストールする

CLI をインストールすると、同梱されているスキルをインストールできます。

maven-indexer-cli skills install                          # every detected agent, global
maven-indexer-cli skills install --target claude,agents   # pick agents
maven-indexer-cli skills install --location local         # into the current project (.claude/skills, ...)
maven-indexer-cli skills install --dir ~/my-agent/skills  # any skills directory
maven-indexer-cli skills status                           # installed / stale / missing per agent
maven-indexer-cli skills uninstall

skills install はべき等です。CLI のアップグレード後に再実行すると、スキルが更新されます。書き込まれるファイルを事前に確認するには --dry-run を追加してください。maven-indexer というディレクトリ名を使用する別のスキルを上書きすることはありません。

手動インストール：スキル

スキルは単一のファイル、skills/maven-indexer/SKILL.md です。これをエージェントのスキルディレクトリ内にある maven-indexer フォルダーにコピーしてください。たとえば Claude Code の場合は次のとおりです。

mkdir -p ~/.claude/skills/maven-indexer
curl -fsSL https://raw.githubusercontent.com/tangcent/maven-indexer-mcp/main/skills/maven-indexer/SKILL.md -o ~/.claude/skills/maven-indexer/SKILL.md

スキルディレクトリ

対象	エージェント	グローバル	ローカル（プロジェクト）
claude	Claude Code	~/.claude/skills/	.claude/skills/
agents	Codex、Gemini CLI、OpenCode、および共通の Agent Skills フォルダーを読み込むその他のクライアント	~/.agents/skills/	.agents/skills/
cursor	Cursor	~/.cursor/skills/	.cursor/skills/

auto は、エージェントのフォルダーが存在するすべての対象（~/.claude、~/.agents、~/.codex、~/.gemini、~/.config/opencode、~/.cursor）を選択します。該当するものがない場合は claude が選択されます。

MCP サーバー

次の設定を MCP クライアントに追加してください。

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ]
    }
  }
}

これにより、サーバーの最新バージョンが自動的にダウンロードされ、実行されます。Maven リポジトリの場所（通常は ~/.m2/repository）と Gradle キャッシュも自動検出されます。

maven-indexer-cli install を使用して、Claude Code、Cursor、Codex、OpenCode、Gemini CLI、Windsurf の設定ファイルにこのエントリー（および短い手順ブロック）を書き込むこともできます。オプションについては maven-indexer-cli install --help を実行してください。

MCP クライアントの設定

Cline

Cline の MCP ガイドに従い、上記の設定を使用してください。

Codex

上記の標準設定を使用して、MCP の設定ガイドに従ってください。

Cursor

ボタンをクリックしてインストールします：

または、手動でインストールします：

Cursor Settings -> MCP -> New MCP Server の順に移動します。上記の設定を使用してください。

JetBrains AI Assistant & Junie

Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add の順に移動します。上記の設定を使用してください。 同じ方法で、Settings | Tools | Junie | MCP Settings ->Add の順に移動すると、JetBrains Junie にも maven-indexer を設定できます。 上記の設定を使用してください。

Kiro

Kiro Settings で、Configure MCP > Open Workspace or User MCP Config の順に移動し、上記の設定スニペットを使用します。

または、IDE の Activity Bar > Kiro > MCP Servers > Click Open MCP Config の順に移動します。上記の設定スニペットを使用してください。

Qoder

Qoder Settings で、MCP Server > + Add の順に移動し、上記の設定スニペットを使用します。

または、MCP ガイドに従い、上記の標準設定を使用してください。

Trae

Settings -> MCP -> + Add -> Add Manually の順に移動して、MCP サーバーを追加します。上記の設定を使用してください。

Windsurf

上記の標準設定を使用して、MCP の設定ガイドに従ってください。

maven-indexer-mcp 1.0.x からのアップグレード

破壊的変更： ツール名が変更され、デフォルトで登録されるのは explore のみです。

アップグレード後、以前の名前を呼び出すエージェントには「tool not found」と表示されます。再び有効にするには、オプトインしてください。

1.0.x のツール	現在
get_class_details	get_class
search_classes	search
search_artifacts	search_artifacts
search_implementations	implementations
refresh_index	削除済み（インデックスは自動同期されます。maven-indexer-cli refresh-index を使用してください）
その他すべて	同じ名前ですが、デフォルトでは登録されません

すべての機能を再び有効にするには、次のように設定します。

MAVEN_INDEXER_MCP_TOOLS=   # empty-but-set enables ALL tools

または、使用するものを指定します：MAVEN_INDEXER_MCP_TOOLS=search,get_class,callers。

その他はすべて変更ありません。公開パッケージ名は引き続き maven-indexer-mcp です（リポジトリ は maven-index に改名されました）。CLI は maven-indexer-cli バイナリ経由で実行されます。

最初のプロンプト

すべてが正常に動作しているか確認するには、エージェントに次のプロンプトを入力してください。

Find the class `StringUtils` in my local maven repository and show me its methods.

エージェントはローカルの Maven リポジトリから StringUtils クラスを読み込み、そのメソッドを表示します。

設定（任意）

自動検出に失敗する場合や、インデックス対象のパッケージを絞り込みたい場合は、設定に環境変数を追加できます。

• MAVEN_REPO：ローカルの Maven リポジトリへの絶対パス（例：/Users/yourname/.m2/repository）。リポジトリが標準以外の場所にある場合に使用します。
• GRADLE_REPO_PATH：Gradle キャッシュへの絶対パス（例： /Users/yourname/.gradle/caches/modules-2/files-2.1）。
• INCLUDED_PACKAGES：インデックス対象のパッケージパターンをカンマ区切りで指定します（例：com.mycompany.*,org.example.*）。 デフォルトは *（すべてをインデックス化）です。エントリーの末尾に ! を付けると、EXCLUDED_PACKAGES の設定より優先して含められます （例：org.springframework.security.web!）。
• EXCLUDED_PACKAGES：インデックス作成時に除外するパッケージプレフィックスのパターンをカンマ区切りで指定します （例：java.*,javax.*,sun.*）。デフォルトは空（すべてをインデックス化）です。強制的に含める（!）エントリーを除き、INCLUDED_PACKAGES より優先されます。推奨されるデフォルト値： java.*,javax.*,sun.*,jdk.internal.*,org.omg.*。org.springframework.* の除外は、インデックスの縮小と Spring 内部のクエリ機能の喪失とのトレードオフです。インデックスサイズが懸念事項でない限り、Spring はインデックス対象のままにしてください。
• MAVEN_INDEXER_CFR_PATH：（任意）特定の CFR デコンパイラー JAR への絶対パスです。指定しない場合、サーバーは同梱の CFR バージョンを使用します。
• VERSION_RESOLUTION_STRATEGY：（任意）複数のバージョンのアーティファクトが見つかり、特定の座標が指定されていない場合に、バージョンを選択するための戦略です。
  • semver：（デフォルト）最も高いセマンティックバージョンを優先します（例：1.2.0 > 1.1.9）。
  • latest-published：公開日時が最も新しいバージョンを優先します（まず *.pom.lastUpdated を確認し、次にファイルの更新日時を確認します）。
  • latest-used：ユーザーが最後にインポート／使用したバージョンを優先します（ファイルの作成日時に基づきます）。

任意の設定を使用する場合の例：

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ],
      "env": {
        "MAVEN_REPO": "/Users/yourname/.m2/repository",
        "GRADLE_REPO_PATH": "/Users/yourname/.gradle/caches/modules-2/files-2.1",
        "INCLUDED_PACKAGES": "com.mycompany.*",
        "MAVEN_INDEXER_CFR_PATH": "/path/to/cfr-0.152.jar",
        "VERSION_RESOLUTION_STRATEGY": "semver"
      }
    }
  }
}

利用可能なツール

デフォルトでは explore のみが登録されます。ほとんどすべての質問に、1 回の呼び出しで対応できます。以下のほかの 16 個のツールは定義済みですが、MAVEN_INDEXER_MCP_TOOLS で有効にした場合にのみ登録されます（個別ツールの選択（MAVEN_INDEXER_MCP_TOOLS によるオプトイン）を参照）。

explore（主要ツール — デフォルトで登録）

• explore：主要ツールです。ローカルの Maven／Gradle アーティファクトキャッシュ内のクラス、依存関係、呼び出しフローに関するほとんどの質問で、まず呼び出してください。クラスのソース／シグネチャ、実装、呼び出し元／呼び出し先、呼び出しパスをまとめて、上限付きの 1 つの応答で返します。「これはどのように動作するのか／どこで使われているのか？」という質問に、1 回の呼び出しで回答します。デフォルトで登録されます（オプトイン不要）。
  • 入力：
    • identifiers（string[]、必須）：名前のリスト。クラス名（FQCN または単純名）、座標（groupId:artifactId[:version]）、メソッドの対象（Class.method）、またはリソースパスを指定します。
    • coordinate（string、任意）：すべてのクラス／メソッド識別子に対して、アーティファクトのバージョンを固定します（groupId:artifactId:version）。
    • include（string[]、任意）：取得するセクションです。省略するとデフォルトのセクション（signatures、implementations、callers、callees）が使われます。選択肢：source、signatures、implementations、callers、callees、path、resources、dependencies、dependents。
    • maxLines（number、任意）：行数の上限（デフォルトは 200）。
    • question（string、任意）：自然言語での質問です。識別子が解決できない場合の代替として使用されます（検索候補モード）。
    • projectPath（string、MCP では必須。CLI では任意 — デフォルトは cwd）：プロジェクトのルートへの絶対パスです。MCP サーバーは信頼できない cwd でグローバルに起動するため、プロジェクトの依存関係に基づいてバージョン解決を行うには、プロジェクトを明示的に指定してください。
  • 出力： 要求されたセクションをまとめた、行数上限付きのテキストです。

Narrow Tools（MAVEN_INDEXER_MCP_TOOLS でオプトイン）

これら16個の限定的なツールは定義されていますが、デフォルトでは登録されていません。exploreで同じ範囲を1回の呼び出しでカバーできます。特定の範囲だけが必要な場合に限り、登録してください。

• MAVEN_INDEXER_MCP_TOOLS=search,get_class,callersを設定して、特定のツールを有効にします（短縮名のCSV）。
• MAVEN_INDEXER_MCP_TOOLS=（空の値を設定）にすると、すべての限定的なツールが有効になります（緊急用の手段。テストやバッチスクリプトに便利です）。
• この設定にかかわらず、exploreは常に登録されます。

以下の各ツールでは、推奨される代替手段としてexploreを挙げています。

• search：名前（FQCN、部分一致、またはキーワード）でJavaクラスを検索します。search_classesの代替です。exploreを推奨します（クラス名をidentifiersに渡してください）。
• get_class：クラスのソースコードまたはシグネチャを取得します。一括処理に対応しています。get_class_detailsの代替です。include: ["source"]または["signatures"]を指定したexploreを推奨します。
• get_resource：JARから単一のテキストリソース（proto、XML、properties）を取得します。include: ["resources"]を指定したexploreを推奨します。
• implementations：指定されたインターフェース／クラスを実装または拡張するクラスを検索します。include: ["implementations"]を指定したexploreを推奨します。
• callers：指定されたクラス／メソッドを呼び出すメソッドを一覧表示します（呼び出しグラフ）。include: ["callers"]を指定したexploreを推奨します。
• callees：指定されたクラス／メソッドから呼び出されるメソッドを一覧表示します（呼び出しグラフ）。include: ["callees"]を指定したexploreを推奨します。
• impact：呼び出しグラフを上方向にBFSでたどり、推移的な影響を調べます（呼び出し元の呼び出し元）。exploreを推奨します（1回の呼び出しで直接の呼び出し元／呼び出し先を提示します）。
• dependencies：アーティファクトの解析済みMaven <dependencies>を一覧表示します。get_dependenciesの代替です。include: ["dependencies"]を指定したexploreを推奨します。
• dependents：指定された座標に依存するインデックス済みアーティファクトを検索します。find_dependentsの代替です。include: ["dependents"]を指定したexploreを推奨します。
• info：アーティファクトの情報（パス、レイアウト、クラス数、リソース数）を取得します。include: ["path"]を指定したexploreを推奨します。
• stats：インデックスの統計情報（アーティファクト数、クラス数、DBサイズ）を集計します。exploreを推奨します（直接的な同等機能はありません。生の件数にはstatsを使用してください）。
• list_classes：特定のアーティファクト座標について、インデックス済みのJava／protobufクラス名をすべて一覧表示します。exploreを推奨します（座標をidentifiersに渡してください）。
• project_context：アクティブなプロジェクトのMaven／Gradleコンテキスト（宣言済み／解決済みの依存関係ツリー、ビルドファイル、プロジェクト座標）を調べます。バージョン解決の結果が予想と異なる場合に便利です。必須のprojectPathを受け取ります。exploreを推奨します（projectPathを渡してください）。
• search_artifacts：groupId、artifactId、キーワード、または完全一致のgroupId:artifactId[:version]座標でアーティファクトを検索します。新しいバージョンから順に表示されます。一括処理に対応しています。exploreを推奨します（座標をidentifiersに渡してください）。
• search_resources：JAR内のテキストリソース（proto、XML、properties）を検索します。include: ["resources"]を指定したexploreを推奨します。
• search_methods：インデックス済みのアーティファクト全体から、名前でJavaメソッドを検索します。exploreを推奨します（Class.methodをidentifiersに渡してください）。

注：doctorコマンド（インデックス済みアーティファクトについて、ディスク上にJARがないか確認するコマンド）はCLI専用です。MCPに相当する機能はありません。

注：syncコマンド（mtimeを使った高速な増分更新）はCLI専用です。MCPにはファイルシステムの変更時に再インデックスする独自のバックグラウンドウォッチャーがあるため、ウォッチャーが有効な場合、手動での同期は不要です。

Maven Indexer MCP と Maven Indexer CLI の比較

このリポジトリには両方のパッケージが含まれています。ワークフローに合ったものを選んでください。

• CLI（maven-indexer-cli）：最新のコーディングエージェントでは、MCP よりも SKILL として公開される CLI ベースのワークフローが選ばれる傾向が強まっています。CLI の呼び出しはトークン効率が高く、大きなツールスキーマをモデルコンテキストに読み込まずに済むため、エージェントは簡潔で目的に特化したコマンドを通じて処理できます。そのため、依存関係の検索と大規模なコードベースの扱い、限られたコンテキストウィンドウ内での推論を両立する必要がある、高スループットのコーディングエージェントには CLI と SKILL の組み合わせが適しています。
  SKILLS を使った Maven Indexer CLIについて詳しく見る。

• MCP（maven-indexer-mcp）：IDE に統合されたエージェント（Cursor、Kiro、Windsurf など）には、バックグラウンドでの継続的なインデックス作成、リポジトリの自動監視、CLI のセットアップ不要でスムーズにツールを呼び出せる MCP が引き続き適しています。MCP サーバーはバックグラウンドでリポジトリのインデックスを作成し、インデックスを自動的に最新の状態に保ちます。

ローカル開発

ソースから実行する場合は、以下の手順に従ってください。

1. リポジトリをクローンします。

   git clone https://github.com/tangcent/maven-indexer-mcp.git
   cd maven-indexer-mcp
   

2. 依存関係をインストールしてビルドします。

   npm install
   npm run build
   

3. 設定には絶対パスを指定します。

   {
     "mcpServers": {
       "maven-indexer": {
         "command": "node",
         "args": ["/absolute/path/to/maven-indexer-mcp/build/index.js"]
       }
     }
   }
   

• テストの実行：npm test
• ウォッチモード：npm run watch

リポジトリ

エンジンの統合（1 つのエンジン、2 つの薄いインターフェース）の一環として、このリポジトリは maven-indexer-mcp から maven-index に名称変更されました。 独立した maven-indexer-cli の Git リポジトリは非推奨です。npm パッケージは現在、このリポジトリのワークスペースから公開されています。

パス	公開名	説明
packages/engine	@maven-indexer/engine（非公開、内部用）	共有エンジン：Indexer、パーサー、スキーマ、リゾルバー、explore()、project_context
packages/cli	maven-indexer-cli	Commander.js の CLI インターフェース — 薄い実装で、エンジンをインポートします
packages/mcp	maven-indexer-mcp	MCP SDK サーバーインターフェース — 薄い実装で、エンジンをインポートします

公開済みの両パッケージ（maven-indexer-cli、maven-indexer-mcp）は、後方互換性のため、名前と bin エントリを変更せずに維持しています。既存の npx -y maven-indexer-mcp@latest と npm install -g maven-indexer-cli の呼び出しは、引き続き使用できます。

ライセンス

ISC