maven-indexer-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2024 tangcent
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# Maven Indexer MCP Server
+
+A Model Context Protocol (MCP) server that indexes your local Maven repository (`~/.m2/repository`) and provides AI agents with tools to search for Java classes, method signatures, and source code.
+
+## Features
+
+*   **Semantic Class Search**: Search for classes by name (e.g., `StringUtils`) or purpose (e.g., `JsonToXml`).
+*   **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 Maven repository 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.
+
+## Getting Started
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "maven-indexer": {
+      "command": "npx",
+      "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`).
+
+### 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.
+*   **`INCLUDED_PACKAGES`**: Comma-separated list of package patterns to index (e.g., `com.mycompany.*,org.example.*`). Default is `*` (index everything).
+
+Example with optional configuration:
+
+```json
+{
+  "mcpServers": {
+    "maven-indexer": {
+      "command": "npx",
+      "args": ["-y", "maven-indexer-mcp@latest"],
+      "env": {
+        "MAVEN_REPO": "/Users/yourname/.m2/repository",
+        "INCLUDED_PACKAGES": "com.mycompany.*"
+      }
+    }
+  }
+}
+```
+
+### Local Development
+
+If you prefer to run from source:
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/tangcent/maven-indexer-mcp.git
+    cd maven-indexer-mcp
+    ```
+
+2.  Install dependencies and build:
+    ```bash
+    npm install
+    npm run build
+    ```
+
+3.  Use the absolute path in your config:
+    ```json
+    {
+      "mcpServers": {
+        "maven-indexer": {
+          "command": "node",
+          "args": ["/absolute/path/to/maven-indexer-mcp/build/index.js"]
+        }
+      }
+    }
+    ```
+
+## Available Tools
+
+*   **`search_classes`**: Search for Java classes.
+    *   Input: `className` (e.g., "StringUtils", "Json parser")
+    *   Output: List of matching classes with their artifacts.
+*   **`get_class_details`**: Get detailed information about a class.
+    *   Input: `className`, `artifactId`, `type` ("signatures", "docs", "source")
+    *   Output: Method signatures, Javadocs, or full source code.
+*   **`search_artifacts`**: Search for artifacts by coordinate (groupId, artifactId).
+
+## Development
+
+*   **Run tests**: `npm test`
+*   **Watch mode**: `npm run watch`
+
+## License
+
+ISC

package/build/config.js

@@ -0,0 +1,99 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import xml2js from 'xml2js';
+export class Config {
+    static instance;
+    localRepository = "";
+    javaBinary = "java";
+    includedPackages = ["*"];
+    constructor() { }
+    static async getInstance() {
+        if (!Config.instance) {
+            Config.instance = new Config();
+            await Config.instance.load();
+        }
+        return Config.instance;
+    }
+    // For testing
+    static reset() {
+        Config.instance = undefined;
+    }
+    async load() {
+        let repoPath = null;
+        // 1. Check environment variable
+        if (process.env.MAVEN_REPO_PATH) {
+            repoPath = process.env.MAVEN_REPO_PATH;
+        }
+        else if (process.env.MAVEN_REPO) {
+            repoPath = process.env.MAVEN_REPO;
+        }
+        // 2. Try user settings
+        if (!repoPath) {
+            const homeDir = os.homedir();
+            const userSettingsPath = path.join(homeDir, '.m2', 'settings.xml');
+            if (await this.fileExists(userSettingsPath)) {
+                repoPath = await this.parseSettings(userSettingsPath);
+            }
+        }
+        // 3. Try global settings if not found
+        if (!repoPath && process.env.M2_HOME) {
+            const globalSettingsPath = path.join(process.env.M2_HOME, 'conf', 'settings.xml');
+            if (await this.fileExists(globalSettingsPath)) {
+                repoPath = await this.parseSettings(globalSettingsPath);
+            }
+        }
+        // 4. Default
+        if (!repoPath) {
+            repoPath = path.join(os.homedir(), '.m2', 'repository');
+        }
+        this.localRepository = repoPath;
+        // Load Java Path
+        if (process.env.JAVA_HOME) {
+            this.javaBinary = path.join(process.env.JAVA_HOME, 'bin', 'java');
+        }
+        // Allow explicit override
+        if (process.env.JAVA_PATH) {
+            this.javaBinary = process.env.JAVA_PATH;
+        }
+        // Load Included Packages
+        if (process.env.INCLUDED_PACKAGES) {
+            this.includedPackages = process.env.INCLUDED_PACKAGES.split(',')
+                .map(p => p.trim())
+                .filter(p => p.length > 0);
+        }
+        // Log to stderr so it doesn't interfere with MCP protocol on stdout
+        console.error(`Using local repository: ${this.localRepository}`);
+        console.error(`Using Java binary: ${this.javaBinary}`);
+        console.error(`Included packages: ${JSON.stringify(this.includedPackages)}`);
+    }
+    getJavapPath() {
+        if (this.javaBinary === 'java')
+            return 'javap';
+        const dir = path.dirname(this.javaBinary);
+        return path.join(dir, 'javap');
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async parseSettings(filePath) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const parser = new xml2js.Parser();
+            const result = await parser.parseStringPromise(content);
+            if (result.settings && result.settings.localRepository && result.settings.localRepository[0]) {
+                return result.settings.localRepository[0];
+            }
+        }
+        catch (error) {
+            console.error(`Failed to parse ${filePath}:`, error);
+        }
+        return null;
+    }
+}

package/build/db/index.js

@@ -0,0 +1,53 @@
+import Database from 'better-sqlite3';
+import path from 'path';
+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);
+        this.initSchema();
+    }
+    static getInstance() {
+        if (!DB.instance) {
+            DB.instance = new DB();
+        }
+        return DB.instance;
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS artifacts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        group_id TEXT NOT NULL,
+        artifact_id TEXT NOT NULL,
+        version TEXT NOT NULL,
+        abspath TEXT NOT NULL,
+        has_source INTEGER DEFAULT 0,
+        UNIQUE(group_id, artifact_id, version)
+      );
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS classes_fts USING fts5(
+        artifact_id UNINDEXED,
+        class_name, -- Fully qualified name
+        simple_name, -- Just the class name
+        tokenize="trigram" 
+      );
+      
+      -- Helper table to track indexed artifacts to avoid re-indexing unchanged ones (simplification: just track ID)
+      CREATE TABLE IF NOT EXISTS indexed_artifacts (
+          artifact_id INTEGER PRIMARY KEY
+      );
+    `);
+    }
+    getDb() {
+        return this.db;
+    }
+    prepare(sql) {
+        return this.db.prepare(sql);
+    }
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+}

