Overview

This project is a Spring Boot server that implements a Model Context Protocol (MCP) backed by Apache Lucene for indexing and retrieving documents. It provides a lightweight REST interface to add, update, delete, and search textual documents using Lucene’s full-text search capabilities. The server is intended to act as a fast, local context provider for retrieval-augmented workflows, chatbots, or any application that needs quick lookups into a document corpus.

Using Lucene gives you fine-grained control over analyzers, tokenization, and indexing strategies while keeping a small operational footprint compared to heavyweight search platforms. Integrating the server into a Spring Boot ecosystem makes it easy to configure, extend, and run alongside other Java services.

Features

Full-text indexing powered by Apache Lucene
REST endpoints for document ingestion, deletion, and retrieval
Configurable index directory and analyzer via Spring Boot properties
Pagination and basic query options (e.g., limit/offset, simple query strings)
Lightweight Spring Boot application: easy to run locally or in containers
Designed to be used as a context provider for model-driven applications (MCP-compatible)

Installation / Configuration

Clone the repository and build with Maven:

git clone https://github.com/VivekKumarNeu/MCP-Lucene-Server.git
cd MCP-Lucene-Server
mvn clean package -DskipTests

Run the packaged JAR:

java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar

Example application.properties (or application.yml). Configure server port and where Lucene stores its index:

# application.properties
server.port=8080
mcp.lucene.index.path=./data/lucene-index
mcp.lucene.analyzer=standard
mcp.lucene.max-results=50

Common environment variables (as alternatives to properties):

SERVER_PORT — Spring Boot server port
MCP_LUCENE_INDEX_PATH — path to Lucene index directory
MCP_LUCENE_ANALYZER — analyzer name (e.g., standard, whitespace)

If you run the service in Docker you can mount a host directory for the index to persist data across container restarts.

API examples

The concrete endpoints may vary by release; the examples below show typical REST interactions you can adapt easily.

Index (add/update) a document:

curl -X POST http://localhost:8080/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "doc-123",
    "title": "Introduction to Lucene",
    "content": "Apache Lucene is a high-performance, full-featured text search engine library...",
    "metadata": {"author": "Alice", "tags": ["search","lucene"]}
  }'

Search the corpus:

curl 'http://localhost:8080/search?q=lucene+performance&limit=10&offset=0'

Delete a document:

curl -X DELETE http://localhost:8080/documents/doc-123

Note: check the repository README or generated OpenAPI/Swagger docs for exact paths and request/response payloads.

Available Resources

Source code and issues: https://github.com/VivekKumarNeu/MCP-Lucene-Server
Lucene documentation: https://lucene.apache.org/core/
Spring Boot documentation: https://spring.io/projects/spring-boot

If the project includes an OpenAPI/Swagger UI, it will usually be available at /swagger-ui.html or /v3/api-docs when the server is running. Consult the repository for any bundled API docs.

Use Cases

Retrieval-Augmented Generation (RAG): Use the server to supply relevant document fragments as context to an LLM prompt, improving factuality and grounding.
Chatbots and Virtual Assistants: Provide fast lookup of product documents, manuals, or knowledge bases to answer user questions.
Enterprise document search: Index internal documents (policies, specs, reports) for fast retrieval by developers or employees.
Prototyping search features: Quickly add search functionality to a Java application without deploying a heavy search cluster.

Concrete example: In a RAG pipeline you would:

Ingest onboarding PDFs or knowledge articles into the MCP Lucene Server.
At query time, run a short text query to retrieve the top-k relevant segments.
Concatenate the retrieved segments with the prompt sent to the language model.

Tips & Best Practices

Choose an analyzer appropriate to your data (standard for natural language, whitespace for token-preserving).
Persist the Lucene index directory on disk (or a mounted volume) to avoid reindexing after restart.
Implement light-weight metadata filtering at query time to narrow searches (e.g., by tags or author).
Monitor index size and optimize/merge segments periodically for larger corpora.

Troubleshooting

Permissions: Ensure the process can read/write the configured index path.
Port conflicts: Change server.port if 8080 is already in use.
Analyzer mismatches: Reindex when you change the analyzer configuration to avoid inconsistent search behavior.

For contributions, bug reports, or to inspect implementation details, see the project on GitHub: https://github.com/VivekKumarNeu/MCP-Lucene-Server.

Lucene MCP Server Spring Boot Document Search