Maven Indexer MCP

🚀 Maven Indexer MCP Server

Maven Indexer MCP Server 是一个模型上下文协议（MCP）服务器，它对本地 Maven 仓库（~/.m2/repository）和 Gradle 缓存（~/.gradle/caches/modules-2/files-2.1）进行索引，为 AI 代理提供搜索 Java 类、方法签名和源代码的工具。该服务器能让 AI “读取” 本地依赖，有效弥补 AI 在处理公司内部私有库和小众公共库时的不足。

✨ 主要特性

• 语义类搜索：按名称或用途搜索类。
• 继承搜索：查找接口的所有实现类或类的所有子类。
• 按需分析：直接从 JAR 文件中提取方法签名和 Javadoc。
• 源代码检索：若可用，提供完整的源代码。
• 实时监控：当仓库发生变化时，自动更新索引。

🚀 快速开始

将以下配置添加到你的 MCP 客户端：

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

这将自动下载并运行服务器的最新版本。它会自动检测你的 Maven 仓库位置（通常是 ~/.m2/repository）和 Gradle 缓存。

MCP 客户端配置

首次提示

在你的 MCP 客户端中输入以下提示，以检查一切是否正常工作：

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

你的 MCP 客户端应该从你的本地 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.*）。默认值为 *（索引所有内容）。
• 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"
      }
    }
  }
}

本地开发

如果你更喜欢从源代码运行：

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"]
    }
  }
}

📚 详细文档

可用工具

• search_classes：在本地 Maven 仓库和 Gradle 缓存中搜索 Java 类。
  • 使用场景：
    1. 内部/私有代码：你需要从公司内部库中查找类。
    2. 小众库：你正在使用 AI 不太了解的不太常见的公共库。
    3. 版本验证：你需要确切检查本地存在哪个版本的类。
  • 注意：对于知名库（例如，标准 Java 库、Spring），AI 可能已经知道类结构，因此此工具的重要性较低。
  • 示例：“Show me the source of StringUtils”，“What methods are available on DateTimeUtils?”，“Where is this class imported from?”。
  • 输入：className（例如，“StringUtils”，“Json parser”）
  • 输出：匹配类及其工件的列表。
• get_class_details：反编译并读取外部库/依赖项的源代码。对于已导入但在 JAR 文件中定义的类，请使用此工具代替 “SearchCodebase”。
  • 关键价值：“不要猜测内部库的作用 — 阅读代码。”
  • 提示：对于文档稀缺或不存在的内部/专有代码至关重要。
  • 输入：className（必需），artifactId（可选），type（“signatures”，“docs”，“source”）
  • 输出：方法签名、Javadoc 或完整源代码。
  • 注意：如果省略 artifactId，工具将自动选择最佳可用工件（优先选择附有源代码的工件）。
• search_artifacts：按坐标（groupId，artifactId）在 Maven/Gradle 缓存中搜索工件。
• search_implementations：搜索实现特定接口或扩展特定类的类。对于在外部库中查找 SPI 实现很有用。
  • 输入：className（例如，“java.util.List”）
  • 输出：实现类/子类名称及其工件的列表。
• refresh_index：触发对 Maven 仓库的重新扫描。

🔧 技术细节

开发

• 运行测试：npm test
• 监视模式：npm run watch

📄 许可证

ISC