MCP Lucene Server

What is MCP Lucene Server about?

MCP Lucene Server implements the Model Context Protocol to expose Lucene’s powerful full‑text search capabilities as a microservice. It runs on Spring Boot, listens on port 8080 by default, and offers endpoints for document upsert, delete, list, query, and health checks.

How to use MCP Lucene Server?

Prerequisites

Java 11+ installed
Maven 3.6.0+ installed
(Optional) Docker if you prefer container deployment

Installation & Build

# Clone the repo
git clone https://github.com/VivekKumarNeu/MCP-Lucene-Server.git
cd MCP-Lucene-Server

# Build with Maven
mvn clean install

Running without Docker

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

The service will be reachable at http://localhost:8080.

Running with Docker

# Build image
docker build -t mcp-lucene-server .

# Run container
docker run -p 8080:8080 mcp-lucene-server

API Interaction Use standard HTTP tools (curl, Postman) to call the endpoints described below.

Key features of MCP Lucene Server

MCP compliance (core Model Context Protocol)
Full‑text indexing and search powered by Apache Lucene
RESTful API for status, upsert, delete, list, and query operations
Support for complex Lucene query syntax and metadata‑based filtering
Spring Boot foundation for easy configuration and extensibility
Dockerfile supplied for containerized deployment
Configurable server port and Lucene index path via Spring Boot properties

Use cases of MCP Lucene Server

Document Management Systems – Index and retrieve large collections of text documents with custom metadata filters.
Knowledge Bases – Provide fast keyword search over support articles, FAQs, or internal documentation.
Analytics Dashboards – Enable ad‑hoc full‑text queries on log files or event streams stored in Lucene.
Micro‑service Architecture – Serve as a dedicated search micro‑service behind other application components.

FAQ from MCP Lucene Server

Q: Which Java version is required? A: Java 11 or higher.

Q: Can I change the default port? A: Yes. Set server.port in application.properties or pass --server.port=xxxx as a command‑line argument.

Q: Where does the index get stored? A: Configure lucene.index.path in application.properties. If omitted, a temporary directory is used.

Q: Is there support for authentication? A: The out‑of‑box project does not include auth, but you can add Spring Security filters as needed.

Q: How do I update the index schema? A: Modify the document model in the source code and rebuild the project; Lucene handles field additions dynamically.

Description

The MCP Lucene Server is a Java-based implementation of the Model Context Protocol (MCP) designed to provide efficient search and retrieval capabilities using Apache Lucene. This server allows you to manage and query documents, leveraging Lucene's powerful indexing and search features. It is built using Spring Boot for easy setup and deployment.

Features

MCP Compliance: Implements the core Model Context Protocol.
Lucene-Powered: Utilizes Apache Lucene for full-text search and indexing.
RESTful API: Provides a RESTful API for interacting with the server.
Document Management:
- Upsert: Add or update documents in the Lucene index.
- Delete: Delete documents from the Lucene index.
- List: Retrieve a list of documents from the index.
Querying:
- Supports complex queries using the Lucene query syntax.
- Filtering: Filter queries based on document metadata.
Status: Check the server status.
Spring Boot: Built with Spring Boot for easy setup and deployment.
Dockerization: Includes instructions for containerizing the application using Docker.

Description
Features
Getting Started
Usage
- API Endpoints
- Examples
Configuration
License

Getting Started

Prerequisites

Java: Java 11 or higher.
Maven: Maven 3.6.0 or higher.
Docker: Install Docker if you plan to use the Docker image.

Installation

Clone the repository:

git clone [https://github.com/your-username/mcp-lucene-server.git](https://github.com/your-username/mcp-lucene-server.git)
cd mcp-lucene-server

(Replace your-username with your GitHub username)

Build the project using Maven:
```
mvn clean install
```

Running the Server

Without Docker

Run the Spring Boot application:
```
java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar
```
(The exact name of the .jar file might vary slightly depending on your project version.)
The server will start on port 8080 by default.

With Docker

Ensure you have Docker installed: Follow the instructions on the official Docker website: https://docs.docker.com/get-docker/
Build the Docker image: Navigate to the root directory of your project in your terminal and run:
```
docker build -t mcp-lucene-server .
```
Run the Docker container:
```
docker run -p 8080:8080 mcp-lucene-server
```
This will map port 8080 on your host machine to port 8080 inside the container.

Usage

API Endpoints

The server provides the following API endpoints:

GET /mcp/v1/status
- Returns the status of the server.

POST /mcp/v1/upsert

Upserts (inserts or updates) one or more documents.

Request body:

{
  "documents": [
    {
      "id": "doc1",
      "text": "This is the text of document 1.",
      "metadata": {
        "category": "example",
        "language": "english"
      }
    },
    {
      "id": "doc2",
      "text": "This is document 2's text.",
      "metadata": {
        "category": "sample",
        "language": "spanish"
      }
    }
  ]
}

POST /mcp/v1/query

Queries the Lucene index.

Request body:

{
  "queries": [
    {
      "query": "document",
      "top_k": 10,
      "filter": {
        "language": "english"
      }
    },
     {
      "query": "text search",
      "filter": {
         "category": "example"
       }
     }
  ]
}

query: The Lucene query string.
top_k: (Optional) The maximum number of results to return (default: 10).
filter: (Optional) A map of metadata fields and values to filter by.

POST /mcp/v1/delete
- Deletes documents from the Lucene index.
- Request body:
```
{
    "ids": ["doc1", "doc2"]
}
```
GET /mcp/v1/list
- Lists documents from the Lucene index.
- Request body:
```
{
    "ids": ["doc1", "doc2"]
}
```

Examples

Get server status:

curl http://localhost:8080/mcp/v1/status

Upsert documents:

curl -X POST 

http://localhost:8080/mcp/v1/upsert 

-H 'Content-Type: application/json' 

-d '{
"documents": [
{
"id": "doc1",
"text": "This is the text of document 1.",
"metadata": {
"category": "example",
"language": "english"
}
},
{
"id": "doc2",
"text": "This is document 2''s text.",
"metadata": {
"category": "sample",
"language": "spanish"
}
}
]
}'

Query documents:

curl -X POST 

http://localhost:8080/mcp/v1/query 

-H 'Content-Type: application/json' 

-d '{
"queries": [
{
"query": "document text",
"top_k": 5,
"filter": {
"language": "english"
}
}
]
}'

Delete documents:

curl -X POST 

http://localhost:8080/mcp/v1/delete 

-H 'Content-Type: application/json' 

-d '{
"ids": ["doc1"]
}'

List documents:

curl -X POST 

http://localhost:8080/mcp/v1/list 

-H 'Content-Type: application/json' 

-d '{
"ids": ["doc1", "doc2"]
}'

Configuration

The server can be configured using Spring Boot's application properties. Here are some of the key properties:

server.port: The port the server listens on (default: 8080).
lucene.index.path: The path to the Lucene index directory. This is where the indexed data is stored. If not set, a default location is used. It is highly recommended to configure this to a persistent storage location.

You can set these properties in an application.properties or application.yml file in your src/main/resources directory, or by using environment variables.

Example application.properties:

server.port=8080 lucene.index.path=/path/to/lucene/index

License

This project is licensed under the Apache 2.0 License.

MCP Lucene Server