Maven Indexer Mcp

Maven Index

一个 MCP 服务和 CLI，可为本地 Maven 仓库（~/.m2/repository）和 Gradle 缓存（~/.gradle/caches/modules-2/files-2.1）建立索引，为 AI Agent 提供搜索 Java 类、方法签名和源代码的工具——即使是公司内部包和不太知名的公共库也适用。

快速安装

有两种方式可以让 Agent 使用索引。任选一种，也可以两种都用：

• CLI + Agent Skill：适用于终端编码 Agent（Claude Code、Codex、Gemini CLI、OpenCode、Cursor）。 Agent 会在 maven-indexer skill 的指引下运行 maven-indexer-cli 命令。上下文窗口中无需放入工具架构，因此占用的 token 更少。
• MCP 服务：适用于 IDE 集成的 Agent（Cursor、Kiro、Windsurf、JetBrains 等）。请参阅 MCP 服务。

CLI + Agent Skill

安装脚本（推荐）

运行一条命令，即可从 npm 安装 maven-indexer-cli，并为检测到的所有编码 Agent 安装 maven-indexer skill：

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>	指定要为哪些 Agent 安装 skill：auto（检测到的 Agent，默认）、all，或以逗号分隔的 claude、agents、cursor（请参阅 skill 目录）。
--location <l>	global（主目录，默认）或 local（当前项目）。
--dir <path>	将 skill 安装到此 skills 目录。
--version <v>	要安装的 maven-indexer-cli 版本（默认为 latest）。
--skip-cli / --skip-skills	仅安装 skill / 仅安装 CLI。
--index	安装后立即构建索引。

重新运行脚本会升级 CLI 和 skill。之后请重启 Agent（或启动新会话），以便加载 skill。

手动安装：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 安装 skill

安装 CLI 后，即可用它安装随附的 skill：

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 后再次运行即可更新 skill。添加 --dry-run 可预览它将写入的文件。它绝不会覆盖恰好使用 maven-indexer 目录名的其他 skill。

手动安装：skill

此 skill 是一个单独的文件 skills/maven-indexer/SKILL.md。将 它复制到 Agent 的 skills 目录下名为 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

Skill 目录

目标	Agent	全局	本地（项目）
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 会选择所有 Agent 文件夹均已存在的目标（~/.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。

升级后，调用旧名称的 Agent 会收到“找不到工具”的提示，除非你选择重新启用这些工具：

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 二进制文件运行。

你的第一个提示词

在 Agent 中输入以下提示词，检查一切是否正常：

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

你的 Agent 应从本地 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——它通过一次调用即可回答几乎所有问题。下面的其他 16 个工具均已定义，但只有在通过 MAVEN_INDEXER_MCP_TOOLS 选择启用后才会注册（参见精简工具）。

explore（主要工具 — 默认注册）

• explore：主要工具——对于有关本地 Maven/Gradle 构件缓存中的类、依赖项或调用流程的问题，几乎总是应首先调用此工具。它会在一次有行数上限的响应中返回类源码/签名、实现、调用者/被调用者以及调用路径。一次调用即可回答“这是如何工作的／这里用在何处？”。默认注册（无需选择启用）。
  • 输入：
    • 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 服务会在全局范围启动，当前工作目录并不可靠，因此请明确指定项目，以便将版本解析限定在项目依赖项中。
  • **输出：**包含所请求部分、并限制行数的组合文本。

窄范围工具（通过 MAVEN_INDEXER_MCP_TOOLS 选择启用）

这 16 个窄范围工具已定义，但默认不会注册——explore 一次调用即可覆盖相同内容。只有在需要特定范围时才注册它们。

• 设置 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（一次调用即可展示直接调用者/被调用者）。
• dependencies：列出某个构件中解析出的 Maven <dependencies>。替代 get_dependencies。优先使用带有 include: ["dependencies"] 的 explore。
• dependents：查找依赖指定坐标的已索引构件。替代 find_dependents。优先使用带有 include: ["dependents"] 的 explore。
• info：获取构件信息（路径、布局、类数量、资源数量）。优先使用带有 include: ["path"] 的 explore。
• stats：汇总索引统计信息（构件数量、类数量、数据库大小）。优先使用 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（在 identifiers 中传入 Class.method）。

注意：doctor 命令（检查索引构件在磁盘上是否缺少 JAR）仅限 CLI 使用——没有对应的 MCP 功能。

注意：sync 命令（通过 mtime 快速增量刷新）仅限 CLI 使用。MCP 有自己的后台监视器，会在文件系统发生更改时重新索引，因此监视器处于活动状态时无需手动同步。

Maven Indexer MCP 与 Maven Indexer CLI

此仓库同时包含这两个包。请选择符合你工作流的形式：

• CLI（maven-indexer-cli）：现代编码 Agent越来越倾向于使用基于 CLI 的工作流，并将其作为 SKILL 提供，而非使用 MCP，因为 CLI 调用更节省 token：它们无需将大型工具架构加载到模型上下文中，让 Agent 能通过简洁、专用的命令执行操作。这使 CLI + SKILL 更适合高吞吐量的编码 Agent：它们必须在有限的上下文窗口内，兼顾依赖项查找、大型代码库和推理。
  了解更多：使用 SKILLS 的 Maven Indexer CLI。

• MCP（maven-indexer-mcp）：对于集成在 IDE 中的 Agent（Cursor、Kiro、Windsurf 等），MCP 仍是更好的选择；这类 Agent 能受益于持续的后台索引、自动监视仓库，以及无需进行任何 CLI 设置即可无缝调用工具。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

仓库

作为引擎统一工作（一个引擎，两种轻量形式）的一部分，此仓库已从 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