MCPLuceneServer

The MCPLuceneServer exposes Apache Lucene full-text search capabilities via the MCP protocol over STDIO. It automatically crawls and indexes documents from configured directories, supports rich Lucene query syntax, and provides structured results with metadata suitable for consumption by MCP clients such as Claude Desktop. Core tools include search, profileQuery for debugging and tuning, indexAdmin for index maintenance, getIndexStats to inspect the index, startCrawl to trigger crawling, and utilities to discover terms and top terms. Use these tools to build an end-to-end search experience over your local documents, with language detection, metadata extraction, and passaged-based results optimized for downstream LLM consumption.

To use the server, first ensure the MCP client is connected via STDIO. Then invoke the available tools in your conversation, for example: ask to start crawling a configured directory, run a search with a Lucene query, or request a profiling analysis for a complex query. The server returns structured results including document metadata, passages, and scoring explanations when profiling is enabled, enabling you to refine queries and understand ranking behavior.

Prerequisites:

• Java 21 or later
• Optional: Maven 3.9+ if building from source

Installation options:

Option A - Use pre-built JAR (recommended):

1. Download the latest pre-built JAR from the project's release page or artifacts in the CI workflow.
2. Place the JAR somewhere accessible, e.g. /opt/luceneserver/luceneserver-0.0.1-SNAPSHOT.jar
3. Run the server using the MCP configuration (see mcp_config) so it can be wired into Claude Desktop or your MCP client. The example uses: java --enable-native-access=ALL-UNNAMED -Xmx2g -Dspring.profiles.active=deployed -jar /absolute/path/to/luceneserver-0.0.1-SNAPSHOT.jar

Option B - Build from source:

1. Ensure Java 21+ and Maven are installed.
2. In the repository root, build the project: ./mvnw clean package -DskipTests
3. The build outputs a JAR, typically at target/luceneserver-0.0.1-SNAPSHOT.jar. Use this JAR in the same way as Option A.

Configuration:

• After obtaining the JAR, configure Claude Desktop (or your MCP client) to load the server using the provided command and arguments. Example: { "mcpServers": { "lucene-search": { "command": "java", "args": [ "--enable-native-access=ALL-UNNAMED", "-Xmx2g", "-Dspring.profiles.active=deployed", "-jar", "/absolute/path/to/luceneserver-0.0.1-SNAPSHOT.jar" ] } } }

Tips and considerations:

• The server uses STDIO transport; ensure your MCP client is configured to communicate over STDIO (as shown in the example configuration).
• The deployed profile disables verbose console logging and web UI for clean STDIO communication; adjust as needed for debugging.
• Document crawling is incremental and supports real-time monitoring; ensure the crawler directories are configured in the MCP client to begin indexing.
• If you encounter memory issues, increase the -Xmx value and monitor GC behavior; Lucene indexing can be memory-intensive with large datasets.
• Ensure that the Java command line includes -jar pointing to the actual JAR file and that absolute paths are correct in the configuration.
• The server exposes commands like search, profileQuery, startCrawl, and getIndexStats; consult your MCP client’s tooling for invocation details and expected response shapes.