MCP Lucene Server

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.

Table of Contents

• Description

• Features

• Getting Started

  • Prerequisites

  • Installation

  • Running the Server

• 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

1. 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)

2. Build the project using Maven:

   mvn clean install
   

Running the Server

Without Docker

1. 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.)

2. The server will start on port 8080 by default.

With Docker

1. Ensure you have Docker installed: Follow the instructions on the official Docker website: https://docs.docker.com/get-docker/

2. Build the Docker image: Navigate to the root directory of your project in your terminal and run:

   docker build -t mcp-lucene-server .
   

3. 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.

MCP Shim for Claude Desktop

This project includes an optional MCP shim (mcp-shim/) that exposes the server's REST endpoints as MCP tools over STDIO so you can use them directly from Claude Desktop.

Prerequisites

• Java 17+
• Node.js 18+
• Maven 3.6+

1) Run the Spring Boot server

mvn spring-boot:run

The API will be available at http://localhost:8080/mcp/v1.

2) Run the MCP shim

cd mcp-shim
npm install
# JSON + text output (default)
LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start
# If your client cannot render JSON tool outputs, force text-only
MCP_FORCE_TEXT=1 LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

3) Configure Claude Desktop

Update `~/.cl

... View full README on GitHub