Maven Indexer MCP

🚀 Maven Indexer MCP Server

A Model Context Protocol (MCP) server that indexes local Maven and Gradle repositories to empower AI agents in searching for Java classes, method signatures, and source code.

🚀 Quick Start

Add the following configuration to your MCP client:

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

This will automatically download and run the latest version of the server. It can auto - detect your Maven repository location (usually ~/.m2/repository) and Gradle cache.

MCP Client configuration

Your first prompt

Enter the following prompt in your MCP client to check if everything is working:

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

Your MCP client should read the class StringUtils from your local Maven repository and show its methods.

✨ Features

• Semantic Class Search: Search for classes by name or purpose.
• Inheritance Search: Find all implementations of an interface or subclasses of a class.
• On - Demand Analysis: Extracts method signatures and Javadocs directly from JARs.
• Source Code Retrieval: Provides full source code if available.
• Real - time Monitoring: Automatically updates the index when repositories change.

📦 Installation

Configuration (Optional)

If the auto - detection fails, or if you want to filter which packages are indexed, you can add environment variables to the configuration:

• MAVEN_REPO: Absolute path to your local Maven repository (e.g., /Users/yourname/.m2/repository). Use this if your repository is in a non - standard location.
• GRADLE_REPO_PATH: Absolute path to your Gradle cache (e.g., /Users/yourname/.gradle/caches/modules - 2/files - 2.1).
• INCLUDED_PACKAGES: Comma - separated list of package patterns to index (e.g., com.mycompany.*,org.example.*). Default is * (index everything).
• MAVEN_INDEXER_CFR_PATH: (Optional) Absolute path to a specific CFR decompiler JAR. If not provided, the server will attempt to use its bundled CFR version.
• VERSION_RESOLUTION_STRATEGY: (Optional) Strategy to choose the version when multiple versions of an artifact are found and no specific coordinate is provided.
  • semver: (Default) Prefer the highest semantic version (e.g. 1.2.0 > 1.1.9).
  • latest - published: Prefer the version with the latest publish time (checks *.pom.lastUpdated first, then file modification time).
  • latest - used: Prefer the version most recently imported/used by the user (based on file creation time).

Example with optional configuration:

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

Local Development

If you prefer to run from source:

1. Clone the repository:

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

2. Install dependencies and build:

npm install
npm run build

3. Use the absolute path in your config:

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

💻 Usage Examples

Available Tools

• search_classes: Search for Java classes in the local Maven repository and Gradle caches.
  • WHEN TO USE: 1. Internal/Private Code: You need to find a class from a company - internal library. 2. Obscure Libraries: You are using a less common public library that the AI doesn't know well. 3. Version Verification: You need to check exactly which version of a class is present locally.
    • Note: For well - known libraries (e.g., standard Java lib, Spring), the AI likely knows the class structure already, so this tool is less critical.
  • Examples: "Show me the source of StringUtils", "What methods are available on DateTimeUtils?", "Where is this class imported from?".
  • Input: className (e.g., "StringUtils", "Json parser")
  • Output: List of matching classes with their artifacts.
• get_class_details: Decompile and read the source code of external libraries/dependencies. Use this instead of 'SearchCodebase' for classes that are imported but defined in JAR files.
  • Key Value: "Don't guess what the internal library does—read the code."
  • Tip: Essential for internal/proprietary code where documentation is scarce or non - existent.
  • Input: className (required), artifactId (optional), type ("signatures", "docs", "source")
  • Output: Method signatures, Javadocs, or full source code.
  • Note: If artifactId is omitted, the tool automatically selects the best available artifact (preferring those with source code attached).
• search_artifacts: Search for artifacts in Maven/Gradle caches by coordinate (groupId, artifactId).
• search_implementations: Search for classes that implement a specific interface or extend a specific class. Useful for finding SPI implementations in external libraries.
  • Input: className (e.g. "java.util.List")
  • Output: List of implementation/subclass names and their artifacts.
• refresh_index: Trigger a re - scan of the Maven repository.

🔧 Technical Details

Development

• Run tests: npm test
• Watch mode: npm run watch

📄 License

ISC