package/build/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import path from 'path';
+import { Indexer } from "./indexer.js";
+import { SourceParser } from "./source_parser.js";
+const server = new Server({
+    name: "maven-indexer",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Start indexing in the background
+const indexer = Indexer.getInstance();
+// We trigger indexing but don't await it so server can start
+indexer.index().then(() => {
+    // Start watching for changes after initial index
+    return indexer.startWatch();
+}).catch(err => console.error("Initial indexing failed:", err));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "search_artifacts",
+                description: "Search for artifacts in the local Maven repository",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search query (groupId, artifactId, or keyword)",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "search_classes",
+                description: "Search for Java classes. Can be used to find classes by name or to find classes for a specific purpose (by searching keywords in class names).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        className: {
+                            type: "string",
+                            description: "Fully qualified class name, partial name, or keywords describing the class purpose (e.g. 'JsonToXml').",
+                        },
+                    },
+                    required: ["className"],
+                },
+            },
+            {
+                name: "get_class_details",
+                description: "Get details about a specific class from an artifact, including method signatures and javadocs (if source is available).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        className: {
+                            type: "string",
+                            description: "Fully qualified class name",
+                        },
+                        artifactId: {
+                            type: "number",
+                            description: "The internal ID of the artifact (returned by search_classes)",
+                        },
+                        type: {
+                            type: "string",
+                            enum: ["signatures", "docs", "source"],
+                            description: "Type of detail to retrieve: 'signatures' (methods), 'docs' (javadocs + methods), 'source' (full source code).",
+                        }
+                    },
+                    required: ["className", "artifactId", "type"],
+                },
+            },
+            {
+                name: "refresh_index",
+                description: "Trigger a re-scan of the Maven repository",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            }
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "search_artifacts") {
+        const query = String(request.params.arguments?.query);
+        const matches = indexer.search(query);
+        // Limit results to avoid overflow
+        const limitedMatches = matches.slice(0, 20);
+        const text = limitedMatches.length > 0
+            ? limitedMatches.map(a => `[ID: ${a.id}] ${a.groupId}:${a.artifactId}:${a.version} (Has Source: ${a.hasSource})`).join("\n")
+            : "No artifacts found matching the query.";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${matches.length} matches${matches.length > 20 ? ' (showing first 20)' : ''}:\n${text}`,
+                },
+            ],
+        };
+    }
+    if (request.params.name === "search_classes") {
+        const className = String(request.params.arguments?.className);
+        const matches = indexer.searchClass(className);
+        const text = matches.length > 0
+            ? matches.map(m => {
+                // Group by artifact ID to allow easy selection
+                const artifacts = m.artifacts.slice(0, 5).map(a => `[ID: ${a.id}] ${a.groupId}:${a.artifactId}:${a.version}${a.hasSource ? ' (Has Source)' : ''}`).join("\n    ");
+                const more = m.artifacts.length > 5 ? `\n    ... (${m.artifacts.length - 5} more versions)` : '';
+                return `Class: ${m.className}\n    ${artifacts}${more}`;
+            }).join("\n\n")
+            : "No classes found matching the query. Try different keywords.";
+        return {
+            content: [{ type: "text", text }]
+        };
+    }
+    if (request.params.name === "get_class_details") {
+        const className = String(request.params.arguments?.className);
+        const artifactId = Number(request.params.arguments?.artifactId);
+        const type = String(request.params.arguments?.type);
+        const artifact = indexer.getArtifactById(artifactId);
+        if (!artifact) {
+            return { content: [{ type: "text", text: "Artifact not found." }] };
+        }
+        let jarPath;
+        if (type === 'signatures') {
+            // Use Main JAR for signatures (javap)
+            jarPath = path.join(artifact.abspath, `${artifact.artifactId}-${artifact.version}.jar`);
+        }
+        else {
+            // Use Source JAR for docs and full source
+            if (!artifact.hasSource) {
+                return { content: [{ type: "text", text: `Artifact ${artifact.groupId}:${artifact.artifactId}:${artifact.version} does not have a sources jar available locally.` }] };
+            }
+            jarPath = path.join(artifact.abspath, `${artifact.artifactId}-${artifact.version}-sources.jar`);
+        }
+        try {
+            const detail = await SourceParser.getClassDetail(jarPath, className, type);
+            if (!detail) {
+                return { content: [{ type: "text", text: `Class ${className} not found in ${type === 'signatures' ? 'artifact' : 'sources'} of ${artifact.artifactId}.` }] };
+            }
+            let resultText = `Class: ${detail.className}\n\n`;
+            if (type === 'source') {
+                resultText += "```java\n" + detail.source + "\n```";
+            }
+            else {
+                if (detail.doc) {
+                    resultText += "Documentation:\n" + detail.doc + "\n\n";
+                }
+                if (detail.signatures) {
+                    resultText += "Methods:\n" + detail.signatures.join("\n") + "\n";
+                }
+            }
+            return { content: [{ type: "text", text: resultText }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error reading source: ${e.message}` }] };
+        }
+    }
+    if (request.params.name === "refresh_index") {
+        // Re-run index
+        indexer.index().catch(console.error);
+        return {
+            content: [{ type: "text", text: "Index refresh started." }]
+        };
+    }
+    throw new Error("Tool not found");
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/indexer.js

