maven-indexer-mcp 1.0.5 → 1.0.7

package/README.md

@@ -1,15 +1,28 @@
 # Maven Indexer MCP Server
 
-A Model Context Protocol (MCP) server that indexes your local Maven repository (`~/.m2/repository`) and Gradle cache (`~/.gradle/caches/modules-2/files-2.1`) to provide AI agents with tools to search for Java classes, method signatures, and source code.
+[![npm version](https://img.shields.io/npm/v/maven-indexer-mcp.svg?style=flat)](https://www.npmjs.com/package/maven-indexer-mcp)
+[![Tests](https://github.com/tangcent/maven-indexer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tangcent/maven-indexer-mcp/actions/workflows/ci.yml)
+
+A Model Context Protocol (MCP) server that indexes your local Maven repository (`~/.m2/repository`) and Gradle cache (
+`~/.gradle/caches/modules-2/files-2.1`) to provide AI agents with tools to search for Java classes, method signatures,
+and source code.
+
+**Key Use Case**: While AI models are well-versed in popular public libraries (like Spring, Apache Commons, Guava), they
+often struggle with:
+
+1. **Internal Company Packages**: Private libraries that are not public.
+2. **Non-Well-Known Public Packages**: Niche or less popular open-source libraries.
+
+This server bridges that gap by allowing the AI to "read" your local dependencies, effectively giving it knowledge of
+your private and obscure libraries.
 
 ## Features
 
-*   **Semantic Class Search**: Search for classes by name (e.g., `StringUtils`) or purpose (e.g., `JsonToXml`).
-*   **Inheritance Search**: Find all implementations of an interface or subclasses of a class.
-*   **On-Demand Analysis**: Extracts method signatures (`javap`) and Javadocs directly from JARs without extracting the entire archive.
-*   **Source Code Retrieval**: Provides full source code if `-sources.jar` is available.
-*   **Real-time Monitoring**: Watches the repositories for changes (e.g., new `mvn install`) and automatically updates the index.
-*   **Efficient Persistence**: Uses SQLite to store the index, handling large repositories with minimal memory footprint.
+* **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.
 
 ## Getting Started
 
@@ -20,22 +33,116 @@ Add the following config to your MCP client:
   "mcpServers": {
     "maven-indexer": {
       "command": "npx",
-      "args": ["-y", "maven-indexer-mcp@latest"]
+      "args": [
+        "-y",
+        "maven-indexer-mcp@latest"
+      ]
     }
   }
 }
 ```
 
-This will automatically download and run the latest version of the server. It will auto-detect your Maven repository location (usually `~/.m2/repository`) and Gradle cache.
+This will automatically download and run the latest version of the server. It will auto-detect your Maven repository
+location (usually `~/.m2/repository`) and Gradle cache.
 
-### Configuration (Optional)
+### MCP Client configuration
+
+<details>
+  <summary>Cline</summary>
+
+Follow <a href="https://docs.cline.bot/mcp/configuring-mcp-servers">Cline's MCP guide</a> and use the config provided
+above.
+</details>
+
+<details>
+  <summary>Codex</summary>
+
+Follow the <a href="https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp">configure MCP
+guide</a> using the standard config from above.
+</details>
+
+<details>
+  <summary>Cursor</summary>
+
+**Click the button to install:**
+
+[![Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=maven-indexer&config=eyJjb21tYW5kIjoibnB4IC15IG1hdmVuLWluZGV4ZXItbWNwQGxhdGVzdCJ9)
+
+**Or install manually:**
+
+Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
+
+</details>
+
+<details>
+  <summary>JetBrains AI Assistant & Junie</summary>
+
+Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.
+The same way `maven-indexer` can be configured for JetBrains Junie in `Settings | Tools | Junie | MCP Settings` ->`Add`.
+Use the config provided above.
+</details>
+
+<details>
+  <summary>Kiro</summary>
+
+In **Kiro Settings**, go to `Configure MCP` > `Open Workspace or User MCP Config` > Use the configuration snippet
+provided above.
 
-If the auto-detection fails, or if you want to filter which packages are indexed, you can add environment variables to the configuration:
+Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Config`. Use the configuration snippet
+provided above.
 
-*   **`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.
+</details>
+
+<details>
+  <summary>Qoder</summary>
+
+In **Qoder Settings**, go to `MCP Server` > `+ Add` > Use the configuration snippet provided above.
+
+Alternatively, follow the <a href="https://docs.qoder.com/user-guide/chat/model-context-protocol">MCP guide</a> and use
+the standard config from above.
+
+</details>
+
+<details>
+  <summary>Trae</summary>
+
+Go to `Settings` -> `MCP` -> `+ Add` -> `Add Manually` to add an MCP Server. Use the config provided above.
+</details>
+
+<details>
+  <summary>Windsurf</summary>
+
+Follow the <a href="https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json">configure MCP guide</a>
+using the standard config from above.
+</details>
+
+## Your first prompt
+
+Enter the following prompt in your MCP Client to check if everything is working:
+
+```text
+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.
+
+### 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:
 
@@ -44,12 +151,16 @@ Example with optional configuration:
   "mcpServers": {
     "maven-indexer": {
       "command": "npx",
-      "args": ["-y", "maven-indexer-mcp@latest"],
+      "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"
+        "MAVEN_INDEXER_CFR_PATH": "/path/to/cfr-0.152.jar",
+        "VERSION_RESOLUTION_STRATEGY": "semver"
       }
     }
   }
@@ -60,19 +171,22 @@ Example with optional configuration:
 
 If you prefer to run from source:
 
-1.  Clone the repository:
+1. Clone the repository:
+
     ```bash
     git clone https://github.com/tangcent/maven-indexer-mcp.git
     cd maven-indexer-mcp
     ```
 
-2.  Install dependencies and build:
+2. Install dependencies and build:
+
     ```bash
     npm install
     npm run build
     ```
 
-3.  Use the absolute path in your config:
+3. Use the absolute path in your config:
+
     ```json
     {
       "mcpServers": {
@@ -86,31 +200,38 @@ If you prefer to run from source:
 
 ## Available Tools
 
-*   **`search_classes`**: Search for Java classes in the local Maven repository (dependencies).
-    *   **WHEN TO USE**:
-        1.  You cannot find a class definition in the current project source (it's likely a dependency).
-        2.  You need to read the source code, method signatures, or Javadocs of an external library class.
-        3.  You need to verify which version of a library class is being used.
-    *   **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 library does—read the code."
-    *   **Tip**: When reviewing usages of an external class, use this to retrieve the class definition to understand the context fully.
-    *   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 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.
+* **`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.
 
 ## Development
 
-*   **Run tests**: `npm test`
-*   **Watch mode**: `npm run watch`
+* **Run tests**: `npm test`
+* **Watch mode**: `npm run watch`
 
 ## License
 
-ISC
+[ISC](LICENSE)

package/build/artifact_resolver.js

@@ -0,0 +1,109 @@
+import fs from 'fs';
+import path from 'path';
+import semver from 'semver';
+import { Config } from './config.js';
+export class ArtifactResolver {
+    static strategies = {
+        'semver': ArtifactResolver.compareSemver,
+        'latest-published': ArtifactResolver.compareLatestPublished,
+        'latest-used': ArtifactResolver.compareLatestUsed
+    };
+    static async resolveBestArtifact(artifacts) {
+        if (!artifacts || artifacts.length === 0)
+            return undefined;
+        const config = await Config.getInstance();
+        const comparator = this.strategies[config.versionResolutionStrategy] || this.strategies['semver'];
+        const sorted = [...artifacts].sort((a, b) => {
+            // 1. Always prefer source if available
+            if (a.hasSource !== b.hasSource) {
+                return a.hasSource ? -1 : 1; // source comes first
+            }
+            // 2. Apply configured strategy
+            try {
+                return comparator(a, b);
+            }
+            catch (e) {
+                // Fallback to ID comparison (likely insert order)
+                return b.id - a.id;
+            }
+        });
+        return sorted[0];
+    }
+    static compareSemver(a, b) {
+        const vA = semver.coerce(a.version);
+        const vB = semver.coerce(b.version);
+        if (vA && vB) {
+            const comparison = semver.rcompare(vA, vB);
+            if (comparison !== 0)
+                return comparison;
+        }
+        if (semver.valid(a.version) && semver.valid(b.version)) {
+            return semver.rcompare(a.version, b.version);
+        }
+        // Fallback for non-semver strings
+        return b.id - a.id;
+    }
+    static getArtifactFileTime(artifact, timeType) {
+        let p = artifact.abspath;
+        try {
+            if (fs.statSync(p).isDirectory()) {
+                // Try jar first, then pom
+                const jarPath = path.join(p, `${artifact.artifactId}-${artifact.version}.jar`);
+                if (fs.existsSync(jarPath))
+                    return fs.statSync(jarPath)[timeType].getTime();
+                const pomPath = path.join(p, `${artifact.artifactId}-${artifact.version}.pom`);
+                if (fs.existsSync(pomPath))
+                    return fs.statSync(pomPath)[timeType].getTime();
+            }
+            return fs.statSync(p)[timeType].getTime();
+        }
+        catch {
+            return 0;
+        }
+    }
+    static getArtifactPublishTime(artifact) {
+        let p = artifact.abspath;
+        try {
+            // 1. Try to read .lastUpdated file (priority)
+            if (fs.statSync(p).isDirectory()) {
+                const pomPath = path.join(p, `${artifact.artifactId}-${artifact.version}.pom`);
+                const lastUpdatedPath = `${pomPath}.lastUpdated`;
+                if (fs.existsSync(lastUpdatedPath)) {
+                    try {
+                        const content = fs.readFileSync(lastUpdatedPath, 'utf-8');
+                        // Try to find property with timestamp
+                        const matches = content.match(/lastUpdated=(\d{13})/g);
+                        if (matches) {
+                            let maxTime = 0;
+                            for (const match of matches) {
+                                const ts = parseInt(match.split('=')[1]);
+                                if (!isNaN(ts) && ts > maxTime)
+                                    maxTime = ts;
+                            }
+                            if (maxTime > 0)
+                                return maxTime;
+                        }
+                    }
+                    catch (e) {
+                        // ignore parse error
+                    }
+                }
+            }
+            // 2. Fallback to mtime
+            return ArtifactResolver.getArtifactFileTime(artifact, 'mtime');
+        }
+        catch {
+            return 0;
+        }
+    }
+    static compareLatestPublished(a, b) {
+        const tA = ArtifactResolver.getArtifactPublishTime(a);
+        const tB = ArtifactResolver.getArtifactPublishTime(b);
+        return tB - tA; // Newer first
+    }
+    static compareLatestUsed(a, b) {
+        const tA = ArtifactResolver.getArtifactFileTime(a, 'birthtime');
+        const tB = ArtifactResolver.getArtifactFileTime(b, 'birthtime');
+        return tB - tA; // Newer first
+    }
+}

package/build/config.js

@@ -11,7 +11,9 @@ export class Config {
     gradleRepository = "";
     javaBinary = "java";
     includedPackages = ["*"];
+    normalizedIncludedPackages = [];
     cfrPath = null;
+    versionResolutionStrategy = 'semver';
     constructor() { }
     static async getInstance() {
         if (!Config.instance) {
@@ -79,6 +81,7 @@ export class Config {
                 .map(p => p.trim())
                 .filter(p => p.length > 0);
         }
+        this.normalizedIncludedPackages = this.normalizeScanPatterns(this.includedPackages);
         // Load CFR Path
         if (process.env.MAVEN_INDEXER_CFR_PATH) {
             this.cfrPath = process.env.MAVEN_INDEXER_CFR_PATH;
@@ -89,6 +92,24 @@ export class Config {
             const __dirname = path.dirname(__filename);
             this.cfrPath = path.resolve(__dirname, '../lib/cfr-0.152.jar');
         }
+        if (process.env.VERSION_RESOLUTION_STRATEGY) {
+            const strategy = process.env.VERSION_RESOLUTION_STRATEGY.toLowerCase();
+            if (strategy === 'semver' || strategy === 'latest-published' || strategy === 'latest-used') {
+                this.versionResolutionStrategy = strategy;
+            }
+            else if (strategy === 'semver-latest') {
+                // Backward compatibility
+                this.versionResolutionStrategy = 'semver';
+            }
+            else if (strategy === 'date-latest' || strategy === 'modification-time' || strategy === 'publish-time') {
+                // Backward compatibility
+                this.versionResolutionStrategy = 'latest-published';
+            }
+            else if (strategy === 'creation-time' || strategy === 'usage-time') {
+                // Backward compatibility
+                this.versionResolutionStrategy = 'latest-used';
+            }
+        }
         if (this.cfrPath && !(await this.fileExists(this.cfrPath))) {
             try {
                 console.error(`CFR jar not found at ${this.cfrPath}, attempting to download...`);
@@ -174,4 +195,55 @@ export class Config {
         }
         return null;
     }
+    /**
+     * Normalizes package patterns for scanning.
+     * 1. Filters out empty or whitespace-only patterns.
+     * 2. Removes wildcards ('*', '.*').
+     * 3. Sorts and removes duplicates/sub-packages.
+     *
+     * @param patterns The raw patterns from configuration.
+     * @returns A list of normalized package prefixes. Returns [] if all packages should be scanned.
+     */
+    normalizeScanPatterns(patterns) {
+        if (!patterns || patterns.length === 0) {
+            return [];
+        }
+        // 1. Filter empty/blank patterns and remove wildcards
+        let clean = patterns
+            .map(p => p.trim())
+            .filter(p => p.length > 0) // Ignore empty strings
+            .map(p => {
+            if (p.endsWith('.*'))
+                return p.slice(0, -2);
+            if (p === '*')
+                return ''; // Will be filtered out later if we want strict prefixes, but '*' usually means ALL
+            return p;
+        });
+        // If any pattern became empty string (meaning '*') or was originally '*', it implies "Scan All"
+        if (clean.includes('')) {
+            return [];
+        }
+        if (clean.length === 0) {
+            // Usually empty config means Scan All.
+            return [];
+        }
+        // 2. Sort to ensure parents come before children
+        clean.sort();
+        // 3. Remove duplicates and sub-packages
+        const result = [];
+        for (const p of clean) {
+            if (result.length === 0) {
+                result.push(p);
+                continue;
+            }
+            const last = result[result.length - 1];
+            // Check if 'p' is sub-package of 'last'
+            // e.g. last="com.test", p="com.test.demo" -> p starts with last + '.'
+            if (p === last || p.startsWith(last + '.')) {
+                continue;
+            }
+            result.push(p);
+        }
+        return result;
+    }
 }