MCP Lucene Server

🚀 MCP Lucene Server

The MCP Lucene Server is a Java-based implementation of the Model Context Protocol (MCP). It aims to provide efficient search and retrieval capabilities using Apache Lucene. This server allows you to manage and query documents, leveraging Lucene's powerful indexing features. It supports document management through insert, query, delete, and list operations.

🚀 Quick Start

Prerequisites

• Java Development Kit (JDK) 1.8 or higher
• Maven or other build tools for project management

Installation Steps

1. Clone the repository

   git clone https://github.com/your-repository/mcp-lucene.git
   cd mcp-lucene
   

2. Build the project Use Maven to build:

   mvn clean install
   

3. Run the server

   java -jar target/mcp-lucene.jar
   

✨ Features

• Upsert: Upload a JSON array containing multiple documents.
• Query: Retrieve documents based on text content and optional filtering conditions. It supports specifying the maximum number of returned results, with a default of 10.
• Delete: Remove specific documents from the index by providing a list of document IDs.
• List: Get the content of specific documents by providing a list of document IDs.

💻 Usage Examples

Interface Description

• Upsert Documents

  POST /mcp/v1/upsert
  Content-Type: application/json
  
  {
    "documents": [
      {
        "id": "doc1",
        "text": "This is the content of the first document.",
        "metadata": {
          "Category": "Example",
          "Language": "Chinese"
        }
      },
      ...
    ]
  }
  

• Query Documents

  POST /mcp/v1/query
  Content-Type: application/json
  
  {
    "queries": [
      {
        "query": "Search keyword",
        "top_k": 5,
        "filter": {
          "Language": "Chinese"
        }
      }
    ]
  }
  

• Delete Documents

  POST /mcp/v1/delete
  Content-Type: application/json
  
  {
    "ids": ["doc1", "doc2"]
  }
  

• List Documents

  POST /mcp/v1/list
  Content-Type: application/json
  
  {
    "ids": ["doc1", "doc2"]
  }
  

Basic Usage

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 first document.",
      "metadata": {
        "Category": "Example",
        "Language": "Chinese"
      }
    },
    {
      "id": "doc2",
      "text": "This is the second document.",
      "metadata": {
        "Category": "Test",
        "Language": "Chinese"
      }
    }
  ]
}'

Query Documents

curl -X POST \
http://localhost:8080/mcp/v1/query \
-H 'Content-Type: application/json' \
-d '
{
  "queries": [
    {
      "query": "Test",
      "top_k": 3,
      "filter": {
        "Language": "Chinese"
      }
    }
  ]
}'

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"]
}'

📚 Documentation

Running Modes

Local Run

After starting the server, it listens on the http://localhost:8080 port by default.

Docker Deployment

1. Package the image:

   FROM java:8-jdk
   COPY target/mcp-lucene.jar /app/
   WORKDIR /app
   ENTRYPOINT ["java", "-jar", "mcp-lucene.jar"]
   

2. Build and run:

   docker build -t mcp-lucene .
   docker run -p 8080:8080 mcp-lucene
   

Configuration

Configure server properties through the application.properties file:

• Port: Specify the port number the server listens on, with a default of 8080.
• Thread Count: Set the maximum number of threads for processing requests. It is recommended to adjust according to hardware resources.

Example configuration:

server.port=8081
server.servlet.thread-count=20

Project Structure

mcp-lucene/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/MCPServer.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── JavaTestCases.java
└── pom.xml

Dependency Management

The project uses Maven to manage dependencies. The core dependencies include:

• Jetty: Embedded HTTP server.
• JSON Processing: Process JSON data.

Development Guide

1. Code Structure
   • MCPServer.java: The main service class, containing startup logic and REST interface definitions.
   • DocumentService.java: The implementation of business logic for document storage and retrieval.
2. Unit Testing Use JUnit and Mockito for unit testing to ensure that each functional module works properly.

📄 License

This project is licensed under the Apache License 2.0. For detailed information, please refer to the LICENSE file.