@@ -0,0 +1,322 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import yauzl from 'yauzl';
+import chokidar from 'chokidar';
+import { Config } from './config.js';
+import { DB } from './db/index.js';
+export class Indexer {
+    static instance;
+    isIndexing = false;
+    watcher = null;
+    debounceTimer = null;
+    constructor() { }
+    static getInstance() {
+        if (!Indexer.instance) {
+            Indexer.instance = new Indexer();
+        }
+        return Indexer.instance;
+    }
+    async startWatch() {
+        const config = await Config.getInstance();
+        const repoPath = config.localRepository;
+        if (!repoPath || !fsSync.existsSync(repoPath)) {
+            console.error("Repository path not found, skipping watch mode.");
+            return;
+        }
+        if (this.watcher) {
+            return;
+        }
+        console.error(`Starting file watcher on ${repoPath}...`);
+        this.watcher = chokidar.watch(repoPath, {
+            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();
+        });
+    }
+    async index() {
+        if (this.isIndexing)
+            return;
+        this.isIndexing = true;
+        console.error("Starting index...");
+        const config = await Config.getInstance();
+        const repoPath = config.localRepository;
+        const db = DB.getInstance();
+        if (!repoPath) {
+            console.error("No local repository path found.");
+            this.isIndexing = false;
+            return;
+        }
+        try {
+            // 1. Scan for artifacts
+            console.error("Scanning repository structure...");
+            const artifacts = await this.scanRepository(repoPath);
+            console.error(`Found ${artifacts.length} artifacts on disk.`);
+            // 2. Persist artifacts and determine what needs indexing
+            const artifactsToIndex = [];
+            db.transaction(() => {
+                const insertArtifact = db.prepare(`
+                INSERT OR IGNORE INTO artifacts (group_id, artifact_id, version, abspath, has_source)
+                VALUES (@groupId, @artifactId, @version, @abspath, @hasSource)
+            `);
+                const selectId = db.prepare(`
+                SELECT id FROM artifacts 
+                WHERE group_id = @groupId AND artifact_id = @artifactId AND version = @version
+            `);
+                const checkIndexed = db.prepare(`
+                SELECT 1 FROM indexed_artifacts WHERE artifact_id = ?
+            `);
+                for (const art of artifacts) {
+                    insertArtifact.run({
+                        ...art,
+                        hasSource: art.hasSource ? 1 : 0
+                    });
+                    const row = selectId.get({
+                        groupId: art.groupId,
+                        artifactId: art.artifactId,
+                        version: art.version
+                    });
+                    if (row) {
+                        art.id = row.id;
+                        const isIndexed = checkIndexed.get(art.id);
+                        if (!isIndexed) {
+                            artifactsToIndex.push(art);
+                        }
+                    }
+                }
+            });
+            console.error(`${artifactsToIndex.length} artifacts need indexing.`);
+            // 3. Scan JARs for classes and update DB
+            const CHUNK_SIZE = 50;
+            let processedCount = 0;
+            for (let i = 0; i < artifactsToIndex.length; i += CHUNK_SIZE) {
+                const chunk = artifactsToIndex.slice(i, i + CHUNK_SIZE);
+                await Promise.all(chunk.map(artifact => this.indexArtifactClasses(artifact)));
+                processedCount += chunk.length;
+                if (processedCount % 100 === 0) {
+                    console.error(`Processed ${processedCount}/${artifactsToIndex.length} artifacts...`);
+                }
+            }
+            console.error(`Indexing complete.`);
+        }
+        catch (e) {
+            console.error("Indexing failed", e);
+        }
+        finally {
+            this.isIndexing = false;
+        }
+    }
+    async scanRepository(rootDir) {
+        const results = [];
+        const scanDir = async (dir) => {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch (e) {
+                return;
+            }
+            const pomFiles = entries.filter(e => e.isFile() && e.name.endsWith('.pom'));
+            if (pomFiles.length > 0) {
+                const version = path.basename(dir);
+                const artifactDir = path.dirname(dir);
+                const artifactId = path.basename(artifactDir);
+                const groupDir = path.dirname(artifactDir);
+                const relGroupPath = path.relative(rootDir, groupDir);
+                const groupId = relGroupPath.split(path.sep).join('.');
+                if (groupId && artifactId && version && !groupId.startsWith('..')) {
+                    const sourceJarPath = path.join(dir, `${artifactId}-${version}-sources.jar`);
+                    // Use sync check for speed in this context or cache it
+                    const hasSource = fsSync.existsSync(sourceJarPath);
+                    results.push({
+                        id: 0, // Placeholder
+                        groupId,
+                        artifactId,
+                        version,
+                        abspath: dir,
+                        hasSource
+                    });
+                    return;
+                }
+            }
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    await scanDir(path.join(dir, entry.name));
+                }
+            }
+        };
+        await scanDir(rootDir);
+        return results;
+    }
+    async indexArtifactClasses(artifact) {
+        const jarPath = path.join(artifact.abspath, `${artifact.artifactId}-${artifact.version}.jar`);
+        const db = DB.getInstance();
+        const config = await Config.getInstance();
+        try {
+            await fs.access(jarPath);
+        }
+        catch {
+            // If jar missing, mark as indexed so we don't retry endlessly? 
+            // Or maybe it's a pom-only artifact.
+            db.prepare('INSERT OR IGNORE INTO indexed_artifacts (artifact_id) VALUES (?)').run(artifact.id);
+            return;
+        }
+        return new Promise((resolve) => {
+            yauzl.open(jarPath, { lazyEntries: true, autoClose: true }, (err, zipfile) => {
+                if (err || !zipfile) {
+                    resolve();
+                    return;
+                }
+                const classes = [];
+                zipfile.readEntry();
+                zipfile.on('entry', (entry) => {
+                    if (entry.fileName.endsWith('.class')) {
+                        // Convert path/to/MyClass.class -> path.to.MyClass
+                        const className = entry.fileName.slice(0, -6).replace(/\//g, '.');
+                        // Simple check to avoid module-info or invalid names
+                        if (!className.includes('$') && className.length > 0) {
+                            // Filter by includedPackages
+                            if (this.isPackageIncluded(className, config.includedPackages)) {
+                                classes.push(className);
+                            }
+                        }
+                    }
+                    zipfile.readEntry();
+                });
+                zipfile.on('end', () => {
+                    // Batch insert classes
+                    try {
+                        db.transaction(() => {
+                            const insertClass = db.prepare(`
+                              INSERT INTO classes_fts (artifact_id, class_name, simple_name)
+                              VALUES (?, ?, ?)
+                          `);
+                            for (const cls of classes) {
+                                const simpleName = cls.split('.').pop() || cls;
+                                insertClass.run(artifact.id, cls, simpleName);
+                            }
+                            db.prepare('INSERT OR IGNORE INTO indexed_artifacts (artifact_id) VALUES (?)').run(artifact.id);
+                        });
+                    }
+                    catch (e) {
+                        console.error(`Failed to insert classes for ${artifact.groupId}:${artifact.artifactId}`, e);
+                    }
+                    resolve();
+                });
+                zipfile.on('error', () => {
+                    resolve();
+                });
+            });
+        });
+    }
+    isPackageIncluded(className, patterns) {
+        if (patterns.length === 0 || (patterns.length === 1 && patterns[0] === '*'))
+            return true;
+        for (const pattern of patterns) {
+            if (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;
+    }
+    search(query) {
+        // 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}%`);
+        return rows;
+    }
+    searchClass(classNamePattern) {
+        const db = DB.getInstance();
+        // Use FTS for smart matching
+        // If pattern has no spaces, we assume it's a prefix or exact match query
+        // "String" -> match "String" in simple_name or class_name
+        const query = `"${classNamePattern}"* OR ${classNamePattern}`;
+        try {
+            const 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);
+            // Group by class name
+            const resultMap = new Map();
+            for (const row of rows) {
+                const art = {
+                    id: row.id,
+                    groupId: row.group_id,
+                    artifactId: row.artifact_id,
+                    version: row.version,
+                    abspath: row.abspath,
+                    hasSource: Boolean(row.has_source)
+                };
+                if (!resultMap.has(row.class_name)) {
+                    resultMap.set(row.class_name, []);
+                }
+                resultMap.get(row.class_name).push(art);
+            }
+            return Array.from(resultMap.entries()).map(([className, artifacts]) => ({
+                className,
+                artifacts
+            }));
+        }
+        catch (e) {
+            console.error("Search failed", e);
+            return [];
+        }
+    }
+    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);
+        if (row) {
+            return {
+                id: row.id,
+                groupId: row.groupId,
+                artifactId: row.artifactId,
+                version: row.version,
+                abspath: row.abspath,
+                hasSource: Boolean(row.hasSource)
+            };
+        }
+        return undefined;
+    }
+}

