maven-indexer-mcp 1.0.6 → 1.0.8

package/README.md

@@ -1,21 +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)
 
-**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.
+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.
 
-This server bridges that gap by allowing the AI to "read" your local dependencies, effectively giving it knowledge of your private and obscure libraries.
+**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
 
@@ -26,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.
+
+Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open 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:
+</details>
 
-*   **`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>
+  <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:
 
@@ -50,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"
       }
     }
   }
@@ -66,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": {
@@ -92,32 +200,38 @@ If you prefer to run from source:
 
 ## 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.
+* **`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;
+    }
 }

package/build/db/index.js

@@ -1,13 +1,26 @@
 import Database from 'better-sqlite3';
 import path from 'path';
+import os from 'os';
+import fs from 'fs';
 export class DB {
     static instance;
     db;
     constructor() {
         // Check environment variable for DB path (useful for testing)
-        const dbName = process.env.DB_FILE || 'maven-index.sqlite';
-        const dbPath = path.join(process.cwd(), dbName);
-        this.db = new Database(dbPath);
+        if (process.env.DB_FILE) {
+            this.db = new Database(process.env.DB_FILE);
+        }
+        else {
+            // Use home directory for the database file
+            const homeDir = os.homedir();
+            const configDir = path.join(homeDir, '.maven-indexer-mcp');
+            // Ensure the directory exists
+            if (!fs.existsSync(configDir)) {
+                fs.mkdirSync(configDir, { recursive: true });
+            }
+            const dbPath = path.join(configDir, 'maven-index.sqlite');
+            this.db = new Database(dbPath);
+        }
         this.initSchema();
     }
     static getInstance() {

package/build/index.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { z } from "zod";
 import { Indexer } from "./indexer.js";
 import { SourceParser } from "./source_parser.js";
+import { ArtifactResolver } from "./artifact_resolver.js";
 const server = new McpServer({
     name: "maven-indexer",
     version: "1.0.0",
@@ -22,7 +23,7 @@ indexer.index().then(() => {
     return indexer.startWatch();
 }).catch(err => console.error("Initial indexing failed:", err));
 server.registerTool("get_class_details", {
-    description: "Retrieve the source code for a class from the **local Maven/Gradle cache** (containing **internal company libraries**). This tool identifies the containing artifact and returns the source code. It prefers actual source files but will fall back to decompilation if necessary. **Use this primarily for internal company libraries** that are not present in the current workspace. **IMPORTANT: Even if the code compiles and imports work, the source code might not be in the current workspace (it comes from a compiled internal library).** Use this tool to see the actual implementation of those internal libraries. Supports batch queries.",
+    description: "Retrieve the source code for a class from the local Maven/Gradle cache (containing internal company libraries). This tool identifies the containing artifact and returns the source code. It prefers actual source files but will fall back to decompilation if necessary. Use this primarily for internal company libraries that are not present in the current workspace. IMPORTANT: Even if the code compiles and imports work, the source code might not be in the current workspace (it comes from a compiled internal library). Use this tool to see the actual implementation of those internal libraries. Supports batch queries.",
     inputSchema: z.object({
         className: z.string().optional().describe("Fully qualified class name"),
         classNames: z.array(z.string()).optional().describe("Batch class names"),
@@ -58,17 +59,11 @@ server.registerTool("get_class_details", {
                 return `Class '${clsName}' not found in the index. Try 'search_classes' with a keyword if you are unsure of the full name.`;
             }
             // We have an exact match, choose the best artifact
-            // Strategy: 1. Prefer hasSource=true. 2. Prefer highest ID (likely newest).
-            const artifacts = exactMatch.artifacts.sort((a, b) => {
-                if (a.hasSource !== b.hasSource) {
-                    return a.hasSource ? -1 : 1; // source comes first
-                }
-                return b.id - a.id; // higher ID comes first
-            });
-            if (artifacts.length === 0) {
+            const bestArtifact = await ArtifactResolver.resolveBestArtifact(exactMatch.artifacts);
+            if (!bestArtifact) {
                 return `Class '${clsName}' found but no artifacts are associated with it (database inconsistency).`;
             }
-            targetArtifact = artifacts[0];
+            targetArtifact = bestArtifact;
         }
         const artifact = targetArtifact;
         let detail = null;
@@ -159,7 +154,7 @@ server.registerTool("get_class_details", {
     return { content: [{ type: "text", text: results.join("\n\n") }] };
 });
 server.registerTool("search_artifacts", {
-    description: "Search for **internal company artifacts** and libraries in the local Maven repository and Gradle caches by coordinate (groupId, artifactId) or keyword. **Use this primarily for internal company packages** or to find available versions of internal projects that are locally built. Also supports searching third-party libraries in the local cache. Supports batch queries.",
+    description: "Search for internal company artifacts and libraries in the local Maven repository and Gradle caches by coordinate (groupId, artifactId) or keyword. Use this primarily for internal company packages or to find available versions of internal projects that are locally built. Also supports searching third-party libraries in the local cache. Supports batch queries.",
     inputSchema: z.object({
         query: z.string().optional().describe("Search query (groupId, artifactId, or keyword)"),
         queries: z.array(z.string()).optional().describe("Batch search queries"),
@@ -192,7 +187,7 @@ server.registerTool("search_artifacts", {
     };
 });
 server.registerTool("search_classes", {
-    description: "Search for Java classes in **internal company libraries** found in the local Maven/Gradle caches. **Essential for finding classes in internal company libraries** that are not part of the current workspace source code. Use this when you see an import (e.g., 'com.company.util.Helper') but cannot find the definition. **Do not assume that because the code compiles or the import exists, the source is local.** It often comes from a compiled **internal library**. This tool helps locate the defining artifact. Supports batch queries.",
+    description: "Search for Java classes in internal company libraries found in the local Maven/Gradle caches. Essential for finding classes in internal company libraries that are not part of the current workspace source code. Use this when you see an import (e.g., 'com.company.util.Helper') but cannot find the definition. Do not assume that because the code compiles or the import exists, the source is local. It often comes from a compiled internal library. This tool helps locate the defining artifact. Supports batch queries.",
     inputSchema: z.object({
         className: z.string().optional().describe("Fully qualified class name, partial name, or keywords describing the class purpose (e.g. 'JsonToXml')."),
         classNames: z.array(z.string()).optional().describe("Batch class names"),
@@ -223,7 +218,7 @@ server.registerTool("search_classes", {
     };
 });
 server.registerTool("search_implementations", {
-    description: "Search for **internal implementations** of an interface or base class. **This is particularly useful for finding implementations of SPIs or base classes within internal company libraries** in the local Maven/Gradle cache. Supports batch queries.",
+    description: "Search for internal implementations of an interface or base class. This is particularly useful for finding implementations of SPIs or base classes within internal company libraries in the local Maven/Gradle cache. Supports batch queries.",
     inputSchema: z.object({
         className: z.string().optional().describe("Fully qualified class name of the interface or base class (e.g. 'java.util.List')"),
         classNames: z.array(z.string()).optional().describe("Batch class names"),

package/build/indexer.js

@@ -15,7 +15,9 @@ export class Indexer {
     isIndexing = false;
     watcher = null;
     debounceTimer = null;
-    constructor() { }
+    pollingTimer = null;
+    constructor() {
+    }
     static getInstance() {
         if (!Indexer.instance) {
             Indexer.instance = new Indexer();
@@ -23,49 +25,95 @@ export class Indexer {
         return Indexer.instance;
     }
     /**
-     * Starts watching the local repository for changes.
-     * Debounces changes to trigger re-indexing.
+     * Starts watching the local repository for changes - ULTRA SIMPLE VERSION
+     * Just watch the root directories without recursion
      */
     async startWatch() {
         const config = await Config.getInstance();
-        const pathsToWatch = [];
+        const watchPaths = [];
+        // Simple: Just add the main repository paths
         if (config.localRepository && fsSync.existsSync(config.localRepository)) {
-            pathsToWatch.push(config.localRepository);
+            watchPaths.push(config.localRepository);
         }
         if (config.gradleRepository && fsSync.existsSync(config.gradleRepository)) {
-            pathsToWatch.push(config.gradleRepository);
+            watchPaths.push(config.gradleRepository);
         }
-        if (pathsToWatch.length === 0) {
+        if (watchPaths.length === 0) {
             console.error("No repository paths found, skipping watch mode.");
             return;
         }
-        if (this.watcher) {
+        if (this.watcher || this.pollingTimer) {
             return;
         }
-        console.error(`Starting file watcher on ${pathsToWatch.join(', ')}...`);
-        this.watcher = chokidar.watch(pathsToWatch, {
-            ignored: /(^|[\/\\])\../, // ignore dotfiles
-            persistent: true,
-            ignoreInitial: true,
-            depth: 10 // Limit depth to avoid too much overhead? Standard maven repo depth is around 3-5
-        });
-        const onChange = () => {
-            if (this.debounceTimer)
-                clearTimeout(this.debounceTimer);
-            this.debounceTimer = setTimeout(() => {
-                console.error("Repository change detected. Triggering re-index...");
-                this.index().catch(console.error);
-            }, 5000); // Debounce for 5 seconds
-        };
-        this.watcher
-            .on('add', (path) => {
-            if (path.endsWith('.jar') || path.endsWith('.pom'))
-                onChange();
-        })
-            .on('unlink', (path) => {
-            if (path.endsWith('.jar') || path.endsWith('.pom'))
-                onChange();
-        });
+        console.error(`🔍 Starting ultra-simple file watcher on: ${watchPaths.join(', ')}`);
+        try {
+            // ULTRA SIMPLE: Watch only root directories, no recursion
+            this.watcher = chokidar.watch(watchPaths, {
+                // Watch only the root directory itself, not subdirectories
+                depth: 0,
+                // Don't trigger for files that already exist
+                ignoreInitial: true,
+                // Wait for files to finish writing before triggering
+                awaitWriteFinish: {
+                    stabilityThreshold: 2000,
+                    pollInterval: 100
+                },
+                // Don't crash on permission errors
+                ignorePermissionErrors: true
+            });
+            // SIMPLE: Watch for any changes in the root directories
+            // This will catch when new directories are created (which means new artifacts)
+            this.watcher
+                .on('addDir', (dirPath) => {
+                console.error(`� New directory detected: ${path.basename(dirPath)}`);
+                this.triggerReindex();
+            })
+                .on('unlinkDir', (dirPath) => {
+                console.error(`🗑️  Directory removed: ${path.basename(dirPath)}`);
+                this.triggerReindex();
+            })
+                .on('error', (error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`❌ Watcher error: ${errorMessage}`);
+                this.fallbackToPolling();
+            });
+            console.error('✅ Ultra-simple file watcher started successfully');
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`❌ Failed to start watcher: ${errorMessage}`);
+            this.fallbackToPolling();
+        }
+    }
+    /**
+     * Falls back to polling mode if watcher fails.
+     * Polls the repository every 1 min
+     */
+    fallbackToPolling() {
+        if (this.pollingTimer) {
+            return;
+        }
+        console.error('⚠️ Falling back to polling mode (every 10s)...');
+        if (this.watcher) {
+            this.watcher.close().catch(err => console.error(`Error closing watcher: ${err}`));
+            this.watcher = null;
+        }
+        this.pollingTimer = setInterval(() => {
+            this.index().catch(console.error);
+        }, 60000);
+    }
+    /**
+     * Trigger reindexing with debouncing (wait a bit for multiple changes)
+     */
+    triggerReindex() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        // Wait 3 seconds after the last change before reindexing
+        this.debounceTimer = setTimeout(() => {
+            console.error('🔄 Changes detected - triggering reindex...');
+            this.index().catch(console.error);
+        }, 3000);
     }
     /**
      * Forces a full re-index of the repository.
@@ -105,13 +153,13 @@ export class Indexer {
             let artifacts = [];
             if (repoPath && fsSync.existsSync(repoPath)) {
                 console.error(`Scanning Maven repo: ${repoPath}`);
-                const mavenArtifacts = await this.scanRepository(repoPath);
+                const mavenArtifacts = await this.scanRepository(repoPath, config.normalizedIncludedPackages);
                 console.error(`Found ${mavenArtifacts.length} Maven artifacts.`);
                 artifacts = artifacts.concat(mavenArtifacts);
             }
             if (gradleRepoPath && fsSync.existsSync(gradleRepoPath)) {
                 console.error(`Scanning Gradle repo: ${gradleRepoPath}`);
-                const gradleArtifacts = await this.scanGradleRepository(gradleRepoPath);
+                const gradleArtifacts = await this.scanGradleRepository(gradleRepoPath, config.normalizedIncludedPackages);
                 console.error(`Found ${gradleArtifacts.length} Gradle artifacts.`);
                 artifacts = artifacts.concat(gradleArtifacts);
             }
@@ -119,9 +167,10 @@ export class Indexer {
             // 2. Persist artifacts and determine what needs indexing
             // We use is_indexed = 0 for new artifacts.
             const insertArtifact = db.prepare(`
-            INSERT OR IGNORE INTO artifacts (group_id, artifact_id, version, abspath, has_source, is_indexed)
-            VALUES (@groupId, @artifactId, @version, @abspath, @hasSource, 0)
-        `);
+                INSERT
+                OR IGNORE INTO artifacts (group_id, artifact_id, version, abspath, has_source, is_indexed)
+                VALUES (@groupId, @artifactId, @version, @abspath, @hasSource, 0)
+            `);
             // Use a transaction only for the batch insert of artifacts
             db.transaction(() => {
                 for (const art of artifacts) {
@@ -144,10 +193,10 @@ export class Indexer {
             }
             // 3. Find artifacts that need indexing (is_indexed = 0)
             const artifactsToIndex = db.prepare(`
-            SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
-            FROM artifacts 
-            WHERE is_indexed = 0
-        `).all();
+                SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
+                FROM artifacts
+                WHERE is_indexed = 0
+            `).all();
             console.error(`${artifactsToIndex.length} artifacts need indexing.`);
             // 4. Scan JARs for classes and update DB
             const CHUNK_SIZE = 50;
@@ -171,8 +220,11 @@ export class Indexer {
     }
     /**
      * Recursively scans a directory for Maven artifacts (POM files).
+     *
+     * @param repoRoot The root directory of the Maven repository.
+     * @param normalizedPatterns List of normalized package patterns to include.
      */
-    async scanRepository(rootDir) {
+    async scanRepository(repoRoot, normalizedPatterns = []) {
         const results = [];
         const scanDir = async (dir) => {
             let entries;
@@ -188,7 +240,7 @@ export class Indexer {
                 const artifactDir = path.dirname(dir);
                 const artifactId = path.basename(artifactDir);
                 const groupDir = path.dirname(artifactDir);
-                const relGroupPath = path.relative(rootDir, groupDir);
+                const relGroupPath = path.relative(repoRoot, groupDir);
                 const groupId = relGroupPath.split(path.sep).join('.');
                 if (groupId && artifactId && version && !groupId.startsWith('..')) {
                     const sourceJarPath = path.join(dir, `${artifactId}-${version}-sources.jar`);
@@ -213,14 +265,49 @@ export class Indexer {
                 }
             }
         };
-        await scanDir(rootDir);
+        const startDirs = this.getMavenStartDirs(repoRoot, normalizedPatterns);
+        console.error(`Scanning Maven directories: ${startDirs.join(', ')}`);
+        for (const startDir of startDirs) {
+            await scanDir(startDir);
+        }
         return results;
     }
+    /**
+     * Calculates the starting directories for Maven scanning based on included packages.
+     *
+     * @param repoRoot The root of the Maven repository.
+     * @param normalizedPatterns The list of normalized included packages.
+     */
+    getMavenStartDirs(repoRoot, normalizedPatterns) {
+        if (normalizedPatterns.length === 0) {
+            return [repoRoot];
+        }
+        return normalizedPatterns.map(p => path.join(repoRoot, p.split('.').join(path.sep)));
+    }
+    /**
+     * Checks if a group ID is included in the normalized patterns.
+     *
+     * @param groupId The group ID (e.g., "com.google.guava").
+     * @param normalizedPatterns The list of normalized patterns.
+     */
+    isGroupIncluded(groupId, normalizedPatterns) {
+        if (!normalizedPatterns || normalizedPatterns.length === 0)
+            return true;
+        for (const pattern of normalizedPatterns) {
+            if (groupId === pattern || groupId.startsWith(pattern + '.')) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Scans a Gradle cache directory for artifacts.
      * Structure: group/artifact/version/hash/file
+     *
+     * @param rootDir The root directory of the Gradle cache (e.g., ~/.gradle/caches/modules-2/files-2.1).
+     * @param normalizedPatterns List of normalized package patterns to include.
      */
-    async scanGradleRepository(rootDir) {
+    async scanGradleRepository(rootDir, normalizedPatterns = []) {
         const results = [];
         // Helper to read directory safely
         const readDirSafe = async (p) => {
@@ -236,6 +323,9 @@ export class Indexer {
             if (!groupEntry.isDirectory())
                 continue;
             const groupId = groupEntry.name;
+            if (!this.isGroupIncluded(groupId, normalizedPatterns)) {
+                continue;
+            }
             const groupPath = path.join(rootDir, groupId);
             const artifactDirs = await readDirSafe(groupPath);
             for (const artifactEntry of artifactDirs) {
@@ -302,7 +392,7 @@ export class Indexer {
             await fs.access(jarPath);
         }
         catch {
-            // If jar missing, mark as indexed so we don't retry endlessly? 
+            // If jar missing, mark as indexed so we don't retry endlessly?
             // Or maybe it's a pom-only artifact.
             db.prepare('UPDATE artifacts SET is_indexed = 1 WHERE id = ?').run(artifact.id);
             return;
@@ -333,13 +423,21 @@ export class Indexer {
                                     // Simple check to avoid module-info or invalid names
                                     if (!info.className.includes('$') && info.className.length > 0) {
                                         // Filter by includedPackages
-                                        if (this.isPackageIncluded(info.className, config.includedPackages)) {
+                                        if (this.isPackageIncluded(info.className, config.normalizedIncludedPackages)) {
                                             classes.push(info.className);
                                             if (info.superClass && info.superClass !== 'java.lang.Object') {
-                                                inheritance.push({ className: info.className, parent: info.superClass, type: 'extends' });
+                                                inheritance.push({
+                                                    className: info.className,
+                                                    parent: info.superClass,
+                                                    type: 'extends'
+                                                });
                                             }
                                             for (const iface of info.interfaces) {
-                                                inheritance.push({ className: info.className, parent: iface, type: 'implements' });
+                                                inheritance.push({
+                                                    className: info.className,
+                                                    parent: iface,
+                                                    type: 'implements'
+                                                });
                                             }
                                         }
                                     }
@@ -360,13 +458,13 @@ export class Indexer {
                     try {
                         db.transaction(() => {
                             const insertClass = db.prepare(`
-                              INSERT INTO classes_fts (artifact_id, class_name, simple_name)
-                              VALUES (?, ?, ?)
-                          `);
+                                INSERT INTO classes_fts (artifact_id, class_name, simple_name)
+                                VALUES (?, ?, ?)
+                            `);
                             const insertInheritance = db.prepare(`
-                              INSERT INTO inheritance (artifact_id, class_name, parent_class_name, type)
-                              VALUES (?, ?, ?, ?)
-                          `);
+                                INSERT INTO inheritance (artifact_id, class_name, parent_class_name, type)
+                                VALUES (?, ?, ?, ?)
+                            `);
                             for (const cls of classes) {
                                 const simpleName = cls.split('.').pop() || cls;
                                 insertClass.run(artifact.id, cls, simpleName);
@@ -391,23 +489,17 @@ export class Indexer {
     }
     /**
      * Checks if a class package is included in the configuration patterns.
+     *
+     * @param className The fully qualified class name.
+     * @param normalizedPatterns The list of normalized package patterns.
      */
-    isPackageIncluded(className, patterns) {
-        if (patterns.length === 0 || (patterns.length === 1 && patterns[0] === '*'))
+    isPackageIncluded(className, normalizedPatterns) {
+        if (!normalizedPatterns || normalizedPatterns.length === 0)
             return true;
-        for (const pattern of patterns) {
-            if (pattern === '*')
+        for (const pattern of normalizedPatterns) {
+            // Match exact package or subpackage
+            if (className === pattern || className.startsWith(pattern + '.')) {
                 return true;
-            if (pattern.endsWith('.*')) {
-                const prefix = pattern.slice(0, -2); // "com.example"
-                // Match exact package or subpackage
-                if (className === prefix || className.startsWith(prefix + '.'))
-                    return true;
-            }
-            else {
-                // Exact match
-                if (className === pattern)
-                    return true;
             }
         }
         return false;
@@ -419,11 +511,11 @@ export class Indexer {
         // Artifact coordinates search
         const db = DB.getInstance();
         const rows = db.prepare(`
-          SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
-          FROM artifacts
-          WHERE group_id LIKE ? OR artifact_id LIKE ?
-          LIMIT 50
-      `).all(`%${query}%`, `%${query}%`);
+            SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
+            FROM artifacts
+            WHERE group_id LIKE ?
+               OR artifact_id LIKE ? LIMIT 50
+        `).all(`%${query}%`, `%${query}%`);
         return rows;
     }
     /**
@@ -438,12 +530,19 @@ export class Indexer {
                 // Regex search
                 const regex = classNamePattern.substring(6);
                 rows = db.prepare(`
-                  SELECT c.class_name, c.simple_name, a.id, a.group_id, a.artifact_id, a.version, a.abspath, a.has_source
-                  FROM classes_fts c
-                  JOIN artifacts a ON c.artifact_id = a.id
-                  WHERE c.class_name REGEXP ? OR c.simple_name REGEXP ?
+                    SELECT c.class_name,
+                           c.simple_name,
+                           a.id,
+                           a.group_id,
+                           a.artifact_id,
+                           a.version,
+                           a.abspath,
+                           a.has_source
+                    FROM classes_fts c
+                             JOIN artifacts a ON c.artifact_id = a.id
+                    WHERE c.class_name REGEXP ? OR c.simple_name REGEXP ?
                   LIMIT 100
-              `).all(regex, regex);
+                `).all(regex, regex);
             }
             else if (classNamePattern.includes('*') || classNamePattern.includes('?')) {
                 // Glob-style search (using LIKE for standard wildcards)
@@ -451,12 +550,19 @@ export class Indexer {
                 // But standard glob is * and ?
                 const likePattern = classNamePattern.replace(/\*/g, '%').replace(/\?/g, '_');
                 rows = db.prepare(`
-                  SELECT c.class_name, c.simple_name, a.id, a.group_id, a.artifact_id, a.version, a.abspath, a.has_source
-                  FROM classes_fts c
-                  JOIN artifacts a ON c.artifact_id = a.id
-                  WHERE c.class_name LIKE ? OR c.simple_name LIKE ?
-                  LIMIT 100
-              `).all(likePattern, likePattern);
+                    SELECT c.class_name,
+                           c.simple_name,
+                           a.id,
+                           a.group_id,
+                           a.artifact_id,
+                           a.version,
+                           a.abspath,
+                           a.has_source
+                    FROM classes_fts c
+                             JOIN artifacts a ON c.artifact_id = a.id
+                    WHERE c.class_name LIKE ?
+                       OR c.simple_name LIKE ? LIMIT 100
+                `).all(likePattern, likePattern);
             }
             else {
                 // Use FTS for smart matching
@@ -468,13 +574,19 @@ export class Indexer {
                     ? `"${escapedPattern}"* OR ${safeQuery}`
                     : `"${escapedPattern}"*`;
                 rows = db.prepare(`
-                  SELECT c.class_name, c.simple_name, a.id, a.group_id, a.artifact_id, a.version, a.abspath, a.has_source
-                  FROM classes_fts c
-                  JOIN artifacts a ON c.artifact_id = a.id
-                  WHERE c.classes_fts MATCH ?
-                  ORDER BY rank
-                  LIMIT 100
-              `).all(query);
+                    SELECT c.class_name,
+                           c.simple_name,
+                           a.id,
+                           a.group_id,
+                           a.artifact_id,
+                           a.version,
+                           a.abspath,
+                           a.has_source
+                    FROM classes_fts c
+                             JOIN artifacts a ON c.artifact_id = a.id
+                    WHERE c.classes_fts MATCH ?
+                    ORDER BY rank LIMIT 100
+                `).all(query);
             }
             // Group by class name
             const resultMap = new Map();
@@ -516,16 +628,17 @@ export class Indexer {
             }
             // Recursive search for all implementations/subclasses
             const rows = db.prepare(`
-              WITH RECURSIVE hierarchy(class_name, artifact_id) AS (
-                SELECT class_name, artifact_id FROM inheritance WHERE parent_class_name = ?
-                UNION
-                SELECT i.class_name, i.artifact_id FROM inheritance i JOIN hierarchy h ON i.parent_class_name = h.class_name
-              )
-              SELECT DISTINCT h.class_name, a.id, a.group_id, a.artifact_id, a.version, a.abspath, a.has_source
-              FROM hierarchy h
-              JOIN artifacts a ON h.artifact_id = a.id
-              LIMIT 100
-          `).all(className);
+                WITH RECURSIVE hierarchy(class_name, artifact_id) AS (SELECT class_name, artifact_id
+                                                                      FROM inheritance
+                                                                      WHERE parent_class_name = ?
+                                                                      UNION
+                                                                      SELECT i.class_name, i.artifact_id
+                                                                      FROM inheritance i
+                                                                               JOIN hierarchy h ON i.parent_class_name = h.class_name)
+                SELECT DISTINCT h.class_name, a.id, a.group_id, a.artifact_id, a.version, a.abspath, a.has_source
+                FROM hierarchy h
+                         JOIN artifacts a ON h.artifact_id = a.id LIMIT 100
+            `).all(className);
             console.error(`Searching implementations for ${className}: found ${rows.length} rows.`);
             if (rows.length === 0) {
                 // Fallback: Try searching without recursion to see if direct children exist
@@ -563,9 +676,10 @@ export class Indexer {
     getArtifactById(id) {
         const db = DB.getInstance();
         const row = db.prepare(`
-          SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
-          FROM artifacts WHERE id = ?
-      `).get(id);
+            SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
+            FROM artifacts
+            WHERE id = ?
+        `).get(id);
         if (row) {
             return {
                 id: row.id,
@@ -584,10 +698,12 @@ export class Indexer {
     getArtifactByCoordinate(groupId, artifactId, version) {
         const db = DB.getInstance();
         const row = db.prepare(`
-          SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
-          FROM artifacts 
-          WHERE group_id = ? AND artifact_id = ? AND version = ?
-      `).get(groupId, artifactId, version);
+            SELECT id, group_id as groupId, artifact_id as artifactId, version, abspath, has_source as hasSource
+            FROM artifacts
+            WHERE group_id = ?
+              AND artifact_id = ?
+              AND version = ?
+        `).get(groupId, artifactId, version);
         if (row) {
             return {
                 id: row.id,

package/build/simple_watcher.js

@@ -0,0 +1,121 @@
+/**
+ * SIMPLIFIED FILE WATCHER for Maven Indexer
+ *
+ * This is a cleaned-up version that's easier to understand.
+ * It watches for new JAR and POM files in your Maven/Gradle repositories.
+ */
+import fs from 'fs';
+import path from 'path';
+export class SimpleWatcher {
+    watcher = null;
+    onChangeCallback;
+    constructor(onChangeCallback) {
+        this.onChangeCallback = onChangeCallback;
+    }
+    /**
+     * Start watching - SIMPLE VERSION
+     * Just watch the main folders and filter for JAR/POM files
+     */
+    async startWatching(mavenRepoPath, gradleRepoPath) {
+        if (this.watcher) {
+            console.log('Watcher already running');
+            return;
+        }
+        const watchPaths = [];
+        // Add Maven repo if it exists
+        if (mavenRepoPath && fs.existsSync(mavenRepoPath)) {
+            watchPaths.push(mavenRepoPath);
+        }
+        // Add Gradle repo if it exists  
+        if (gradleRepoPath && fs.existsSync(gradleRepoPath)) {
+            watchPaths.push(gradleRepoPath);
+        }
+        if (watchPaths.length === 0) {
+            console.log('No repository paths to watch');
+            return;
+        }
+        console.log(`🔍 Watching for new JAR/POM files in: ${watchPaths.join(', ')}`);
+        // SIMPLE: Use chokidar with basic ignore patterns
+        const chokidar = await import('chokidar');
+        this.watcher = chokidar.watch(watchPaths, {
+            // Ignore common junk files (simple patterns)
+            ignored: [
+                '**/.*', // Hidden files
+                '**/*.tmp', // Temp files
+                '**/*.sha1', // Checksum files
+                '**/*.sha256', // Checksum files
+                '**/*.md5', // Checksum files
+            ],
+            // Don't watch too deep (Maven repos are usually 3-4 levels)
+            depth: 6,
+            // Don't trigger for files that already exist
+            ignoreInitial: true,
+            // Wait for files to finish writing before triggering
+            awaitWriteFinish: {
+                stabilityThreshold: 2000, // Wait 2 seconds after file stops changing
+                pollInterval: 100
+            }
+        });
+        // SIMPLE: Just watch for new files being added
+        this.watcher
+            .on('add', (filePath) => {
+            // Only care about JAR and POM files
+            if (filePath.endsWith('.jar') || filePath.endsWith('.pom')) {
+                console.log(`📦 New file detected: ${path.basename(filePath)}`);
+                this.triggerReindex();
+            }
+        })
+            .on('unlink', (filePath) => {
+            // Also watch for files being deleted
+            if (filePath.endsWith('.jar') || filePath.endsWith('.pom')) {
+                console.log(`🗑️  File removed: ${path.basename(filePath)}`);
+                this.triggerReindex();
+            }
+        })
+            .on('error', (error) => {
+            console.log(`❌ Watcher error: ${error.message}`);
+        });
+        console.log('✅ File watcher started successfully');
+    }
+    /**
+     * Stop watching
+     */
+    stopWatching() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+            console.log('🛑 File watcher stopped');
+        }
+    }
+    /**
+     * Trigger reindexing with debouncing (wait a bit for multiple changes)
+     */
+    debounceTimer = null;
+    triggerReindex() {
+        // Clear any existing timer
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        // Wait 3 seconds after the last change before reindexing
+        this.debounceTimer = setTimeout(() => {
+            console.log('🔄 Changes detected - triggering reindex...');
+            this.onChangeCallback();
+        }, 3000);
+    }
+}
+/**
+ * USAGE EXAMPLE:
+ *
+ * const watcher = new SimpleWatcher(() => {
+ *     console.log('Time to reindex the repository!');
+ *     // Put your reindexing code here
+ * });
+ *
+ * await watcher.startWatching(
+ *     '/Users/tangcent/.m2/repository',
+ *     '/Users/tangcent/.gradle/caches/modules-2/files-2.1'
+ * );
+ *
+ * // Later... when you want to stop
+ * watcher.stopWatching();
+ **/ 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maven-indexer-mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "MCP server for indexing local Maven repository",
   "main": "build/index.js",
   "type": "module",
@@ -46,10 +46,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
+    "@types/semver": "^7.7.1",
     "@types/xml2js": "^0.4.14",
     "@types/yauzl": "^2.10.3",
     "better-sqlite3": "^12.5.0",
     "chokidar": "^5.0.0",
+    "semver": "^7.7.3",
     "xml2js": "^0.6.2",
     "yauzl": "^3.2.0",
     "zod": "^4.1.13"