package/build/source_parser.js

@@ -0,0 +1,127 @@
+import yauzl from 'yauzl';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { Config } from './config.js';
+const execAsync = promisify(exec);
+export class SourceParser {
+    static async getClassDetail(jarPath, className, type) {
+        if (type === 'signatures') {
+            return this.getSignaturesWithJavap(jarPath, className);
+        }
+        // className: com.example.MyClass
+        // internalPath: com/example/MyClass.java
+        const internalPath = className.replace(/\./g, '/') + '.java';
+        return new Promise((resolve, reject) => {
+            yauzl.open(jarPath, { lazyEntries: true, autoClose: true }, (err, zipfile) => {
+                if (err || !zipfile) {
+                    resolve(null);
+                    return;
+                }
+                let found = false;
+                zipfile.readEntry();
+                zipfile.on('entry', (entry) => {
+                    if (entry.fileName === internalPath) {
+                        found = true;
+                        zipfile.openReadStream(entry, (err, readStream) => {
+                            if (err || !readStream) {
+                                resolve(null);
+                                return;
+                            }
+                            const chunks = [];
+                            readStream.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+                            readStream.on('end', () => {
+                                const source = Buffer.concat(chunks).toString('utf-8');
+                                resolve(SourceParser.parse(className, source, type));
+                            });
+                        });
+                    }
+                    else {
+                        zipfile.readEntry();
+                    }
+                });
+                zipfile.on('end', () => {
+                    if (!found)
+                        resolve(null);
+                });
+            });
+        });
+    }
+    static async getSignaturesWithJavap(jarPath, className) {
+        try {
+            const config = await Config.getInstance();
+            const javap = config.getJavapPath();
+            // Use -public to show public members (closest to API surface)
+            // or default (protected)
+            const { stdout } = await execAsync(`"${javap}" -cp "${jarPath}" "${className}"`);
+            const lines = stdout.split('\n')
+                .map(l => l.trim())
+                .filter(l => l.length > 0 &&
+                !l.startsWith('Compiled from') &&
+                !l.includes('static {};') &&
+                l !== '}');
+            return {
+                className,
+                signatures: lines
+            };
+        }
+        catch (e) {
+            // Fallback or error
+            // If javap fails (e.g. class not found in main jar?), return null
+            // console.error(`javap failed for ${className} in ${jarPath}:`, e);
+            return null;
+        }
+    }
+    static parse(className, source, type) {
+        if (type === 'source') {
+            return { className, source };
+        }
+        // Very simple regex-based parsing to extract methods and javadocs
+        // This is heuristic and won't be perfect, but it's fast and dependency-free
+        const signatures = [];
+        let doc = "";
+        const allDocs = [];
+        const lines = source.split('\n');
+        let currentDoc = [];
+        let inDoc = false;
+        // Regex to match method signatures (public/protected, return type, name, args)
+        // ignoring annotations for simplicity
+        const methodRegex = /^\s*(public|protected)\s+(?:[\w<>?\[\]]+\s+)+(\w+)\s*\([^)]*\)\s*(?:throws\s+[\w,.\s]+)?\s*\{?/;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Javadoc extraction
+            if (trimmed.startsWith('/**')) {
+                inDoc = true;
+                currentDoc = [];
+            }
+            if (inDoc) {
+                currentDoc.push(trimmed.replace(/^\/\*\*|\*\/|^\*\s?/g, '').trim());
+            }
+            if (trimmed.endsWith('*/')) {
+                inDoc = false;
+                if (currentDoc.length > 0) {
+                    const docBlock = currentDoc.filter(s => s.length > 0).join('\n');
+                    allDocs.push(docBlock);
+                    // If we found a class doc (usually before class definition), keep it as primary doc
+                    if (doc === "") {
+                        doc = docBlock;
+                    }
+                }
+            }
+            // Method extraction
+            const match = line.match(methodRegex);
+            if (match) {
+                // match[0] is the whole line up to {
+                // Clean it up
+                let sig = match[0].trim();
+                if (sig.endsWith('{'))
+                    sig = sig.slice(0, -1).trim();
+                signatures.push(sig);
+            }
+        }
+        return {
+            className,
+            signatures,
+            doc: type === 'docs' ? allDocs.join('\n\n') : undefined
+        };
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "maven-indexer-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for indexing local Maven repository",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "maven-indexer-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "doc": "doc"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node build/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangcent/maven-indexer-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "maven",
+    "index"
+  ],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/tangcent/maven-indexer-mcp/issues"
+  },
+  "homepage": "https://github.com/tangcent/maven-indexer-mcp#readme",
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@types/xml2js": "^0.4.14",
+    "@types/yauzl": "^2.10.3",
+    "better-sqlite3": "^12.5.0",
+    "chokidar": "^5.0.0",
+    "xml2js": "^0.6.2",
+    "yauzl": "^3.2.0",
+    "zod": "^4.1.13"
+  }
+}